@ajuarezso/sui-design-system 0.20.0 → 0.21.0

package/docs/sui-day-cell/README.md

@@ -0,0 +1,118 @@
+---
+name: sui-day-cell
+selector: sui-day-cell
+resumen: Un día del calendario, con sus estados de elegido, rango, hoy, marcado y bloqueado
+alternativas: [sui-datepicker (el calendario completo, que ya la trae), sui-tab-chips (pocos días para elegir, con nombre: hoy, mañana)]
+---
+
+# sui-day-cell
+
+Story: [Molecules/Date & Time/Day Cell](https://sui-design-system.web.app/?path=/docs/molecules-date-time-day-cell--docs)
+
+## Cuándo usarlo / cuándo no
+
+**Úsalo** solo para **armar un calendario propio** que el `sui-datepicker` no cubre: una grilla
+de la semana con los días de turno del repartidor, o un mes con los días que el local cerró.
+
+**No lo uses** para:
+
+- Un calendario normal: `sui-datepicker` ya arma la grilla, las filas y la banda del rango.
+- Elegir entre pocos días: `sui-tab-chips` (la hoja del pedido programado ya lo hace así).
+- Mostrar una fecha como texto: un `<span>` con la fecha formateada.
+
+## Qué variante usar
+
+> **La guía del DS no tiene página para este componente** (vive dentro del datepicker). Todo es
+> **propuesta, falta aprobación**.
+>
+> Uso medido el 03-10-2026 en `master-pedidos/src/app`: **0 usos directos**. Lo usa por dentro
+> `sui-datepicker`.
+
+### `type` y `rangePosition`
+
+| valor | cuándo | fuente |
+|---|---|---|
+| `type="basic"` (default) | Calendario de una fecha. | propuesta |
+| `type="range"` | Calendario de rango. Va con `rangePosition`. | propuesta |
+| `rangePosition="start"` | Primer día del rango (fondo naranja, esquina izquierda). | propuesta |
+| `rangePosition="end"` | Último día (fondo naranja, esquina derecha). | propuesta |
+| `rangePosition="in"` | Días del medio (texto naranja, sin fondo propio: la banda la pinta la fila). | propuesta |
+| `rangePosition=null` | Fuera del rango. | propuesta |
+
+### Estados
+
+| input | cuándo | fuente |
+|---|---|---|
+| `selected` | El día elegido (fondo naranja). Uno solo en `basic`. | propuesta |
+| `today` | Hoy: un punto debajo del número. Siempre, para que la persona se ubique. | propuesta |
+| `marked` | El día tiene algo (pedidos, un turno). Si además es hoy, gana el punto de hoy. | propuesta |
+| `disabled` | Fuera de `min`/`max` o no se puede elegir (local cerrado ese día). | propuesta |
+| `outOfMonth` | Días del mes anterior o siguiente que completan la grilla: se ven apagados. | propuesta |
+| `ariaLabel` | Siempre que el número solo no alcance: «Martes 7 de octubre, con pedidos». El default dice «Día 7». | propuesta |
+
+Usos de hoy que rompen la regla: **0**.
+
+## Tamaño en mobile y en web
+
+**No tiene `size`.** Mide 40 × 40 fijo. En el `sui-datepicker` el paso entre celdas es de 44 px en
+mobile (gap 4) y 48 en web (gap 8): llega justo a los 44.
+
+| uso | mobile | web | fuente |
+|---|---|---|---|
+| celda de una grilla | 40 × 40 con gap 4 (paso 44) | 40 × 40 con gap 8 | medido |
+
+```html
+<!-- La grilla da el paso: gap 4 en mobile, 8 en web -->
+<div class="semana" [style.gap.px]="bp.isMobile() ? 4 : 8">
+  @for (d of dias(); track d.fecha) {
+    <sui-day-cell [day]="d.numero" [today]="d.esHoy" [marked]="d.conTurno" (clicked)="elegir(d)" />
+  }
+</div>
+```
+
+## «No usar»: por qué no hoy y cuándo sí
+
+| qué | por qué no hoy | cuándo sí, en un flujo nuevo |
+|---|---|---|
+| todo el componente suelto (0 usos) | no hay calendarios propios | la semana de turnos del repartidor o el mes de cierres del local |
+| `type="range"` suelto | el rango completo lo resuelve el datepicker, con la banda | ninguno fuera del datepicker |
+
+## API
+
+<!-- api:inicio -->
+<!-- generada: no editar a mano — `npm run docs` -->
+
+| input | tipo | default |
+|---|---|---|
+| `day` | `number \| string` | — (requerido) |
+| `type` | `'basic' \| 'range'` | `'basic'` |
+| `rangePosition` | `'start' \| 'end' \| 'in' \| null` | `null` |
+| `selected` | `boolean` | `false` |
+| `marked` | `boolean` | `false` |
+| `today` | `boolean` | `false` |
+| `disabled` | `boolean` | `false` |
+| `outOfMonth` | `boolean` | `false` |
+| `ariaLabel` | `string \| null` | `null` |
+
+| output | payload |
+|---|---|
+| `clicked` | `MouseEvent` |
+<!-- api:fin -->
+
+## Trampas
+
+- **`day` es el número del día, no una fecha.** Toda la lógica (qué día es, si es hoy) la hace
+  quien lo usa.
+- **La banda del rango no la pinta la celda**: en `in` solo cambia el color del texto. La franja
+  continua la dibuja la fila en el datepicker; suelta, un rango se ve como números naranjas sueltos.
+- `today` y `marked` juntos: se ve solo el punto de hoy.
+- `outOfMonth` no la bloquea: se puede tocar igual. Para bloquearla, `disabled`.
+- Ya trae el arreglo de iOS para el `:active` pegado.
+
+## Ejemplo
+
+```html
+<sui-day-cell day="7" [today]="true" />
+<sui-day-cell day="9" [selected]="true" />
+<sui-day-cell day="12" [marked]="true" ariaLabel="Domingo 12 de octubre, con pedidos" />
+```

package/docs/sui-day-label/README.md

@@ -0,0 +1,81 @@
+---
+name: sui-day-label
+selector: sui-day-label
+resumen: La inicial del día de la semana arriba de cada columna del calendario
+alternativas: [sui-datepicker (el calendario completo, que ya la trae), sui-button-group (elegir días de la semana: L M M J V S D)]
+---
+
+# sui-day-label
+
+Story: [Molecules/Date & Time/Day Label](https://sui-design-system.web.app/?path=/docs/molecules-date-time-day-label--docs)
+
+## Cuándo usarlo / cuándo no
+
+**Úsalo** solo como **cabecera de columna** de un calendario armado a mano con `sui-day-cell`.
+
+**No lo uses** para:
+
+- Un calendario normal: `sui-datepicker` ya pone LU, MA, MI, JU, VI, SÁ, DO.
+- **Elegir días de la semana** (el horario del local o los turnos del repartidor): eso se toca,
+  y esto es solo texto. Va `sui-button-group` `multi`.
+- El nombre de un día en una lista («Lunes»): texto normal.
+
+## Qué variante usar
+
+> **La guía del DS no tiene página para este componente** (vive dentro del datepicker). Todo es
+> **propuesta, falta aprobación**.
+>
+> Uso medido el 03-10-2026 en `master-pedidos/src/app`: **0 usos directos**. Lo usa por dentro
+> `sui-datepicker`.
+
+| input | valor | cuándo | fuente |
+|---|---|---|---|
+| `label` | dos letras en mayúsculas | Lo normal, igual que el datepicker: `LU MA MI JU VI SÁ DO`. La semana arranca el lunes. | propuesta |
+| `label` | una letra | No usar: «M» es martes y miércoles a la vez. | no usar |
+| `label` | tres letras o más | No usar: «MIÉ» entra justo en 40 px, pero rompe el formato de dos letras del datepicker; «LUNES» ya no entra. | no usar |
+
+Usos de hoy que rompen la regla: **0**.
+
+## Tamaño en mobile y en web
+
+**No tiene `size`.** Mide 40 × 40, igual que `sui-day-cell`, para que las columnas calcen. No se
+toca: el tamaño solo importa para alinear.
+
+| uso | mobile | web | fuente |
+|---|---|---|---|
+| cabecera de columna | 40 × 40 | 40 × 40 | medido |
+
+```html
+@for (d of ['LU','MA','MI','JU','VI','SÁ','DO']; track d) { <sui-day-label [label]="d" /> }
+```
+
+## «No usar»: por qué no hoy y cuándo sí
+
+| qué | por qué no hoy | cuándo sí, en un flujo nuevo |
+|---|---|---|
+| todo el componente suelto (0 usos) | no hay calendarios propios | la cabecera de una semana de turnos armada con `sui-day-cell` |
+| una letra o tres | ambiguo, o rompe el formato del datepicker | ninguno |
+
+## API
+
+<!-- api:inicio -->
+<!-- generada: no editar a mano — `npm run docs` -->
+
+| input | tipo | default |
+|---|---|---|
+| `label` | `string` | — (requerido) |
+
+Outputs: ninguno.
+<!-- api:fin -->
+
+## Trampas
+
+- El host lleva `role="columnheader"`: tiene sentido dentro de un `role="grid"`; suelto, confunde
+  al lector de pantalla.
+- Acepta cualquier texto, pero el ancho es fijo de 40 px: lo que no entra se corta.
+
+## Ejemplo
+
+```html
+<sui-day-label label="LU" />
+```

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

@@ -0,0 +1,127 @@
+---
+name: sui-drawer-footer
+selector: sui-drawer-footer
+resumen: Pie de un panel lateral con dos botones y un extra a la izquierda; hoy sin uso, los botones van en sui-modal-footer
+alternativas: [sui-modal-footer (el canon de botones de toda la app), sui-filter-panel-footer (pie de un panel de filtros)]
+---
+
+# sui-drawer-footer
+
+Story: [Molecules/Drawer/Drawer Footer](https://sui-design-system.web.app/?path=/docs/molecules-drawer-drawer-footer--docs)
+
+## Cuándo usarlo / cuándo no
+
+**Hoy no se usa, y aunque aparezca el panel lateral, los botones van en `sui-modal-footer`.** El
+canon de la app (CLAUDE.md, «Botones — composición y orden», 27-07-2026) dice que `sui-modal-footer`
+legisla **todos** los grupos de botones, no solo los de modales. El drawer-footer pone los botones
+en el mismo orden (secundario a la izquierda, primario a la derecha), pero le faltan dos cosas que
+el canon exige:
+
+- **No tiene `buttonSize`**: los botones quedan en 40 px. El canon pide `large` (48) en modales.
+- **No admite `color: 'error'`** en el primario (lo ignora): no sirve para confirmar algo destructivo.
+
+**No lo uses** para el pie de un modal, un sheet o un formulario: `sui-modal-footer`.
+
+Regla corta: **cualquier par de botones → sui-modal-footer.**
+
+## Qué variante usar
+
+> **Lo que dice la guía del DS**: el drawer es «un panel que sale desde el borde de la pantalla» y
+> su pie es un contenedor libre. No trae tipos ni do/don't.
+>
+> Uso medido el 03-10-2026 en `master-pedidos/src/app` (misma exclusión que `sui-badge`): **0 usos**.
+> `sui-modal-footer` se usa en los modales de toda la app.
+
+### `type` — qué va a la izquierda de los botones
+
+Cada tipo tiene su equivalente en `sui-modal-footer`, cuyo slot izquierdo admite lo mismo:
+
+| type | qué dibuja | equivalente canon | fuente |
+|---|---|---|---|
+| `stretch` (default) | Dos botones 50/50 a todo el ancho. | `sui-modal-footer [stretch]="true"` | canon (CLAUDE.md, botones) |
+| `basic` | Botones a la derecha. | `sui-modal-footer` | canon (CLAUDE.md, botones) |
+| `checkbox` | Un checkbox con texto a la izquierda («No volver a mostrar»). | `sui-checkbox-label` en el slot izquierdo | canon (CLAUDE.md, botones: el slot izquierdo admite checkbox) |
+| `toggle` | Un switch con texto a la izquierda. | `sui-switch-label` en el slot izquierdo | canon (CLAUDE.md, botones) |
+| `stepper` | Puntos del paso actual. | `sui-stepper variant="dot"` en el slot izquierdo | canon (CLAUDE.md, botones) |
+| `link-button` | Una tercera acción como enlace. | `sui-link-button` en el slot izquierdo | canon (CLAUDE.md, botones: la tercera acción es un link-button) |
+
+### Botones
+
+| input | regla | fuente |
+|---|---|---|
+| `primaryButton` | Con el verbo de lo que hace («Guardar», «Aplicar filtros»); el default es «Continuar». | según el código |
+| `secondaryButton` | El default es «Cancelar»; `null` para un solo botón. | según el código |
+| `disabled` (en la config) | Primario deshabilitado mientras falta un dato. | propuesta, falta aprobación |
+| `color` (en la config) | **No sirve**: el primario es siempre naranja. | según el código |
+
+Usos de hoy que rompen las reglas: **0** (no se usa).
+
+## Tamaño en mobile y en web
+
+**No tiene tamaño**: los botones miden **40 px**, sin input para cambiarlos. En mobile el canon de
+modales pide 48. El pie mide 80 px de alto.
+
+| uso | mobile | web | fuente |
+|---|---|---|---|
+| par de botones | `sui-modal-footer` (botones `large`, 48) | `sui-modal-footer` | canon (CLAUDE.md, botones: size `large` en todos los modales) |
+
+```html
+<sui-modal-footer secondaryButton="Cancelar" primaryButton="Guardar" [stretch]="bp.isMobile()" … />
+```
+
+## «No usar»: por qué no hoy y cuándo sí
+
+| qué | por qué no hoy | cuándo sí, en un flujo nuevo |
+|---|---|---|
+| el componente entero | `sui-modal-footer` hace lo mismo con tamaño 48 y color de error | ninguno mientras el modal-footer exista; si el DS suma un panel lateral, usa también modal-footer |
+
+## API
+
+<!-- api:inicio -->
+<!-- generada: no editar a mano — `npm run docs` -->
+
+| input | tipo | default |
+|---|---|---|
+| `type` | `'stretch' \| 'basic' \| 'checkbox' \| 'toggle' \| 'stepper' \| 'link-button'` | `'stretch'` |
+| `primaryButton` | `SuiFooterButtonConfig \| string` | `'Continuar'` |
+| `secondaryButton` | `SuiFooterButtonConfig \| string \| null` | `'Cancelar'` |
+| `checkboxLabel` | `string` | `''` |
+| `checkboxActive` · model, `[(checkboxActive)]` | `boolean` | `false` |
+| `toggleLabel` | `string` | `''` |
+| `toggleActive` · model, `[(toggleActive)]` | `boolean` | `false` |
+| `stepper` | `{ current: number; total: number } \| null` | `null` |
+| `link` | `SuiLinkConfig \| string \| null` | `null` |
+
+| output | payload |
+|---|---|
+| `primaryClick` | `Event` |
+| `secondaryClick` | `Event` |
+| `linkClick` | `MouseEvent` |
+<!-- api:fin -->
+
+```ts
+type SuiDrawerFooterType = 'stretch' | 'basic' | 'checkbox' | 'toggle' | 'stepper' | 'link-button';
+interface SuiFooterButtonConfig { label: string; disabled?: boolean; color?: 'primary' | 'error'; }
+```
+
+## Trampas
+
+- **Defaults en español** (desde 03-10-2026; antes «Continue» / «Cancel»): sin `primaryButton` dice
+  «Continuar» y sin `secondaryButton` dice «Cancelar». Para un solo botón pasa
+  `[secondaryButton]="null"`.
+- **`color: 'error'` se ignora**: el primario está fijo en `primary`.
+- **Sin tamaño**: botones de 40 px.
+- `stepper` usa `{ current, total }` con `current` desde 0, y dibuja sus propios puntos (no es
+  `sui-stepper`).
+- `checkboxActive` y `toggleActive` son `model`: `[(checkboxActive)]`.
+- El borde de arriba ya viene puesto: no le sumes otro.
+
+## Ejemplo
+
+```html
+<!-- Lo que va en la app -->
+<sui-modal-footer
+  secondaryButton="Cancelar"
+  [primaryButton]="{ label: 'Guardar' }"
+  (secondaryClick)="cerrar()" (primaryClick)="guardar()" />
+```

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

@@ -0,0 +1,140 @@
+---
+name: sui-drawer-header
+selector: sui-drawer-header
+resumen: Cabecera de un panel lateral (título, descripción, cerrar); hoy sin contenedor en SUI y sin uso en la app
+alternativas: [sui-modal (con title y description: la cabecera de todos los modales de la app), sui-modal-header (la cabecera suelta del modal), sui-page-header (título de una página)]
+---
+
+# sui-drawer-header
+
+Story: [Molecules/Drawer/Drawer Header](https://sui-design-system.web.app/?path=/docs/molecules-drawer-drawer-header--docs)
+
+## Cuándo usarlo / cuándo no
+
+**Hoy no se usa.** SUI no tiene el contenedor del drawer (el panel que sale del borde): solo esta
+cabecera y su pie. En la app, todo lo que se abre encima es un `sui-modal` (fullscreen en mobile,
+canon) o un `sui-modal-sheet`, y su cabecera sale de los inputs `title` y `description` del modal.
+
+**Úsalo** cuando exista un panel lateral de web (un detalle que se abre a la derecha sin tapar la
+lista, como el pedido en el panel de órdenes) y haga falta su cabecera.
+
+**No lo uses** para:
+
+- La cabecera de un modal o un sheet: `sui-modal` con `title`/`description` (o `sui-modal-header`).
+- El título de una página: `sui-page-header`.
+- Mobile: un panel lateral en 390 px es un modal fullscreen.
+
+Regla corta: **modal o sheet → sui-modal con title · panel lateral de web → drawer-header (cuando exista el panel).**
+
+## Qué variante usar
+
+> **Lo que dice la guía del DS**: el drawer es «un panel que sale desde el borde de la pantalla».
+> Su cabecera trae título y **botón de cerrar visible por default**. No habla de tipos ni tamaños.
+>
+> Uso medido el 03-10-2026 en `master-pedidos/src/app` (misma exclusión que `sui-badge`): **0 usos**.
+
+### `type`
+
+| type | cuándo | fuente |
+|---|---|---|
+| `basic` (default) | Lo normal: título y cerrar. | propuesta, falta aprobación |
+| `left-icon` | El ícono dice de qué es el panel antes de leer («history-line» en el historial). En `small` va suelto (24); en `large`/`xlarge`, en un círculo con borde. | propuesta, falta aprobación |
+
+### `size`
+
+| size | qué cambia | cuándo | fuente |
+|---|---|---|---|
+| `small` (default) | 64 px, todo en una línea; **no muestra `description`** | Panel con título que se explica solo. Es el único que admite `link`. | propuesta, falta aprobación |
+| `large` | 88 px, título arriba y `description` debajo | Panel que necesita una línea de contexto («Últimos 30 días»). | propuesta, falta aprobación |
+| `xlarge` | padding 24, título 20, descripción 16 | No: extensión de SUI sin caso; en web no hace falta letra más grande. | propuesta, falta aprobación |
+
+### Lo demás
+
+| input | valor | cuándo | fuente |
+|---|---|---|---|
+| `showDismiss` | `true` (default) | Siempre. | según la guía del DS (cerrar visible por default) |
+| `showDismiss` | `false` | Solo si el panel no se puede cerrar sin decidir (y entonces es un modal, no un drawer). | propuesta, falta aprobación |
+| `showDivider` | `true` | Cuando el cuerpo scrollea por debajo de la cabecera. | propuesta, falta aprobación |
+| `badge` | número | Pendientes dentro del panel (círculo rojo). | propuesta, falta aprobación |
+| `badge` | texto o `SuiBadgeConfig` | Un estado o etiqueta al lado del título. Pasa `variant: 'lighter'`: el default de aquí es `light` (ver Trampas). | canon (README de `sui-badge`: `lighter` en cabeceras) |
+| `link` | texto | Una acción menor en la cabecera («Ver todo»). Solo en `small`. | propuesta, falta aprobación |
+| `dismissAriaLabel` | «Cerrar» (default) | Ya está en español. | según el código |
+
+Usos de hoy que rompen las reglas: **0** (no se usa).
+
+## Tamaño en mobile y en web
+
+**No tiene tamaño para mobile**: el botón de cerrar mide **24 px** (compact-button `large`), lejos de
+los 40-44 del dedo. Es una pieza de web.
+
+| uso | mobile | web | fuente |
+|---|---|---|---|
+| cabecera de panel | no se usa: `sui-modal` fullscreen con `title` | `small` o `large` | propuesta, falta aprobación |
+
+```html
+@if (!bp.isMobile()) {
+  <sui-drawer-header size="large" title="Pedido #1042" description="Sabores Andinos · hace 5 min" (dismiss)="cerrar()" />
+}
+```
+
+## «No usar»: por qué no hoy y cuándo sí
+
+| qué | por qué no hoy | cuándo sí, en un flujo nuevo |
+|---|---|---|
+| el componente entero | SUI no tiene el panel que lo contiene; los modales traen su cabecera | un panel lateral de detalle en web (el pedido en el panel de órdenes) |
+| `xlarge` | sin caso | nunca en web |
+| `showDismiss` en `false` | un panel siempre se cierra | nunca en un drawer |
+| en mobile | cerrar de 24 px | nunca |
+
+## API
+
+<!-- api:inicio -->
+<!-- generada: no editar a mano — `npm run docs` -->
+
+| input | tipo | default |
+|---|---|---|
+| `type` | `'basic' \| 'left-icon'` | `'basic'` |
+| `size` | `'small' \| 'large' \| 'xlarge'` | `'small'` |
+| `title` | `string` | `''` |
+| `description` | `string \| null` | `null` |
+| `icon` | `string \| null` | `null` |
+| `badge` | `SuiBadgeConfig \| number \| string \| null` | `null` |
+| `link` | `SuiLinkConfig \| string \| null` | `null` |
+| `showDismiss` | `boolean` | `true` |
+| `showDivider` | `boolean` | `false` |
+| `dismissAriaLabel` | `string` | `'Cerrar'` |
+
+| output | payload |
+|---|---|
+| `dismiss` | `MouseEvent` |
+| `linkClick` | `MouseEvent` |
+<!-- api:fin -->
+
+```ts
+type SuiDrawerHeaderType = 'basic' | 'left-icon';
+type SuiDrawerHeaderSize = 'small' | 'large' | 'xlarge';
+```
+
+## Trampas
+
+- **`description` no se ve en `small`** y **`link` no se ve en `large`/`xlarge`**: los dos se pasan
+  sin error y no aparecen.
+- **El badge de texto sale `orange` + `light` por default**, que va contra el canon del badge
+  (`lighter` en cabeceras, naranja solo si pide atención). Pasa un `SuiBadgeConfig` completo.
+- **`badge` en `0` sí se dibuja** (un círculo rojo con «0»). Pasa `null` para no mostrarlo.
+- **`left-icon` sin `icon` no dibuja nada.**
+- El título es un `<h2>`: si la página ya tiene un `h2` al mismo nivel, revisa el orden de títulos.
+- No hay contenedor: el fondo, el ancho y la animación del panel los pones tú.
+
+## Ejemplo
+
+```html
+<sui-drawer-header
+  type="left-icon"
+  size="large"
+  icon="history-line"
+  title="Historial de pedidos"
+  description="Últimos 30 días"
+  [showDivider]="true"
+  (dismiss)="cerrar()" />
+```

package/docs/sui-empty-state/README.md

@@ -0,0 +1,145 @@
+---
+name: sui-empty-state
+selector: sui-empty-state
+resumen: Pantalla o lista sin nada que mostrar (o que no pudo cargar) con emoji animado, título, explicación y una acción opcional
+alternativas: [sui-alert (un aviso dentro de una pantalla que sí tiene contenido), sui-banner (aviso de toda la app), skeleton (mientras carga, nunca un empty)]
+---
+
+# sui-empty-state
+
+Story: [Molecules/Empty State](https://sui-design-system.web.app/?path=/docs/molecules-empty-state--docs)
+
+## Cuándo usarlo / cuándo no
+
+**Úsalo** cuando una lista o una pantalla no tiene nada que mostrar: el carrito vacío, sin pedidos
+aún, una búsqueda sin resultados, un filtro que no trae nada. También cuando la lista **no pudo
+cargar**, con una acción para reintentar.
+
+**No lo uses** para:
+
+- Mientras carga: eso es un skeleton. Un empty que aparece y después se llena se lee como «no
+  hay nada» por un segundo.
+- Un aviso dentro de una pantalla que sí tiene contenido («Tu local está cerrado»): `sui-alert`.
+- Un error de un formulario: el mensaje va en el campo (`error` / `errorMessage`).
+
+Regla corta: **no hay nada que mostrar → empty-state · está cargando → skeleton · hay contenido y
+algo que avisar → alert.**
+
+## Qué variante usar
+
+> **La guía del DS no tiene página del empty state.** El componente de SUI se construyó a
+> propósito con Fluent Emoji animados en vez de ilustraciones: es una decisión del proyecto
+> (memoria «emojis animados en empty states», 17-04-2026).
+>
+> Uso medido el 03-10-2026 en `master-pedidos/src/app` (misma exclusión que `sui-card`): **66
+> empty-states en 40 archivos**. 25 con `action` (10 con `route`). 4 con `emoji` propio, 22 con la
+> URL del zorro pegada a mano (que ya es el default) y 40 sin `emoji`. 29 con un atributo `icon`
+> que el componente no tiene.
+
+### Las piezas
+
+| prop | cuándo | fuente |
+|---|---|---|
+| `emoji` vacío (default: el zorro) | Lo normal. El zorro es la mascota de los empty states y sale solo: **no pegues su URL**. | canon (memoria del proyecto) |
+| `emoji` propio | Cuando el emoji dice algo del caso: el reloj de arena en «Aún no tienes facturas» (se está esperando algo), el chef en los avisos del local. Siempre de `FLUENT_EMOJI_ANIM` (`core/fluent-emoji.ts`) o de `assets/emoji-anim/`. | canon (memoria del proyecto) |
+| `title` (obligatorio) | Qué pasa, en corto y sin punto: «Tu carrito está vacío», «Sin pedidos aún». En una búsqueda, repite lo buscado: «Nada con “pollo broaster”». | propuesta (práctica de la app) |
+| `subtitle` | Qué va a pasar o qué puede hacer la persona: «Cuando hagas tu primer pedido, aparecerá aquí.» | propuesta |
+| `action` como string + `(actionClicked)` | La salida es algo de esta misma pantalla: «Reintentar», «Ver todo el catálogo», «Activar captura». | propuesta |
+| `action` como `{ label, route }` | La salida es otra pantalla: «Ver negocios» → `/cliente/inicio`. | propuesta |
+| sin `action` | No hay un paso obvio, o la pantalla ya tiene el botón para llenarla (el «Nuevo local» de arriba). | propuesta |
+| error de carga | Siempre con `action="Reintentar"`. Excepción: la pantalla reintenta sola y lo dice («Seguimos intentando»). | propuesta |
+
+**Usos de hoy que rompen las reglas:**
+
+- **29 con `icon="…"`**: `icon` no es un input, el atributo no hace nada. Ejemplos:
+  `pages/customer/cart/cart.html:18`, `pages/drivers/drivers.html:87`,
+  `pages/customer/order-history/order-history.html:20`. Se borra.
+- **22 con la URL del zorro pegada** (`emoji="…/Animals/Fox.png"`), que ya es el default:
+  `pages/customers/customers.html:65`, `pages/products/products.html:113`,
+  `pages/locations/locations.html:16`. Se borra.
+- **4 errores de carga sin «Reintentar»**:
+  `pages/driver/driver-dashboard/driver-dashboard.html:1071`,
+  `pages/customer/order-history/order-history.html:20`,
+  `pages/super-admin/master-drivers/master-drivers.html:524` y `:754`.
+  (`pages/public/pedido-en-vivo/pedido-en-vivo.html:50` no cuenta: reintenta solo.)
+
+## Tamaño en mobile y en web
+
+El emoji mide 120 en las dos; el padding pasa solo de 48 / 24 en web a 32 / 20 desde tablet hacia
+abajo (media query `bp.medium` del componente). El `size` solo cambia **el botón de la acción**:
+
+| size | botón | fuente |
+|---|---|---|
+| `medium` (default) | 40 px (`sui-button` `medium`) | lo que había en el DS |
+| `large` | 48 px (`sui-button` `large`, texto 16) | canon (aprobado por el dueño, 03-10-2026): extensión SUI |
+
+| uso | mobile | web | fuente |
+|---|---|---|---|
+| ilustración + texto | lo resuelve el componente | lo resuelve el componente | lo que hay en el DS |
+| botón de la acción | `large` (48) | `medium` (40) | propuesta: el tamaño es extensión SUI aprobada (03-10-2026); el «cuándo» falta aprobarlo |
+
+```html
+<sui-empty-state
+  title="Tu carrito está vacío"
+  [action]="{ label: 'Ver negocios', route: '/cliente/inicio' }"
+  [size]="bp.isMobile() ? 'large' : 'medium'" />
+```
+
+## «No usar»: por qué no hoy y cuándo sí
+
+| qué | por qué no hoy | cuándo sí, en un flujo nuevo |
+|---|---|---|
+| un emoji que no sea animado (PNG estático, SVG, ícono) | la regla del proyecto es emoji animado | nunca |
+| empty con `action` que hace lo mismo que un botón ya visible en la pantalla | dos botones para lo mismo | nunca |
+
+## API
+
+<!-- api:inicio -->
+<!-- generada: no editar a mano — `npm run docs` -->
+
+| input | tipo | default |
+|---|---|---|
+| `emoji` | `string` | `''` |
+| `title` | `string` | — (requerido) |
+| `subtitle` | `string` | `''` |
+| `action` | `SuiEmptyStateAction \| string \| null` | `null` |
+| `size` | `'medium' \| 'large'` | `'medium'` |
+
+| output | payload |
+|---|---|
+| `actionClicked` | `void` |
+<!-- api:fin -->
+
+```ts
+interface SuiEmptyStateAction { label: string; route?: string; }
+```
+
+`EMPTY_STATE_FOX_EMOJI` (exportada) es la URL del zorro.
+
+## Trampas
+
+- **`icon` no existe.** Viene de un `app-empty-state` viejo; Angular no se queja porque lo toma
+  como atributo HTML.
+- **`emoji` es una URL**, no un nombre de `SuiEmoji` (`'bell'` no funciona).
+- **`title` es obligatorio** y el host borra el atributo `title` del DOM (sin tooltip nativo).
+- Con `route`, el botón usa `routerLink` y **no emite** `actionClicked`.
+- El botón es `sui-button` `filled` `primary`: el color no se cambia; el tamaño sí, con `size` (`medium` 40 · `large` 48).
+- El emoji carga con `loading="lazy"`: en una captura de pantalla completa puede salir vacío.
+
+## Ejemplo
+
+```html
+<!-- Lista vacía con salida a otra pantalla -->
+<sui-empty-state
+  title="Tu carrito está vacío"
+  subtitle="Explora las tiendas y agrega productos para empezar."
+  [action]="{ label: 'Ver negocios', route: '/cliente/inicio' }" />
+
+<!-- Error de carga -->
+<sui-empty-state
+  [emoji]="emoji.thinking"
+  title="No se pudieron cargar tus pedidos"
+  subtitle="Revisa tu conexión y vuelve a intentar."
+  action="Reintentar"
+  (actionClicked)="cargar()" />
+```