@ajuarezso/sui-design-system 0.20.0 → 0.22.0

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()" />
+```

package/docs/sui-file-upload/README.md

@@ -0,0 +1,154 @@
+---
+name: sui-file-upload
+selector: sui-file-upload
+resumen: Área para arrastrar o elegir archivos que no son una foto (PDF, Excel, CSV)
+alternativas: [sui-image-upload (una sola imagen con vista previa: logo, portada, comprobante), sui-image-upload-profile (foto de perfil con botones Subir/Cambiar/Eliminar), sui-file-upload-card (el archivo ya elegido, con su progreso)]
+---
+
+# sui-file-upload
+
+Story: [Molecules/Upload/File Upload](https://sui-design-system.web.app/?path=/docs/molecules-upload-file-upload--docs)
+
+## Cuándo usarlo / cuándo no
+
+**Úsalo** para subir **documentos**: un PDF, un Excel, un CSV, o varios archivos a la vez. La
+persona arrastra el archivo o toca para buscarlo.
+
+**No lo uses** para:
+
+- **Una imagen** (logo, portada, foto del producto, captura del Yape): `sui-image-upload`, que
+  muestra la vista previa y se integra con el recortador y el compresor de la app.
+- Una foto de perfil con botones: `sui-image-upload-profile`.
+- Mostrar el archivo que ya se eligió: va `sui-file-upload-card` debajo.
+
+Regla corta: **foto → image-upload · documento o varios archivos → file-upload · el archivo ya
+elegido → file-upload-card.**
+
+## Qué variante usar
+
+> **Lo que dice la guía del DS** (página del file upload): es la forma de **arrastrar y soltar, o
+> buscar en el equipo**, para subir un archivo. Su ejemplo arma el texto así: una línea que invita
+> («Elige un archivo o arrástralo aquí»), una línea con **formatos y tamaño máximo** («JPEG, PNG,
+> PDF y MP4, hasta 50 MB») y el botón **«Buscar archivo»**. Trae aparte el ícono por tipo de
+> archivo (en SUI, `sui-file-icon`). No dice cuándo usar cada tamaño. El resto es **propuesta,
+> falta aprobación**.
+>
+> Uso medido el 03-10-2026 en `master-pedidos/src/app`: **0 usos**. Hoy todo lo que se sube es
+> imagen y va con `sui-image-upload` (13) o con un `<input type="file">` a mano (3: `renewal-modal`,
+> `add-product` y la miniatura de `option-image`; ver el README de `sui-image-upload`).
+
+### Textos: `title`, `subtitle`, `browseLabel`
+
+| input | cuándo | fuente |
+|---|---|---|
+| `title` | Qué se sube, en la voz de la persona: «Sube tu carta en PDF», «Arrastra tu Excel aquí». Si se omite, sale «Arrastra y suelta el archivo aquí». | guía (línea que invita) |
+| `subtitle` | **Formatos y tamaño máximo**, siempre: «PDF o Excel, hasta 10 MB». El default «o haz clic para seleccionar» no dice nada que el área no diga. | guía (formatos y tamaño) |
+| `browseLabel` | El default ya es «Buscar archivo»; se pasa solo para otro texto («Elegir foto»). | guía (el botón) · el texto es propuesta |
+
+### `accept`, `multiple`, `maxSize`
+
+| input | cuándo | fuente |
+|---|---|---|
+| `accept` | Siempre, con lo mismo que dice el `subtitle`: `".pdf,.xlsx,.csv"`. Si el texto y el filtro no coinciden, la persona elige un archivo que se rechaza. | propuesta |
+| `multiple` | Varios archivos del mismo tipo (las boletas del mes). Con `multiple` cada archivo va en su `sui-file-upload-card`. | propuesta |
+| `maxSize` | Siempre, en **bytes** (`10 * 1024 * 1024`), y el mismo número en el `subtitle`. | propuesta |
+
+### `size`
+
+| valor | padding | cuándo | fuente |
+|---|---|---|---|
+| `small` | 24 | En mobile y dentro de un modal o una card. | propuesta |
+| `medium` (default) | 32 | En web, en una página o un modal ancho. | guía (es el único tamaño que muestra) |
+| `large` | 40 | Cuando subir el archivo es lo único de la pantalla (importar la carta). | propuesta |
+| `xlarge` | 48 | No usar: más aire no ayuda a soltar el archivo. | no usar |
+
+### Estados: `error`, `errorMessage`, `disabled`
+
+| input | cuándo | fuente |
+|---|---|---|
+| `error` + `errorMessage` | El archivo se subió y el servidor lo rechazó («El PDF está protegido con clave»). Lo de tamaño y tipo ya lo avisa solo. | propuesta |
+| `disabled` | Mientras se sube, o si ya se llegó al máximo de archivos. | propuesta |
+
+Usos de hoy que rompen la regla: **0** (no hay file-upload).
+
+## Tamaño en mobile y en web
+
+En mobile se toca con el dedo: lo que se toca mide **44 px o más**. Aquí **toda el área se toca**
+(abre el selector), así que pasa en cualquier tamaño; en el celular no se arrastra, por eso va
+más compacta. En pantallas de los dos, con el servicio de breakpoints de la app (`bp`, en
+`services/breakpoints.service.ts`).
+
+| uso | mobile | web | fuente |
+|---|---|---|---|
+| subir un documento en un formulario o modal | `small` | `medium` | propuesta |
+| subir es lo único de la pantalla | `medium` | `large` | propuesta |
+
+```html
+<sui-file-upload [size]="bp.isMobile() ? 'small' : 'medium'"
+                 title="Sube tu carta en PDF" subtitle="PDF, hasta 10 MB"
+                 accept=".pdf" [maxSize]="10 * 1024 * 1024" (filesSelected)="subir($event)" />
+```
+
+Llena el ancho del contenedor (antes 400 fijo; extensión SUI, 03-10-2026). El botón «Buscar
+archivo» mide 32 px (`xsmall`) en todos los tamaños: solo, en mobile **no
+llegaría**; pasa porque el área entera también abre el selector.
+
+## «No usar»: por qué no hoy y cuándo sí
+
+Nada se borra del DS. Lo marcado «no usar» no tiene caso en la app de hoy; si un flujo nuevo cae
+en la columna de la derecha, se usa (aprobado por el dueño, 03-10-2026).
+
+| qué | por qué no hoy | cuándo sí, en un flujo nuevo |
+|---|---|---|
+| todo el componente (0 usos) | todo lo que se sube hoy es una imagen | la carta del local en PDF o Excel para cargarla, la ficha RUC, los documentos del repartidor escaneados en PDF |
+| `multiple` | no hay subidas de varios archivos | las boletas del mes de un gasto, varias fotos de un reclamo |
+| `size="xlarge"` | más aire no ayuda | ninguno |
+| para imágenes | no muestra la vista previa ni pasa por el recortador | — |
+
+## API
+
+<!-- api:inicio -->
+<!-- generada: no editar a mano — `npm run docs` -->
+
+| input | tipo | default |
+|---|---|---|
+| `accept` | `string` | `''` |
+| `multiple` | `boolean` | `false` |
+| `maxSize` | `number` | `0` |
+| `title` | `string \| null` | `null` |
+| `subtitle` | `string \| null` | `null` |
+| `browseLabel` | `string` | `'Buscar archivo'` |
+| `disabled` | `boolean` | `false` |
+| `error` | `boolean` | `false` |
+| `errorMessage` | `string \| null` | `null` |
+| `size` | `'small' \| 'medium' \| 'large' \| 'xlarge'` | `'medium'` |
+
+| output | payload |
+|---|---|
+| `filesSelected` | `File[]` |
+| `errorEvent` | `string` |
+<!-- api:fin -->
+
+## Trampas
+
+- `browseLabel` dice «Buscar archivo» por defecto (antes «Browse File»).
+- **Llena el ancho del contenedor** desde el 03-10-2026 (antes medía 400 fijo y había que forzar
+  `style="width: 100%"`). Las pantallas que lo dejaban en 400 en un contenedor ancho ahora se
+  estiran; para un ancho fijo, se lo pone el consumer al host.
+- **`maxSize` va en bytes**, no en MB. `0` = sin límite.
+- **Emite solo los archivos válidos**: si de tres uno pesa de más, `filesSelected` trae dos y
+  `errorEvent` avisa del tercero (con el texto ya armado: «"x.pdf" supera el tamaño máximo (10.0 MB)»).
+- Sin `multiple`, aunque se suelten varios, **emite solo el primero**.
+- `accept` filtra al elegir **y** al soltar, por extensión (`.pdf`) o por tipo (`image/*`).
+- El error interno queda pegado hasta el próximo intento válido; `errorMessage` gana sobre él.
+- **No sube nada**: entrega los `File` y la subida (y el progreso en `sui-file-upload-card`) la
+  hace quien lo usa.
+- El atributo `title` del host se borra solo (no sale el tooltip gris del navegador).
+
+## Ejemplo
+
+```html
+<sui-file-upload title="Sube tu carta en PDF o Excel" subtitle="PDF o Excel, hasta 10 MB"
+                 browseLabel="Buscar archivo" accept=".pdf,.xlsx" [maxSize]="10 * 1024 * 1024"
+                 (filesSelected)="subirCarta($event)" (errorEvent)="avisar($event)" />
+```

package/docs/sui-file-upload-card/README.md

@@ -0,0 +1,129 @@
+---
+name: sui-file-upload-card
+selector: sui-file-upload-card
+resumen: La fila de un archivo que se está subiendo, con su progreso, listo o error para reintentar
+alternativas: [sui-file-upload (el área para elegir el archivo), sui-image-upload (una imagen: muestra la vista previa en vez de la fila), sui-file-icon (un archivo en una lista, sin subida)]
+---
+
+# sui-file-upload-card
+
+Story: [Molecules/Upload/File Upload Card](https://sui-design-system.web.app/?path=/docs/molecules-upload-file-upload-card--docs)
+
+## Cuándo usarlo / cuándo no
+
+**Úsalo** debajo de un `sui-file-upload`, una fila por archivo, para mostrar **cómo va la subida**:
+subiendo con su barra, listo, o falló con «Reintentar».
+
+**No lo uses** para:
+
+- Una imagen: `sui-image-upload` muestra la vista previa, que dice más que un nombre de archivo.
+- Una lista de archivos ya guardados (sin subida): `sui-file-icon` en una fila normal.
+- Un progreso que no es de un archivo: `sui-progress-bar`.
+
+## Qué variante usar
+
+> **La guía del DS no tiene página para este componente** (su página del file upload solo muestra
+> el área y el ícono por tipo). Todo es **propuesta, falta aprobación**.
+>
+> Uso medido el 03-10-2026 en `master-pedidos/src/app`: **0 usos**. Las subidas de hoy son de
+> imágenes y avisan con el `subtitle` del image-upload («Procesando…») o lo deshabilitan.
+
+### `state`
+
+| valor | cuándo | qué muestra | fuente |
+|---|---|---|---|
+| `in-progress` (default) | Mientras sube. Va con `progress`. | barra azul, ícono de carga, X para cancelar | propuesta |
+| `success` | Subió. | check verde, tacho para quitar | propuesta |
+| `error` | Falló. Va con `statusText` que diga por qué. | ícono rojo, «Reintentar», tacho | propuesta |
+
+### Textos y datos
+
+| input | cuándo | fuente |
+|---|---|---|
+| `file` | El nombre real del archivo (`'carta-octubre.pdf'`). La extensión da el ícono y el color. | propuesta |
+| `description` | **Siempre** se pasa: el default es un texto de ejemplo («0 KB de 120 KB»). Subiendo: «1,2 MB de 3,4 MB»; listo: «3,4 MB». | propuesta |
+| `progress` | 0–100, solo en `in-progress`. | propuesta |
+| `statusText` | Los defaults ya están en español («Subiendo…», «Completado», «Falló»); en error, mejor el motivo: «Se cortó la conexión». | propuesta |
+| `showStatus=false` | Solo en `success`, cuando el check sobra porque la lista ya dice «Archivos subidos». | propuesta |
+| `retryLabel` | El default ya es «Reintentar». | propuesta |
+
+Usos de hoy que rompen la regla: **0**.
+
+## Tamaño en mobile y en web
+
+**No tiene `size`.** Llena el ancho del contenedor (antes 400 fijo) y la X o el tacho de la derecha
+es un `sui-compact-button` `2xlarge` de **32 px** (Figma: 24), que con el aire de la tarjeta (16 de
+padding, 72 de alto mínimo) se toca bien con el dedo. «Reintentar» sigue siendo un link de 20 px de
+alto: en mobile conviene que la fila entera también reintente.
+
+| pieza | mobile | web | fuente |
+|---|---|---|---|
+| ancho | el del contenedor | el del contenedor | canon (aprobado por el dueño, 03-10-2026), extensión SUI |
+| X / tacho | 32 px | 32 px | canon (aprobado por el dueño, 03-10-2026), extensión SUI |
+| «Reintentar» | link de 20 px — **no llega** | link | medido |
+
+```html
+<sui-file-upload-card [file]="a.nombre" [state]="a.estado" [progress]="a.pct"
+                      [description]="a.peso" (actionClicked)="quitar(a)" (retryClicked)="reintentar(a)" />
+```
+
+## «No usar»: por qué no hoy y cuándo sí
+
+Nada se borra del DS. Lo marcado «no usar» no tiene caso en la app de hoy; si un flujo nuevo cae
+en la columna de la derecha, se usa (aprobado por el dueño, 03-10-2026).
+
+| qué | por qué no hoy | cuándo sí, en un flujo nuevo |
+|---|---|---|
+| todo el componente (0 usos) | todo lo que se sube es una imagen y se ve con su vista previa | junto a `sui-file-upload`: la carta en PDF, varias boletas de un gasto, documentos del repartidor |
+| para imágenes | la vista previa dice más que el nombre del archivo | — |
+
+## API
+
+<!-- api:inicio -->
+<!-- generada: no editar a mano — `npm run docs` -->
+
+| input | tipo | default |
+|---|---|---|
+| `file` | `SuiFileUploadCardFile \| string` | `'file.pdf'` |
+| `description` | `string` | `'0 KB de 120 KB'` |
+| `state` | `'in-progress' \| 'success' \| 'error'` | `'in-progress'` |
+| `progress` | `number` | `10` |
+| `statusText` | `string \| null` | `null` |
+| `showStatus` | `boolean` | `true` |
+| `cancelLabel` | `string` | `'Cancelar subida'` |
+| `removeLabel` | `string` | `'Quitar archivo'` |
+| `progressLabel` | `string` | `'Progreso de la subida'` |
+| `retryLabel` | `string` | `'Reintentar'` |
+
+| output | payload |
+|---|---|
+| `actionClicked` | `void` |
+| `retryClicked` | `void` |
+<!-- api:fin -->
+
+```ts
+interface SuiFileUploadCardFile { filename: string; extension?: string; }
+```
+
+## Trampas
+
+- Los textos de fábrica están en español desde el 03-10-2026: «0 KB de 120 KB», «Subiendo…»,
+  «Completado», «Falló», «Reintentar», y para el lector de pantalla «Cancelar subida», «Quitar
+  archivo» y «Progreso de la subida» (estos tres, con `cancelLabel`, `removeLabel` y
+  `progressLabel`).
+- Llena el ancho del contenedor, igual que `sui-file-upload` (antes 400 fijo).
+- **`progress` arranca en 10**, no en 0.
+- **`actionClicked` significa dos cosas**: cancelar mientras sube y quitar cuando terminó. Quien lo
+  usa mira `state` para saber cuál.
+- La barra de progreso es azul, no naranja.
+- No sube nada: refleja el estado que le pasan.
+
+## Ejemplo
+
+```html
+<sui-file-upload-card file="carta-octubre.pdf" state="in-progress" [progress]="45"
+                      description="1,2 MB de 2,6 MB" statusText="Subiendo…" />
+<sui-file-upload-card file="carta-octubre.pdf" state="error" description="2,6 MB"
+                      statusText="Se cortó la conexión" retryLabel="Reintentar"
+                      (retryClicked)="reintentar()" (actionClicked)="quitar()" />
+```

package/docs/sui-filter/README.md

@@ -0,0 +1,181 @@
+---
+name: sui-filter
+selector: sui-filter-bar, sui-filter-item, sui-filter-panel-header, sui-filter-panel-footer
+resumen: Piezas de filtros de una lista o tabla del panel; la barra horizontal (buscador, vista, orden) y el panel vertical (fila, cabecera con «Limpiar», pie con «Limpiar» / «Aplicar»)
+alternativas: [sui-segmented-control (2 a 4 vistas que se aplican al instante), sui-compact-select (un filtro suelto), sui-tab-chips (filtros rápidos con chips), sui-activity-filter (filtro del feed de actividad), sui-modal-sheet (el panel de filtros en mobile)]
+---
+
+# sui-filter
+
+Story: [Organisms/Filter Bar](https://sui-design-system.web.app/?path=/docs/organisms-filter-bar--docs)
+
+Son **cuatro componentes** en una carpeta, sin uno llamado `sui-filter`:
+
+- `sui-filter-bar`: la **barra horizontal** arriba de una tabla. Es solo layout: un lado
+  izquierdo (`slot="start"`) y uno derecho (`slot="end"`); los controles se proyectan.
+- `sui-filter-item`: una **fila** del panel vertical (una categoría de filtro: «Estado», «Local»).
+- `sui-filter-panel-header`: la **cabecera** del panel, con un link «Limpiar» opcional.
+- `sui-filter-panel-footer`: el **pie** del panel, con «Limpiar» y «Aplicar».
+
+El panel vertical **no existe como contenedor**: se arma con header + items + footer dentro de un
+`sui-dropdown-menu` (web) o de un `sui-modal-sheet` (mobile).
+
+## Cuándo usarlo / cuándo no
+
+**Úsalo** en las listas y tablas del panel del local o del super admin que necesitan filtrar
+(pedidos, productos, repartidores): la barra arriba con el buscador, la vista y el orden; el panel
+cuando hay varias categorías de filtro que se combinan y se aplican juntas.
+
+**No lo uses** para:
+
+- 2 a 4 vistas que se aplican al tocar (Hoy · Semana · Mes): `sui-segmented-control` solo, sin barra.
+- Un único filtro: un `sui-compact-select` o `sui-select` suelto.
+- Filtros rápidos de un toque en mobile (Todos · Pendientes · Entregados): `sui-tab-chips`.
+- El feed de actividad: `sui-activity-filter`.
+
+Regla corta: **barra arriba de una tabla → filter-bar · varias categorías que se aplican juntas →
+panel (header + items + footer) · un filtro suelto → compact-select.**
+
+## Qué variante usar
+
+> **La guía del DS no tiene página de filtros**: estas piezas salen solo del Figma del DS
+> («Filters»: HorizontalFilter y VerticalFilter). Todo lo de abajo es **propuesta, falta
+> aprobación**, salvo lo marcado canon.
+>
+> Uso medido el 03-10-2026 en `master-pedidos/src/app` (misma exclusión que `sui-dropdown-menu`):
+> **0 usos**. Solo aparecen en la vitrina `master-preview`.
+
+### `sui-filter-bar`
+
+| variant | cuándo | fuente |
+|---|---|---|
+| `table` (default) | Arriba de una tabla: a la izquierda la vista (`sui-segmented-control`), a la derecha el buscador (`sui-input type="search"`) y el orden (`sui-select` o `sui-compact-select`). | propuesta (composición del Figma) |
+| `calendar` | Arriba de una vista por fechas: a la izquierda «Hoy» + el rango (`sui-button-group`), a la derecha el buscador. | propuesta (composición del Figma) |
+
+`variant` solo marca el host (`data-sui-variant`): **no cambia el layout**. Lo que se ve lo deciden
+los controles que se proyectan.
+
+### El panel: `sui-filter-item` + header + footer
+
+| pieza | regla | fuente |
+|---|---|---|
+| `sui-filter-item` `active` | La categoría abierta (la que muestra sus opciones al lado): fondo gris, texto negro, flecha a la derecha. | propuesta (estados del Figma) |
+| `sui-filter-item` `leftIcon` | Un ícono por categoría si ayuda a ubicarla («Estado», «Local», «Repartidor»). | propuesta |
+| `sui-filter-panel-header` `clear` | Pásale texto (`clear="Limpiar"`), no `true`: con `true` dice «Clear». | canon (CANON-SUI §5: copy en español) |
+| `sui-filter-panel-footer` | «Limpiar» a la izquierda (`stroke neutral`), «Aplicar» a la derecha (`filled primary`), mitad y mitad. | canon (orden de `sui-modal-footer`, CLAUDE.md «Botones») |
+| «Limpiar» en header **y** footer | Elegir uno. Con el footer, el header va sin link. | propuesta |
+| `applyButton` deshabilitado | `{ label: 'Aplicar', disabled: !cambio() }` mientras no se toca nada. | propuesta |
+
+## Tamaño en mobile y en web
+
+Ninguna pieza cambia sola en mobile, salvo la barra, que apila sus dos lados por debajo de 640 px.
+
+| pieza | mobile | web | fuente |
+|---|---|---|---|
+| `sui-filter-bar` | sin tamaño; los controles adentro van `large` (48) | sin tamaño; los controles `small` (36) | propuesta (igual que `sui-compact-select` en una barra) |
+| `sui-filter-item` | 36 de alto, no se puede cambiar: debajo de los 44 del dedo | 36 | propuesta |
+| `sui-filter-panel-footer` | `medium` (40) es lo más grande que tiene; en mobile, mejor `sui-modal-footer` (48) dentro de un `sui-modal-sheet` | `small` (36, default) | canon para el 48 de mobile (CLAUDE.md: footer de modal `large`); el resto, propuesta |
+| `sui-filter-panel-header` | sin tamaño | sin tamaño | — |
+
+```html
+<sui-filter-bar>
+  <sui-segmented-control slot="start" … />
+  <div slot="end">
+    <sui-input type="search" [size]="bp.isMobile() ? 'large' : 'small'" placeholder="Buscar pedido…" … />
+  </div>
+</sui-filter-bar>
+```
+
+## API
+
+<!-- api:inicio -->
+<!-- generada: no editar a mano — `npm run docs` -->
+
+### `sui-filter-bar`
+
+| input | tipo | default |
+|---|---|---|
+| `variant` | `'calendar' \| 'table'` | `'table'` |
+
+Outputs: ninguno.
+
+### `sui-filter-item`
+
+| input | tipo | default |
+|---|---|---|
+| `active` | `boolean` | `false` |
+| `disabled` | `boolean` | `false` |
+| `leftIcon` | `string \| null` | `null` |
+| `activeIcon` | `string` | `'arrow-right-s-line'` |
+
+| output | payload |
+|---|---|
+| `selected` | `Event` |
+
+### `sui-filter-panel-footer`
+
+| input | tipo | default |
+|---|---|---|
+| `clearButton` | `SuiFooterButtonConfig \| string` | `'Clear'` |
+| `applyButton` | `SuiFooterButtonConfig \| string` | `'Apply'` |
+| `size` | `'small' \| 'medium'` | `'small'` |
+
+| output | payload |
+|---|---|
+| `clear` | `void` |
+| `apply` | `void` |
+
+### `sui-filter-panel-header`
+
+| input | tipo | default |
+|---|---|---|
+| `label` | `string` | `''` |
+| `leftIcon` | `string \| null` | `null` |
+| `clear` | `string \| boolean` | `false` |
+
+| output | payload |
+|---|---|
+| `clearClick` | `void` |
+<!-- api:fin -->
+
+Slots de `sui-filter-bar`: `[slot=start]`, `[slot=end]` y el contenido por defecto (fila única si no
+se usan los slots). El label de `sui-filter-item` es su contenido proyectado. `clearButton` y
+`applyButton` aceptan un string o `SuiFooterButtonConfig` (`{ label, disabled? }`, la misma interfaz
+de `sui-drawer-footer`).
+
+## Trampas
+
+- **Los textos por defecto están en inglés**: «Clear» y «Apply» en el footer, «Clear» en el header con
+  `clear=true`. Pásalos siempre.
+- **La barra apila a 640 px; la app cambia a mobile a 767.** Entre 641 y 767 px la app ya está en
+  mobile y la barra sigue en una fila.
+- **Varios controles en un lado van en un contenedor.** Cada slot es una fila con 12 px de separación,
+  pero un solo elemento por `slot` queda más ordenado (`<div slot="end">`), como en el Figma.
+- **`sui-filter-item` tiene `role="option"`**: el contenedor tiene que llevar `role="listbox"`.
+- **`active` no es «elegido»**: marca la categoría abierta, no un valor aplicado. Para decir que una
+  categoría tiene un filtro puesto no hay prop (un `sui-badge` en el label es lo más cercano).
+- **El footer separa sus botones 16 px** (del Figma); el canon de la app entre botones hermanos es 12
+  (CANON-SUI §0, `sui-modal-footer`).
+- El footer no llega a `large`: en mobile queda más chico que el footer de cualquier modal.
+- `disabled` del item usa opacidad (no está en el Figma).
+
+## Ejemplo
+
+```html
+<!-- Panel de filtros en web, anclado a un botón «Filtros» -->
+<sui-dropdown-menu #filtros="suiDropdownMenu" [minWidth]="320">
+  <sui-button trigger variant="stroke" color="neutral" size="small">Filtros</sui-button>
+  <ng-template suiDropdownPanel>
+    <sui-filter-panel-header label="Filtros" leftIcon="equalizer-line" />
+    <div role="listbox" aria-label="Categorías de filtro">
+      <sui-filter-item leftIcon="checkbox-circle-line" [active]="cat() === 'estado'"
+                       (selected)="cat.set('estado')">Estado</sui-filter-item>
+      <sui-filter-item leftIcon="store-2-line" [active]="cat() === 'local'"
+                       (selected)="cat.set('local')">Local</sui-filter-item>
+    </div>
+    <sui-filter-panel-footer clearButton="Limpiar"
+                             [applyButton]="{ label: 'Aplicar', disabled: !cambio() }"
+                             (clear)="limpiar()" (apply)="filtros.close(); aplicar()" />
+  </ng-template>
+</sui-dropdown-menu>
+```