diff --git a/AGENTS.md b/AGENTS.md index 250ac87..caed3f0 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -80,7 +80,7 @@ Estado remoto en TanStack Query; claves centralizadas e invalidación explícita No duplicar estado remoto ni usar efectos para derivar valores calculables durante render. Mantener accesibilidad y estados de carga, error, vacío y acciones deshabilitadas. Separar componentes por responsabilidades reales, sin fragmentar JSX trivial. -Los listados no muestran formularios de alta ni edición junto a los datos. El alta se inicia con un botón en la cabecera, a la derecha; formularios sencillos en modal shadcn/ui y formularios complejos o extensos en una página propia. La edición se abre mediante una acción explícita, siguiendo el mismo criterio. Mantener foco, cierre por teclado, cancelación y errores dentro del formulario. +Los listados no muestran formularios de alta ni edición junto a los datos. El alta se inicia con un botón en la cabecera, a la derecha; formularios en modal shadcn/ui como norma general, con anchura y desplazamiento adaptados a su contenido. La edición se abre mediante una acción explícita, siguiendo el mismo criterio. Mantener foco, cierre por teclado, cancelación y errores dentro del formulario. Incluir ayuda contextual con finalidad, ámbito y ejemplos, sin rellenar los campos automáticamente. En formularios, colocar la ayuda en la parte inferior, inmediatamente antes del pie del modal con Guardar y Cancelar. ## Validación y entrega diff --git a/docs/ayuda-contextual.md b/docs/ayuda-contextual.md new file mode 100644 index 0000000..2301719 --- /dev/null +++ b/docs/ayuda-contextual.md @@ -0,0 +1,15 @@ +# Ayuda integrada en Metis Desk + +Cada formulario de compañías, personas, departamentos, sedes, asignaciones y cuentas y accesos incluye una explicación de qué representa el elemento y para qué sirve. La ayuda está en la parte inferior, justo antes del pie con Guardar y Cancelar. + +«Ver ejemplos y recomendaciones» despliega valores orientativos y reglas útiles. Los ejemplos nunca rellenan campos ni crean registros. En sistemas puedes consultar Dominio, Microsoft 365, ERP, Brevo, Zoom o Canva. + +Los sistemas, tipos de recurso y permisos explican su ámbito: global para todas las compañías o exclusivo de la compañía actual. Las plantillas globales comparten valores iniciales, mientras que miembros y accesos se mantienen separados por compañía. + +El botón Ayuda en Catálogos informáticos y Cuentas y accesos explica la sección seleccionada sin abrir el alta. Todo el contenido está disponible en español e inglés. + +Los formularios se abren en modales como norma general. Personas y formularios extensos usan mayor anchura y desplazamiento cuando hace falta. La ayuda desplegable funciona con teclado y los diálogos conservan cancelación y cierre con Escape. + +## Validación + +44 pruebas automatizadas correctas, comprobaciones de tipos y estilo y compilación. Verificación en navegador de sistemas globales y propios, ayuda de consulta, alta y edición de personas, modal amplio de cuentas, ejemplos desplegables y cancelación sin guardar. diff --git a/docs/componentes-de-interfaz.md b/docs/componentes-de-interfaz.md index a63b4af..eb87546 100644 --- a/docs/componentes-de-interfaz.md +++ b/docs/componentes-de-interfaz.md @@ -13,11 +13,11 @@ El código se genera desde el registro oficial y queda versionado en este reposi - Checkbox: estado activo de usuarios, compañías, personas y departamentos. - Table: listados de usuarios, compañías, personas y departamentos. - Textarea: dirección opcional de las sedes, con varias líneas. -- Dialog: formularios sencillos de alta y edición, con foco y cierre por teclado. FormDialog comparte el título y la cancelación traducidos. +- Dialog: formularios de alta y edición, con foco y cierre por teclado. FormDialog comparte el título y la cancelación traducidos. ## Convención de navegación -Los listados presentan datos, búsqueda y acciones. El botón de alta se coloca en la cabecera, a la derecha. Los formularios sencillos se abren en un modal; los complejos o con muchos campos se presentan en una página propia. No mostrar formularios junto al listado. Las ediciones se abren mediante una acción explícita. Compañías, personas, departamentos, asignaciones, sedes y usuarios siguen este criterio. Las personas se crean y editan en una página propia; los departamentos y las asignaciones usan modales. El historial se consulta en un diálogo. Catálogos, cuentas, grupos, recursos, permisos y necesidades siguen la misma convención. Los permisos de una necesidad se eligen mediante casillas shadcn/ui. +Los listados presentan datos, búsqueda y acciones. El botón de alta se coloca en la cabecera, a la derecha. Los formularios se abren en modal como norma general, con anchura adaptable y desplazamiento si el contenido lo requiere. No mostrar formularios junto al listado. Las ediciones se abren mediante una acción explícita. Compañías, personas, departamentos, asignaciones, sedes y usuarios siguen este criterio. Las personas, los departamentos y las asignaciones se crean y editan en modales. El historial se consulta en un diálogo. Catálogos, cuentas, grupos, recursos, permisos y necesidades siguen la misma convención. Los permisos de una necesidad se eligen mediante casillas shadcn/ui. TanStack Table filtra el listado de compañías por nombre; React Hook Form gestiona los formularios con los contratos Zod compartidos. @@ -54,3 +54,11 @@ lucide-react aporta los iconos del selector y tw-animate-css sus transiciones. shadcn es una herramienta de desarrollo; su hoja de estilos común se incorpora al compilar. Guías oficiales: [monorepos](https://ui.shadcn.com/docs/monorepo) e [instalación manual](https://ui.shadcn.com/docs/installation/manual). + +## Ayuda contextual + +ContextHelp muestra una explicación breve y permite desplegar ejemplos y recomendaciones mediante teclado. EntityHelp aporta contenido específico en español e inglés para compañías, personas, departamentos, sedes, asignaciones y todas las secciones de cuentas y accesos. Los catálogos explican si la definición es global o exclusiva de la compañía. Los ejemplos son orientativos: nunca se convierten en valores del formulario. + +El botón Ayuda de Cuentas y accesos y Catálogos informáticos permite consultar la explicación de la sección sin abrir un alta. La misma ayuda aparece dentro de los modales de alta y edición. FormDialog utiliza una variante amplia para personas y formularios con más campos; el número de campos no cambia la navegación a una página propia. + +La ayuda de los formularios se coloca en su parte inferior, inmediatamente antes de FormActions. Este pie compartido reúne Guardar y Cancelar dentro del formulario, conservando el envío y el cierre accesible del diálogo. Los diálogos de consulta mantienen únicamente Cerrar. diff --git a/docs/personas-y-departamentos.md b/docs/personas-y-departamentos.md index d9cb973..eccc89c 100644 --- a/docs/personas-y-departamentos.md +++ b/docs/personas-y-departamentos.md @@ -4,7 +4,7 @@ Abrir una compañía y elegir Personas o Departamentos. -- Nueva persona, a la derecha de la cabecera, abre una página propia. Nombre obligatorio; puesto general, email y teléfono opcionales. El estado activo y la marca Contacto de la compañía se editan por separado. +- Nueva persona, a la derecha de la cabecera, abre un modal. Nombre obligatorio; puesto general, email y teléfono opcionales. El estado activo y la marca Contacto de la compañía se editan por separado. - El listado permite buscar por nombre y mostrar solo contactos. Abrir ficha muestra los datos de la persona y sus asignaciones. - Nuevo departamento abre un modal con nombre y estado activo. Los nombres son únicos dentro de cada compañía, ignorando mayúsculas y espacios exteriores. No hay departamentos anidados. - Desde la ficha de una persona, Asignar departamento abre un modal con departamento, puesto específico opcional, fecha de inicio, fecha de fin opcional y marca de departamento principal. diff --git a/modules/companies/src/web/access/access-form.tsx b/modules/companies/src/web/access/access-form.tsx index 57ccf9a..3a763f8 100644 --- a/modules/companies/src/web/access/access-form.tsx +++ b/modules/companies/src/web/access/access-form.tsx @@ -1,4 +1,5 @@ import { Button } from "@repo/shadcn-ui/components/button"; +import { FormActions } from "@repo/shadcn-ui/components/form-dialog"; import { useMutation, useQueryClient } from "@tanstack/react-query"; import { useId, useState } from "react"; import { useForm } from "react-hook-form"; @@ -14,6 +15,7 @@ import { accessFields } from "./access-fields"; import type { AccessFormValues } from "./access-form-values"; import { compatibleOption, fieldDefault, formBody } from "./access-form-values"; import { accessLabel } from "./access-labels"; +import { EntityHelp } from "./entity-help"; export function AccessForm({ scope, kind, @@ -119,7 +121,6 @@ export function AccessForm({ const editableFields = fields.filter((field) => field.key !== "configuration" || !technical); return (
); } diff --git a/modules/companies/src/web/components/department-section.tsx b/modules/companies/src/web/components/department-section.tsx index 0efed60..d95712a 100644 --- a/modules/companies/src/web/components/department-section.tsx +++ b/modules/companies/src/web/components/department-section.tsx @@ -2,7 +2,7 @@ import { zodResolver } from "@hookform/resolvers/zod"; import { Button } from "@repo/shadcn-ui/components/button"; import { Card, CardContent } from "@repo/shadcn-ui/components/card"; import { Checkbox } from "@repo/shadcn-ui/components/checkbox"; -import { FormDialog } from "@repo/shadcn-ui/components/form-dialog"; +import { FormActions, FormDialog } from "@repo/shadcn-ui/components/form-dialog"; import { Input } from "@repo/shadcn-ui/components/input"; import { Label } from "@repo/shadcn-ui/components/label"; import { @@ -20,6 +20,7 @@ import { useTranslation } from "react-i18next"; import type { CompanyDTO, DepartmentDTO, DepartmentRequestDTO } from "../../common"; import { DepartmentRequestSchema } from "../../common"; +import { EntityHelp } from "../access/entity-help"; import { companyApi, companyKeys } from "../api/company-api"; import { CompanyFeedback } from "./company-feedback"; @@ -73,9 +74,13 @@ function DepartmentForm({ error={mutation.error} invalid={Object.keys(form.formState.errors).length > 0} /> - + +{t("personHelp")}
{t("personHelp")}
+