# 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](componentes-de-interfaz.md) describe sus APIs y consumidores;
el [inventario de modales](inventario-de-modales.md) 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.
- Las altas guiadas de recursos y activos desde el inventario de compañía siguen tres
  pasos: plantilla, características y datos finales. Reutilizar `FormProgress` y
  `FormStepActions`, validar antes de avanzar y conservar el borrador al retroceder.
  Guardar se muestra al final; ayuda, cancelación y errores permanecen dentro del diálogo.
  El alta usa tamaño medio y la edición completa conserva tamaño grande.
- 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.