@ajuarezso/sui-stencil 0.0.0-stage → 0.1.0

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

@@ -0,0 +1,234 @@
+---
+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
+
+<!-- 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-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/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` (según la guía del DS: el switch
+  es «para prender o apagar un ajuste de forma inmediata»).
+- 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 04-10-2026 en `master-pedidos/src/app` (misma exclusión que `sui-card`): **16
+> switch-cards en 8 archivos**. Tipos: 14 `left-icon` (los 14 con el ícono proyectado), 2 `basic`.
+> Tamaños: los 16 con `bp.controlSize()`. Ninguna vive ya en un formulario que se guarda con un
+> botón: las 10 que lo hacían pasaron a `sui-checkbox-card` el 03-10-2026.
+
+### `type` (el leading)
+
+| type | cuándo | fuente |
+|---|---|---|
+| `left-icon` + ícono proyectado | Lo normal: `<sui-icon sui-switch-card-leading name="…" size="20" />`. | canon (aprobado por el dueño, 05-10-2026, bloque B2) (14 de 16) |
+| `left-icon` + `emoji` | Ver «No usar». | canon (aprobado por el dueño, 05-10-2026, bloque B6) |
+| `basic` | El ajuste es EL tema de la pantalla y no necesita ícono («Disponible» en el inicio del repartidor, «Disponibilidad automática»). | canon (aprobado por el dueño, 05-10-2026, bloque B2) |
+| `avatar` (`imageUrl`) | Ver «No usar». | canon (aprobado por el dueño, 05-10-2026, bloque B6) |
+| `card-provider`, `brand`, `company` (`imageUrl` o proyectado) | Ver «No usar». | canon (aprobado por el dueño, 05-10-2026, bloque B6) |
+
+### Las piezas
+
+| prop | cuándo | fuente |
+|---|---|---|
+| `label` | Siempre. Qué hace prenderlo, sin cambiar con el estado: «Notificaciones», no «Activadas / Desactivadas». | canon (aprobado por el dueño, 05-10-2026, bloque B4) (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.» | canon (aprobado por el dueño, 05-10-2026, bloque B4) |
+| `sublabel` | Precisión corta: «(beta)». | canon (aprobado por el dueño, 05-10-2026, bloque B4) |
+| `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). | canon (aprobado por el dueño, 05-10-2026, bloque B8) |
+| `checked` + `checkedChange` | Siempre los dos: es controlada. | según el código |
+
+### `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) | Computadora, vía `bp.controlSize()`. Un paso menos que el celular; no baja a `medium`. | canon (aprobado por el dueño, 28-09-2026); confirmado en D16, dueño 06-10-2026 |
+| `medium` (default) | No usar en pantallas nuevas. | canon (aprobado por el dueño, 28-09-2026) |
+
+**Usos de hoy que rompen las reglas: 1** (medido el 06-10-2026, 22 switch-cards en 11 archivos).
+`pages/super-admin/master-categorias/master-categorias.html:170` («Chapa «Beta»») va con
+`size="large"` fijo: en el teléfono queda un paso chico. Va `size={bp.controlSize()}`. Los 10 que
+se guardaban con un botón (métodos de pago de mi-negocio y 5 ajustes de master-settings) pasaron a
+`sui-checkbox-card`, y el de `pages/notifications/notifications.html:59` («Sonidos de la app») ya
+lleva `bp.controlSize()`, los dos el 03-10-2026.
+
+## Tamaño en mobile y en web
+
+La card entera se toca: 74 px con descripción (16 + 40 + 16 de padding y contenido, más 2 de
+borde) y 54 px la más chica (`basic`, sin descripción, `medium`). 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' -->
+```
+
+### Por dispositivo (D16)
+
+Fuente: D16, dueño 05-10-2026, con la fila de checkbox, radio y switch resuelta el 06-10-2026.
+
+| dispositivo | size | nota |
+|---|---|---|
+| celular chico (< 380) | `xlarge` | la card entera ya pasa de 44; el size solo agranda el interruptor |
+| celular (380–767) | `xlarge` | |
+| tablet táctil (`pointer: coarse`) | `xlarge` | `bp.controlSize()` mira solo el ancho: un iPad de 768 o más recibe `large` hasta que el helper mire el puntero |
+| computadora (`pointer: fine`) | `large` | un paso menos que el celular; no baja a `medium` (D16, dueño 06-10-2026) |
+
+Ultrawide: igual que la computadora (`large`).
+
+En master-pedidos: `size={bp.controlSize()}` (`xlarge` hasta 767 px, `large` desde ahí). La
+expresión exacta de D16, con la tablet, es `bp.tactil() ? '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 | no hay: en la computadora va `large` (D16, dueño 06-10-2026) |
+
+## API
+
+<!-- api:inicio -->
+<!-- generada: no editar a mano — `npm run docs` -->
+
+| prop | atributo | tipo | default |
+|---|---|---|---|
+| `badge` | `badge` | `SuiBadgeConfig \| null \| string` | `null` |
+| `checked` | `checked` | `boolean` | `false` |
+| `description` | `description` | `null \| string` | `null` |
+| `disabled` | `disabled` | `boolean` | `false` |
+| `emoji` | `emoji` | `"bar-chart" \| "bell" \| "bell-with-slash" \| "birthday-cake" \| "busts-in-silhouette" \| "card-index-dividers" \| "check-mark" \| "check-mark-button" \| "clapping-hands" \| "confused-face" \| "cross-mark" \| "delivery-truck" \| "dollar-banknote" \| "face-screaming" \| "face-with-rolling-eyes" \| "gear" \| "glowing-star" \| "grinning-face" \| "grinning-face-smiling-eyes" \| "hamburger" \| "hammer" \| "handshake" \| "house" \| "kick-scooter" \| "label" \| "locked" \| "magnifying-glass-tilted-left" \| "mobile-phone" \| "money-bag" \| "money-with-wings" \| "motorcycle" \| "neutral-face" \| "no-entry" \| "office-building" \| "package" \| "party-popper" \| "partying-face" \| "pensive-face" \| "pizza" \| "pushpin" \| "receipt" \| "rocket" \| "shop" \| "shopping-bags" \| "shopping-cart" \| "sleeping-face" \| "slightly-smiling-face" \| "smiling-face-hearts" \| "sparkles" \| "spiral-calendar" \| "star-struck" \| "taco" \| "thinking-face" \| "thumbs-up" \| "unlocked" \| "warning" \| "waving-hand" \| "wrench" \| null` | `null` |
+| `icon` | `icon` | `null \| string` | `null` |
+| `iconSrc` | `icon-src` | `null \| string` | `null` |
+| `imageUrl` | `image-url` | `null \| string` | `null` |
+| `label` | `label` | `string` | `''` |
+| `size` | `size` | `"large" \| "medium" \| "xlarge"` | `'medium'` |
+| `sublabel` | `sublabel` | `null \| string` | `null` |
+| `type` | `type` | `"avatar" \| "basic" \| "brand" \| "card-provider" \| "company" \| "left-icon"` | `'basic'` |
+
+| evento | `event.detail` |
+|---|---|
+| `checkedChange` | `boolean` |
+
+Slots: `leading`.
+
+### Diferencias con el SUI Angular
+
+- **Props solo de aquí:** `icon`, `iconSrc`
+<!-- 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.
+- **Teclado**: el único tab stop es el switch de la derecha, con nombre = `label` y descripción =
+  `description` (`aria-labelledby` / `aria-describedby`). Espacio y Enter emiten
+  `checkedChange` **una vez** (revisión 04-10-2026); antes emitían dos (el switch y, por burbujeo, la card),
+  y en formulario el valor se revertía.
+- El interruptor siempre va a la derecha (no hay `flip`).
+- `badge` con string sale **azul `light` `small`** (en `sui-switch-label` sale naranja).
+
+## Bien y mal
+
+Tamaño fijo
+
+```html
+<!-- ❌ mal: large fijo; en el teléfono el interruptor queda un paso chico (pages/super-admin/master-categorias/master-categorias.html:170) -->
+<sui-switch-card type="basic" size="large" label="Chapa «Beta»"
+  checked={!!e.etiqueta} onCheckedChange={(e) => editar('etiqueta', e.detail ? 'Beta' : '')} />
+```
+
+```html
+<!-- ✅ bien -->
+<sui-switch-card type="basic" size={bp.controlSize()} label="Chapa «Beta»"
+  checked={!!e.etiqueta} onCheckedChange={(e) => editar('etiqueta', e.detail ? 'Beta' : '')} />
+```
+
+Interruptor que no se mueve
+
+```html
+<!-- ❌ mal: es controlada; sin checkedChange el toque no cambia nada -->
+<sui-switch-card type="basic" size={bp.controlSize()} label="Estoy trabajando"
+  checked={isAvailable()} />
+```
+
+```html
+<!-- ✅ bien (como pages/driver/driver-dashboard/driver-dashboard.html:211) -->
+<sui-switch-card type="basic" size={bp.controlSize()} label="Estoy trabajando"
+  checked={isAvailable()} onCheckedChange={(e) => onAvailabilityChange(e.detail)} />
+```
+
+Ícono del ajuste
+
+```html
+<!-- ❌ mal: el ícono no se proyecta con slot=; left-icon queda con el círculo vacío -->
+<sui-switch-card type="left-icon" size={bp.controlSize()} label="Notificaciones" checked={push()} onCheckedChange={(e) => cambiarPush(e.detail)}>
+  <sui-icon slot="leading" name="notification-3-line" size="20" />
+</sui-switch-card>
+```
+
+```html
+<!-- ✅ bien -->
+<sui-switch-card type="left-icon" size={bp.controlSize()} label="Notificaciones" checked={push()} onCheckedChange={(e) => cambiarPush(e.detail)}>
+  <sui-icon sui-switch-card-leading name="notification-3-line" size="20" />
+</sui-switch-card>
+```
+
+## Ejemplo
+
+```html
+<sui-switch-card
+  size={bp.controlSize()}
+  type="left-icon"
+  label="Ubicación siempre"
+  description={ubicacionTexto()}
+  checked={ubicacionSiempre()}
+  disabled={guardando()}
+  onCheckedChange={(e) => cambiarUbicacion(e.detail)}>
+  <sui-icon sui-switch-card-leading name="map-pin-line" size="20" />
+</sui-switch-card>
+```

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

@@ -0,0 +1,242 @@
+---
+name: sui-switch-label
+selector: sui-switch-label
+resumen: Interruptor con su texto (y opcionalmente descripción, badge y link) para un ajuste que se aplica al instante
+alternativas: [sui-switch (el interruptor solo, el texto vive en otra parte), sui-switch-card (cada ajuste es una tarjeta), sui-integration-switch (fila de integración con logo), sui-checkbox-label (se confirma después)]
+---
+
+# sui-switch-label
+
+<!-- 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-label`); 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 Label](https://sui-design-system.web.app/?path=/docs/atoms-checkbox-radio-switch-switch-label--docs)
+
+## Cuándo usarlo / cuándo no
+
+**Úsalo** para cada fila de ajustes que se prende o se apaga: «Disponible para pedir», «Recibir
+pedidos», «Un uso por cliente», «Permitir analítica de uso». Es el default de una lista de
+ajustes: toda la fila se toca y el texto queda alineado con el interruptor.
+
+**No lo uses** para:
+
+- Un ajuste que merece tarjeta (borde, ícono, más contexto): `sui-switch-card`.
+- Una integración con logo y botón de administrar: `sui-integration-switch`.
+- Algo que se confirma después con «Guardar» y no tiene efecto propio: `sui-checkbox-label`.
+- Algo destructivo o que no se deshace.
+
+Regla corta: **ajuste con texto → este · ajuste con peso → switch-card · sin texto → sui-switch.**
+
+## Qué variante usar
+
+> **La guía del DS dice para qué es el switch** («prender o apagar un ajuste de forma inmediata»)
+> y su ejemplo avanzado arma Label + (Sublabel) + badge «NEW» + descripción + Link Button, con el
+> interruptor a la izquierda o a la derecha. No dice cuándo va cada lado.
+>
+> Uso medido el 03-10-2026 en `master-pedidos/src/app` (misma exclusión que `sui-badge`):
+> **5 usos en 4 archivos**, todos con `description`. Desde el 03-10-2026, 3 con `flip` (los
+> ajustes del producto en `add-product-modal` y la analítica de `privacidad`) y 2 sin él porque
+> viven dentro de un formulario (el horario de una categoría en `products`, «Cerrar por hoy» en
+> `central-inicio`). Tamaños (revisado el 06-10-2026): 2 `ctrlSize()` (`large`/`xlarge`), 1
+> `bp.isMobile() ? '2xlarge' : 'xlarge'` («Cerrar por hoy»), 2 sin `size` (`medium`). Hay **19
+> `sui-switch` con el texto armado a mano** y 1 nativo que deberían ser este componente.
+
+### Las piezas
+
+| prop | cuándo | fuente |
+|---|---|---|
+| `label` | Siempre. Qué hace prenderlo, sin cambiar con el estado: «Recibir pedidos», no «Abierto/Cerrado». | según la guía del DS (pieza); la regla de qué dice: canon (aprobado por el dueño, 05-10-2026, bloque B4) (precedente en `pages/schedule/schedule.html:31`) |
+| `description` | Cuando conviene decir la consecuencia: «Los clientes pueden agregarlo al carrito. Apágalo si se te acabó.» Es lo que ya hacen los 5 usos. | según la guía del DS (pieza); el «cuándo» ya es práctica de la app |
+| `sublabel` | Precisión corta entre paréntesis: «(beta)». | según la guía del DS |
+| `badge` | Solo novedad. Con string sale naranja `light`: pasa el objeto. | según la guía del DS (pieza «NEW»); el color es propuesta |
+| `link` | «Saber más» que no toca el interruptor. Solo se ve con `description`. | según la guía del DS |
+| `flip` | Interruptor a la **derecha** en listas de ajustes: el texto se lee primero y el control queda bajo el pulgar, como en iOS y Android (es lo que hacen a mano `drivers.html:58`, `discounts.html:207`, `schedule.html:46`). Sin `flip` (izquierda) dentro de un formulario, alineado con las casillas o los switches del resto del form. | canon (aprobado por el dueño, 03-10-2026) |
+| `disabled` | Mientras se guarda el cambio o cuando no aplica. | según la guía del DS |
+
+### `size`
+
+| size | cuándo | fuente |
+|---|---|---|
+| `xlarge` | Celular y tablet táctil: `size={bp.tactil() ? 'xlarge' : 'large'}`. Con descripción la fila pasa los 44 sola. En la computadora, solo si el ajuste es la acción principal de la pantalla («Cerrar por hoy» en Central): excepción previa a D16, pendiente de confirmar. | celular y tablet: D16 (fila de checkbox, radio y switch, dueño 05-10-2026); computadora: canon (aprobado por el dueño, 28-09-2026: «componentes grandes») |
+| `large` | Computadora. | canon (aprobado por el dueño, 28-09-2026); confirmado en D16, dueño 06-10-2026 |
+| `2xlarge` | Existe: la misma fila de `xlarge` con `min-height: 44px`. En qué dispositivo va está **pendiente** (ver «Por dispositivo»). | el size: canon (dueño, 04-10-2026: piso táctil 44 en el teléfono); su uso: pendiente |
+| `medium` (default) | No usar en pantallas nuevas. | canon (aprobado por el dueño, 28-09-2026) |
+
+**Usos de hoy que rompen las reglas:**
+
+- **2 en `medium`:** `pages/products/products.html:303` («Horario propio
+  para esta categoría») y `pages/public/privacidad/privacidad.html:132` («Permitir analítica de uso»).
+- **19 `sui-switch` con texto a mano + 1 nativo** que deberían ser este componente: el detalle
+  está en el README de `sui-switch`. Ejemplos: `pages/discounts/discounts.html:207`,
+  `pages/drivers/drivers.html:58`, `components/settings-panel/settings-panel.html:97`.
+
+## Tamaño en mobile y en web
+
+| uso | mobile | web | fuente |
+|---|---|---|---|
+| fila de ajustes | `xlarge` (switch 48 × 28; con descripción la fila pasa los 44) | `large` (40 × 24) | D16 (fila de checkbox, radio y switch, dueño 05-10-2026; computadora 06-10-2026) |
+| ajuste que es la acción principal de la pantalla («Cerrar por hoy») | `xlarge` | `xlarge` | mobile: D16. Web `xlarge`: excepción previa a D16 (canon, dueño 28-09-2026), que pone `large` en la computadora y no la menciona. Pendiente de confirmar |
+
+```html
+<sui-switch-label size={bp.tactil() ? 'xlarge' : 'large'} … />
+```
+
+| size | switch | label | descripción | alto de la fila sin descripción |
+|---|---|---|---|---|
+| `medium` (default, Figma) | 32 × 20 | 14/20 | 12/16 | 20 |
+| `large` | 40 × 24 | 16/24 | 12/16 | 24 |
+| `xlarge` | 48 × 28 | 16/24 | 12/16 | 28 |
+| `2xlarge` | 48 × 28 | 16/24 | 12/16 | **44** (`min-height`) |
+
+El bloque entero se toca, así que con descripción la fila pasa los 44 px sola. Sin descripción
+`xlarge` mide 28. `2xlarge` es la misma fila con `min-height: 44px` y todo centrado en vertical
+(canon, dueño 04-10-2026: piso táctil 44 en el teléfono). `2xlarge` no es un size del switch: el
+switch interno se queda en `xlarge`.
+
+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.
+
+### Por dispositivo (D16)
+
+| dispositivo | size | nota |
+|---|---|---|
+| celular chico (< 380 px) | `xlarge` (switch 48 × 28) | con descripción la fila pasa los 44; sin descripción mide 28 (ver pendiente) |
+| celular (380–767 px) | `xlarge` | igual |
+| tablet táctil (`pointer: coarse`) | `xlarge` | se toca con el dedo, aunque mida más de 767 |
+| computadora (`pointer: fine`) | `large` | un paso menos que el celular; no baja a `medium` (D16, dueño 06-10-2026) |
+
+Ultrawide (≥ 1920 px): igual que la computadora (`large`).
+
+**Pendiente: `2xlarge` en la fila sin descripción.** El canon del 04-10-2026 pide una fila de 44 en
+el teléfono, y en este componente eso es `2xlarge`. La fila de D16 (05-10 y 06-10-2026) dice
+`xlarge` para toda la familia y no nombra `2xlarge`. Con descripción no chocan: `xlarge` ya pasa
+los 44, y los 5 usos de hoy la tienen. Sin descripción, `xlarge` deja la fila en 28 y D16 no dice
+si sube a `2xlarge`. Lo decide el dueño; hasta entonces va `xlarge` y, si el ajuste no tiene
+descripción, conviene escribirle una.
+
+En master-pedidos: `size={bp.tactil() ? 'xlarge' : 'large'}`. La fila de D16 nombra
+`bp.controlSize()`, 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.
+
+## «No usar»: por qué no hoy y cuándo sí
+
+| qué | por qué no hoy | cuándo sí, en un flujo nuevo |
+|---|---|---|
+| `badge` (0 usos) | ningún ajuste es nuevo | un ajuste recién agregado en una pantalla que el usuario ya conoce |
+| `link` (0 usos) | ningún ajuste necesita más detalle | «Permitir analítica de uso» con «Qué se mide» (con `description`) |
+| `size="medium"` | se pierde en el teléfono | una tabla densa solo de desktop |
+
+## API
+
+<!-- api:inicio -->
+<!-- generada: no editar a mano — `npm run docs` -->
+
+| prop | atributo | tipo | default |
+|---|---|---|---|
+| `active` | `active` | `boolean` | `false` |
+| `badge` | `badge` | `SuiBadgeConfig \| null \| string` | `null` |
+| `description` | `description` | `null \| string` | `null` |
+| `disabled` | `disabled` | `boolean` | `false` |
+| `flip` | `flip` | `boolean` | `false` |
+| `label` | `label` | `string` | `''` |
+| `link` | `link` | `SuiLinkConfig \| null \| string` | `null` |
+| `size` | `size` | `"2xlarge" \| "large" \| "medium" \| "xlarge"` | `'medium'` |
+| `sublabel` | `sublabel` | `null \| string` | `null` |
+
+| evento | `event.detail` |
+|---|---|
+| `activeChange` | `boolean` |
+| `linkClick` | `MouseEvent` |
+
+### Diferencias con el SUI Angular
+
+Ninguna en nombres de props, eventos y valores.
+<!-- api:fin -->
+
+Implementa `ControlValueAccessor` (`ngModel` + `ngModelChange`, `formControlName`).
+
+## Trampas
+
+- **El estado se llama `active` / `activeChange`**, no `checked` como en `sui-switch`.
+- **Es controlado**, como `sui-switch`: sin `active` + `activeChange` o `activeChange` el toque no se ve.
+- **El host es `inline-flex`.** Con `flip`, para que el interruptor quede pegado al borde derecho
+  de la fila, dale `display: flex` (o `width: 100%`) desde afuera.
+- **`link` solo se dibuja con `description`.**
+- `description` sube el label a peso medio y abre el bloque en columna.
+- Deshabilitado baja todo el bloque a 0.5 de opacidad **además** del gris propio del switch.
+- El badge con string sale naranja; en `sui-switch-card` el default es azul.
+- `flip` usa CSS `order`: el orden de lectura no cambia.
+- El switch de adentro es el tab stop y toma su nombre del `label` y su descripción de la
+  `description` (`aria-labelledby` / `aria-describedby`) (revisión 04-10-2026).
+
+## Bien y mal
+
+Ajuste en una página que también se abre en el teléfono
+
+```html
+<!-- ❌ mal: sin size queda en medium, switch de 32 × 20 (pages/public/privacidad/privacidad.html:132) -->
+<sui-switch-label flip label="Permitir analítica de uso"
+  description="Se puede activar o desactivar en cualquier momento. Nada de lo que escribes sale de tu dispositivo."
+  active={analiticaActiva()} onActiveChange={(e) => cambiarAnalitica(e.detail)} />
+```
+
+```html
+<!-- ✅ bien -->
+<sui-switch-label size={bp.tactil() ? 'xlarge' : 'large'} flip label="Permitir analítica de uso"
+  description="Se puede activar o desactivar en cualquier momento. Nada de lo que escribes sale de tu dispositivo."
+  active={analiticaActiva()} onActiveChange={(e) => cambiarAnalitica(e.detail)} />
+```
+
+Ajuste dentro de un modal con formulario
+
+```html
+<!-- ❌ mal: sin size queda en medium en el teléfono y en la computadora (pages/products/products.html:303) -->
+<sui-switch-label
+  label="Horario propio para esta categoría"
+  description="Fuera de ese horario, sus productos se ven atenuados y no se pueden agregar al carrito. Sin horario propio, la categoría está disponible siempre."
+  active={categoryScheduleEnabled()}
+  disabled={categoryScheduleSaving()}
+  onActiveChange={(e) => categoryScheduleEnabled.set(e.detail)} />
+```
+
+```html
+<!-- ✅ bien: sin flip, porque vive dentro de un formulario -->
+<sui-switch-label
+  size={bp.tactil() ? 'xlarge' : 'large'}
+  label="Horario propio para esta categoría"
+  description="Fuera de ese horario, sus productos se ven atenuados y no se pueden agregar al carrito. Sin horario propio, la categoría está disponible siempre."
+  active={categoryScheduleEnabled()}
+  disabled={categoryScheduleSaving()}
+  onActiveChange={(e) => categoryScheduleEnabled.set(e.detail)} />
+```
+
+Link sin descripción
+
+```html
+<!-- ❌ mal: link solo se dibuja con description; «Qué se mide» no aparece -->
+<sui-switch-label label="Permitir analítica de uso" link="Qué se mide" active={analitica} onActiveChange={(e) => (analitica = e.detail)} />
+```
+
+```html
+<!-- ✅ bien -->
+<sui-switch-label size={bp.tactil() ? 'xlarge' : 'large'} label="Permitir analítica de uso"
+  description="Nada de lo que escribes sale de tu dispositivo." link="Qué se mide" active={analitica} onActiveChange={(e) => (analitica = e.detail)} />
+```
+
+## Ejemplo
+
+```html
+<sui-switch-label
+  size={bp.tactil() ? 'xlarge' : 'large'}
+  flip
+  label="Recibir pedidos"
+  description="Desactívalo para cerrar un rato sin tocar el horario."
+  active={abierto()}
+  disabled={guardando()}
+  onActiveChange={(e) => cambiarAbierto(e.detail)} />
+```