@ajuarezso/sui-design-system 0.19.0 → 0.21.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/README.md

@@ -0,0 +1,146 @@
+---
+name: sui-switch
+selector: sui-switch
+resumen: Interruptor solo para prender o apagar algo que se aplica al instante, sin texto propio
+alternativas: [sui-switch-label (interruptor con su texto, el caso normal), sui-switch-card (cada ajuste es una tarjeta), sui-integration-switch (fila de integración con logo), sui-checkbox (valor que se confirma después con un botón)]
+---
+
+# sui-switch
+
+Story: [Atoms/Checkbox, Radio & Switch/Switch](https://sui-design-system.web.app/?path=/docs/atoms-checkbox-radio-switch-switch--docs)
+
+## Cuándo usarlo / cuándo no
+
+**Úsalo** para prender o apagar algo que **se aplica en el momento**, sin botón de guardar:
+la disponibilidad de un producto, un cupón activo, un día del horario, una oferta. Pelado,
+solo cuando el texto vive en otra parte: una celda de tabla con su cabecera, una fila con su
+propio título (día de la semana, tarjeta de la oferta).
+
+**No lo uses** para:
+
+- **Un interruptor con su texto al lado** (casi siempre): `sui-switch-label`, que trae label,
+  descripción y el toque en toda la fila.
+- Un valor de formulario que se confirma con «Guardar»: `sui-checkbox`. (Excepción aceptada hoy:
+  los formularios de producto y de planes usan switch para «disponible»/«activo» aunque se guarden
+  después; es el patrón que la persona reconoce.)
+- Algo destructivo o que no se deshace: el switch promete que se puede volver atrás al toque.
+- Elegir entre dos modos con nombre: `sui-segmented-control` si se aplica al instante (cuadrícula /
+  lista); `sui-radio-card` si se guarda después («Por distancia» / «Precio único» en ajustes).
+
+Regla corta: **se aplica ya → switch · se confirma después → checkbox · dos modos con nombre → segmented (inmediato) o radio-card (se guarda).**
+
+## Qué variante usar
+
+> **La guía del DS lo define en una frase**: se usa «para prender o apagar un ajuste de forma
+> inmediata». Muestra deshabilitado, con label y con label avanzado. No dice nada de tamaños.
+>
+> Uso medido el 03-10-2026 en `master-pedidos/src/app` (misma exclusión que `sui-badge`):
+> **29 switches en 13 archivos**. Tamaños: 25 `bp.controlSize()` / `ctrlSize()` (`large` en
+> desktop, `xlarge` en mobile), 1 `xlarge` fijo, 1 `large` fijo y 2 sin `size` (`medium`, el
+> default). Más **1 `<input type="checkbox">` dibujado como
+> switch**.
+
+### Estado (`checked`, `disabled`)
+
+| estado | cuándo | fuente |
+|---|---|---|
+| prendido / apagado | `[(checked)]` o `[checked]` + `(checkedChange)`. | según la guía del DS |
+| `disabled` | Mientras se guarda el cambio (`[disabled]="guardando()"`) o cuando no aplica. | según la guía del DS (existe); el «cuándo» ya es práctica de la app |
+
+### `size`
+
+| size | px | cuándo | fuente |
+|---|---|---|---|
+| `xlarge` | 48 × 28 | Mobile, vía `bp.controlSize()`. Y en tarjetas donde el switch es la acción principal (ofertas de Central). | 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) | 32 × 20 | No usar en pantallas nuevas (ver abajo). Es el único tamaño de la guía. | canon (aprobado por el dueño, 28-09-2026) |
+
+### La etiqueta dice lo que hace, no el estado
+
+| caso | regla | fuente |
+|---|---|---|
+| Texto al lado del switch | Dice **qué hace prenderlo** y no cambia con el estado: «Recibir pedidos», no «Sucursal en pausa». El estado ya lo dice el switch (y un badge si hace falta). | propuesta, falta aprobación (precedente escrito en `pages/schedule/schedule.html:31`) |
+
+**Usos de hoy que rompen las reglas:**
+
+- **19 switches con su texto armado a mano → `sui-switch-label`.** Ejemplos:
+  `pages/discounts/discounts.html:198` («Un uso por cliente», con `sui-form-label` + `<span>`),
+  `pages/drivers/drivers.html:58` («Aceptar pedidos automáticamente»),
+  `pages/super-admin/master-plans/master-plans.html:90` («Plan activo», y 8 más en ese archivo).
+  El resto: `discounts.html:302`, `pages/super-admin/master-map-overview/master-map-overview.html:67`,
+  `pages/schedule/schedule.html:46`, `components/add-product-modal/add-product-modal.html:196`, `:255`, `:280`,
+  `components/option-sections-manager/option-sections-manager.html:107`, `:123`.
+- **3 con la etiqueta que repite el estado** («Disponible» / «No disponible», «Activo»):
+  `components/option-sections-manager/option-sections-manager.html:143`,
+  `components/add-product-modal/add-product-modal.html:303`, `pages/employees/employees.html:99`.
+- **2 en `medium` (sin `size`):** `pages/drivers/drivers.html:58`,
+  `pages/super-admin/master-map-overview/master-map-overview.html:67`.
+- **1 nativo dibujado como switch:** `components/settings-panel/settings-panel.html:97`
+  («Notificaciones Push») → `sui-switch-label`.
+
+Bien pelados (el texto vive en la fila o la tabla): `pages/discounts/discounts.html:96` (columna
+de la tabla), `pages/super-admin/master-settings/master-settings.html:103`, los días de
+`components/weekly-schedule-editor/weekly-schedule-editor.html:5` y
+`pages/driver/driver-schedule/driver-schedule.html:108`, `pages/central/central-ofertas/central-ofertas.html:19`.
+
+## Tamaño en mobile y en web
+
+| uso | mobile | web |
+|---|---|---|
+| switch en una fila, tabla o tarjeta | `xlarge` (48 × 28) | `large` (40 × 24) |
+| switch que es la acción principal de la tarjeta (ofertas de Central) | `xlarge` | `xlarge` |
+
+```html
+<sui-switch [size]="bp.controlSize()" … />   <!-- isMobile() ? 'xlarge' : 'large' -->
+```
+
+El más grande mide 28 px de alto: el toque cómodo (≥ 44 px) lo da la fila; por eso con texto
+va `sui-switch-label`, que hace tocable todo el bloque.
+
+## «No usar»: por qué no hoy y cuándo sí
+
+| qué | por qué no hoy | cuándo sí, en un flujo nuevo |
+|---|---|---|
+| `size="medium"` | en el teléfono se pierde (el dueño lo marcó en Central, 28-09-2026) | una tabla densa solo de desktop donde 24 px desalinea la fila |
+| pelado con texto al lado | lo hace `sui-switch-label` con el toque en toda la fila | nunca; pelado solo si el texto vive en otra columna o en el título de la tarjeta |
+
+## API
+
+<!-- api:inicio -->
+<!-- generada: no editar a mano — `npm run docs` -->
+
+| input | tipo | default |
+|---|---|---|
+| `size` | `'medium' \| 'large' \| 'xlarge'` | `'medium'` |
+| `checked` | `boolean` | `false` |
+| `disabled` | `boolean` | `false` |
+
+| output | payload |
+|---|---|
+| `checkedChange` | `boolean` |
+<!-- api:fin -->
+
+Implementa `ControlValueAccessor` (`[(ngModel)]`, `formControlName`).
+
+## Trampas
+
+- **Es controlado: no se mueve solo.** `[checked]` sin `(checkedChange)` ni `[(checked)]` = el
+  toque no hace nada visible. Es a propósito: el padre puede rechazar el cambio (abrir una
+  confirmación, revertir si falla el guardado).
+- Con `formControlName` sí guarda su propio estado; a partir de ahí **ignora `[checked]`**. No
+  mezcles las dos formas.
+- `disabled` no baja la opacidad: cambia el color y achica el círculo. Un `opacity` encima lo duplica.
+- No tiene `aria-label`: pelado, pásalo con `[attr.aria-label]` (como en `central-ofertas`).
+- Ya trae el arreglo de iOS para el `:active` pegado.
+
+## Ejemplo
+
+```html
+<!-- Pelado en una tarjeta que ya tiene su título -->
+<sui-switch [size]="bp.controlSize()" [checked]="oferta.activo" [disabled]="guardando()"
+            [attr.aria-label]="'Prender ' + oferta.titulo" (checkedChange)="prender(oferta, $event)" />
+
+<!-- Con texto: sui-switch-label -->
+<sui-switch-label [size]="bp.controlSize()" label="Recibir pedidos" [flip]="true"
+                  [(active)]="abierto" />
+```

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>
+```