metis-desk/docs/patron-de-dialogos.md

Patrón de diseño de cuadros de diálogo

Fuente normativa para crear o modificar diálogos de Metis Desk. Recoge las decisiones aplicadas a los editores de plantillas de activos y recursos y a los selectores PickerList. La guía de componentes describe sus APIs y consumidores; el inventario de modales recoge las implementaciones existentes.

Composición y reutilización

• Cada interacción modal con responsabilidad propia vive en un componente y fichero .tsx independientes. El padre decide su apertura y aporta datos y callbacks.
• Reutilizar FormDialog, FormBody y FormActions de @repo/rdx-ui, apoyados en las primitivas de shadcn/ui y Base UI. Consultar los patrones existentes antes de crear otro.
• Mantener los bloques visuales genéricos independientes de entidades, DTO, consultas y endpoints. El módulo aporta textos traducidos, controles, datos y acciones.
• Aplicar el mismo patrón a alta, edición y copia y a entidades equivalentes. Conservar los campos y restricciones propios de cada entidad, como el uso de las plantillas de recursos.

Grupos, títulos y separación

• Las etiquetas de campos utilizan FormLabel de @repo/rdx-ui. Añadir required solo cuando el campo sea obligatorio: muestra un asterisco al final en color destructive. Los campos optativos muestran únicamente su nombre, sin «(opcional)».

• La marca sigue las mismas condiciones que la validación del campo, también en selectores, características de plantillas y fechas condicionales. Conservar htmlFor, los atributos de validación y la ayuda accesible del control. No incluir el asterisco en las traducciones ni en el nombre de la característica. Los grupos con leyenda reutilizan RequiredIndicator.

• Usar FormSectionTitle para los títulos de grupo: texto pequeño, seminegrita, mayúsculas, espaciado entre letras y color atenuado (text-xs font-semibold uppercase tracking-wide text-muted-foreground mb-4). Conservar el nivel semántico del encabezado; las mayúsculas pertenecen a la presentación CSS y los textos pasan por i18n.

• El título principal del diálogo y los nombres editables de secciones tienen su propia función. El nombre editable de una sección va en su cabecera, junto a sus acciones.

• Para los datos generales, preferir FormSection variant="plain", sin borde ni relleno de tarjeta. Los grupos repetidos que necesitan identidad visual usan borde y fondo semánticos discretos. Evitar acumular marcos y rellenos en grupos anidados.

• Mantener más separación entre grupos principales que entre controles relacionados. En el patrón de plantillas, TemplateMetadataSection deja 36 px antes del grupo de secciones (20 px del cuerpo y 16 px adicionales); las columnas y tarjetas se separan 16 px.

• Situar las acciones locales en la cabecera del grupo al que afectan. Por ejemplo, «Añadir campo» se ofrece en «Campos» y lleva implícita la sección de destino.

Distribución responsive y alturas

• Decidir las columnas por el ancho disponible del contenedor, mediante container queries. En espacios estrechos, apilar el contenido y permitir que nombres y acciones se adapten.
• En formularios con nombre, icono y descripción, reutilizar TemplateMetadataSection: nombre e icono debajo a la izquierda, descripción a la derecha, en dos columnas iguales desde 560 px. Ambas columnas tienen igual altura y el área de descripción ocupa el alto restante. En una columna, el recorrido es nombre, icono y descripción.
• Para secciones repetidas equivalentes, usar una columna con poco espacio y dos cuando sus controles quepan con comodidad. TemplateSectionsEditor sectionLayout="responsive" cambia a dos columnas desde 1.000 px. Las secciones de cada fila tienen la misma altura, determinada por la más alta, y se reajustan al plegar, desplegar o cambiar su contenido.
• Mantener el orden de izquierda a derecha y de arriba abajo en el DOM, la numeración, el teclado y el arrastre. No introducir un orden visual diferente mediante CSS.
• Cada grupo de campos responde a su propio ancho, también cuando su sección ocupa media fila. El bloque «Sin sección» permanece debajo de las secciones, a ancho completo.
• No convertir formularios sencillos en cuadrículas de secciones ni imponerles altura fija. Los umbrales anteriores corresponden a los componentes citados; otros contenidos deben elegir su disposición según el espacio que necesitan sus controles.

Secciones plegables y filas compactas

• Las secciones extensas o repetidas utilizan la primitiva Collapsible mediante TemplateSectionEditor. Empiezan abiertas y conservan el estado de apertura por identidad al reordenarse. El nombre, el agarre y las acciones permanecen en la cabecera.
• Conservar los controles al plegar. Si la validación detecta un control inválido oculto, abrir la sección antes de enfocarlo. Plegar no modifica los datos.
• En listas de configuración de campos, utilizar la presentación compacta TemplateSectionsEditor fieldLayout="compact": agarre, switch de obligatoriedad, nombre, flechas de desplazamiento y papelera. Evitar una segunda fila de controles cuando esta configuración sea suficiente. Esta pauta corresponde a referencias de campos dentro de una plantilla; los formularios de edición de sus valores conservan sus controles propios.
• Dar nombre accesible a los switches y botones de icono, incluyendo el campo o la sección. La obligatoriedad conserva su etiqueta accesible y ayuda al pasar el ratón.
• Reutilizar IconPicker como desplegable compacto con icono y texto, incluida la opción sin icono. Evitar una fila permanente con todas las opciones de iconos.

Ordenación y selección de campos

• Reutilizar useDragReorder, ReorderHandle y el indicador de destino. Mantener flechas explícitas y ordenación por teclado; el arrastre no es la única forma de cambiar el orden.
• Las secciones se ordenan entre sí y los campos dentro de su sección. Conservar el foco y bloquear los movimientos imposibles o las acciones durante el guardado. Cancelar un arrastre no cambia los datos y guardar confirma el borrador del formulario.
• Cuando se incorporen varias referencias de un catálogo, utilizar un selector múltiple en diálogo en lugar de un desplegable que obligue a añadirlas una a una. En plantillas, reutilizar CatalogFieldPickerDialog desde la cabecera de cada grupo de campos, sin un bloque independiente de incorporación tras los datos generales.
• Confirmar la selección como lote, conservarla al buscar o paginar y descartar la selección provisional al cancelar. Respetar límites, disponibilidad y ausencia de duplicados.
• El alta rápida opcional se ofrece a la izquierda del pie mediante leadingActions. Debe poder ocultarse o deshabilitarse desde el consumidor. Mantener el selector y su estado durante el alta anidada; crear el elemento no confirma por sí solo el lote seleccionado.

Diálogos de selección PickerList

• Todos utilizan FormDialog layout="picker" y EntityTable layout="fill": altura estable adaptada a la ventana, independiente de búsquedas, carga y número de resultados. La tabla ocupa el espacio restante y mantiene desplazamiento interno con espacio reservado para la barra; búsqueda, filtros, paginación y acciones permanecen estables.
• Mantener el área de resultados incluso vacía y las cabeceras visibles durante el scroll. En ventanas pequeñas, permitir el desplazamiento adicional del cuerpo para acceder a todos los controles.
• La columna selection es la primera, antes del nombre: anchura ajustada al checkbox o radio, poco espacio hasta el nombre y cabecera visualmente oculta con nombre accesible. No se ordena, no se oculta y no se ancla a la derecha como las acciones.
• Pulsar una zona no interactiva de una fila disponible alterna su checkbox o selecciona su radio. Reutilizar onRowClick de la tabla; los controles internos ejecutan solo su propia acción, sin duplicar cambios. Respetar filas deshabilitadas y navegación por teclado.

Cuerpo, pie y accesibilidad

• Elegir la anchura del diálogo según su contenido y respetar los márgenes de la ventana. Mantener cabecera y pie visibles y el cuerpo desplazable cuando el contenido lo requiera.
• Los formularios conservan altura según contenido; la altura estable por resultados es la regla de los PickerList. No introducir pestañas ni pasos para resolver solo espacio.
• Situar ayuda contextual general al final del cuerpo, inmediatamente antes de FormActions. Mantener errores junto al contexto que los origina y las acciones dentro del formulario.
• Conservar foco, cancelación, cierre por teclado, estados de carga, error, vacío y envío. No cerrar ni limpiar el formulario antes de confirmar una operación correcta.
• Validar los cambios de interacción con pruebas dirigidas y revisar visualmente los anchos estrecho y amplio, nombres largos, secciones de distinta altura, plegado y resultados vacíos cuando correspondan. Informar de las comprobaciones que no se hayan podido ejecutar.