@ajuarezso/sui-stencil 0.0.0-stage → 0.1.0

package/docs/sui-modal/README.md

@@ -0,0 +1,368 @@
+---
+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 (solo en el celular: 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
+
+<!-- generado por scripts/gen-docs.mjs — no editar a mano; `npm run docs` -->
+
+> **De dónde sale este doc.** El criterio es el del SUI Angular (`sui-modal`); la API es la de este
+> paquete, leída del código. Los ejemplos se pasaron de Angular de forma mecánica: lo literal va como
+> atributo (`only-icon`, `size="large"`), lo dinámico entre llaves (`size={expr}` → `el.size = expr`)
+> y los eventos como `onValueChange={…}` → `el.addEventListener('valueChange', …)`. `@if`, `@for` y
+> `<ng-template>` quedan como en Angular: se leen como pseudocódigo.
+>
+> **La API de aquí no es igual a la de Angular.** Lo que el texto nombre y figure en «Diferencias con
+> el SUI Angular» (dentro de API) aquí no existe.
+
+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.**
+
+## Celular, tablet y computadora: modal u hoja
+
+Canon (decisión del dueño, 08-10-2026). La superficie depende del **dispositivo**, y el ancho del
+modal depende de **cuánto contenido** hay:
+
+| dispositivo | contenido para mirar o elegir (listas, grillas, detalles) | formularios y confirmaciones |
+|---|---|---|
+| celular (≤ 768 px) | `sui-modal-sheet` | `sui-modal` (a pantalla completa en la app) |
+| tablet y computadora (> 768 px) | **`sui-modal` centrado, nunca una hoja** | `sui-modal` centrado |
+
+En tablet y computadora el ancho sale de la cantidad de contenido:
+
+- **mucho contenido** (una grilla, una lista larga, más de una pantalla de opciones): el más ancho,
+  `xlarge`;
+- **poco contenido** (unas frases, un formulario corto): `small` o `medium`;
+- entre medio, `large`. La tabla de `size` de abajo tiene los casos.
+
+Cuando el mismo contenido se abre en los dos, va en un `ng-template` y se elige la superficie con
+el breakpoint de la app:
+
+```html
+<ng-template #contenido> … </ng-template>
+
+@if (bp.isMobile()) {
+  <sui-modal-sheet open={abierta()} onClosed={() => abierta.set(false)}>
+    <ng-container *ngTemplateOutlet="contenido" />
+  </sui-modal-sheet>
+} @else {
+  <sui-modal open={abierta()} size="xlarge" title="Categorías" onClosed={() => abierta.set(false)}>
+    <ng-container *ngTemplateOutlet="contenido" />
+  </sui-modal>
+}
+```
+
+Ejemplo real: «Ver todo» de las categorías del inicio del cliente
+(`pages/customer/store-browser/store-browser.html`), con más de 30 rubros en `xlarge`.
+
+## 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` o de la aprobación del dueño del 05-10-2026; 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 `backdrop-blur="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` a mano) |
+| `fullscreen` | 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, y la regla es **cuánto
+contenido hay**: mucho → el más ancho; poco → el más angosto que lo contenga sin apretarlo.
+
+| 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` | canon (aprobado por el dueño, 05-10-2026, bloque B1) |
+| `medium` (440, default) | formulario corto (hasta ~5 campos) o un detalle simple | `pages/discounts/discounts.html:122` («Crear descuento») | canon (aprobado por el dueño, 05-10-2026, bloque B1) |
+| `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` | canon (aprobado por el dueño, 05-10-2026, bloque B1) |
+| `xlarge` (720) | **mucho contenido**: mapa, formularios de dos columnas, listas largas o grillas de opciones | `components/address-picker-modal/address-picker-modal.html:1` · `pages/customer/checkout/checkout.html:1` · Categorías del inicio (`pages/customer/store-browser/store-browser.html`) | canon (aprobado por el dueño, 05-10-2026, bloque B1; «mucho contenido → el más ancho», 08-10-2026) |
+
+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 | canon (aprobado por el dueño, 05-10-2026, bloque B2) |
+| `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`) | canon (aprobado por el dueño, 05-10-2026, bloque B2) |
+| `headerIcon` | círculo gris con un ícono propio (Remix) | identifica **qué se está editando**: `edit-line`, `user-add-line`, `time-line`. Gana sobre `iconVariant` | canon (aprobado por el dueño, 05-10-2026, bloque B2) |
+| `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:364` «Suspender Negocio», `:484` «Evidencia de Pago»,
+`:501` «Rechazar Solicitud», `:572` «Rechazar Promoción» (líneas al 06-10-2026).
+
+### 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 | canon (aprobado por el dueño, 05-10-2026, bloque B8) |
+| `showClose` | `true` | `false` solo cuando la persona **tiene** que elegir un botón (actualización obligatoria, oferta de pedido al repartidor). Hoy 8 | canon (aprobado por el dueño, 05-10-2026, bloque B8) |
+| `closeOnEscape` | `true` | `false` solo junto con `showClose` `false`, o mientras corre una operación; el resto, `true`: es la salida por teclado en desktop | canon (aprobado por el dueño, 05-10-2026, bloque B13) |
+
+### `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`.
+
+### Por dispositivo (D16)
+
+No aplica: `size` es el **ancho del modal centrado** y lo elige el contenido (tabla de arriba), no
+el dispositivo; a 768 px o menos ni se usa, porque el modal toma el ancho completo (centrado o
+fullscreen). En la tablet de 820 o 1024 px el modal se ve centrado con su `size`, igual que en la
+computadora y el ultrawide. Lo que se toca adentro lleva su propio D16: el pie va `large` en todos
+los dispositivos (D2) y los campos del body siguen la fila de `input`.
+
+En master-pedidos: sin helper para el modal; `<sui-modal-footer>` sin `buttonSize` (ya es
+`large`) y los campos del body con `size={bp.sizeControl()}`.
+
+## API
+
+<!-- api:inicio -->
+<!-- generada: no editar a mano — `npm run docs` -->
+
+| prop | atributo | tipo | default |
+|---|---|---|---|
+| `backdropBlur` | `backdrop-blur` | `boolean` | `true` |
+| `closeOnBackdrop` | `close-on-backdrop` | `boolean` | `true` |
+| `closeOnEscape` | `close-on-escape` | `boolean` | `true` |
+| `description` | `description` | `null \| string` | `null` |
+| `fullBody` | `full-body` | `boolean` | `false` |
+| `fullscreen` | `fullscreen` | `"" \| "auto" \| "false" \| "true" \| boolean` | `'auto'` |
+| `headerIcon` | `header-icon` | `null \| string` | `null` |
+| `heading` | `heading` | `null \| string` | `null` |
+| `iconVariant` | `icon-variant` | `"error" \| "info" \| "success" \| "warning" \| null` | `null` |
+| `open` | `open` | `boolean` | `false` |
+| `showClose` | `show-close` | `boolean` | `true` |
+| `size` | `size` | `"large" \| "medium" \| "small" \| "xlarge"` | `'medium'` |
+| `statusAlignment` | `status-alignment` | `"horizontal" \| "vertical" \| null` | `null` |
+
+| evento | `event.detail` |
+|---|---|
+| `closed` | `void` |
+| `openChange` | `boolean` |
+
+| método | firma |
+|---|---|
+| `close` | `close() => Promise<void>` |
+
+Slots: `footer`, `(por defecto)`.
+
+### Diferencias con el SUI Angular
+
+- **Props de Angular que aquí no existen:** `title`
+- **Props solo de aquí:** `heading`
+<!-- api:fin -->
+
+<!-- textos:inicio -->
+### Textos
+
+Lo que el componente escribe solo sale de `provideSuiTextos` (español por defecto, se cambia en vivo; ver `docs/TEXTOS.md`). El input de la última columna le gana al texto global.
+
+| clave | por defecto | se pisa con |
+|---|---|---|
+| `comun.cerrar` | Cerrar | — |
+<!-- textos: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`.
+- **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 `show-close="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.
+
+## Bien y mal
+
+Confirmación de sí o no
+
+```html
+<!-- ❌ mal: sin fullscreen="false", el 'auto' lo abre a pantalla completa en la app (components/confirm-dialog/confirm-dialog.html:1) -->
+<sui-modal open={open} onOpenChange={(e) => (open = e.detail)} size="small"
+  title={title()} description={description()} close-on-backdrop="false">
+  <sui-modal-footer slot="footer" secondary-button="Cancelar" primary-button="Confirmar" />
+</sui-modal>
+```
+
+```html
+<!-- ✅ bien -->
+<sui-modal open={open} onOpenChange={(e) => (open = e.detail)} size="small" fullscreen="false"
+  title={title()} description={description()} close-on-backdrop="false">
+  <sui-modal-footer slot="footer" secondary-button="Cancelar" primary-button="Confirmar" />
+</sui-modal>
+```
+
+Pie con los botones
+
+```html
+<!-- ❌ mal: sin slot="footer" el pie cae dentro del body: doble padding y scrollea con el contenido -->
+<sui-modal open={creando} onOpenChange={(e) => (creando = e.detail)} title="Crear descuento">
+  <sui-modal-footer secondary-button="Cancelar" primary-button="Crear descuento" />
+</sui-modal>
+```
+
+```html
+<!-- ✅ bien -->
+<sui-modal open={creando} onOpenChange={(e) => (creando = e.detail)} title="Crear descuento">
+  <sui-modal-footer slot="footer" secondary-button="Cancelar" primary-button="Crear descuento" />
+</sui-modal>
+```
+
+Título del modal
+
+```html
+<!-- ❌ mal: título en Title Case; el canon es sentence case (pages/super-admin/super-admin.html:364) -->
+<sui-modal open={suspendiendo} onOpenChange={(e) => (suspendiendo = e.detail)} icon-variant="error" title="Suspender Negocio" />
+```
+
+```html
+<!-- ✅ bien -->
+<sui-modal open={suspendiendo} onOpenChange={(e) => (suspendiendo = e.detail)} icon-variant="error" title="Suspender negocio" />
+```
+
+## Ejemplo
+
+```html
+<!-- Formulario: fullscreen automático en la app, medium en desktop -->
+<sui-modal
+  open={creando} onOpenChange={(e) => (creando = e.detail)}
+  title="Crear descuento"
+  header-icon="add-circle-line"
+  closeOnBackdrop={!guardando()}>
+  <sui-input label="Nombre" value={nombre} onValueChange={(e) => (nombre = e.detail)} />
+  <sui-modal-footer
+    slot="footer"
+    stretch
+    secondary-button="Cancelar"
+    primaryButton={{ label: 'Crear descuento', disabled: !valido() }}
+    onSecondaryClick={() => creando.set(false)}
+    onPrimaryClick={() => guardar()} />
+</sui-modal>
+
+<!-- Confirmación de una línea: siempre centrada -->
+<sui-modal
+  open={confirmando} onOpenChange={(e) => (confirmando = e.detail)}
+  size="small"
+  fullscreen="false"
+  icon-variant="error"
+  title="¿Eliminar este gasto?"
+  description="Se borra del reporte del mes.">
+  <sui-modal-footer
+    slot="footer"
+    secondary-button="Cancelar"
+    primaryButton={{ label: 'Eliminar', color: 'error' }}
+    onSecondaryClick={() => confirmando.set(false)}
+    onPrimaryClick={() => eliminar()} />
+</sui-modal>
+```

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

@@ -0,0 +1,276 @@
+---
+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 (pie del panel de notificaciones: ayuda de teclado y link a ajustes)]
+---
+
+# sui-modal-footer
+
+<!-- generado por scripts/gen-docs.mjs — no editar a mano; `npm run docs` -->
+
+> **De dónde sale este doc.** El criterio es el del SUI Angular (`sui-modal-footer`); la API es la de este
+> paquete, leída del código. Los ejemplos se pasaron de Angular de forma mecánica: lo literal va como
+> atributo (`only-icon`, `size="large"`), lo dinámico entre llaves (`size={expr}` → `el.size = expr`)
+> y los eventos como `onValueChange={…}` → `el.addEventListener('valueChange', …)`. `@if`, `@for` y
+> `<ng-template>` quedan como en Angular: se leen como pseudocódigo.
+
+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`) | `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:1691` («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:334` («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:361` | 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, falta
+aprobación: `stretch={bp.isMobile()}` para que desktop vuelva al tipo Basic.
+
+**Usos de hoy que rompen el canon:**
+
+- **4 footers con un solo botón en `secondaryButton`** → pasarlo a `primaryButton`:
+  `pages/driver/driver-dashboard/driver-dashboard.html:1390`, `:1537` y `:1673` (los tres
+  «Cerrar»), y `pages/central/central-gastos/central-gastos.html:97` cuando el gasto está
+  anulado (el primario pasa a `null` y queda solo «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:16`. Al migrarlo se
+  pierde el ícono del botón «Copiar» (`file-copy-line` → `check-line`): ver «Bien y mal».
+- 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`, 50/50 | botones a la derecha | canon en mobile (CANON-SUI §6.3), propuesta en web (falta aprobación) |
+| 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 ya dice lo mismo: footer de modal con botones `large` (48), por encima del
+Figma que dibuja `small`.
+
+### Por dispositivo (D16)
+
+D16 lo nombra en la fila de `button`: **footer de modal, `large` siempre** (D2). No baja a
+`medium` en la computadora como los botones sueltos.
+
+| dispositivo | size | nota |
+|---|---|---|
+| celular chico (< 380) | `large` | ya llega a 48, no necesita el área de 44 aparte |
+| celular (380–767) | `large` | |
+| tablet táctil | `large` | |
+| computadora | `large` | D2 manda sobre la regla de `medium` en la computadora |
+
+Ultrawide: igual, `large`. Fuente: D16, dueño 05-10-2026 (fila `button`) y D2.
+
+En master-pedidos: no se pasa `buttonSize`; `null` ya resuelve a `large`. Nunca
+`buttonSize={bp.sizeControl()}`: en la computadora bajaría a `medium`.
+
+## API
+
+<!-- api:inicio -->
+<!-- generada: no editar a mano — `npm run docs` -->
+
+| prop | atributo | tipo | default |
+|---|---|---|---|
+| `buttonSize` | `button-size` | `"2xsmall" \| "large" \| "medium" \| "small" \| "xlarge" \| "xsmall" \| null` | `null` |
+| `primaryButton` | `primary-button` | `SuiFooterButtonConfig \| null \| string` | `null` |
+| `secondaryButton` | `secondary-button` | `SuiFooterButtonConfig \| null \| string` | `null` |
+| `stretch` | `stretch` | `boolean` | `false` |
+
+| evento | `event.detail` |
+|---|---|
+| `primaryClick` | `void` |
+| `secondaryClick` | `void` |
+
+Slots: `(por defecto)`.
+
+### Diferencias con el SUI Angular
+
+Ninguna en nombres de props, eventos y valores.
+<!-- 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: `<slot>` 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`).
+- **Dentro de `sui-modal-sheet` hay que sacarle el padding y el borde.** El footer trae
+  `padding: 16px 20px` y `border-top`, pensados para el pie de un modal. En la hoja va dentro del
+  body, que ya tiene el margen de 20: se suman (el botón queda a 40 del borde) y aparece un
+  divisor que el modal fullscreen en el celular no muestra. Visto por el dueño en el aviso de app
+  cerrada el 01-11-2026. Arreglo, con una clase en el footer desde la pantalla que lo usa (le gana
+  al `:host` sin `::ng-deep`):
+  ```scss
+  .mi-hoja__botones { padding: 0; border-top: 0; background: transparent; margin-top: 24px; }
+  ```
+  Ejemplo: `components/aviso-cierre/aviso-cierre.scss` en master-pedidos.
+- **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`).
+
+## Bien y mal
+
+Un modal que solo informa
+
+```html
+<!-- ❌ mal: la única acción va en el secundario (pages/driver/driver-dashboard/driver-dashboard.html:1390) -->
+<sui-modal-footer slot="footer" secondary-button="Cerrar"
+  onSecondaryClick={() => modalTope.set(false)} />
+```
+
+```html
+<!-- ✅ bien -->
+<sui-modal-footer slot="footer" primary-button="Cerrar"
+  onPrimaryClick={() => modalTope.set(false)} />
+```
+
+Copiar un texto y cerrar
+
+```html
+<!-- ❌ mal: pie hecho a mano con dos sui-button (components/copy-text-dialog/copy-text-dialog.html:16) -->
+<div slot="footer">
+  <sui-button variant="stroke" color="neutral" size="large" onClick={() => close()}>{closeLabel()}</sui-button>
+  <sui-button variant="filled" color="primary" size="large" onClick={() => onCopy()}>
+    <sui-icon slot="start" name={copied() ? 'check-line' : 'file-copy-line'} size="16" />
+    {copied() ? copiedLabel() : copyLabel()}
+  </sui-button>
+</div>
+```
+
+```html
+<!-- ✅ bien: el label sigue al estado copiado -->
+<sui-modal-footer slot="footer" secondaryButton={closeLabel()}
+  primaryButton={copied() ? copiedLabel() : copyLabel()}
+  onSecondaryClick={() => close()} onPrimaryClick={() => onCopy()} />
+```
+
+Lo que se pierde: el ícono. `SuiFooterButtonConfig` solo acepta `label`, `disabled` y `color`, así
+que el footer no dibuja el `sui-icon` que hoy pasa de `file-copy-line` a `check-line`. El aviso de
+«copiado» sigue llegando por el label («Copiar» → «Copiado»). Conservar el ícono pide un `icon` en
+`SuiFooterButtonConfig`, que hoy no existe (**propuesta**, sin decidir); no es razón para volver al
+pie a mano.
+
+Botones del footer en la computadora
+
+```html
+<!-- ❌ mal: D16 deja el footer en large siempre (D2); esto lo baja a medium en la computadora -->
+<sui-modal-footer slot="footer" secondary-button="Cancelar" primary-button="Guardar"
+  buttonSize={bp.sizeControl()} />
+```
+
+```html
+<!-- ✅ bien: sin buttonSize, resuelve a large -->
+<sui-modal-footer slot="footer" secondary-button="Cancelar" primary-button="Guardar" />
+```
+
+## Ejemplo
+
+```html
+<!-- 2 acciones, destructiva -->
+<sui-modal-footer
+  slot="footer"
+  secondary-button="Cancelar"
+  primaryButton={{ label: 'Eliminar', color: 'error' }}
+  onSecondaryClick={() => cerrar()}
+  onPrimaryClick={() => borrar()} />
+
+<!-- 3 acciones: la tercera es un link en el slot izquierdo -->
+<sui-modal-footer
+  slot="footer"
+  stretch
+  secondary-button="Cancelar"
+  primaryButton={{ label: guardando() ? 'Guardando…' : 'Guardar', disabled: guardando() }}
+  onSecondaryClick={() => cerrar()}
+  onPrimaryClick={() => guardar()}>
+  <sui-link-button left-icon="eye-line" onClicked={() => verPrevia()}>Vista previa</sui-link-button>
+</sui-modal-footer>
+```