@ajuarezso/sui-design-system 0.20.0 → 0.21.0

package/docs/sui-store-card/README.md

@@ -0,0 +1,147 @@
+---
+name: sui-store-card
+selector: sui-store-card
+resumen: Tarjeta de un local para los listados del cliente con portada, logo, abierto/cerrado, favorito, nota, ubicación, envío y distancia
+alternativas: [sui-product-card (un producto, no un local), sui-content-card (un local en una fila de un panel, sin portada), sui-card (cualquier otro contenido)]
+---
+
+# sui-store-card
+
+Story: [Molecules/Card/Store Card](https://sui-design-system.web.app/?path=/docs/molecules-card-store-card--docs)
+
+## Cuándo usarlo / cuándo no
+
+**Úsalo** para un local en un listado que ve el cliente (favoritos) y para la vista previa de un
+local que el super admin aprueba o que el dueño revisa antes de publicar.
+
+**No lo uses** para:
+
+- Un local en una tabla o un ranking de un panel: `sui-content-card` o una fila (sin portada).
+- Un producto: `sui-product-card`.
+- Fuera de la app de Master Pedidos: el link va fijo a `/cliente/restaurante/:id` (ver Trampas).
+
+Regla corta: **local en un listado del cliente → store-card · local en un panel → content-card.**
+
+## Qué variante usar
+
+> **La guía del DS no tiene página de la store card.** Es un componente propio de SUI. Igual que
+> la product card, **dibuja, no decide**: el texto del envío y de la distancia le llega escrito
+> (`deliveryText`, `distanceText`) desde que la tarjeta y el checkout cobraban distinto.
+>
+> Uso medido el 03-10-2026 en `master-pedidos/src/app` (misma exclusión que `sui-card`): **2
+> store-cards en 2 archivos**: favoritos del cliente (`pages/customer/favorites/favorites.html:121`,
+> con `deliveryText` y `distanceText`) y la cola de aprobación
+> (`pages/super-admin/master-approvals/master-approvals.html:32`, en vista previa). El inicio del
+> cliente arma sus filas de locales con clases propias.
+
+### Los estados (salen de `store`)
+
+| estado | cuándo | fuente |
+|---|---|---|
+| `isOpen: true` | Abierto: chip verde «Abierto». | propuesta |
+| `isOpen: false` | Cerrado: chip «Cerrado» y la portada en gris; sigue abriendo la carta (se puede mirar). | propuesta |
+| `isSuspended: true` | No se puede pedir: «No disponible», toda la tarjeta al 60 % y sin link. | propuesta |
+| `isOwnerPreview` + `ownerPreviewStatus` | Vista previa: «Borrador», «En revisión» o «Rechazado»; sin corazón, sin nota ni distancia (solo ubicación y envío). | propuesta |
+
+### Las piezas
+
+| prop | cuándo | fuente |
+|---|---|---|
+| `store` (obligatorio) | Siempre, con `SuiStoreCardData`. | propuesta |
+| `deliveryText` string | **Siempre en pantallas nuevas**: el texto del envío calculado por la app (`StateService.computeDeliveryFee`). | propuesta (precedente: favoritos) |
+| `deliveryText = null` | No hay envío que mostrar: la columna desaparece y el distrito deja de cortarse. | propuesta |
+| `deliveryText` sin pasar | La tarjeta lo deduce de `deliveryType` (Gratis / Recojo / Courier / S/ X). Solo para no romper lo viejo. | propuesta |
+| `distanceText` | Lo mismo para la distancia: un rango mientras es estimada («menos de 500 m»), el número cuando la ruta se midió («475 m»). `null` la quita. | propuesta |
+| `isFavorite` + `(toggleFavorite)` | El corazón lleno o vacío; el padre guarda el favorito. | propuesta |
+| `(ratingClicked)` | La nota abre las opiniones y la info del local (`StoreRatingsModalService`). | propuesta |
+| `disableLink` | La tarjeta no navega (una vitrina, una lámina, una vista previa). | propuesta |
+
+**Usos de hoy que rompen las reglas:** 0. A mirar: la cola de aprobación no pasa
+`deliveryText` (deduce el envío del `deliveryType`).
+
+## Tamaño en mobile y en web
+
+El ancho lo da el contenedor. El `size` cambia **el corazón de favorito**, en la escala del
+`sui-button`:
+
+| size | corazón | glyph | fuente |
+|---|---|---|---|
+| `small` (default) | 36 × 36 | 18 | lo que había en el DS |
+| `medium` | 40 × 40 | 20 | canon (aprobado por el dueño, 03-10-2026): extensión SUI |
+
+| uso | mobile | web | fuente |
+|---|---|---|---|
+| tarjeta | ancho completo | celda de una grilla de 2–3 columnas (≥ 300 de ancho) | lo que hay en la app |
+| corazón de favorito | `medium` (40) | `small` (36) | propuesta: el tamaño es extensión SUI aprobada (03-10-2026); el «cuándo» falta aprobarlo |
+| nota (abre las opiniones) | el alto de su columna (~40) | ~40 | lo que hay en el DS |
+
+```html
+<sui-store-card [store]="local" [size]="bp.isMobile() ? 'medium' : 'small'" />
+```
+
+## «No usar»: por qué no hoy y cuándo sí
+
+| qué | por qué no hoy | cuándo sí, en un flujo nuevo |
+|---|---|---|
+| `deliveryText` / `distanceText` sin pasar | la tarjeta deduciría un precio distinto del checkout | nunca en pantallas nuevas |
+| la tarjeta en un ancho menor a ~300 | la fila de 4 datos se pisa | nunca: con menos ancho, pasa `null` a la distancia o al envío |
+
+## API
+
+<!-- api:inicio -->
+<!-- generada: no editar a mano — `npm run docs` -->
+
+| input | tipo | default |
+|---|---|---|
+| `store` | `SuiStoreCardData` | — (requerido) |
+| `isFavorite` | `boolean` | `false` |
+| `disableLink` | `boolean` | `false` |
+| `linkBase` | `string` | `'/cliente/restaurante'` |
+| `size` | `'small' \| 'medium'` | `'small'` |
+| `deliveryText` | `string \| null` | `undefined` |
+| `distanceText` | `string \| null` | `undefined` |
+
+| output | payload |
+|---|---|
+| `toggleFavorite` | `Event` |
+| `ratingClicked` | `{ id: string; name: string; logoUrl: string \| null }` |
+<!-- api:fin -->
+
+`SuiStoreCardData`: `id`, `name` y opcionales `businessType`, `district`, `rating`,
+`reviewCount`, `distanceKm`, `deliveryFee`, `deliveryType`, `offersPickup`, `isOpen`,
+`isSuspended`, `isOwnerPreview`, `ownerPreviewStatus`, `ownerRejectionReason`,
+`isOwnerApproved`, `logoUrl`, `coverUrl`.
+
+## Trampas
+
+- **El link va a `[linkBase, store.id]`** (`RouterLink` adentro). `linkBase` es
+  `'/cliente/restaurante'` por defecto (la ruta del cliente de Master Pedidos); otra app pasa la
+  suya. Para no navegar, `disableLink`.
+- **Los botones (corazón, nota) viven dentro del `<a>`** de la tarjeta: un control interactivo
+  dentro de un link es HTML inválido. Cortan la propagación y el `preventDefault`, así que
+  funcionan; queda pendiente pasarla al patrón de `sui-product-card` (link estirado).
+- **`null` y «no pasar» no son lo mismo** en `deliveryText` / `distanceText`: `null` quita la
+  columna, `undefined` la deduce.
+- La nota sale como «4.62 (38)», con punto y hasta dos decimales; **sin opiniones dice «5.0
+  (0)»** a propósito (el cero se ve).
+- `ownerRejectionReason` e `isOwnerApproved` están en la interfaz pero la tarjeta **no los
+  dibuja**: el motivo del rechazo y el aviso de «ya estás público» van afuera.
+- Un `distanceText` largo («menos de 500 m») en una tarjeta angosta **parte en dos líneas** por
+  palabras (desde 03-10-2026; antes se salía de su columna). La columna no baja de 64 px; la nota
+  y el envío no se encogen, y el distrito se recorta con «…».
+- La portada carga con `loading="lazy"` y reintenta sola (`suiImgRetry`); sin portada queda el
+  degradé oscuro.
+- Los íconos usan `color="var(--sui-primary-base, #fa7319)"`: el hex es respaldo, no se repite
+  afuera.
+
+## Ejemplo
+
+```html
+<sui-store-card
+  [store]="local"
+  [isFavorite]="true"
+  [deliveryText]="envioDeLaTarjeta(local)"
+  [distanceText]="distanciaDeLaTarjeta(local)"
+  (toggleFavorite)="quitarFavorito(local.id)"
+  (ratingClicked)="abrirOpiniones($event)" />
+```

package/docs/sui-switch-card/README.md

@@ -0,0 +1,149 @@
+---
+name: sui-switch-card
+selector: sui-switch-card
+resumen: Ajuste con tarjeta (ícono, título, descripción y el interruptor) que se aplica al instante
+alternativas: [sui-switch-label (el mismo ajuste sin tarjeta, en una lista de ajustes), sui-integration-switch (una integración con logo y «Administrar»), sui-checkbox-card (varias opciones que se guardan con «Guardar»)]
+---
+
+# sui-switch-card
+
+Story: [Molecules/Card/Switch Card](https://sui-design-system.web.app/?path=/docs/molecules-card-switch-card--docs)
+
+## Cuándo usarlo / cuándo no
+
+**Úsalo** para un ajuste que se prende o se apaga **al toque**, sin botón de guardar, y que merece
+su propia tarjeta: «Notificaciones», «Ubicación siempre», «Recibir pedidos de la plataforma»,
+«Repartidores propios», «Disponible».
+
+**No lo uses** para:
+
+- Algo que se confirma después con «Guardar»: `sui-checkbox-card` (canon del switch-label).
+- Una lista larga de ajustes parecidos: `sui-switch-label` con `flip`, uno por fila.
+- Una integración con otro servicio (logo + «Administrar»): `sui-integration-switch`.
+- Algo destructivo o que no se deshace: un botón con confirmación.
+
+Regla corta: **ajuste con peso, al toque → switch-card · lista de ajustes → switch-label con flip
+· se guarda después → checkbox-card.**
+
+## Qué variante usar
+
+> **La guía del DS no tiene página de la switch card.** De la guía sale lo del switch que lleva
+> adentro: **«para prender o apagar un ajuste de forma inmediata»**.
+>
+> Uso medido el 03-10-2026 en `master-pedidos/src/app` (misma exclusión que `sui-card`): **26
+> switch-cards en 8 archivos**. Tipos: 19 `left-icon` (los 19 con el ícono proyectado), 7 `basic`
+> (5 de ellos sin `type`). Tamaños: 20 `bp.controlSize()`, 6 sin `size`. 10 viven en formularios
+> que se guardan con un botón.
+
+### `type` (el leading)
+
+| type | cuándo | fuente |
+|---|---|---|
+| `left-icon` + ícono proyectado | Lo normal: `<sui-icon sui-switch-card-leading name="…" [size]="20" />`. | propuesta (19 de 26) |
+| `left-icon` + `emoji` | Ver «No usar». | propuesta |
+| `basic` | El ajuste es EL tema de la pantalla y no necesita ícono («Disponible» en el inicio del repartidor, «Disponibilidad automática»). | propuesta |
+| `avatar` (`imageUrl`) | Ver «No usar». | propuesta |
+| `card-provider`, `brand`, `company` (`imageUrl` o proyectado) | Ver «No usar». | propuesta |
+
+### Las piezas
+
+| prop | cuándo | fuente |
+|---|---|---|
+| `label` | Siempre. Qué hace prenderlo, sin cambiar con el estado: «Notificaciones», no «Activadas / Desactivadas». | propuesta (misma regla que el switch-label) |
+| `description` | La consecuencia o el estado real del permiso: «Push activado — recibes alertas cuando se te asigna un pedido.» | propuesta |
+| `sublabel` | Precisión corta: «(beta)». | propuesta |
+| `badge` | Solo novedad. Con string sale azul `light`. | propuesta |
+| `disabled` | Mientras se guarda el cambio, o cuando no aplica (no puedes estar disponible sin saldo). | propuesta |
+| `checked` + `(checkedChange)` | Siempre los dos: es controlada. | propuesta |
+
+### `size` (el interruptor de adentro)
+
+| size | cuándo | fuente |
+|---|---|---|
+| `xlarge` (48 × 28) | Mobile, vía `bp.controlSize()`. | canon (aprobado por el dueño, 28-09-2026: «componentes grandes») |
+| `large` (40 × 24) | Desktop, vía `bp.controlSize()`. | canon (aprobado por el dueño, 28-09-2026) |
+| `medium` (default) | No usar en pantallas nuevas. | canon (aprobado por el dueño, 28-09-2026) |
+
+**Usos de hoy que rompen las reglas:**
+
+- **10 switch-cards en formularios que se guardan con un botón** (van `sui-checkbox-card`): los 5
+  métodos de pago de `pages/mi-negocio/mi-negocio.html:1181`–`:1217` («Guardar cambios») y 5 de
+  `pages/super-admin/master-settings/master-settings.html` (`:36` «Pausar los pedidos», `:179`,
+  `:336`, `:342`, `:349`, cada uno con su «Guardar…» abajo).
+- **6 sin `size`**: los 5 de `master-settings` de arriba y `pages/notifications/notifications.html:59`
+  («Sonidos de la app»).
+
+## Tamaño en mobile y en web
+
+La card entera se toca (≥ 72 con descripción): llega al piso de 44 sola. El `size` cambia solo el
+interruptor.
+
+| uso | mobile | web |
+|---|---|---|
+| toda switch-card | `xlarge` (48 × 28) | `large` (40 × 24) |
+
+```html
+<sui-switch-card [size]="bp.controlSize()" … />   <!-- isMobile() ? 'xlarge' : 'large' -->
+```
+
+## «No usar»: por qué no hoy y cuándo sí
+
+| qué | por qué no hoy | cuándo sí, en un flujo nuevo |
+|---|---|---|
+| `emoji` (0 usos) | los ajustes de hoy llevan un ícono Remix | un ajuste de los grandes del rol que quiera el emoji animado del catálogo (`SuiEmoji`) |
+| `type="avatar"` (0 usos) | no se prende ni apaga a una persona | prender o apagar a un repartidor de tu flota |
+| `type="brand"` / `"company"` / `"card-provider"` (0 usos) | no hay integraciones | casi nunca: una integración es `sui-integration-switch` |
+| `size="medium"` | el interruptor de 32 × 20 se pierde en el teléfono | una tabla densa solo de desktop |
+
+## API
+
+<!-- api:inicio -->
+<!-- generada: no editar a mano — `npm run docs` -->
+
+| input | tipo | default |
+|---|---|---|
+| `type` | `'basic' \| 'left-icon' \| 'avatar' \| 'card-provider' \| 'brand' \| 'company'` | `'basic'` |
+| `size` | `'medium' \| 'large' \| 'xlarge'` | `'medium'` |
+| `label` | `string` | `''` |
+| `sublabel` | `string \| null` | `null` |
+| `description` | `string \| null` | `null` |
+| `emoji` | `SuiEmojiName \| null` | `null` |
+| `imageUrl` | `string \| null` | `null` |
+| `badge` | `SuiBadgeConfig \| string \| null` | `null` |
+| `checked` | `boolean` | `false` |
+| `disabled` | `boolean` | `false` |
+
+| output | payload |
+|---|---|
+| `checkedChange` | `boolean` |
+<!-- api:fin -->
+
+Slot: `[sui-switch-card-leading]` (el ícono o el logo). Implementa `ControlValueAccessor`.
+
+## Trampas
+
+- **Es controlada**: `checked` es input y `checkedChange` solo avisa. Si no actualizas tu señal,
+  el interruptor no se mueve (al revés que `sui-checkbox-card`).
+- **`type="left-icon"` sin `emoji` ni nada proyectado deja el círculo vacío.** El ícono se
+  proyecta con el atributo **`sui-switch-card-leading`** (no `slot=`).
+- No tiene `icon` como input (la radio y la checkbox card sí): el ícono siempre va proyectado.
+- `avatar` siempre dibuja un `sui-avatar` con `imageUrl` (si falla, las iniciales del `label`): no usa lo
+  proyectado. `card-provider`, `brand` y `company` leen `imageUrl` y, sin ella, usan lo proyectado.
+- Toda la card togglea; el toque sobre el propio switch no cuenta doble.
+- El interruptor siempre va a la derecha (no hay `flip`).
+- `badge` con string sale **azul `light` `small`** (en `sui-switch-label` sale naranja).
+
+## Ejemplo
+
+```html
+<sui-switch-card
+  [size]="bp.controlSize()"
+  type="left-icon"
+  label="Ubicación siempre"
+  [description]="ubicacionTexto()"
+  [checked]="ubicacionSiempre()"
+  [disabled]="guardando()"
+  (checkedChange)="cambiarUbicacion($event)">
+  <sui-icon sui-switch-card-leading name="map-pin-line" [size]="20" />
+</sui-switch-card>
+```

package/docs/sui-tab-chips/README.md

@@ -0,0 +1,185 @@
+---
+name: sui-tab-chips
+selector: sui-tab-chips
+resumen: Fila de chips que se desliza en horizontal para filtrar una lista o saltar entre categorías; siempre hay uno elegido
+alternativas: [sui-segmented-control (2 a 4 modos de la misma vista), sui-tab-menu-horizontal (secciones de contenido distinto), sui-radio-card (elegir un valor de un formulario), sui-tag (chip que se quita)]
+---
+
+# sui-tab-chips
+
+Story: [Molecules/Tabs/Tab Chips](https://sui-design-system.web.app/?path=/docs/molecules-tabs-tab-chips--docs)
+
+## Cuándo usarlo / cuándo no
+
+**Úsalo** para:
+
+- **Filtrar una lista** por estado, período, rol o zona: «Todos · Activos · Entregados · Cancelados»,
+  «Hoy · 7 días · 30 días», los meses de la central.
+- **Saltar entre categorías** de un catálogo que viene de la base («Hamburguesas · Pizzas ·
+  Bebidas»), con `sticky` en la carta del local.
+
+Sirve cuando las opciones son muchas, cambian según los datos o no caben y tienen que deslizarse.
+
+**No lo uses** para:
+
+- **2 a 4 modos de la misma vista** (por semana / día vs día): `sui-segmented-control`.
+- **Secciones de contenido distinto** (Ventas · Productos · Repartidores): `sui-tab-menu-horizontal`.
+- **Elegir un valor que se guarda** con un botón (radio de visibilidad, motivo de rechazo,
+  sumar o descontar): `sui-radio-card` o `sui-segmented-control`. El tab-chips **siempre tiene uno
+  elegido** y no puede quedar vacío (ver Trampas).
+- Un chip que la persona quita: `sui-tag`.
+
+Regla corta (la misma del README de `sui-segmented-control`, 03-10-2026): **2-4 modos de la misma
+vista → segmented · secciones → tab menu · filtros o categorías → tab-chips.**
+
+## Qué variante usar
+
+> **La guía del DS no tiene este componente**: es una extensión de SUI (la «cat nav» de las apps de
+> delivery). Todo lo que sigue es propuesta salvo lo marcado como canon.
+>
+> Uso medido el 03-10-2026 en `master-pedidos/src/app` (sin `master-preview`, `master-prototipos`,
+> `mockup-*`, `dx/*`, `_guia-*`, `master-rutina`, `master-medico`, `master-ejercicios`):
+> **41 usos en 28 archivos `.html`**. `[sticky]="true"`: 1 (carta del local). `count`: 5 listas.
+> `[(value)]`: 2; el resto `[value]` + `(valueChange)`. `autoScroll`: 0. `size`: 0 (no existe en
+> la versión publicada).
+
+### Para qué se usa (el contenido de los chips)
+
+| caso | cuándo | ejemplo real de la app | fuente |
+|---|---|---|---|
+| filtro de estado | La lista es la misma; los chips la recortan. «Todos» va primero y es el elegido por defecto. | `pages/envios/envios.html:98` («Todos · Activos · Entregados · Cancelados») · `pages/orders/orders.html:64` | propuesta, falta aprobación |
+| filtro de período | Rango de fechas de un reporte o gráfico. | `pages/super-admin/master-earnings/master-earnings.html:11` · `pages/central/central-gastos/central-gastos.html:10` (meses) | propuesta, falta aprobación |
+| categorías del catálogo | Saltar a una categoría de la carta; con `sticky` y `autoScroll`. | `pages/customer/restaurant-menu/restaurant-menu.html:226` | propuesta, falta aprobación |
+| sugerencias rápidas | **No.** Un motivo frecuente que completa un texto no es una selección: el chip elige el primero solo. Si se usa, el primer chip es el neutro («Otro motivo») y el texto lleva su propio signal. | `pages/super-admin/master-orders/master-orders.html:898` (bien resuelto) | propuesta, falta aprobación |
+
+### `sticky`
+
+| valor | cuándo | fuente |
+|---|---|---|
+| `false` (default) | Filtros arriba de una lista corta o dentro de un modal o sheet. | propuesta, falta aprobación |
+| `true` | Solo la navegación de categorías de una lista larga que scrollea (la carta). Se pega arriba del contenedor de scroll y, pegado, pinta fondo `bg-weak-50`. | propuesta, falta aprobación |
+
+### `autoScroll`
+
+| valor | cuándo | fuente |
+|---|---|---|
+| `true` (default) | Siempre: centra el chip elegido cuando cambia `value` (también si lo cambia el scroll de la carta). | propuesta, falta aprobación |
+| `false` | Solo si el `value` cambia muy seguido por código y el movimiento distrae. Hoy ningún caso. | propuesta, falta aprobación |
+
+### Ítems (`chips`)
+
+| qué | cuándo | fuente |
+|---|---|---|
+| `string[]` | Cuando el texto es el valor (meses, provincias). | propuesta, falta aprobación |
+| `{ value, label }` | Cuando el valor es un id o una clave en inglés (`'active'` → «Activos»). | propuesta, falta aprobación |
+| `count` | El número de ítems detrás del filtro, cuando ayuda a decidir («Recargas 3»). `0` o `undefined` no se dibuja. **El número va en `count`, no dentro del `label`.** | propuesta, falta aprobación |
+| texto | Una o dos palabras, sentence case, sin punto. Plural si filtra («Activos»). | canon (copy de `docs/CANON-SUI.md`) |
+
+**Usos de hoy que rompen las reglas:**
+
+- **3 con un bug real: el motivo escrito a mano rebota al primer chip.** En los modales de rechazo
+  del super admin, los chips y el textarea comparten el mismo signal. Cada tecla deja un texto que
+  no es ningún chip; el componente vuelve al primero y lo emite, así que el textarea se reescribe con
+  «El comprobante no se lee». No se puede escribir un motivo propio, y al abrir el modal ya hay un
+  motivo elegido sin que nadie lo toque. `pages/super-admin/master-drivers/master-drivers.html:652`,
+  `:924` y `:1002`. Es el mismo bug que se arregló en `master-orders` el 01-09-2026 (signal propio
+  para los chips y «Otro motivo» primero).
+- **4 son secciones de contenido distinto** (→ `sui-tab-menu-horizontal` en web; en mobile, a
+  discutir porque el tab menu no se desliza, ver su README): `pages/products/products.html:6`
+  («Categorías · Productos · Secciones reutilizables»), `pages/promociones/promociones.html:7`
+  («Carrusel pagado · Push notifications»), `pages/super-admin/master-drivers/master-drivers.html:16`,
+  `pages/reports/reports.html:98` («Ventas · Productos · Repartidores · Clientes»).
+- **2 son modos de la misma vista** (→ `sui-segmented-control`):
+  `pages/super-admin/master-semanas/master-semanas.html:67` (3 métricas del mismo gráfico) y `:72`
+  («Por semana · Día vs día»).
+- **4 eligen un valor de un formulario** (→ `sui-radio-card` o `sui-segmented-control`):
+  `components/option-sections-manager/option-sections-manager.html:175` (a qué se aplica),
+  `pages/super-admin/master-drivers/master-drivers.html:98` («Sumar · Descontar»),
+  `pages/mi-negocio/mi-negocio.html:938` (radio de visibilidad) y `:973` (tiempo para confirmar).
+  A discutir: `pages/customer/checkout/checkout.html:468` (día del pedido programado), que filtra
+  las franjas de abajo y se parece más a un filtro.
+- **1 con el número dentro del texto:** `pages/notifications/notifications.ts:191`
+  (`No leídas (3)` → `count: 3`).
+- **41 sin tamaño por plataforma** (el input todavía no está publicado): cuando se publique, los de
+  pantallas del cliente y del repartidor pasan a `large`.
+
+## Tamaño en mobile y en web
+
+> `size` está **en el repo del DS (03-10-2026) y no en la versión publicada 0.19.0**. Hasta que se
+> publique, todos miden lo de `medium`.
+
+Alto del chip: `small` 32 px · `medium` 36 px (el de siempre, default) · `large` 40 px. Los tres
+con texto de 14 px; cambia el alto y el aire lateral. El scroller suma 12 px arriba y abajo.
+
+| uso | mobile | web | fuente |
+|---|---|---|---|
+| filtros y categorías | `large` (40; con el aire del scroller llega a 44+ de área táctil) | `medium` | canon (dueño: tamaño por plataforma, 03-10-2026) |
+| filtros densos en la cabecera de una tabla | — | `small` | propuesta, falta aprobación |
+
+```html
+<sui-tab-chips [chips]="filtros" [(value)]="filtro" [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 |
+|---|---|---|
+| `autoScroll` en `false` | ningún caso cambia el valor tan seguido como para que moleste | una vista que sincroniza el chip con un scroll muy rápido y el movimiento distrae |
+| `sticky` fuera de la carta | en una lista corta tapa contenido sin ayudar | otra lista larga por categorías (un catálogo de bodega con muchas secciones) |
+| `small` en mobile | 32 px no llega al dedo | nunca en mobile |
+
+## API
+
+<!-- api:inicio -->
+<!-- generada: no editar a mano — `npm run docs` -->
+
+| input | tipo | default |
+|---|---|---|
+| `chips` | `readonly (string \| SuiTabChipItem)[]` | — (requerido) |
+| `value` · model, `[(value)]` | `string` | `''` |
+| `sticky` | `boolean` | `false` |
+| `size` | `'small' \| 'medium' \| 'large'` | `'medium'` |
+| `autoScroll` | `boolean` | `true` |
+
+Outputs: ninguno.
+<!-- api:fin -->
+
+```ts
+interface SuiTabChipItem {
+  value: string;
+  label: string;
+  count?: number;   // 0 o undefined no se dibuja
+}
+type SuiTabChipsSize = 'small' | 'medium' | 'large';   // repo del DS, no en 0.19.0
+```
+
+## Trampas
+
+- **Siempre hay uno elegido.** Si `value` está vacío o no coincide con ningún chip, el componente
+  elige el **primero y lo emite** por `valueChange`. No existe «ninguno». Si el valor también lo
+  escribe otro control (un textarea), cada tecla rebota al primer chip: usa un signal propio para
+  los chips.
+- **`value` es `string`.** Para números (km, minutos) hay que convertir en los dos sentidos
+  (`radioEfectivo() + ''` y `+$event`).
+- **Lleva `role="tablist"`** aunque se use como filtro: el lector de pantalla lo anuncia como pestañas.
+- **No tiene padding lateral propio**: lo pone la pantalla. Sí trae 12 px arriba y abajo.
+- **`sticky` cambia el host a `display: contents`**: las clases que le pongas al host dejan de
+  pintar caja (márgenes, anchos). Pon el estilo en un contenedor.
+- **Pegado, el fondo es `bg-weak-50`**: sobre una página blanca se nota la franja gris.
+  Con `sticky` el sentinel agrega 16 px arriba.
+- **`count` en 0 no se dibuja**: no sirve para decir «0 pendientes».
+- **El chip activo es oscuro** (`bg-strong-950`), no naranja: es el estilo del componente, no se
+  cambia por pantalla.
+
+## Ejemplo
+
+```html
+<!-- Filtro de estado: «Todos» primero -->
+<sui-tab-chips
+  [chips]="[{ value: 'todos', label: 'Todos' }, { value: 'activos', label: 'Activos' },
+            { value: 'entregados', label: 'Entregados' }, { value: 'cancelados', label: 'Cancelados' }]"
+  [(value)]="filtro" />
+
+<!-- Categorías de la carta -->
+<sui-tab-chips [chips]="categorias()" [value]="categoria()" (valueChange)="irA($event)" [sticky]="true" />
+```

package/docs/sui-tab-menu-horizontal/README.md

@@ -0,0 +1,142 @@
+---
+name: sui-tab-menu-horizontal
+selector: sui-tab-menu-horizontal
+resumen: Pestañas subrayadas para cambiar entre secciones de contenido distinto dentro de una pantalla
+alternativas: [sui-tab-chips (filtros o categorías que se deslizan), sui-segmented-control (2 a 4 modos de la misma vista), sui-tab-menu-vertical (menú lateral de ajustes en web)]
+---
+
+# sui-tab-menu-horizontal
+
+Story: [Molecules/Tabs/Tab Menu Horizontal](https://sui-design-system.web.app/?path=/docs/molecules-tabs-tab-menu-horizontal--docs)
+
+## Cuándo usarlo / cuándo no
+
+**Úsalo** para cambiar entre **secciones de contenido distinto** de la misma pantalla o detalle:
+«Opiniones · Información» en el modal del local, «Ventas · Productos · Repartidores · Clientes» en
+reportes. Cada pestaña muestra otra cosa, no la misma lista recortada.
+
+**No lo uses** para:
+
+- **Filtrar una lista** o saltar entre categorías: `sui-tab-chips`.
+- **2 a 4 modos de la misma vista** (cuadrícula o lista): `sui-segmented-control`.
+- **Secciones que no entran a lo ancho en mobile** (4 con nombres largos o con `number`, o 5+): el
+  componente no se desliza y las pestañas se salen de la pantalla (ver Trampas). Ahí, por ahora,
+  `sui-tab-chips`.
+- Un menú lateral de ajustes en web: `sui-tab-menu-vertical`.
+
+Regla corta (README de `sui-segmented-control`, 03-10-2026): **2-4 modos de la misma vista →
+segmented · secciones → tab menu · filtros → tab-chips.**
+
+## Qué variante usar
+
+> **Lo que dice la guía del DS**: es un layout lineal para **cambiar entre secciones o categorías**.
+> Muestra un ejemplo con pestañas que **desbordan y se deslizan**, y su pestaña mide 48 px de alto
+> (toda la franja es tocable). No trae do/don't ni tamaños.
+>
+> Uso medido el 03-10-2026 en `master-pedidos/src/app` (misma exclusión que `sui-badge`):
+> **1 uso**: `components/store-ratings-modal/store-ratings-modal.html:43` («Opiniones ·
+> Información»), sin `size`, sin ícono, sin `number`.
+
+### Ítems (`tabs`)
+
+| qué | cuándo | fuente |
+|---|---|---|
+| texto | Lo normal: el nombre de la sección, una o dos palabras. | según la guía del DS (ejemplos con texto) |
+| `icon` | Solo si **todas** las pestañas llevan ícono y ayuda a reconocerlas. Nunca en una sola. | propuesta, falta aprobación |
+| `number` | Pendientes **que piden acción** dentro de esa sección («Solicitudes 3»). Es un círculo rojo: no lo uses para totales neutros. | propuesta, falta aprobación |
+| `rightIcon` | No: la flecha dice «te lleva a otra pantalla» y una pestaña no navega. | propuesta, falta aprobación |
+| `disabled` | Una sección que existe pero no aplica todavía (depende del plan). | propuesta, falta aprobación |
+
+### `size`
+
+| size | cuándo | fuente |
+|---|---|---|
+| `medium` (default) | El único que cambia algo: **ninguno**. El input existe pero no tiene estilos; los cuatro valores se ven igual. No lo pases. | según el código (`sui-tab-menu-horizontal.scss`: no hay reglas por tamaño) |
+| `small` · `large` · `xlarge` | No usar: no hacen nada. | según el código |
+
+**Usos de hoy que rompen las reglas:**
+
+- **0** en este componente. Los casos que deberían ser tab menu y hoy son `sui-tab-chips` están en el
+  README de `sui-tab-chips` (4: `pages/products/products.html:6`, `pages/promociones/promociones.html:7`,
+  `pages/super-admin/master-drivers/master-drivers.html:16`, `pages/reports/reports.html:98`).
+- **A verificar en mobile:** el uso actual es del modal del local, que el cliente abre en el
+  teléfono. La pestaña mide 20 px de alto tocable (ver Tamaño).
+
+## Tamaño en mobile y en web
+
+Cada pestaña ocupa **todo el alto de la franja**, así que lo tocable es la franja entera (desde
+03-10-2026; antes eran solo los 20 px del texto). El `size` cambia ese alto y el texto:
+
+| size | franja tocable (+ 2 de bordes) | texto | ícono | gap | fuente |
+|---|---|---|---|---|---|
+| `small` | 40 | `label-sm` 14/20 | 20 | 20 | canon (aprobado por el dueño, 03-10-2026): extensión SUI |
+| `medium` (default) | 48 | `label-sm` 14/20 | 20 | 24 | Figma |
+| `large` | 52 | `label-md` 16/24 | 20 | 24 | canon (aprobado por el dueño, 03-10-2026): extensión SUI |
+| `xlarge` | 56 | `label-md` 16/24 | 24 | 28 | canon (aprobado por el dueño, 03-10-2026): extensión SUI |
+
+| uso | mobile | web | fuente |
+|---|---|---|---|
+| 2-3 secciones | `large` (52, texto 16) | `medium` (48) | propuesta: el tamaño es extensión SUI aprobada (03-10-2026); el «cuándo» falta aprobarlo |
+| 4+ secciones | si no entran a 390 px, se salen sin poder deslizarse (las 4 del panel de repartidores, con sus números, ya no entran a 360): va `sui-tab-chips` | el mismo | según el código |
+
+```html
+<sui-tab-menu-horizontal [tabs]="secciones" [(active)]="seccion" [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 |
+|---|---|---|
+| `rightIcon` | una pestaña no lleva a otra pantalla | nunca en pestañas; es del tab menu vertical cuando cada ítem abre una página |
+| `icon` | ningún caso de hoy lo necesita | secciones con ícono reconocible en las tres (Mapa · Lista · Fotos) en web |
+| `number` | ninguna sección del único uso tiene pendientes | «Solicitudes» o «Recargas» del panel de repartidores, si se pasa a tab menu |
+| `disabled` | ninguna sección bloqueada | una sección que depende del plan («Reportes» en plan básico) |
+
+## API
+
+<!-- api:inicio -->
+<!-- generada: no editar a mano — `npm run docs` -->
+
+| input | tipo | default |
+|---|---|---|
+| `tabs` | `SuiTabMenuHorizontalItem<T>[]` | — (requerido) |
+| `active` · model, `[(active)]` | `T` | `undefined` |
+| `size` | `'small' \| 'medium' \| 'large' \| 'xlarge'` | `'medium'` |
+
+| output | payload |
+|---|---|
+| `tabChange` | `T` |
+<!-- api:fin -->
+
+```ts
+interface SuiTabMenuHorizontalItem<T = string> {
+  value: T;
+  label: string;
+  icon?: string;        // RemixIcon, 20 px
+  rightIcon?: boolean;  // flecha en píldora
+  number?: number;      // círculo rojo; 0/undefined no se dibuja
+  disabled?: boolean;
+}
+```
+
+## Trampas
+
+- **Sin `active` no se marca ninguna pestaña.** Pásale siempre un valor inicial.
+- **No se desliza.** El track no tiene `overflow-x`: con muchas pestañas en un ancho chico se salen
+  del contenedor. La guía del DS sí lo resuelve; SUI todavía no.
+- **El área tocable es toda la franja** (40–56 según `size`), desde 03-10-2026: el aire de 14 px
+  que Figma pone en el contenedor ahora va dentro de cada pestaña. Si algo de afuera le pone
+  padding al `.sui-tab-menu-horizontal__track`, la franja crece al doble.
+- **Emite dos veces**: `tabChange` y `activeChange`. Con `[(active)]` no hace falta `(tabChange)`.
+- **Trae bordes arriba y abajo** (`stroke-soft-200`) y fondo blanco: no lo metas en una card que ya
+  tiene borde, o quedan dos líneas.
+- El ícono de la pestaña activa es `strong-950`, no naranja; en el tab menu vertical es naranja.
+  Es a propósito.
+
+## Ejemplo
+
+```html
+<sui-tab-menu-horizontal
+  [tabs]="[{ value: 'opiniones', label: 'Opiniones' }, { value: 'info', label: 'Información' }]"
+  [(active)]="tab" />
+```