@ajuarezso/sui-stencil 0.0.0-stage → 0.1.0

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

@@ -0,0 +1,231 @@
+---
+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
+
+<!-- generado por scripts/gen-docs.mjs — no editar a mano; `npm run docs` -->
+
+> **De dónde sale este doc.** El criterio es el del SUI Angular (`sui-store-card`); la API es la de este
+> paquete, leída del código. Los ejemplos se pasaron de Angular de forma mecánica: lo literal va como
+> atributo (`only-icon`, `size="large"`), lo dinámico entre llaves (`size={expr}` → `el.size = expr`)
+> y los eventos como `onValueChange={…}` → `el.addEventListener('valueChange', …)`. `@if`, `@for` y
+> `<ng-template>` quedan como en Angular: se leen como pseudocódigo.
+>
+> **La API de aquí no es igual a la de Angular.** Lo que el texto nombre y figure en «Diferencias con
+> el SUI Angular» (dentro de API) aquí no existe.
+
+Story: [Molecules/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:117`,
+> con `deliveryText` y `distanceText`) y la cola de aprobación
+> (`pages/super-admin/master-approvals/master-approvals.html:31`, en vista previa). Líneas
+> revisadas el 06-10-2026. 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». | según el código |
+| `isOpen: false` | Cerrado: chip «Cerrado» y la portada en gris; sigue abriendo la carta (se puede mirar). | según el código |
+| `isSuspended: true` | No se puede pedir: «No disponible», toda la tarjeta al 60 % y sin link. | según el código |
+| `isOwnerPreview` + `ownerPreviewStatus` | Vista previa: «Borrador», «En revisión» o «Rechazado»; sin corazón, sin nota ni distancia (solo ubicación y envío). | según el código |
+
+### Las piezas
+
+| prop | cuándo | fuente |
+|---|---|---|
+| `store` (obligatorio) | Siempre, con `SuiStoreCardData`. | según el código |
+| `deliveryText` string | **Siempre en pantallas nuevas**: el texto del envío calculado por la app (`StateService.computeDeliveryFee`). | canon (aprobado por el dueño, 05-10-2026, bloque B9); precedente: favoritos |
+| `deliveryText = null` | No hay envío que mostrar: la columna desaparece y el distrito deja de cortarse. | según el código |
+| `deliveryText` sin pasar | La tarjeta lo deduce de `deliveryType` (Gratis / Recojo / Courier / S/ X). Solo para no romper lo viejo. | según el código |
+| `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. | canon (aprobado por el dueño, 05-10-2026, bloque B4) |
+| `isFavorite` + `toggleFavorite` | El corazón lleno o vacío; el padre guarda el favorito. | según el código |
+| `ratingClicked` | La nota abre las opiniones y la info del local (`StoreRatingsModalService`). | canon (aprobado por el dueño, 05-10-2026, bloque B9) |
+| `disableLink` | La tarjeta no navega (una vitrina, una lámina, una vista previa). | según el código |
+
+**Usos de hoy que rompen las reglas:** 1. Favoritos pasa `small` en la computadora
+(`pages/customer/favorites/favorites.html:117`, `size={bp.isMobile() ? 'large' : 'small'}`): con
+D16 va `medium` (ver «Por dispositivo»). 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 |
+| `large` | 44 × 44 | 20 | canon (dueño, 04-10-2026): piso táctil 44 en el teléfono. Size nuevo del 04-10-2026; además la nota se toca en 44 de alto |
+
+| 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 | `large` (44) | `medium` (40) | mobile: canon (dueño, 04-10-2026): piso táctil 44 en el teléfono · web: canon (dueño, 05-10-2026, D16), antes `small` (el default del componente: hay que pasarlo) |
+| nota (abre las opiniones) | `large`: se ve igual (≈ 38) y se toca en 44 de alto con un `::before` invisible que no se estira a los lados (no pisa la columna de al lado) | ≈ 38: padding 4 × 2 + etiqueta de 10 px + gap 2 + valor de 13 px, con el `line-height` heredado | canon (dueño, 04-10-2026): piso táctil 44 en el teléfono (área) · medido del `.scss` (alto visible) |
+
+```html
+<sui-store-card store={local} size={bp.sizeControl()} />
+```
+
+`medium` (40) es el de la computadora (D16); la tablet va como el teléfono, porque se toca.
+**Favoritos pasa `small` en la computadora** (`pages/customer/favorites/favorites.html:117`,
+`size={bp.isMobile() ? 'large' : 'small'}`): el corazón queda en 36 y en un iPad de 768 o más
+también, porque `isMobile()` no mira el puntero. Va `size={bp.sizeControl()}` (cambio de la app,
+no del DS).
+
+### Por dispositivo (D16)
+
+El corazón y la nota se tocan: la tarjeta sigue la fila «lo que se toca». Fuente: D16, dueño
+05-10-2026 (tabla por componente: «el default del componente es `small`: hay que pasar `size`»).
+
+| dispositivo | size | nota |
+|---|---|---|
+| celular chico (< 380) | `large` (interino) | D16 pide `medium` con área de 44, pero el DS todavía no estira el corazón de 40 a 44: hasta que lo haga, se queda `large` |
+| celular (380–767) | `large` | corazón de 44 y la nota tocable en 44 de alto |
+| tablet táctil (`pointer: coarse`) | `large` | se toca igual que el teléfono |
+| computadora (`pointer: fine`) | `medium` | corazón de 40; nunca `small` (el default) |
+
+En el ultrawide, igual que en la computadora: el espacio extra va a más columnas en la grilla, no
+a una tarjeta más grande.
+
+En master-pedidos: `size={bp.sizeControl()}` (`large` en todo celular y pantalla táctil,
+`medium` en la computadora).
+
+## «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` -->
+
+| prop | atributo | tipo | default |
+|---|---|---|---|
+| `deliveryText` | `delivery-text` | `null \| string \| undefined` | `undefined` |
+| `disableLink` | `disable-link` | `boolean` | `false` |
+| `distanceText` | `distance-text` | `null \| string \| undefined` | `undefined` |
+| `isFavorite` | `is-favorite` | `boolean` | `false` |
+| `linkBase` | `link-base` | `string` | `'/cliente/restaurante'` |
+| `size` | `size` | `"large" \| "medium" \| "small"` | `'small'` |
+| `store` | — (solo por propiedad JS) | `SuiStoreCardData \| undefined` | `undefined` |
+| `storeJson` | `store-json` | `string \| undefined` | `undefined` |
+
+| evento | `event.detail` |
+|---|---|
+| `ratingClicked` | `SuiStoreRatingClickDetail` |
+| `toggleFavorite` | `Event` |
+
+### Diferencias con el SUI Angular
+
+- **Props solo de aquí:** `storeJson`
+<!-- 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.
+
+## Bien y mal
+
+Corazón en la computadora
+
+```html
+<!-- ❌ mal: small (36) en la computadora y en el iPad; D16 pide medium y large (pages/customer/favorites/favorites.html:117) -->
+<sui-store-card size={bp.isMobile() ? 'large' : 'small'} store={fav} is-favorite />
+```
+
+```html
+<!-- ✅ bien -->
+<sui-store-card size={bp.sizeControl()} store={fav} is-favorite />
+```
+
+Envío y distancia en un listado nuevo
+
+```html
+<!-- ❌ mal: sin deliveryText la tarjeta deduce el envío del deliveryType y puede cobrar distinto que el checkout (mismo patrón que pages/super-admin/master-approvals/master-approvals.html:31, a mirar) -->
+<sui-store-card store={local} size={bp.sizeControl()} />
+```
+
+```html
+<!-- ✅ bien: el texto llega escrito; null quita la columna -->
+<sui-store-card store={local} size={bp.sizeControl()}
+  deliveryText={envioDeLaTarjeta(local)} distanceText={distanciaDeLaTarjeta(local)} />
+```
+
+Tarjeta en una vitrina
+
+```html
+<!-- ❌ mal: sin disableLink la tarjeta navega a /cliente/restaurante/:id desde una lámina -->
+<sui-store-card store={local} size={bp.sizeControl()} />
+```
+
+```html
+<!-- ✅ bien -->
+<sui-store-card store={local} size={bp.sizeControl()} disable-link />
+```
+
+## Ejemplo
+
+```html
+<sui-store-card
+  store={local}
+  size={bp.sizeControl()}
+  is-favorite
+  deliveryText={envioDeLaTarjeta(local)}
+  distanceText={distanciaDeLaTarjeta(local)}
+  onToggleFavorite={() => quitarFavorito(local.id)}
+  onRatingClicked={(e) => abrirOpiniones(e.detail)} />
+```

package/docs/sui-swatch/README.md

@@ -0,0 +1,35 @@
+---
+name: sui-swatch
+selector: sui-swatch
+resumen: Celda de color para documentar la paleta de tokens del DS
+alternativas: []
+---
+
+# sui-swatch
+
+<!-- generado por scripts/gen-docs.mjs — no editar a mano; `npm run docs` -->
+
+> El SUI Angular no tiene un componente con este nombre, así que no hay criterio de uso que
+> heredar. Lo de abajo es la descripción que trae el código y su API.
+
+`<sui-swatch>` — Celda de color para documentar la paleta de tokens del DS.
+
+Componente utilitario mínimo (foundations). Renderiza un bloque de color
+con su nombre de token y el valor resuelto. Pensado para la story
+"Foundations/Tokens", no para uso en producto.
+
+## API
+
+<!-- api:inicio -->
+<!-- generada: no editar a mano — `npm run docs` -->
+
+| prop | atributo | tipo | default |
+|---|---|---|---|
+| `label` | `label` | `string \| undefined` | `undefined` |
+| `token` | `token` | `string` | — (requerido) |
+| `value` | `value` | `string \| undefined` | `undefined` |
+
+Eventos: ninguno.
+
+CSS parts: `chip`, `meta`.
+<!-- api:fin -->

package/docs/sui-switch/README.md

@@ -0,0 +1,234 @@
+---
+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
+
+<!-- generado por scripts/gen-docs.mjs — no editar a mano; `npm run docs` -->
+
+> **De dónde sale este doc.** El criterio es el del SUI Angular (`sui-switch`); la API es la de este
+> paquete, leída del código. Los ejemplos se pasaron de Angular de forma mecánica: lo literal va como
+> atributo (`only-icon`, `size="large"`), lo dinámico entre llaves (`size={expr}` → `el.size = expr`)
+> y los eventos como `onValueChange={…}` → `el.addEventListener('valueChange', …)`. `@if`, `@for` y
+> `<ng-template>` quedan como en Angular: se leen como pseudocódigo.
+
+Story: [Atoms/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. Canon: aprobado por el dueño, 05-10-2026, bloque B2.)
+- 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` + `checkedChange` 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 | Celular y tablet táctil: `bp.tactil() ? 'xlarge' : 'large'`. 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»); la tablet: D16, dueño 05-10-2026 |
+| `large` | 40 × 24 | Computadora. | canon (aprobado por el dueño, 28-09-2026); confirmado en D16, dueño 06-10-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). | canon (aprobado por el dueño, 05-10-2026, bloque B4; 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:207` («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:92` («Plan activo», y 8 más en ese archivo).
+  El resto: `discounts.html:319`, `pages/super-admin/master-map-overview/master-map-overview.html:67`,
+  `pages/schedule/schedule.html:46`, `components/add-product-modal/add-product-modal.html:205`, `:264`, `:289`,
+  `components/option-sections-manager/option-sections-manager.html:107`, `:125`.
+- **3 con la etiqueta que repite el estado** («Disponible» / «No disponible», «Activo»):
+  `components/option-sections-manager/option-sections-manager.html:145`,
+  `components/add-product-modal/add-product-modal.html:312`, `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:98` (columna
+de la tabla), `pages/super-admin/master-settings/master-settings.html:105`, los días de
+`components/weekly-schedule-editor/weekly-schedule-editor.html:5` y
+`pages/driver/driver-schedule/driver-schedule.html:106`, `pages/central/central-ofertas/central-ofertas.html:19`.
+
+## Tamaño en mobile y en web
+
+| uso | mobile | web | fuente |
+|---|---|---|---|
+| switch en una fila, tabla o tarjeta | `xlarge` (48 × 28) | `large` (40 × 24) | canon (aprobado por el dueño, 28-09-2026); web confirmado en D16, dueño 06-10-2026 |
+| switch que es la acción principal de la tarjeta (ofertas de Central) | `xlarge` | `xlarge` | canon (aprobado por el dueño, 28-09-2026). Excepción previa a D16: la tabla de D16 pone `large` en la computadora y no la menciona. Pendiente de confirmar |
+
+```html
+<sui-switch size={bp.tactil() ? '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.
+
+### Por dispositivo (D16)
+
+Fila de `switch` en la tabla de D16 (dueño, 05-10-2026; computadora resuelta el 06-10-2026): se
+toca, y en la computadora va **un paso menos que en el celular**, sin bajar a `medium`.
+
+| dispositivo | size | nota |
+|---|---|---|
+| celular chico (< 380 px) | `xlarge` (48 × 28) | la fila que lo contiene da los 44 de alto |
+| celular (380–767 px) | `xlarge` (48 × 28) | |
+| tablet táctil (`pointer: coarse`) | `xlarge` (48 × 28) | se toca con el dedo, aunque mida más de 767 |
+| computadora (`pointer: fine`) | `large` (40 × 24) | un paso menos que el celular (dueño, 06-10-2026) |
+
+Ultrawide (≥ 1920 px): igual que la computadora, `large`. `medium` no se usa en ningún dispositivo
+(ver «No usar»).
+
+En master-pedidos: `size={bp.tactil() ? 'xlarge' : 'large'}`, la misma expresión que
+`sui-switch-label`. La fila de D16 nombra `bp.controlSize()`, que es lo que usan los 25 switches de
+hoy, pero ese helper mira solo el ancho (`isMobile()`, ≤ 767): en un iPad de 768 o más da `large`.
+`bp.tactil()` también mira el puntero y da lo que pide la tabla. Si `controlSize()` pasa a mirar
+`tactil()`, los 25 quedan bien sin tocar las pantallas.
+
+## «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` -->
+
+| prop | atributo | tipo | default |
+|---|---|---|---|
+| `checked` | `checked` | `boolean` | `false` |
+| `disabled` | `disabled` | `boolean` | `false` |
+| `focusable` | `focusable` | `boolean` | `true` |
+| `size` | `size` | `"large" \| "medium" \| "xlarge"` | `'medium'` |
+
+| evento | `event.detail` |
+|---|---|
+| `checkedChange` | `boolean` |
+
+### Diferencias con el SUI Angular
+
+Ninguna en nombres de props, eventos y valores.
+<!-- api:fin -->
+
+Implementa `ControlValueAccessor` (`ngModel` + `ngModelChange`, `formControlName`).
+
+## Trampas
+
+- **Es controlado: no se mueve solo.** `checked` sin `checkedChange` ni `checked` + `checkedChange` = 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`).
+  Dentro de `sui-switch-label`, `sui-switch-card`, `sui-integration-switch` y el toggle de
+  `sui-content-label` ya toma el nombre del texto con `aria-labelledby` (revisión 04-10-2026).
+- **`focusable="false"` lo saca del Tab** (tabindex -1), para cuando un padre es el control
+  enfocable. `tabindex="-1"` en el host no sirve: el binding del componente lo pisa.
+- Ya trae el arreglo de iOS para el `:active` pegado.
+
+## Bien y mal
+
+Interruptor con su texto al lado
+
+```html
+<!-- ❌ mal: texto armado a mano y sin size, queda en medium (pages/drivers/drivers.html:58) -->
+<label class="drivers__autoconfirm">
+  <div class="drivers__autoconfirm-text">
+    <span class="drivers__autoconfirm-title">Aceptar pedidos automáticamente</span>
+    <span class="drivers__autoconfirm-desc">El pedido salta la confirmación y pasa directo a buscar repartidor (como los locales administrados).</span>
+  </div>
+  <sui-switch checked={autoConfirm()} onCheckedChange={(e) => setAutoConfirm(e.detail)} />
+</label>
+```
+
+```html
+<!-- ✅ bien -->
+<sui-switch-label size={bp.tactil() ? 'xlarge' : 'large'} flip
+  label="Aceptar pedidos automáticamente"
+  description="El pedido salta la confirmación y pasa directo a buscar repartidor (como los locales administrados)."
+  active={autoConfirm()} onActiveChange={(e) => setAutoConfirm(e.detail)} />
+```
+
+Estado de un empleado en su tarjeta
+
+```html
+<!-- ❌ mal: large fijo en el teléfono y una etiqueta que cambia con el estado (pages/employees/employees.html:99) -->
+<sui-switch size="large" checked={employee.status === 'Activo'} onCheckedChange={() => toggleStatus(employee.id)} />
+<span class="employees__toggle-label">{employee.status}</span>
+```
+
+```html
+<!-- ✅ bien -->
+<sui-switch-label size={bp.tactil() ? 'xlarge' : 'large'} label="Empleado activo"
+  active={employee.status === 'Activo'} onActiveChange={() => toggleStatus(employee.id)} />
+```
+
+Pelado sin nombre accesible
+
+```html
+<!-- ❌ mal: sin aria-label el lector de pantalla dice «interruptor» y nada más -->
+<sui-switch size={bp.tactil() ? 'xlarge' : 'large'} checked={oferta.activo} onCheckedChange={(e) => prender(oferta, e.detail)} />
+```
+
+```html
+<!-- ✅ bien -->
+<sui-switch size={bp.tactil() ? 'xlarge' : 'large'} checked={oferta.activo}
+  aria-label={'Prender ' + oferta.titulo} onCheckedChange={(e) => prender(oferta, e.detail)} />
+```
+
+## Ejemplo
+
+```html
+<!-- Pelado en una tarjeta que ya tiene su título -->
+<sui-switch size={bp.tactil() ? 'xlarge' : 'large'} checked={oferta.activo} disabled={guardando()}
+            aria-label={'Prender ' + oferta.titulo} onCheckedChange={(e) => prender(oferta, e.detail)} />
+
+<!-- Con texto: sui-switch-label -->
+<sui-switch-label size={bp.tactil() ? 'xlarge' : 'large'} label="Recibir pedidos" flip
+                  active={abierto} onActiveChange={(e) => (abierto = e.detail)} />
+```