@ajuarezso/sui-design-system 0.20.0 → 0.22.0

package/docs/sui-stepper/README.md

@@ -0,0 +1,166 @@
+---
+name: sui-stepper
+selector: sui-stepper
+resumen: Indica en qué paso de un flujo con orden está la persona, cuánto hizo y cuánto le falta
+alternativas: [sui-progress-bar (importa el porcentaje, no los pasos), sui-pagination (páginas de una lista), sui-tab-menu-horizontal (secciones sin orden)]
+---
+
+# sui-stepper
+
+Story: [Molecules/Stepper](https://sui-design-system.web.app/?path=/docs/molecules-stepper--docs)
+
+Ojo: es el **indicador de pasos** de un proceso. El «− 1 +» de cantidad es otra cosa
+(`sui-counter-input` o los botones del producto).
+
+## Cuándo usarlo / cuándo no
+
+**Úsalo** cuando un flujo tiene **pasos con nombre y orden** y ayuda saber cuántos faltan: el alta
+del local («Tu local → Producto»), del cliente («Ubicación → Teléfono»), del repartidor («Datos →
+Vehículo → Listo»).
+
+**No lo uses** para:
+
+- Un avance que es porcentaje (subida de un archivo, perfil completo al 70 %): `sui-progress-bar`.
+- Un pedido en curso (preparando, en camino, entregado): ese seguimiento tiene su propia línea de
+  tiempo y estados que no son pasos que la persona completa.
+- Secciones que se visitan en cualquier orden: `sui-tab-menu-horizontal`.
+- Un solo paso: no hay nada que indicar.
+
+Regla corta: **pasos con nombre y orden → stepper · porcentaje → progress-bar · secciones sin orden → tab menu.**
+
+## Qué variante usar
+
+> **Lo que dice la guía del DS**: tiene tres piezas. El **de puntos**, «muy mínimo, usado a menudo
+> como puntos de carrusel», con tamaños `small` y `xsmall`. El **horizontal**, «una guía visual de
+> procesos secuenciales». El **vertical**, el mismo indicador «para layouts diversos», con una
+> flecha en el paso activo. Estados de cada paso: `default`, `active`, `completed`. No trae do/don't.
+>
+> Uso medido el 03-10-2026 en `master-pedidos/src/app` (misma exclusión que `sui-badge`):
+> **7 usos en 7 archivos**, los 7 en los onboardings: todos `variant="horizontal"`, sin `size`
+> (`small`), sin `interactive`, de 2 o 3 pasos.
+
+### `variant`
+
+| variant | cuándo | ejemplo real de la app | fuente |
+|---|---|---|---|
+| `horizontal` (default) | Flujo de **2 a 4 pasos** con nombre, arriba del contenido del paso. Mobile y web. | `pages/driver-onboarding/step-info/step-info.html:3` («Datos → Vehículo → Listo») | según la guía del DS (procesos secuenciales); el límite de pasos es propuesta |
+| `vertical` | Flujo de **5+ pasos** en web, en una columna al costado del formulario. | (sin uso) | según la guía del DS (la pieza existe); el cuándo es propuesta |
+| `dot` | Pantallas que se pasan de a una sin nombre: carrusel de bienvenida, fotos. | (sin uso) | según la guía del DS (puntos de carrusel) |
+
+### `size`
+
+| size | qué cambia | cuándo | fuente |
+|---|---|---|---|
+| `small` (default) | punto de 8 · indicador de 20 · texto 14 | Web. | según la guía del DS (`small` es su default) |
+| `xsmall` | solo el punto: 4 px. Horizontal y vertical quedan igual que `small`. | Puntos sobre una foto o un banner chico, donde 8 px tapan. | según la guía del DS (el tamaño existe); el cuándo es propuesta |
+| `medium` | punto de 10 · indicador de 24 · texto 16 · card vertical de 44 | Mobile. **Está en el repo del DS (03-10-2026), no en la versión publicada 0.19.0.** | canon (dueño: tamaño por plataforma, 03-10-2026) |
+
+### Estado de cada paso (`currentStep`, `errorStep`)
+
+| estado | cómo se logra | cuándo | fuente |
+|---|---|---|---|
+| `completed` | índice menor que `currentStep` | pasos ya hechos (check verde) | según la guía del DS |
+| `active` | índice igual a `currentStep` | el paso en pantalla | según la guía del DS |
+| `default` | índice mayor que `currentStep` | lo que falta | según la guía del DS |
+| todos `completed` | `currentStep` = cantidad de pasos | la pantalla final («Listo») | propuesta, falta aprobación |
+| `error` | `errorStep` = índice | un flujo que se cortó en ese paso (pago rechazado, documento no aprobado). Extensión de SUI. | propuesta, falta aprobación |
+
+### `interactive`
+
+| valor | cuándo | fuente |
+|---|---|---|
+| `false` (default) | Los onboardings: se avanza con el botón «Continuar», no tocando el paso. | propuesta, falta aprobación |
+| `true` | Solo si los pasos hechos se pueden **volver a editar** y en web (el área tocable es chica, ver Tamaño). | propuesta, falta aprobación |
+
+### `steps`, `count`, `ariaLabel`
+
+| input | cuándo | fuente |
+|---|---|---|
+| `steps` | Siempre en `horizontal` y `vertical`, con `label` en cada uno. | propuesta, falta aprobación |
+| `count` | Solo en `dot`, cuando los pasos no tienen nombre. Si pasas `steps`, `count` se ignora. | según el código |
+| `ariaLabel` | Default «Progreso». Cámbialo si hay más de un stepper en la pantalla («Pasos del registro»). | propuesta, falta aprobación |
+
+**Usos de hoy que rompen las reglas:**
+
+- **0 de variante o estado**: los 7 son horizontales de 2 o 3 pasos, y `step-complete` usa
+  `currentStep = stepLabels.length` para marcar todo hecho (`pages/driver-onboarding/step-complete/step-complete.html:3`).
+- **7 sin tamaño por plataforma** (el `medium` todavía no está publicado): los onboardings se hacen
+  en el teléfono. Cuando se publique, `[size]="bp.isMobile() ? 'medium' : 'small'"`. Ejemplos:
+  `pages/customer-onboarding/step-phone/step-phone.html:3`, `pages/business-onboarding/step-info/step-info.html:3`.
+
+## Tamaño en mobile y en web
+
+| uso | mobile | web | fuente |
+|---|---|---|---|
+| horizontal arriba de un paso | `medium` (indicador 24, texto 16) | `small` (indicador 20, texto 14) | canon (dueño: tamaño por plataforma, 03-10-2026) |
+| vertical al costado | no se usa (no entra al lado del formulario) | `small` | propuesta, falta aprobación |
+| puntos de carrusel | `medium` (10) | `small` (8) | propuesta, falta aprobación |
+
+```html
+<sui-stepper [steps]="pasos" [currentStep]="paso - 1" [size]="bp.isMobile() ? 'medium' : 'small'" />
+```
+
+Sin `interactive` el tamaño solo afecta lo que se lee. Con `interactive`, **ningún tamaño llega a
+44 px tocables** en horizontal (24 de alto con `medium`) ni en puntos (10 px): por eso
+`interactive` queda para web. La card vertical `medium` sí llega a 44.
+
+## «No usar»: por qué no hoy y cuándo sí
+
+| qué | por qué no hoy | cuándo sí, en un flujo nuevo |
+|---|---|---|
+| `vertical` | ningún flujo tiene 5+ pasos | un alta de local completa en web (datos, carta, horario, pagos, repartidores) |
+| `dot` | ningún carrusel usa el componente | un carrusel de bienvenida o de fotos del producto |
+| `xsmall` | no hay puntos sobre fotos | puntos sobre el banner del carrusel del home |
+| `errorStep` | ningún flujo muestra dónde se cortó | el estado de una solicitud de repartidor rechazada en el paso «Documentos» |
+| `interactive` | en los onboardings se avanza con el botón | un formulario largo en web donde se vuelve a corregir un paso hecho |
+
+## API
+
+<!-- api:inicio -->
+<!-- generada: no editar a mano — `npm run docs` -->
+
+| input | tipo | default |
+|---|---|---|
+| `variant` | `'dot' \| 'horizontal' \| 'vertical'` | `'horizontal'` |
+| `steps` | `SuiStepperItem[]` | `[]` |
+| `count` | `number` | `0` |
+| `currentStep` | `number` | `0` |
+| `errorStep` | `number \| null` | `null` |
+| `size` | `'small' \| 'xsmall' \| 'medium'` | `'small'` |
+| `interactive` | `boolean` | `false` |
+| `ariaLabel` | `string` | `'Progreso'` |
+
+| output | payload |
+|---|---|
+| `stepClick` | `number` |
+<!-- api:fin -->
+
+```ts
+interface SuiStepperItem {
+  label?: string;   // sin label sale «Paso N»
+}
+type SuiStepperVariant = 'dot' | 'horizontal' | 'vertical';
+type SuiStepperSize = 'small' | 'xsmall' | 'medium';   // medium: repo del DS, no en 0.19.0
+```
+
+## Trampas
+
+- **`currentStep` arranca en 0.** La app numera los pasos desde 1: por eso los onboardings pasan
+  `currentStep - 1`.
+- **Un paso sin `label` dice «Paso 2»** (hasta el 03-10-2026 decía «Step 2»).
+- **`xsmall` solo achica los puntos**: en horizontal y vertical se ve igual que `small`.
+- **El horizontal hace `flex-wrap`**: con muchos pasos o nombres largos baja a otra línea en vez de
+  cortarse. Con 4+ pasos en mobile, revisa a 390 px.
+- **`stepClick` solo sale con `interactive`**; sin él los pasos son `div` y no responden.
+- `errorStep` gana sobre `currentStep`: los anteriores quedan hechos y los siguientes por hacer.
+- El activo usa `--sui-primary-base`, que en la app es naranja.
+
+## Ejemplo
+
+```html
+<sui-stepper
+  variant="horizontal"
+  [steps]="[{ label: 'Datos' }, { label: 'Vehículo' }, { label: 'Listo' }]"
+  [currentStep]="1"
+  [size]="bp.isMobile() ? 'medium' : 'small'" />
+```

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-switch-label/README.md

@@ -80,6 +80,9 @@ Regla corta: **ajuste con texto → este · ajuste con peso → switch-card · s
 El bloque entero se toca, así que con descripción la fila pasa los 44 px sola. Sin descripción,
 dale a la fila un alto mínimo de 44 px.
 
+En large y xlarge el texto sube a 16 px (regla del 03-10-2026): el label va en 16/24; sublabel y
+descripción se quedan en 12.
+
 ## «No usar»: por qué no hoy y cuándo sí
 
 | qué | por qué no hoy | cuándo sí, en un flujo nuevo |

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

@@ -0,0 +1,188 @@
+---
+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. `small` y
+`medium` con texto de 14 px; cambia el alto y el aire lateral. El scroller suma 12 px arriba y abajo.
+
+En large y xlarge el texto sube a 16 px (regla del 03-10-2026): el chip `large` va en 16/24 y sigue
+midiendo 40. El número del contador se queda en 12.
+
+| 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" />
+```