@ajuarezso/sui-stencil 0.0.0-stage → 0.1.0

package/docs/sui-dropdown-search/README.md

@@ -0,0 +1,195 @@
+---
+name: sui-dropdown-search
+selector: sui-dropdown-search
+resumen: Buscador sin caja que va arriba del panel de un menú flotante para filtrar sus items
+alternativas: [sui-input type="search" (buscador de una pantalla o una lista a la vista), sui-command-menu-search (buscador del ⌘K), sui-select (elegir de una lista corta, sin buscar)]
+---
+
+# sui-dropdown-search
+
+<!-- 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-dropdown-search`); 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/Dropdown/Dropdown Search](https://sui-design-system.web.app/?path=/docs/organisms-dropdown-dropdown-search--docs)
+
+Es solo el campo: **no filtra nada**. Quien lo usa recibe el texto (`value` + `valueChange`) y decide qué items
+pinta debajo.
+
+## Cuándo usarlo / cuándo no
+
+**Úsalo** arriba del panel de un `sui-dropdown-menu` cuando la lista es larga para scrollear y la
+persona sabe lo que busca: más de ~10 opciones (un repartidor entre 40, un país, una etiqueta).
+
+**No lo uses** para:
+
+- El buscador de una pantalla o de una lista que ya está a la vista: `sui-input type="search"`
+  (con caja, label y tamaños).
+- El ⌘K que busca en toda la app: `sui-command-menu-search`.
+- Una lista corta: con 6 opciones el buscador estorba.
+- Fuera de un panel: no tiene borde ni radio, se pierde en la pantalla.
+
+Regla corta: **filtrar los items de un menú → dropdown-search · buscar en una pantalla → sui-input
+search · buscar en toda la app → command-menu-search.**
+
+`sui-select` **no tiene buscador**. Si un select necesita buscar, hoy se arma con
+`sui-dropdown-menu` + este buscador + `sui-dropdown-item mode="option"` (es lo que muestra su story
+«En contexto»), sabiendo que se pierde el `ControlValueAccessor` del select. Propuesta, falta
+aprobación.
+
+## Qué variante usar
+
+> **La guía del DS no tiene buscador en su dropdown**; el buscador de lista vive en su command
+> menu. Este sale del Figma del DS («Dropdown Misc Items», estados Default / Hover / Active). Las
+> reglas marcadas canon están aprobadas; lo que sigue en propuesta espera decisión.
+>
+> Uso medido el 03-10-2026 en `master-pedidos/src/app` (misma exclusión que `sui-dropdown-menu`):
+> **0 usos**.
+
+No tiene variantes. Los estados salen solos: sin texto, lupa gris; con texto, lupa oscura y una X
+para limpiar.
+
+| prop | regla | fuente |
+|---|---|---|
+| `placeholder` | **Siempre**, en español y con elipsis: «Buscar repartidor…». El default genérico es `'Buscar…'`. | canon (CANON-SUI §5: copy en español, elipsis `…`) |
+| `value` + `valueChange` | El texto; con él se filtra la lista. | API |
+| `disabled` | Extensión SUI, no está en el Figma. Sin caso hoy. | — |
+
+## Tamaño en mobile y en web
+
+No tiene tamaños: 36 px de alto (8 + 20 + 8), texto 14/20 en web y 16 en ≤ 767 px (anti-zoom de iOS, desde 0.26.0).
+
+| uso | mobile | web | fuente |
+|---|---|---|---|
+| buscador del menú | no se usa: `sui-modal-sheet` con `sui-input type="search"` arriba | 36, fijo | mobile: canon (aprobado por el dueño, 05-10-2026, bloque B7) y D16 (dueño 05-10-2026: lo que se toca llega a 44, y este campo mide 36) · web: lo que hay en el DS |
+
+Desde 0.26.0 el texto sube a 16 en ≤ 767 px (sin zoom de iOS) y el teclado trae la lupa
+(`enterkeyhint="search"`), pero sigue midiendo 36, bajo el piso de 44. Para buscar en una lista larga en
+mobile, mejor un `sui-modal-sheet` con `sui-input type="search"` arriba. Canon (aprobado por el dueño, 05-10-2026, bloque B7).
+
+### Por dispositivo (D16)
+
+No aplica como tabla: **no tiene `size`** (36 px fijo, del celular chico al ultrawide), así que D16
+no lo agranda; lo único que cambia por dispositivo es **si se usa**. Se toca, y 36 no llega a 44:
+en el celular (también el chico) y en la tablet táctil va el sheet con `sui-input type="search"`
+(que sí tiene `size`); en la computadora y el ultrawide, este buscador dentro del menú. La tablet
+entra con el celular porque D16 pone la tablet táctil con el celular en todo lo que se toca.
+
+En master-pedidos: `@if (bp.tactil())` → sheet con `<sui-input type="search" size={bp.sizeControl()}>`;
+`@else` → `sui-dropdown-search` en el menú, sin `size`.
+
+## API
+
+<!-- api:inicio -->
+<!-- generada: no editar a mano — `npm run docs` -->
+
+| prop | atributo | tipo | default |
+|---|---|---|---|
+| `ariaLabel` | `aria-label` | `null \| string` | `null` |
+| `disabled` | `disabled` | `boolean` | `false` |
+| `placeholder` | `placeholder` | `string` | `'Buscar…'` |
+| `value` | `value` | `string` | `''` |
+
+| evento | `event.detail` |
+|---|---|
+| `cleared` | `void` |
+| `valueChange` | `string` |
+
+### Diferencias con el SUI Angular
+
+- **Eventos de Angular que aquí no existen:** `valueChanged`
+<!-- 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.limpiarBusqueda` | Limpiar búsqueda | — |
+| `comun.buscar` | Buscar… | `placeholder` |
+<!-- textos:fin -->
+
+`valueChanged` sale con cada tecla (lo mismo que `value`, como evento). `cleared` sale al tocar la X,
+que además deja `value` en `''`.
+
+## Trampas
+
+- **No filtra.** Hay que filtrar la lista con el `value` (un `computed` sobre las opciones).
+- **El default del placeholder es genérico** (`'Buscar…'`, en español desde el 04-10-2026): pásalo siempre diciendo qué se busca.
+- **El nombre accesible es el placeholder** si no pasas `ariaLabel`. Con un placeholder de ejemplo
+  («Ej. Juan…») pasa `ariaLabel` con lo que se busca.
+- Lleva `enterkeyhint="search"` y **no** `inputmode` (D14: `inputmode="search"` le quita la lupa al
+  teclado de Android). Texto en 16 en ≤ 767 px. Las dos cosas desde 0.26.0.
+- **Al abrir el menú el foco no entra al buscador**: quien quiera escribir de una tiene que enfocarlo
+  a mano.
+- El `<input>` no tiene `keydown`: Enter no hace nada salvo que quien lo usa lo escuche.
+
+## Bien y mal
+
+Hoy no hay usos en la app (0, medido el 03-10-2026): los pares salen de «Trampas» y de la regla B7.
+
+Qué se busca
+
+```html
+<!-- ❌ mal: sin placeholder sale el genérico «Buscar…» y no dice qué se busca -->
+<sui-dropdown-search value={busqueda} onValueChange={(e) => (busqueda = e.detail)} />
+```
+
+```html
+<!-- ✅ bien -->
+<sui-dropdown-search value={busqueda} onValueChange={(e) => (busqueda = e.detail)} placeholder="Buscar repartidor…" />
+```
+
+Filtrar la lista
+
+```html
+<!-- ❌ mal: el buscador no filtra; la lista sigue entera aunque se escriba -->
+<sui-dropdown-search value={busqueda} onValueChange={(e) => (busqueda = e.detail)} placeholder="Buscar repartidor…" />
+@for (r of repartidores(); track r.uid) { <sui-dropdown-item label={r.nombre} /> }
+```
+
+```html
+<!-- ✅ bien: repartidoresFiltrados() es un computed sobre busqueda() -->
+<sui-dropdown-search value={busqueda} onValueChange={(e) => (busqueda = e.detail)} placeholder="Buscar repartidor…" />
+@for (r of repartidoresFiltrados(); track r.uid) { <sui-dropdown-item label={r.nombre} /> }
+```
+
+Buscar en el celular
+
+```html
+<!-- ❌ mal: mide 36, bajo el piso de 44 en lo que se toca (D1, D16) -->
+<sui-dropdown-search value={busqueda} onValueChange={(e) => (busqueda = e.detail)} placeholder="Buscar repartidor…" />
+```
+
+```html
+<!-- ✅ bien: en el celular y la tablet táctil, sheet con el input de búsqueda (B7) -->
+<sui-modal-sheet open={buscando} onOpenChange={(e) => (buscando = e.detail)}>
+  <sui-input type="search" size={bp.sizeControl()} placeholder="Buscar repartidor…"
+             value={busqueda} onValueChange={(e) => (busqueda = e.detail)} />
+</sui-modal-sheet>
+```
+
+## Ejemplo
+
+```html
+<sui-dropdown-menu #menu="suiDropdownMenu" min-width="280">
+  <sui-button trigger variant="stroke" color="neutral">Asignar repartidor</sui-button>
+  <ng-template suiDropdownPanel>
+    <sui-dropdown-search value={busqueda} onValueChange={(e) => (busqueda = e.detail)} placeholder="Buscar repartidor…" />
+    @for (r of repartidoresFiltrados(); track r.uid) {
+      <sui-dropdown-item label={r.nombre} onClicked={() => { menu.close(); asignar(r.uid) }}>
+        <sui-avatar slot="leading" size="xs" src={r.avatarUrl} initials={r.nombre.charAt(0)} />
+      </sui-dropdown-item>
+    }
+  </ng-template>
+</sui-dropdown-menu>
+```

package/docs/sui-emoji/README.md

@@ -0,0 +1,214 @@
+---
+name: sui-emoji
+selector: sui-emoji
+resumen: Un emoji 3D animado (Fluent) para los momentos con emoción: estados vacíos, celebraciones, onboarding
+alternativas: [sui-icon (ícono funcional, monocromo), sui-empty-state (el estado vacío completo, que ya trae su emoji)]
+---
+
+# sui-emoji
+
+<!-- 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-emoji`); 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: [Atoms/Emoji](https://sui-design-system.web.app/?path=/docs/atoms-emoji--docs)
+
+## Cuándo usarlo / cuándo no
+
+**Úsalo** donde la pantalla tiene que **sentirse**, no solo funcionar: un estado vacío, «Pedido
+confirmado», los pasos de una landing, la barra de calificación.
+
+**No lo uses** para:
+
+- Un ícono funcional (un botón, una fila, un menú): eso es `sui-icon`. Un emoji no es un ícono.
+- Muchos a la vez animados: cada uno es un APNG de ~1 MB en bucle.
+- Una imagen propia que no es un emoji (la moneda de sol): un `<img>`.
+
+## Qué variante usar
+
+> **La guía del DS no tiene este componente**: es propio de SUI. Las reglas marcadas canon están
+> aprobadas; lo que sigue en propuesta espera decisión.
+>
+> Uso medido el 03-10-2026 en `master-pedidos/src/app`: 10 emojis en 3 archivos, sin contar
+> prototipos ni vitrinas. El catálogo tiene 59.
+
+### Dónde va
+
+| caso | cómo | fuente |
+|---|---|---|
+| Estados vacíos y celebraciones | Emoji animado, uno solo. Nada de íconos genéricos en un estado vacío. El del vacío lo pone `sui-empty-state` en `full` (caja de 120); el `size` de la celebración está **pendiente** (P38). | canon (CANON-SUI §5.6) para los estados vacíos · `full` en el vacío: según el código (`sui-empty-state.html`) · celebración: pendiente (P38) |
+| Pasos de una landing | `lg`, uno por paso. | canon (aprobado por el dueño, 05-10-2026, bloque B1) |
+| Junto a un título o dentro de un texto | `md` o `sm`, como acento. | canon (aprobado por el dueño, 05-10-2026, bloque B1) |
+| Como ícono de un botón | No: el botón lleva `leftIcon`. | canon (CANON-SUI §5.7: emojis solo en contenido escrito por un usuario; en un botón, `leftIcon` con `sui-icon`) |
+
+### `size`
+
+| valor | px | cuándo | fuente |
+|---|---|---|---|
+| `xl` | 48 | El más grande con nombre. Para la celebración, **pendiente** (P38): todavía no se decidió su `size`. El estado vacío no lo usa: va en `full`. | pendiente (P38) |
+| `lg` | 32 | Pasos de una landing, la barra de calificación. | canon (aprobado por el dueño, 05-10-2026, bloque B1) |
+| `md` (default) | 24 | Acompaña un título. | canon (aprobado por el dueño, 05-10-2026, bloque B1) |
+| `sm` | 20 | Dentro de una línea de texto. | canon (aprobado por el dueño, 05-10-2026, bloque B1) |
+| `xs` | 16 | No usar hoy. | canon (aprobado por el dueño, 05-10-2026, bloque B6) |
+| `full` | 100 % | Llena su caja: es el del estado vacío (`sui-empty-state` lo pone en una caja de 120). | según el código |
+
+### `animated`, `src`, `name`, `ariaLabel`
+
+| input | cuándo | fuente |
+|---|---|---|
+| `animated` (default `true`) | Uno solo → animado. **Varios a la vez → `false`.** Ojo: solo las 5 caritas de la calificación (`pensive-face` … `grinning-face-smiling-eyes`) tienen copia estática; para el resto, `false` no cambia nada. | propuesta (la regla ya está escrita en `sui-emoji.ts`) |
+| `name` | Uno del catálogo. Si no está, se agrega al catálogo del DS. | canon (aprobado por el dueño, 05-10-2026, bloque B9) |
+| `src` | Un emoji que no está en el catálogo, mientras se agrega. **Nunca** un `<img>` suelto con la URL del emoji. | canon (aprobado por el dueño, 05-10-2026, bloque B9) |
+| `ariaLabel` | Solo si el emoji dice algo que el texto no dice. Si no, queda decorativo (`aria-hidden`). | canon (aprobado por el dueño, 05-10-2026, bloque B5) |
+
+**Usos de hoy que romperían la propuesta:**
+
+- **2 emojis como ícono de botón**: «Encargarme yo» en `pages/orders/orders.html:323` y `:354` → `leftIcon`.
+- **5 animados a la vez** en `pages/public/landing-customers/landing-customers.html:160`–`:184`
+  (más otro en `:56`). No tienen copia estática: o se acepta el peso en la landing o se generan
+  las copias.
+- **Un catálogo paralelo**: `core/fluent-emoji.ts` arma sus propias URLs (otro CDN incluido) y lo
+  importan 11 archivos (medido el 04-10-2026) (`components/permission-prime-modal/permission-prime-modal.ts`,
+  `pages/role-selector/role-selector.ts`, `pages/customer/order-tracking/order-tracking.ts`…).
+- **10 `<img>` con un emoji**, fuera del componente: `pages/products/add-product/add-product.html:122`
+  (la URL del paquete escrita a mano, y 3 más en el mismo archivo),
+  `components/location-flow-outlet/location-flow-outlet.html:14`,
+  `pages/customer/order-tracking/order-tracking.html:249`. No cuentan las imágenes de los rubros
+  (`pages/customer/store-browser/store-browser.html:193` y similares): vienen de datos y no son
+  del catálogo.
+
+## Tamaño en mobile y en web
+
+El emoji no se toca: en el celular va **un paso más grande** que en la computadora (D16, P1 b),
+porque ahí se lee más de cerca y en una columna sola. Se elige con el servicio de breakpoints de
+la app (`bp`, en `services/breakpoints.service.ts`), también en las pantallas del cliente y del
+repartidor: el celular chico y la tablet llevan el valor de web.
+
+| uso | mobile | web | fuente |
+|---|---|---|---|
+| estado vacío | `full` (caja de 120) | `full` (caja de 120) | según el código: lo pone `sui-empty-state` y no cambia por dispositivo |
+| celebración | **pendiente** (P38) | **pendiente** (P38) | P38 sigue abierta: no se decidió el `size` |
+| pasos de una landing | `xl` (48) | `lg` (32) | web: canon (aprobado por el dueño, 05-10-2026, bloque B1) · mobile: D16, dueño 05-10-2026 (antes decía `lg` en mobile y `xl` en web, al revés de P1 b) |
+| dentro de un texto | `md` (24) | `sm` (20) | propuesta; cuadra con D16 (un paso más en el celular) |
+
+```html
+<sui-emoji name="hamburger" size={bp.celular() ? 'xl' : 'lg'} />
+```
+
+El tamaño con nombre más grande es `xl` (48); para uno más grande, `size="full"` dentro de una
+caja con el alto que se quiera.
+
+### Por dispositivo (D16)
+
+No está en la tabla por componente de D16; como no se toca, sigue la columna «lo que no se toca»:
+valor «web» en todos salvo el celular de 380 o más. Dos casos quedan fuera: el estado vacío no
+cambia por dispositivo (lo pone `sui-empty-state` en `full`) y la celebración espera P38 («Lo que
+esta hoja no cierra» de D16).
+
+| dispositivo | size | nota |
+|---|---|---|
+| celular chico (< 380) | valor «web»: landing `lg` · texto `sm` · vacío `full` · celebración pendiente (P38) | lo que no se toca no sube en el celular chico |
+| celular (380–767) | valor «mobile»: landing `xl` · texto `md` · vacío `full` · celebración pendiente (P38) | un paso más que en la computadora (P1 b); el vacío no cambia, lo pone `sui-empty-state` |
+| tablet táctil (`pointer: coarse`) | valor «web»: landing `lg` · texto `sm` · vacío `full` · celebración pendiente (P38) | |
+| computadora (`pointer: fine`) | valor «web»: landing `lg` · texto `sm` · vacío `full` · celebración pendiente (P38) | `sm` (20) aquí es el alto de una línea de texto 14/20, no el `small` de los controles que D16 saca |
+
+Ultrawide: igual que la computadora. Fuente: D16, dueño 05-10-2026.
+
+En master-pedidos: no hay helper (`bp.sizeAvatar()` es solo del avatar, con otra escala). Landing:
+`size={bp.celular() ? 'xl' : 'lg'}` · dentro de un texto: `size={bp.celular() ? 'md' : 'sm'}` ·
+estado vacío: no se usa `sui-emoji` suelto, va `sui-empty-state` (que lo pone en `full`) ·
+celebración: pendiente (P38).
+
+## «No usar»: por qué no hoy y cuándo sí
+
+| qué | por qué no hoy | cuándo sí, en un flujo nuevo |
+|---|---|---|
+| `size` `xs` | a 16 px un emoji ya no se distingue | dentro de un tag de categoría, solo con copia estática |
+| como ícono de botón o de fila | un emoji no es un ícono | ninguno |
+
+## API
+
+<!-- api:inicio -->
+<!-- generada: no editar a mano — `npm run docs` -->
+
+| prop | atributo | tipo | default |
+|---|---|---|---|
+| `animated` | `animated` | `boolean` | `true` |
+| `ariaLabel` | `aria-label` | `null \| string` | `null` |
+| `name` | `name` | `"bar-chart" \| "bell" \| "bell-with-slash" \| "birthday-cake" \| "busts-in-silhouette" \| "card-index-dividers" \| "check-mark" \| "check-mark-button" \| "clapping-hands" \| "confused-face" \| "cross-mark" \| "delivery-truck" \| "dollar-banknote" \| "face-screaming" \| "face-with-rolling-eyes" \| "gear" \| "glowing-star" \| "grinning-face" \| "grinning-face-smiling-eyes" \| "hamburger" \| "hammer" \| "handshake" \| "house" \| "kick-scooter" \| "label" \| "locked" \| "magnifying-glass-tilted-left" \| "mobile-phone" \| "money-bag" \| "money-with-wings" \| "motorcycle" \| "neutral-face" \| "no-entry" \| "office-building" \| "package" \| "party-popper" \| "partying-face" \| "pensive-face" \| "pizza" \| "pushpin" \| "receipt" \| "rocket" \| "shop" \| "shopping-bags" \| "shopping-cart" \| "sleeping-face" \| "slightly-smiling-face" \| "smiling-face-hearts" \| "sparkles" \| "spiral-calendar" \| "star-struck" \| "taco" \| "thinking-face" \| "thumbs-up" \| "unlocked" \| "warning" \| "waving-hand" \| "wrench" \| null` | `null` |
+| `size` | `size` | `"full" \| "lg" \| "md" \| "sm" \| "xl" \| "xs"` | `'md'` |
+| `src` | `src` | `null \| string` | `null` |
+
+Eventos: ninguno.
+
+### Diferencias con el SUI Angular
+
+Ninguna en nombres de props, eventos y valores.
+<!-- api:fin -->
+
+## Trampas
+
+- **Pesan**: los animados son APNG de ~1 MB y 73 fotogramas cada uno, servidos desde
+  `raw.githubusercontent.com`. Si ese servidor se cae, no hay emoji.
+- **`animated=false` solo sirve para 5**: las caritas. El resto no tiene copia estática.
+- **`src` gana sobre `name`.**
+- **No toma color**: no responde a `currentColor` ni al tema.
+- Sin `ariaLabel` es decorativo: el lector de pantalla no lo dice.
+- `loading="lazy"`: fuera de la pantalla, no carga hasta que se acerca.
+
+## Bien y mal
+
+El emoji de un botón
+
+```html
+<!-- ❌ mal: un emoji no es un ícono (pages/orders/orders.html:323 y :354) -->
+<sui-button variant="stroke" color="neutral" size={bp.sizeControl()} onClick={() => handleMyself(order)}>
+  <sui-emoji slot="start" name="shop" size="sm" />
+  Encargarme yo
+</sui-button>
+```
+
+```html
+<!-- ✅ bien -->
+<sui-button variant="stroke" color="neutral" size={bp.sizeControl()} left-icon="store-2-line"
+            onClick={() => handleMyself(order)}>Encargarme yo</sui-button>
+```
+
+Pasos de una landing
+
+```html
+<!-- ❌ mal: lg fijo; en el celular no sube el paso que pide D16 (pages/public/landing-customers/landing-customers.html:160) -->
+<sui-emoji name="pushpin" size="lg" class="landing-customers__flow-icon"></sui-emoji>
+```
+
+```html
+<!-- ✅ bien -->
+<sui-emoji name="pushpin" size={bp.celular() ? 'xl' : 'lg'} class="landing-customers__flow-icon" />
+```
+
+Un emoji del catálogo con `<img>`
+
+```html
+<!-- ❌ mal: la URL del paquete escrita a mano, fuera del componente (pages/products/add-product/add-product.html:122) -->
+<img src="https://raw.githubusercontent.com/Tarikul-Islam-Anik/Animated-Fluent-Emojis/master/Emojis/Objects/Package.png"
+     alt="Producto" width="48" height="48" />
+```
+
+```html
+<!-- ✅ bien: decorativo, el título de al lado ya lo dice -->
+<sui-emoji name="package" size="xl" />
+```
+
+## Ejemplo
+
+```html
+<!-- Junto a un texto: un paso más en el celular (D16) -->
+<p>Pedido confirmado <sui-emoji name="party-popper" size={bp.celular() ? 'md' : 'sm'} /></p>
+
+<!-- La barra de calificación: cinco juntos, estáticos -->
+<sui-emoji name="neutral-face" size="lg" animated="false" aria-label="Regular" />
+```

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

@@ -0,0 +1,217 @@
+---
+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
+
+<!-- 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-empty-state`); 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: [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, escrita
+> en CANON-SUI §5.6 (ilustración = Fluent Emoji animado, default el zorro).
+>
+> Uso medido el 06-10-2026 en `master-pedidos/src/app` (misma exclusión que `sui-card`): **70
+> empty-states en 42 archivos**. 31 con `action` (10 con `route`). 8 con `emoji` propio y 62 sin
+> `emoji` (sale el zorro). 0 con `icon`, 0 con la URL del zorro pegada, 0 con `size`.
+
+### 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 (CANON-SUI §5.6) |
+| `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 (CANON-SUI §5.6: Fluent Emoji animado) |
+| `title` (obligatorio) | Qué pasa, sin punto y en 2 a 4 palabras, con uno de tres patrones: «Todavía no hay <cosa>», «Sin <cosa>», «Tu <cosa> está vacío» («Tu carrito está vacío», «Sin pedidos aún»). En una búsqueda, repetir lo buscado («Nada con “pollo broaster”») queda fuera de esos patrones. | canon (CANON-SUI §5.6) · lo de la búsqueda: propuesta, falta aprobación |
+| `subtitle` | Una oración con punto, en futuro tranquilizador: «Cuando hagas tu primer pedido, aparecerá aquí.» | canon (CANON-SUI §5.6) |
+| `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`. | canon (aprobado por el dueño, 05-10-2026, bloque B10) |
+| sin `action` | No hay un paso obvio, o la pantalla ya tiene el botón para llenarla (el «Nuevo local» de arriba). | canon (aprobado por el dueño, 05-10-2026, bloque B9) |
+| error de carga | Siempre con `action="Reintentar"`. Excepción: la pantalla reintenta sola y lo dice («Seguimos intentando»). | canon (aprobado por el dueño, 05-10-2026, bloque B4) |
+
+**Usos de hoy que rompen las reglas:** 0. Los 29 `icon="…"` (que no es un input), las 22 URL del
+zorro pegadas a mano y los 4 errores de carga sin «Reintentar» se corrigieron el 03-10-2026 (commit
+`461efbec` de la app). `pages/public/pedido-en-vivo/pedido-en-vivo.html:50` sigue sin «Reintentar»
+a propósito: reintenta solo y lo dice.
+
+## 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) | el tamaño es extensión SUI aprobada (03-10-2026) · mobile: canon (decisión del dueño 04-10-2026, piso táctil 44) · web: D16, dueño 05-10-2026 (fila `button`) |
+
+```html
+<sui-empty-state
+  title="Tu carrito está vacío"
+  action={{ label: 'Ver negocios', route: '/cliente/inicio' }}
+  size={bp.sizeControl()} />
+```
+
+### Por dispositivo (D16)
+
+El `size` es el del botón de la acción, que se toca: sigue la fila `button` de D16. Sin `action`,
+`size` no cambia nada y no hace falta pasarlo.
+
+| dispositivo | size | nota |
+|---|---|---|
+| celular chico (< 380) | `large` | D16 pide `medium` con área de 44, pero el DS todavía no la estira: hasta entonces, `large` |
+| celular (380–767) | `large` (48) | |
+| tablet táctil (`pointer: coarse`) | `large` | Apple pide 44 también en iPad |
+| computadora (`pointer: fine`) | `medium` (40) | el default |
+
+Ultrawide: igual que la computadora. Fuente: D16, dueño 05-10-2026.
+
+En master-pedidos: `size={bp.sizeControl()}` en todo empty-state con `action`. Medido el
+06-10-2026: 0 de los 31 con `action` lo pasan, así que en el celular y la tablet todos salen en 40.
+
+## «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` -->
+
+| prop | atributo | tipo | default |
+|---|---|---|---|
+| `action` | `action` | `SuiEmptyStateAction \| null \| string` | `null` |
+| `emoji` | `emoji` | `null \| string` | `null` |
+| `heading` | `heading` | `null \| string` | `null` |
+| `size` | `size` | `"large" \| "medium"` | `'medium'` |
+| `subtitle` | `subtitle` | `null \| string` | `null` |
+
+| evento | `event.detail` |
+|---|---|
+| `actionClicked` | `void` |
+
+Slots: `action`.
+
+### Diferencias con el SUI Angular
+
+- **Props de Angular que aquí no existen:** `title`
+- **Props solo de aquí:** `heading`
+<!-- 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.
+
+## Bien y mal
+
+La acción en el celular
+
+```html
+<!-- ❌ mal: sin size el botón sale en 40 también en el celular (pages/customer/cart/cart.html:18) -->
+<sui-empty-state
+  title="Tu carrito está vacío"
+  action={{ label: 'Explorar negocios', route: '/cliente/inicio' }} />
+```
+
+```html
+<!-- ✅ bien -->
+<sui-empty-state
+  title="Tu carrito está vacío"
+  action={{ label: 'Explorar negocios', route: '/cliente/inicio' }}
+  size={bp.sizeControl()} />
+```
+
+Un emoji propio
+
+```html
+<!-- ❌ mal: emoji es una URL, no un nombre de sui-emoji; 'hourglass' no carga nada -->
+<sui-empty-state emoji="hourglass" title="Aún no tienes facturas" />
+```
+
+```html
+<!-- ✅ bien: la URL de FLUENT_EMOJI_ANIM, como pages/invoices/invoices.ts:50 -->
+<sui-empty-state emoji={emptyEmoji} title="Aún no tienes facturas" />
+<!-- emptyEmoji = FLUENT_EMOJI_ANIM.hourglass -->
+```
+
+Mientras carga
+
+```html
+<!-- ❌ mal: mientras llega la lista se lee «no hay nada» por un segundo -->
+@if (pedidos().length === 0) {
+  <sui-empty-state title="Sin pedidos aún" />
+}
+```
+
+```html
+<!-- ✅ bien: skeleton hasta que cargue; el vacío solo con la lista ya cargada (el guard `hasLoaded()` es el de pages/locations/locations.html:15; esa pantalla, mientras carga, muestra un texto y no un skeleton) -->
+@if (isLoading()) { <!-- skeleton de la lista --> }
+@else if (hasLoaded() && pedidos().length === 0) { <sui-empty-state title="Sin pedidos aún" /> }
+```
+
+## 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"
+  onActionClicked={() => cargar()} />
+```