@ajuarezso/sui-design-system 0.20.0 → 0.22.0

package/docs/sui-modal/README.md

@@ -0,0 +1,238 @@
+---
+name: sui-modal
+selector: sui-modal
+resumen: Diálogo que se abre encima de la pantalla y pide terminar o cerrar algo antes de seguir
+alternativas: [sui-modal-sheet (hoja que sube desde abajo y deja ver lo de atrás, p. ej. un mapa), sui-alert (aviso en la misma pantalla, sin interrumpir), sui-toast (confirmación breve de una acción), sui-popover (contenido chico anclado a un botón), sui-drawer-header (panel lateral)]
+---
+
+# sui-modal
+
+Story: [Organisms/Modal/Modal](https://sui-design-system.web.app/?path=/docs/organisms-modal-modal--docs)
+
+## Cuándo usarlo / cuándo no
+
+**Úsalo** cuando la persona tiene que **hacer o decidir algo antes de volver** a la pantalla:
+llenar un formulario corto (crear un descuento, editar sus datos), confirmar algo que no se
+deshace (eliminar, cancelar un pedido), ver un detalle que no merece pantalla propia (un
+comprobante, el detalle de un pedido).
+
+**No lo uses** para:
+
+- Contenido que tiene que convivir con lo de atrás (un mapa que se sigue moviendo, el
+  seguimiento de un pedido): eso es `sui-modal-sheet`.
+- Avisar algo sin pedir respuesta: `sui-alert` en la pantalla, o `sui-toast` si es la
+  confirmación de un clic.
+- Un flujo de varios pasos o un formulario largo: merece su propia ruta.
+- Modal sobre modal. El componente lo soporta (bloqueo de scroll y barra inferior se cuentan
+  por instancia), pero dos capas de backdrop confunden: cierra el primero o cambia su contenido.
+
+Regla corta: **hay que responder → modal · se mira junto al fondo → sheet · solo se avisa → alert/toast.**
+
+## Qué variante usar
+
+El modal tiene tres decisiones: **cómo se presenta en mobile** (`fullscreen`), **qué tan ancho
+es en desktop** (`size`) y **qué cabecera lleva** (`iconVariant` / `headerIcon` /
+`statusAlignment`). Las tres se eligen por separado.
+
+> **La guía del DS dibuja la anatomía pero no dice cuándo usar cada cosa.** El Figma del DS
+> trae el header (nodo 466:4778, tipos Basic / Left Icon / Error / Warning / Success / Info en
+> tamaños Small 56 y Medium 80), el footer (472:566), los Status Modals (480:1372) y el overlay
+> (480:2474). No trae do/don't. Lo marcado **canon** sale de `master-pedidos/CLAUDE.md` y
+> `docs/CANON-SUI.md`; lo marcado **propuesta** falta aprobar.
+>
+> Uso medido el 03-10-2026 en `master-pedidos/src/app`: 128 modales, sin contar prototipos ni
+> vitrinas (`master-preview`, `master-prototipos`, `mockup-sheets-*`, `dx/*`, `master-rutina`,
+> `master-medico`, `dev-index`), las copias locales de `components/sui/` ni los `.spec.ts`.
+
+### Lo que sí dice la guía del DS
+
+- **Contenedor**: fondo blanco, borde `stroke-soft-200`, radio 20 y sombra media. El overlay es
+  gris al 24 %; el **blur de 10 px es extensión de SUI** (se quita con `[backdropBlur]="false"`).
+- **Anchos**: `small` 400 · `medium` 440 · `large` 560 · `xlarge` 720 px.
+- **Header Small (56)** = solo título; **Medium (80)** = título + descripción. El modal elige
+  solo: con `description` va Medium, sin ella Small.
+- **Body** con 20 px de padding y 20 px entre bloques.
+- **Status Modal**: icono en un recuadro y texto centrados (vertical) o en fila (horizontal),
+  sin header. En SUI es `statusAlignment`.
+
+### `fullscreen` — cómo se presenta en mobile (lo que más cambió)
+
+`fullscreen` **solo actúa en pantallas de 768 px o menos**; en desktop el modal sigue centrado
+con su `size`. Desde el paquete **0.21.0 el default es `'auto'`**: dentro de la app nativa
+(clase `platform-ios` / `platform-android` en `<html>`) va a pantalla completa, y en el
+navegador del teléfono queda centrado.
+
+| valor | qué hace | cuándo | fuente |
+|---|---|---|---|
+| sin poner (`'auto'`) | pantalla completa en la app, centrado en la web móvil | todo modal de contenido: formularios, detalles, selección | propuesta (reemplaza el `[fullscreen]="true"` a mano) |
+| `[fullscreen]="true"` | pantalla completa también en la web móvil | lo que hoy hace toda la app por regla; con `'auto'` solo cambia la web móvil | canon (CLAUDE.md, 2026-07-26), **a revisar** con el `'auto'` |
+| `[fullscreen]="false"` | siempre centrado | **confirmación de una línea con dos botones** («¿Cancelar pedido?»): ocupar toda la pantalla para un sí/no la hace parecer más grande de lo que es | canon (CLAUDE.md y CANON-SUI §6.5) |
+
+Hoy: 95 con `true`, 32 sin el atributo, 1 con `false` (`pages/driver/driver-order-detail/driver-order-detail.html:986`).
+
+**Usos de hoy que rompen el canon** (no tienen `[fullscreen]="false"`, así que con el `'auto'`
+de 0.21.0 se abren **a pantalla completa** dentro de la app):
+
+- `components/confirm-dialog/confirm-dialog.html:1` — el diálogo genérico que abre
+  `SuiConfirmService.confirm()`. Arreglarlo aquí arregla todas sus llamadas.
+- Sí/no sin campos: `pages/driver/driver-order-detail/driver-order-detail.html:771` («¿Recibiste
+  el efectivo?») y `:857` («¿Liberar este pedido?»), `pages/central/central-inicio/central-inicio.html:140`,
+  `pages/central/central-locales/central-locales.html:76`, `pages/super-admin/master-gastos/master-gastos.html:279`,
+  `pages/super-admin/master-drivers/master-drivers.html:619`, `pages/super-admin/master-orders/master-orders.html:766`,
+  `pages/mi-negocio/mi-negocio.html:1248`, `pages/customer/restaurant-menu/restaurant-menu.html:487`,
+  `pages/customer/order-tracking/order-tracking.html:756`.
+- Las confirmaciones **con un campo de motivo** (`sui-textarea`) sí van mejor a pantalla
+  completa por el teclado: `pages/customer/order-tracking/order-tracking.html:774`,
+  `pages/central/central-gastos/central-gastos.html:128`, los «Rechazar…» y «Suspender» de
+  `pages/super-admin/super-admin.html`. Ahí el `'auto'` acierta.
+
+### `size` — el ancho en desktop
+
+En mobile **no se usa**: a 768 px o menos el contenedor toma `max-width: 100%` (centrado) o la
+pantalla entera (fullscreen). Elegirlo es una decisión de desktop.
+
+| size | cuándo | ejemplo real de la app | fuente |
+|---|---|---|---|
+| `small` (400) | confirmación o aviso: título, una o dos frases y los botones | `pages/customer/order-tracking/order-tracking.html:756` | propuesta |
+| `medium` (440, default) | formulario corto (hasta ~5 campos) o un detalle simple | `pages/discounts/discounts.html:122` («Crear descuento») | propuesta |
+| `large` (560) | detalle con tabla o imagen: comprobantes, el detalle de un pedido | `pages/orders/orders.html:146` · `pages/super-admin/master-drivers/master-drivers.html:685` | propuesta |
+| `xlarge` (720) | mapa, formularios de dos columnas, listas largas de opciones | `components/address-picker-modal/address-picker-modal.html:1` · `pages/customer/checkout/checkout.html:1` | propuesta |
+
+Hoy: 45 `small`, 63 `medium` (50 explícitos + 13 por default), 5 `large`, 14 `xlarge` y 1 que cambia según el caso.
+
+### Cabecera — `iconVariant`, `headerIcon`, `statusAlignment`
+
+| input | qué dibuja | cuándo | fuente |
+|---|---|---|---|
+| ninguno (Basic) | solo título (+ descripción) y la X | el caso normal: un formulario o un detalle | propuesta |
+| `iconVariant` | círculo de color con el ícono del estado (`info`, `success`, `warning`, `error`) | el modal **es** un aviso de ese tipo: «Eliminar usuario» (`error`), «Estás a punto de cambiar de local» (`warning`) | propuesta |
+| `headerIcon` | círculo gris con un ícono propio (Remix) | identifica **qué se está editando**: `edit-line`, `user-add-line`, `time-line`. Gana sobre `iconVariant` | propuesta |
+| `statusAlignment` | quita el header y pone ícono + texto dentro del body (`vertical` centrado, `horizontal` en fila) | pantallas de resultado («Pedido enviado») o confirmaciones con más peso visual. Requiere `iconVariant` o `headerIcon`. 0 usos hoy | según el Figma del DS (Status Modals) |
+
+**Usos de hoy que rompen el copy canon** (CANON-SUI: títulos en sentence case):
+`pages/super-admin/super-admin.html:353` «Suspender Negocio», `:471` «Evidencia de Pago»,
+`:487` «Rechazar Solicitud», `:557` «Rechazar Promoción».
+
+### Cerrar
+
+| input | default | cuándo cambiarlo | fuente |
+|---|---|---|---|
+| `closeOnBackdrop` | `true` | `false` si el modal tiene un formulario a medio llenar o una operación en curso (`[closeOnBackdrop]="!guardando()"`): un toque fuera no debe tirar lo escrito. Hoy 42 en `false` y 5 dinámicos | propuesta |
+| `showClose` | `true` | `false` solo cuando la persona **tiene** que elegir un botón (actualización obligatoria, oferta de pedido al repartidor). Hoy 8 | propuesta |
+| `closeOnEscape` | `true` | casi nunca: es la salida por teclado en desktop | propuesta |
+
+### `fullBody` — contenido a sangre
+
+Quita los 20 px del body para mapas o imágenes de borde a borde. Hoy 12 usos
+(`components/map-picker-modal/map-picker-modal.html:1`, el comprobante de
+`pages/driver/driver-order-detail/driver-order-detail.html:1091`). Con `fullBody` el espaciado
+interno lo pone quien proyecta. Canon (CLAUDE.md, 2026-07-21).
+
+## Tamaño en mobile y en web
+
+| | mobile app (≤ 768 px) | web móvil (≤ 768 px) | web desktop | fuente |
+|---|---|---|---|---|
+| presentación | pantalla completa flotante (8 px de margen) | centrado, ancho completo menos 16 px | centrado | componente |
+| `size` | no aplica | no aplica | el de la tabla de arriba | componente |
+| alto máximo | toda la pantalla menos safe-areas | **la mitad de la pantalla** (`50dvh − 16px`); el body scrollea | `100dvh − 32px` | componente |
+| esquinas | iOS 36 arriba / 54 abajo (concéntrico con el display) · Android 20 | 20 | 20 | canon (CLAUDE.md, 2026-07-22) |
+| botones del footer | `large` (48) | `large` (48) | `large` (48) | canon (ver `sui-modal-footer`) |
+
+El modal **no tiene un size para mobile**: la decisión de mobile es `fullscreen`.
+
+## API
+
+<!-- api:inicio -->
+<!-- generada: no editar a mano — `npm run docs` -->
+
+| input | tipo | default |
+|---|---|---|
+| `open` · model, `[(open)]` | `boolean` | `false` |
+| `size` | `'small' \| 'medium' \| 'large' \| 'xlarge'` | `'medium'` |
+| `title` | `string \| null` | `null` |
+| `description` | `string \| null` | `null` |
+| `closeOnBackdrop` | `boolean` | `true` |
+| `closeOnEscape` | `boolean` | `true` |
+| `showClose` | `boolean` | `true` |
+| `iconVariant` | `'info' \| 'success' \| 'warning' \| 'error' \| null` | `null` |
+| `headerIcon` | `string \| null` | `null` |
+| `statusAlignment` | `'horizontal' \| 'vertical' \| null` | `null` |
+| `backdropBlur` | `boolean` | `true` |
+| `fullscreen` | `boolean \| 'auto'` | `'auto'` |
+| `fullBody` | `boolean` | `false` |
+
+| output | payload |
+|---|---|
+| `closed` | `void` |
+<!-- api:fin -->
+
+Slots: el contenido sin atributo va al **body**; `slot="footer"` va al pie. El pie canon es
+`<sui-modal-footer slot="footer">` (trae su propio padding y borde); un `<div slot="footer">`
+también funciona y recibe padding 16 × 20, gap 12 y alineación a la derecha.
+
+Método público: `close()`. Signal pública: `scrollActive` (el body tiene más contenido abajo;
+pinta una sombra sobre el footer).
+
+## Trampas
+
+- **`slot="footer"` no es opcional.** Sin él, el `sui-modal-footer` se proyecta **dentro del
+  body**: queda con doble padding y scrollea con el contenido.
+- **El padding del body es fuente única** (canon, CLAUDE.md 2026-07-21): 20 px. No lo pises con
+  `::ng-deep .sui-modal__body` ni le pongas padding lateral o inferior a tus secciones: se
+  suman y queda margen doble.
+- **En la web móvil el modal mide como mucho media pantalla.** Si el contenido es largo, el
+  body scrollea dentro de ese 50 %. Si eso estorba, `[fullscreen]="true"`.
+- **El `'auto'` se decide al nacer el modal**, leyendo la clase de plataforma de `<html>`. Si
+  la app pone `platform-ios` / `platform-android` tarde, los modales creados antes quedan
+  centrados.
+- **La app esconde la barra inferior mirando la clase `.sui-modal__container--fullscreen`**
+  (`UiOverlayService.SELECTOR_FULLSCREEN` en master-pedidos). Si se renombra aquí, los botones
+  del footer vuelven a quedar debajo del tab bar nativo de iOS y dejan de responder.
+- El modal también pide ocultar la barra por el token `SUI_NAVBAR_VISIBILITY` (si la app lo
+  provee), con un contador por instancia: dos modales abiertos no se pisan.
+- **Teclado**: en iOS el modal fullscreen resta `--sui-keyboard-h` de su alto; en Android no,
+  porque el `dvh` ya se achica solo. Restarlo también en Android deja una franja gris (canon,
+  CLAUDE.md). El input enfocado se centra con `scrollIntoView` en las dos.
+- **`headerIcon` gana sobre `iconVariant`** y pinta el círculo en gris. Para un aviso de color,
+  solo `iconVariant`.
+- `statusAlignment` sin `iconVariant` ni `headerIcon` no hace nada: vuelve el header normal.
+- Sin `title` y con `[showClose]="false"` no hay header: el body arranca arriba del todo. Así lo usan los modales de permisos y ubicación (`components/location-flow-outlet/location-flow-outlet.html:4`).
+- El host borra el atributo `title` nativo (sin tooltip gris del navegador).
+- `(closed)` se emite **después** de cerrar, por cualquier vía (X, backdrop, Escape o
+  `open = false`). Para limpiar estado, escúchalo ahí y no en el botón.
+
+## Ejemplo
+
+```html
+<!-- Formulario: fullscreen automático en la app, medium en desktop -->
+<sui-modal
+  [(open)]="creando"
+  title="Crear descuento"
+  headerIcon="add-circle-line"
+  [closeOnBackdrop]="!guardando()">
+  <sui-input label="Nombre" [(value)]="nombre" />
+  <sui-modal-footer
+    slot="footer"
+    [stretch]="true"
+    secondaryButton="Cancelar"
+    [primaryButton]="{ label: 'Crear descuento', disabled: !valido() }"
+    (secondaryClick)="creando.set(false)"
+    (primaryClick)="guardar()" />
+</sui-modal>
+
+<!-- Confirmación de una línea: siempre centrada -->
+<sui-modal
+  [(open)]="confirmando"
+  size="small"
+  [fullscreen]="false"
+  iconVariant="error"
+  title="¿Eliminar este gasto?"
+  description="Se borra del reporte del mes.">
+  <sui-modal-footer
+    slot="footer"
+    secondaryButton="Cancelar"
+    [primaryButton]="{ label: 'Eliminar', color: 'error' }"
+    (secondaryClick)="confirmando.set(false)"
+    (primaryClick)="eliminar()" />
+</sui-modal>
+```

package/docs/sui-modal-footer/README.md

@@ -0,0 +1,178 @@
+---
+name: sui-modal-footer
+selector: sui-modal-footer
+resumen: Pie de modal con la acción principal a la derecha, la secundaria a su izquierda y un slot izquierdo para un checkbox, un link o un texto
+alternativas: [sui-button (botones sueltos fuera de un modal o una hoja), sui-drawer-footer (pie de un panel lateral), sui-notification-footer (acciones de una notificación)]
+---
+
+# sui-modal-footer
+
+Story: [Organisms/Modal/Modal Footer](https://sui-design-system.web.app/?path=/docs/organisms-modal-modal-footer--docs)
+
+## Cuándo usarlo / cuándo no
+
+**Úsalo** en todo `sui-modal` que tenga botones, siempre con `slot="footer"`, y al pie de una
+`sui-modal-sheet` cuando la hoja termina en una acción. Es la pieza que fija el **orden y el
+peso de los botones** de toda la app: no solo de los modales.
+
+**No lo uses** para:
+
+- Una fila de botones en medio de una pantalla: ahí van `sui-button` sueltos, pero con **el
+  mismo orden** (secundario a la izquierda, primario a la derecha, gap 12).
+- Más de dos botones: no existe un tercero (ver abajo).
+- Proyectar tus propios `sui-button` adentro: el contenido proyectado cae en el slot
+  **izquierdo**, no reemplaza a los botones.
+
+## Qué variante usar
+
+> **La guía del DS dibuja los tipos pero no dice cuándo usar cada uno.** El Figma del DS
+> (nodo 472:566) trae siete tipos: Basic, Checkbox, Information, Toggle, Stepper, Link Button y
+> Stretch. SUI no los tipa: los botones van por `primaryButton` / `secondaryButton` y el resto
+> se proyecta en el slot izquierdo. Las reglas de orden y peso son **canon** (CLAUDE.md
+> «Botones — composición y orden», 2026-07-27); lo demás es **propuesta**.
+>
+> Uso medido el 03-10-2026 en `master-pedidos/src/app`: 121 footers, sin contar prototipos ni
+> vitrinas (`master-preview`, `master-prototipos`, `mockup-sheets-*`, `dx/*`, `master-rutina`,
+> `master-medico`, `dev-index`), las copias de `components/sui/` ni los `.spec.ts`.
+
+### Lo que sí dice la guía del DS
+
+- Pie con fondo blanco, **borde arriba** y padding 16 × 20.
+- Acciones a la **derecha**, separadas por 12 px.
+- El tipo **Stretch** reparte los botones a lo ancho.
+- El lado izquierdo lleva, según el tipo, un checkbox con label, un switch con label, un texto
+  informativo, un stepper o un link.
+- Dibuja los botones en `small` (36). **SUI los sube a `large` (48)**: ver tamaño.
+
+### Cuántas acciones
+
+| acciones | cómo | ejemplo real de la app | fuente |
+|---|---|---|---|
+| **1** | solo `primaryButton`. Queda a la derecha, no a todo el ancho (para eso, `[stretch]="true"`) | `pages/super-admin/master-sonidos-push/master-sonidos-push.html:146` («Cerrar») | canon (CLAUDE.md) |
+| **2** | `secondaryButton` + `primaryButton`. El componente los pone en orden: secundario a la izquierda | `pages/driver/driver-dashboard/driver-dashboard.html:1574` («Cancelar» / «Enviar») | canon (CLAUDE.md) |
+| **3+** | **no hay tercer botón.** La tercera acción va como `sui-link-button` en el slot izquierdo | `components/add-product-modal/add-product-modal.html:332` («Vista previa») | canon (CLAUDE.md) |
+
+### El slot izquierdo
+
+| qué va | cuándo | ejemplo real de la app | fuente |
+|---|---|---|---|
+| `sui-link-button` | la tercera acción, de menos peso | `pages/central/central-gastos/central-gastos.html:97` | canon (CLAUDE.md) |
+| `sui-checkbox-label` / `sui-switch-label` | una opción que acompaña la confirmación («No volver a preguntar») | (sin uso hoy) | según el Figma del DS |
+| texto | un dato que se lee antes de confirmar («Llega a las 8:30») | `components/add-product-modal/add-product-modal.html:359` | según el Figma del DS |
+| `sui-counter-input` (stepper) | elegir cantidad junto al botón de agregar | `pages/customer/restaurant-menu/restaurant-menu.html:461` | según el Figma del DS |
+
+Con `stretch` y algo en el slot izquierdo, se reparte 50 % slot / 50 % botones.
+
+### El color de los botones
+
+| botón | variante | regla | fuente |
+|---|---|---|---|
+| secundario | `stroke` `neutral`, **fijo** | no se configura: `SuiFooterButtonConfig.color` solo lo lee el primario | canon (CLAUDE.md) |
+| primario | `filled` `primary` | la acción que termina el flujo | canon (CLAUDE.md) |
+| primario destructivo | `filled` con `color: 'error'` | eliminar, cancelar un pedido, rechazar. **El destructivo va siempre en el primario**, a la derecha. Hoy 28 | canon (CLAUDE.md) |
+
+### `stretch`
+
+| valor | cuándo | fuente |
+|---|---|---|
+| `true` | en el modal a pantalla completa de mobile: botones a lo ancho, 50/50 | canon (CANON-SUI §6.3) |
+| `false` (default) | modal centrado en desktop: botones a la derecha, del ancho de su texto | según el Figma del DS (tipo Basic) |
+
+El componente **no tiene `@media`**: `stretch` se ve igual en las dos plataformas. Hoy 95 de 121
+lo pasan fijo en `true`, así que también en desktop los botones van 50/50. Propuesta:
+`[stretch]="bp.isMobile()"` para que desktop vuelva al tipo Basic.
+
+**Usos de hoy que rompen el canon:**
+
+- **3 footers con un solo botón en `secondaryButton`** → pasarlo a `primaryButton`:
+  `pages/driver/driver-dashboard/driver-dashboard.html:1272`, `:1419` y `:1555` (los tres
+  «Cerrar»). Contraargumento a decidir: en un modal que solo informa, un «Cerrar» relleno de
+  naranja grita más que el contenido; si se prefiere así, hay que escribirlo como excepción.
+- **1 pie hecho a mano** con dos `sui-button` en un `<div slot="footer">` →
+  `sui-modal-footer`: `components/copy-text-dialog/copy-text-dialog.html:15`.
+- Botones `sui-button` proyectados dentro del footer: 0.
+
+## Tamaño en mobile y en web
+
+| uso | mobile | web | fuente |
+|---|---|---|---|
+| botones | `large` (48) | `large` (48) | canon (CLAUDE.md, decisión de marca 2026-07-23; el Figma dibuja `small`) |
+| reparto | `[stretch]="true"`, 50/50 | botones a la derecha | canon en mobile (CANON-SUI §6.3), propuesta en web |
+| borde de arriba | sin borde en el modal a pantalla completa | con borde | componente (`sui-modal.scss`) |
+
+`buttonSize` existe para un caso puntual, no para «achicar porque se ve grande». Hoy 0 usos.
+
+`CANON-SUI.md` §6.3 todavía dice «botones `small`»: quedó viejo frente a la decisión del
+2026-07-23 y al default del componente.
+
+## API
+
+<!-- api:inicio -->
+<!-- generada: no editar a mano — `npm run docs` -->
+
+| input | tipo | default |
+|---|---|---|
+| `primaryButton` | `SuiFooterButtonConfig \| string \| null` | `null` |
+| `secondaryButton` | `SuiFooterButtonConfig \| string \| null` | `null` |
+| `stretch` | `boolean` | `false` |
+| `buttonSize` | `'2xsmall' \| 'xsmall' \| 'small' \| 'medium' \| 'large' \| 'xlarge' \| null` | `null` |
+
+| output | payload |
+|---|---|
+| `primaryClick` | `void` |
+| `secondaryClick` | `void` |
+<!-- api:fin -->
+
+```ts
+// Exportada desde sui-button
+interface SuiFooterButtonConfig {
+  label: string;
+  disabled?: boolean;
+  color?: 'primary' | 'error'; // solo lo lee el primario
+}
+```
+
+Un `string` es atajo de `{ label }`. `null`, `''` o un config con `label` vacío no dibuja el
+botón. `buttonSize` en `null` resuelve a `large`.
+
+Slot: `<ng-content>` sin selector → el bloque **izquierdo**.
+
+## Trampas
+
+- **Dentro de `sui-modal` lleva `slot="footer"`.** Sin él se proyecta dentro del body: doble
+  padding y scrollea con el contenido. En `sui-modal-sheet` no hay slot de footer: va al final
+  del contenido, sin `slot` (`pages/customer/checkout/checkout.html:490`).
+- **Lo que proyectas va a la izquierda.** Dos `sui-button` adentro quedan a la izquierda de los
+  botones del componente, con su propio tamaño y sin el orden canon.
+- **No hay `loading`.** Para «guardando», cambia el label y deshabilita:
+  `{ label: enviando() ? 'Enviando…' : 'Enviar', disabled: enviando() }`.
+- **`color` en el secundario no hace nada**: siempre sale `stroke neutral`. Un «Eliminar»
+  rojo a la izquierda no se puede armar, y es a propósito.
+- **`stretch` no cambia el orden**: el primario sigue a la derecha, nunca arriba.
+- Los botones son `type="button"`: el footer **no envía un `<form>`**. Llama al guardado en
+  `(primaryClick)`.
+- Dentro de `sui-modal` el footer recibe una sombra arriba mientras el body tiene más contenido
+  para scrollear (`scrollActive`).
+
+## Ejemplo
+
+```html
+<!-- 2 acciones, destructiva -->
+<sui-modal-footer
+  slot="footer"
+  secondaryButton="Cancelar"
+  [primaryButton]="{ label: 'Eliminar', color: 'error' }"
+  (secondaryClick)="cerrar()"
+  (primaryClick)="borrar()" />
+
+<!-- 3 acciones: la tercera es un link en el slot izquierdo -->
+<sui-modal-footer
+  slot="footer"
+  [stretch]="true"
+  secondaryButton="Cancelar"
+  [primaryButton]="{ label: guardando() ? 'Guardando…' : 'Guardar', disabled: guardando() }"
+  (secondaryClick)="cerrar()"
+  (primaryClick)="guardar()">
+  <sui-link-button leftIcon="eye-line" (clicked)="verPrevia()">Vista previa</sui-link-button>
+</sui-modal-footer>
+```

package/docs/sui-modal-header/README.md

@@ -0,0 +1,115 @@
+---
+name: sui-modal-header
+selector: sui-modal-header
+resumen: Cabecera de modal con título, descripción, ícono opcional y la X de cerrar; sui-modal ya la dibuja sola
+alternativas: [sui-modal (ya trae este header por title/description/iconVariant), sui-drawer-header (cabecera de un panel lateral), sui-page-header (título de una pantalla)]
+---
+
+# sui-modal-header
+
+Story: [Organisms/Modal/Modal Header](https://sui-design-system.web.app/?path=/docs/organisms-modal-modal-header--docs)
+
+## Cuándo usarlo / cuándo no
+
+**No lo uses dentro de `sui-modal`.** El modal ya lo dibuja con sus inputs `title`,
+`description`, `iconVariant`, `headerIcon` y `showClose`, y elige el tamaño solo. Ponerlo a mano
+en el body da **dos cabeceras**.
+
+**Úsalo** solo para armar un panel o una superficie propia que tiene que verse como un modal y
+no puede ser `sui-modal`: un panel fijo en desktop, un overlay propio. Es el par de
+`sui-modal-footer` para esos casos.
+
+Uso medido el 03-10-2026 en `master-pedidos/src/app`: **0 usos directos**. Los 128 modales de
+la app lo usan a través de `sui-modal`.
+
+## Qué variante usar
+
+> **La guía del DS dibuja los tipos pero no dice cuándo usar cada uno.** El Figma del DS
+> (nodo 466:4778) trae seis tipos —Basic, Left Icon, Error, Warning, Success, Information— en dos
+> tamaños, Small (56) y Medium (80). Lo marcado **propuesta** falta aprobar.
+
+### Lo que sí dice la guía del DS
+
+- **Medium (80 px de alto mínimo)**: título + descripción. El ícono va en un círculo de 20 px.
+- **Small (56)**: solo título. El ícono va **plano, de 24 px, sin círculo**.
+- Título en Label/Small (14/500), descripción en Paragraph/X-Small (12/400) gris.
+- Borde abajo, padding 16 / 20 y la X de cerrar arriba a la derecha.
+
+### `size`
+
+| size | cuándo | fuente |
+|---|---|---|
+| `medium` (default) | hay `description` | según el Figma del DS |
+| `small` | solo título | según el Figma del DS |
+
+Es la misma regla que aplica `sui-modal`: `[size]="description ? 'medium' : 'small'"`. El
+componente **no la aplica solo**: si lo usas suelto, elige tú.
+
+### Ícono
+
+| input | qué dibuja | cuándo | fuente |
+|---|---|---|---|
+| ninguno | Basic: solo texto | el caso normal | según el Figma del DS |
+| `iconVariant` | ícono del estado en un círculo de su color | el panel **es** un aviso de error, advertencia, éxito o información | propuesta |
+| `icon` | ícono propio (Remix) en un círculo gris | identifica qué se edita (`edit-line`, `user-add-line`). Gana sobre `iconVariant` | propuesta |
+
+## Tamaño en mobile y en web
+
+El `size` de este componente **no es de plataforma**: lo decide si hay descripción. Es igual en
+mobile y en web. La X mide 24 px en las dos (`sui-compact-button` `large`).
+
+| uso | mobile | web | fuente |
+|---|---|---|---|
+| con descripción | `medium` | `medium` | según el Figma del DS |
+| solo título | `small` | `small` | según el Figma del DS |
+
+## API
+
+<!-- api:inicio -->
+<!-- generada: no editar a mano — `npm run docs` -->
+
+| input | tipo | default |
+|---|---|---|
+| `title` | `string` | `''` |
+| `description` | `string \| null` | `null` |
+| `size` | `'medium' \| 'small'` | `'medium'` |
+| `iconVariant` | `'info' \| 'success' \| 'warning' \| 'error' \| null` | `null` |
+| `icon` | `string \| null` | `null` |
+| `showClose` | `boolean` | `true` |
+| `titleId` | `string \| null` | `null` |
+| `descriptionId` | `string \| null` | `null` |
+
+| output | payload |
+|---|---|
+| `closed` | `void` |
+<!-- api:fin -->
+
+`titleId` y `descriptionId` ponen el `id` al `<h2>` y al `<p>`: sirven para el
+`aria-labelledby` / `aria-describedby` del contenedor que hace de diálogo.
+
+## Trampas
+
+- **Los nombres no coinciden con `sui-modal`**: aquí el ícono propio es `icon`; en el modal es
+  `headerIcon`. `iconVariant` sí se llama igual.
+- **`size` no se ajusta solo** a la descripción (en `sui-modal` sí). Con `description` y
+  `size="small"` la descripción se ve igual, pero el ícono pasa a plano de 24.
+- **`closed` no cierra nada**: solo avisa que se tocó la X. Cerrar el panel es tuyo.
+- Sin `titleId`, el contenedor no tiene nombre accesible: si haces un diálogo, pásalo y úsalo
+  en `aria-labelledby`.
+- El host borra el atributo `title` nativo (sin tooltip gris del navegador).
+
+## Ejemplo
+
+```html
+<!-- Panel propio con la cabecera de modal -->
+<section class="panel" role="dialog" aria-labelledby="filtros-titulo">
+  <sui-modal-header
+    size="small"
+    title="Filtros"
+    titleId="filtros-titulo"
+    (closed)="cerrarPanel()" />
+  …
+  <sui-modal-footer secondaryButton="Limpiar" primaryButton="Aplicar"
+    (secondaryClick)="limpiar()" (primaryClick)="aplicar()" />
+</section>
+```