@ajuarezso/sui-design-system 0.20.0 → 0.22.0

package/docs/sui-card/README.md

@@ -0,0 +1,168 @@
+---
+name: sui-card
+selector: sui-card
+resumen: Superficie con borde, radio y sombra que agrupa contenido, con slots de header, cuerpo, media y footer
+alternativas: [sui-content-card (una fila «cara + nombre + detalle» dentro de su cajita), sui-radio-card / sui-checkbox-card / sui-switch-card (la card ES la opción que se elige), sui-product-card (un producto de la carta), sui-store-card (un local en un listado del cliente), sui-modal-sheet (contenido encima de la pantalla)]
+---
+
+# sui-card
+
+Story: [Molecules/Card/Card](https://sui-design-system.web.app/?path=/docs/molecules-card-card--docs)
+
+## Cuándo usarlo / cuándo no
+
+**Úsalo** como la superficie de una sección o de un ítem: un bloque de KPIs, un gráfico con su
+título, una fila de lista que se toca, un formulario corto dentro de una página.
+
+**No lo uses** para:
+
+- Una fila «foto o ícono + nombre + detalle»: eso es `sui-content-card` (o `sui-content-label`
+  dentro de una card que ya existe).
+- Una opción que se elige: `sui-radio-card`, `sui-checkbox-card` o `sui-switch-card` ya traen la
+  card, el estado elegido y el área táctil.
+- Un producto de la carta o un local del listado del cliente: `sui-product-card` y
+  `sui-store-card`.
+- Contenido que aparece encima de la pantalla: `sui-modal` / `sui-modal-sheet`.
+
+Regla corta: **agrupa contenido → card · es una fila con cara → content-card · se elige → card de
+selección.**
+
+## Qué variante usar
+
+> **La guía del DS no tiene página de la card.** Nada de lo que sigue sale de una guía: lo
+> marcado «propuesta» sale de cómo la usa la app y falta el ok del dueño; lo «canon» ya está
+> aprobado.
+>
+> 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`): **253 cards en 79 archivos**. Variantes: 227 `default` explícito, 24 sin
+> `variant` (también default), 2 `elevated`, 0 `flat`. Tamaños: 95 `small`, 123 `medium`
+> explícito + 21 sin `size`, 14 `large`, 0 `xlarge`. 9 con `[interactive]`. Slots: 23
+> `sui-card-header`, 11 `sui-card-footer`, 4 `sui-card-media`.
+
+### `variant`
+
+| variant | cuándo | fuente |
+|---|---|---|
+| `default` | Lo normal: la card sobre el fondo de la app (borde + sombra x-small). 251 de 253. | propuesta (práctica de la app) |
+| `elevated` | La card flota sobre un mapa, una foto o un fondo de color, donde el borde se pierde y hace falta la sombra media. Precedente: el seguimiento público del pedido (`pages/public/pedido-en-vivo/pedido-en-vivo.html:19`, `:69`). | propuesta |
+| `flat` | Ver «No usar». | propuesta |
+
+### `size` (padding × gap entre slots)
+
+| size | medidas | cuándo | fuente |
+|---|---|---|---|
+| `small` | 16 / 12 | Filas de una lista de cards, KPIs chicos, cards tocables. **Toda card en mobile.** | propuesta |
+| `medium` (default) | 20 / 16 | Secciones en web. | propuesta |
+| `large` | 24 / 20 | La sección principal de una pantalla de web (los 14 de hoy son gráficos de reportes y los pasos del onboarding). | propuesta |
+| `xlarge` | 28 / 24 | Ver «No usar». Extensión SUI (no está en Figma). | propuesta |
+
+### `interactive`
+
+| valor | cuándo | fuente |
+|---|---|---|
+| `true` | La card entera es **una** acción: abre un detalle o lleva a otra pantalla («Mis direcciones», una factura). Da cursor, hover, foco y el arreglo de iOS. | propuesta |
+| `false` (default) | La card tiene 2 acciones o más adentro, o ninguna. Las acciones van como botones dentro. | propuesta |
+
+### Slots
+
+| slot | cuándo | fuente |
+|---|---|---|
+| `[sui-card-header]` | Título de la card a la izquierda y, si hace falta, una acción chica a la derecha (`sui-link-button` «Ver todo»). | propuesta |
+| cuerpo (sin atributo) | El contenido. **Con 2 bloques o más, envuélvelos en un div propio con `display:flex; flex-direction:column; gap`** (ver Trampas). | canon (memoria del proyecto, 10-05-2026) |
+| `[sui-card-media]` | Gráfico, mapa o foto de borde a borde, al final. Si después va un footer, la media deja de comerse el borde inferior. | propuesta |
+| `[sui-card-footer]` | La acción de la card o un resumen. Si son dos botones, siguen el orden de `sui-modal-footer` (secundario a la izquierda, primario a la derecha). | canon (orden de botones, CLAUDE.md) |
+
+**Usos de hoy que rompen las reglas:**
+
+- **18 cards en 6 archivos con `gap` puesto en la clase del `sui-card`**, que no llega a los hijos
+  del cuerpo: `pages/central/central-inicio/central-inicio.html:36` (×6),
+  `pages/super-admin/master-semanas/master-semanas.html:21` (×4),
+  `pages/central/central-ingresos/central-ingresos.html:36` (×3), `pages/invoices/invoices.html:19`
+  (×2), `pages/driver/driver-history/driver-history.html:17` (×2) y
+  `pages/driver/driver-wallet/driver-wallet.html:154` (ahí además el `flex-direction: row` del host
+  no pone el badge al lado del monto: el cuerpo es un solo hijo).
+- **3 cards tocables armadas a mano** (`(click)` o `routerLink` sin `[interactive]`): sin foco, sin
+  hover y sin el arreglo de iOS. `pages/super-admin/master-users/master-users.html:156` (con
+  `role="button"` y `touchstart` a mano), `pages/super-admin/master-settings/master-settings.html:601`,
+  `pages/driver/driver-dashboard/driver-dashboard.html:990`.
+
+## Tamaño en mobile y en web
+
+El `size` de la card es su padding, no un área táctil: no tiene que llegar a 44. Lo que importa en
+mobile es no perder ancho.
+
+| uso | mobile | web |
+|---|---|---|
+| sección, KPI, gráfico | `small` (16) | `medium` (20) |
+| sección principal de un reporte | `small` | `large` (24) |
+| fila de lista tocable | `small` | `small` |
+
+```html
+<sui-card [size]="bp.isMobile() ? 'small' : 'medium'"> … </sui-card>
+```
+
+`bp` es el `BreakpointsService` de la app. Va al ritmo de los gaps de página (12 / 16 / 20 por
+breakpoint). Si la card es tocable, el alto de la fila (≥ 44) lo da su contenido, no el `size`.
+
+## «No usar»: por qué no hoy y cuándo sí
+
+| qué | por qué no hoy | cuándo sí, en un flujo nuevo |
+|---|---|---|
+| `variant="flat"` (0 usos) | la app siempre pone la card sobre el fondo gris, donde la sombra ayuda | una card dentro de otra superficie blanca (un sheet, otra card), donde la sombra dobla el borde |
+| `size="xlarge"` (0 usos) | ninguna pantalla lo pide; no está en Figma | un hero de desktop (la portada de un reporte impreso) |
+
+## API
+
+<!-- api:inicio -->
+<!-- generada: no editar a mano — `npm run docs` -->
+
+| input | tipo | default |
+|---|---|---|
+| `variant` | `'default' \| 'elevated' \| 'flat'` | `'default'` |
+| `size` | `'small' \| 'medium' \| 'large' \| 'xlarge'` | `'medium'` |
+| `interactive` | `boolean` | `false` |
+
+Outputs: ninguno.
+<!-- api:fin -->
+
+Slots: `[sui-card-header]`, cuerpo (`<ng-content>`), `[sui-card-media]`, `[sui-card-footer]`.
+
+## Trampas
+
+- **El `gap` del host separa slots, no hijos.** El cuerpo va dentro de `.sui-card__body` (flex en
+  columna, sin gap). Poner `gap` en una clase del `sui-card` no separa nada de lo que proyectas: se
+  necesita un wrapper propio (`<div class="x__card-body">` con flex y gap).
+- Sin header ni footer el host queda con `gap: 0` (`:has(> .sui-card__body:only-child)`).
+- **`interactive` no trae output, pero sí teclado** (desde 03-10-2026): pone `role="button"`,
+  `tabindex="0"`, hover y foco, y **Enter / Espacio hacen click en la card**, así que tu `(click)`
+  (o el `routerLink` de un `<a>` que la envuelve) también responde al teclado. No agregues
+  `(keydown.enter)` además: se dispararía dos veces. Una tecla dentro de un campo o botón
+  proyectado es de ese control, no de la card.
+- Los slots son **atributos** (`sui-card-header`), no `slot="…"`.
+- El host tiene `overflow: hidden` y radio 16: lo que sobresalga (un badge colgado de la esquina)
+  se corta.
+- `sui-card-media` rompe el padding con margen negativo leído de `--sui-card-padding-x`; si le
+  cambias el padding a la card desde afuera, la media queda corrida.
+- En modo oscuro `elevated` usa `--sui-card-elevated-border` para el borde (la sombra no se ve).
+
+## Ejemplo
+
+```html
+<!-- Sección con título, dos bloques y una acción -->
+<sui-card [size]="bp.isMobile() ? 'small' : 'medium'">
+  <div sui-card-header class="ganancias__head">
+    <h3>Tus días del mes</h3>
+    <sui-link-button variant="primary" size="small" (click)="verTodo()">Ver todo</sui-link-button>
+  </div>
+  <div class="ganancias__card-body">   <!-- display:flex; flex-direction:column; gap:12px -->
+    <span>Martes 3 · 6 entregas · S/ 42.00</span>
+    <span>Miércoles 4 · 4 entregas · S/ 28.50</span>
+  </div>
+</sui-card>
+
+<!-- Fila tocable -->
+<sui-card size="small" [interactive]="true" (click)="abrirDirecciones()">
+  …
+</sui-card>
+```

package/docs/sui-chart-legend/README.md

@@ -0,0 +1,140 @@
+---
+name: sui-chart-legend
+selector: sui-chart-legend
+resumen: Leyenda de un gráfico — punto de color, nombre de la serie y su valor — dibujada fuera del gráfico
+alternativas: [sui-chart-legend-dot (el punto suelto, en una fila o tabla), la leyenda propia de ECharts (cuando hay que poder apagar series tocándolas), sui-badge (una etiqueta, no una serie)]
+---
+
+# sui-chart-legend
+
+Story: [Molecules/Chart/Chart Legend](https://sui-design-system.web.app/?path=/docs/molecules-chart-chart-legend--docs)
+
+## Cuándo usarlo / cuándo no
+
+**Úsalo** debajo o al lado de un gráfico para decir **qué es cada color**, y cuánto suma cada
+serie si el número importa («Yape 42 · Efectivo 31 · Plin 9»). Es texto de la página, así que se lee
+igual en el celular, sin tocar nada.
+
+**No lo uses** para:
+
+- Una leyenda que tiene que **apagar series** al tocarlas: eso lo hace la leyenda de ECharts
+  (`legend: {…}`), que es interactiva. Esta no tiene clic.
+- Un estado o una categoría que no viene de un gráfico: `sui-badge` o `sui-status-badge`.
+- Esconder los números en un tooltip: en el celular no hay hover (así lo hizo bien
+  `pages/super-admin/master-drivers/master-drivers.html:226`).
+
+## Qué variante usar
+
+> La guía del DS no tiene página para este componente: sale del Figma del DS (set «Chart Legends»).
+> Todo lo de abajo es **propuesta**, salvo lo marcado «según el componente» o «canon».
+>
+> Uso medido el 03-10-2026 en `master-pedidos/src/app` (sin prototipos ni vitrinas): **1 uso**, más
+> **5 leyendas hechas a mano** y **9 gráficos con la leyenda de ECharts**.
+
+### `items` — cada serie
+
+| campo | valor | cuándo | fuente |
+|---|---|---|---|
+| `label` | nombre corto | El nombre de la serie, tal como se dice en la app: «Entregados», «Yape». | propuesta |
+| `color` | sin pasar | **Lo normal** en categorías sin bien ni mal (canales, métodos de pago, distritos): el componente reparte azul, naranja, rojo, verde… en orden. | según el componente (orden) · cuándo: propuesta |
+| `color` | el del estado | Cuando la serie **es un estado**: entregados `green`, cancelados `red`, pendientes `orange`. Mismo significado que en `sui-badge`. | canon (colores con significado del badge) |
+| `customColor` | el color que ya usa el gráfico | Solo cuando el gráfico tiene su propia paleta y el punto tiene que coincidir. Va el mismo valor en los dos lados. | propuesta |
+| `value` | número o texto | Cuando el número importa para leer el gráfico: «42», «S/ 1,200», «38 %». | propuesta |
+| `disabled` | `true` | Una serie sin datos en el período: se ve, apagada, para que no parezca que falta. | propuesta |
+
+Los 12 valores de `color`, uno por uno y con su regla, están en el README de `sui-chart-legend-dot`.
+
+Para que el gráfico y la leyenda pinten **el mismo color**, ECharts recibe la paleta desde
+`SUI_CHART_LEGEND_HEX` (exportado por el paquete): `color: [SUI_CHART_LEGEND_HEX.blue, …]`.
+
+### `orientation`
+
+| orientation | cuándo | fuente |
+|---|---|---|
+| `horizontal` (default) | Debajo de un gráfico de barras o de líneas. Si no entra, baja a la línea siguiente. | propuesta |
+| `vertical` | Al lado de una dona o un pie, con el `value` de cada serie. En mobile, debajo de la dona. | propuesta |
+
+### Usos de hoy que romperían la regla
+
+- **5 leyendas hechas a mano** (punto con `[style.background]` + nombre + valor) → `sui-chart-legend`
+  con `customColor` o la paleta del DS: `components/marketing-channels/marketing-channels.html:10`,
+  `components/customer-segments/customer-segments.html:26`,
+  `pages/overview/components/overview-retention/overview-retention.html:12`,
+  `pages/reports/reports.html:59` y `:80`.
+- **A discutir — 9 gráficos con la leyenda de ECharts**: `pages/super-admin/master-semanas/master-semanas.ts:187`
+  (y `:248`, `:288`, `:335`), `pages/super-admin/master-overview/master-overview.ts:264` y `:401`,
+  `pages/reports/reports.ts:338` y `:381`, `core/utils/chart-barras-repartidores.ts:166`. Si nadie
+  apaga series tocándolas, pasarían a `sui-chart-legend` (fuente, tamaño y color del DS en vez de
+  `#525252` y 12 px puestos a mano). `pages/reports/` tiene además la leyenda a mano: hay dos
+  leyendas para el mismo gráfico.
+
+## Tamaño en mobile y en web
+
+**No tiene `size`**: punto de 16 px y texto de 12 en las dos. No se toca, así que no tiene mínimo
+para el dedo; lo que cambia por plataforma es la orientación.
+
+| uso | mobile | web | fuente |
+|---|---|---|---|
+| bajo barras o líneas | `horizontal` (envuelve) | `horizontal` | propuesta |
+| junto a una dona | `vertical`, **debajo** de la dona | `vertical`, a la derecha | propuesta |
+
+```html
+<sui-chart-legend [orientation]="bp.isMobile() ? 'horizontal' : 'vertical'" [items]="metodos()" />
+```
+
+El texto de 12 px queda chico en mobile y el componente no tiene un tamaño mayor: no se cambia aquí.
+
+## «No usar»: por qué no hoy y cuándo sí
+
+| qué | por qué no hoy | cuándo sí, en un flujo nuevo |
+|---|---|---|
+| `disabled` | ningún gráfico muestra series vacías | una serie sin datos en el período elegido |
+| `customColor` con un hex propio | la paleta del DS ya cubre las series | un gráfico con colores de marca de terceros (Yape morado, Plin celeste) |
+
+## API
+
+<!-- api:inicio -->
+<!-- generada: no editar a mano — `npm run docs` -->
+
+| input | tipo | default |
+|---|---|---|
+| `items` | `readonly SuiChartLegendItem[]` | — (requerido) |
+| `orientation` | `'horizontal' \| 'vertical'` | `'horizontal'` |
+
+Outputs: ninguno.
+<!-- api:fin -->
+
+```ts
+interface SuiChartLegendItem {
+  label: string;
+  color?: SuiChartLegendColor;  // 'gray' | 'light-gray' | 'blue' | 'orange' | 'red' | 'green' | 'yellow' | 'purple' | 'sky' | 'pink' | 'teal' | 'disabled'
+  customColor?: string;         // cualquier color CSS; gana sobre `color`
+  value?: string | number;
+  disabled?: boolean;           // gana sobre los dos colores
+}
+```
+
+## Trampas
+
+- **Sin `color`, los colores salen en orden fijo** (azul, naranja, rojo, verde, amarillo…), no los
+  del gráfico: si ECharts usa otra paleta, el punto y la barra no coinciden. Usa
+  `SUI_CHART_LEGEND_HEX` en el gráfico o pasa el color.
+- El orden automático empieza en **azul**, no en el naranja de la marca.
+- `value` sale a 4 px del nombre, en negro (el nombre va en gris): el formato («S/ 1,200», «38 %») lo arma quien la usa.
+- Host con `role="list"` y cada item `role="listitem"`; el punto es decorativo.
+- `items` es obligatorio.
+
+## Ejemplo
+
+```html
+<sui-chart-legend orientation="vertical" [items]="[
+  { label: 'Yape', value: 42 },
+  { label: 'Efectivo', value: 31 },
+  { label: 'Plin', value: 9 },
+]" />
+
+<sui-chart-legend [items]="[
+  { label: 'Entregados', color: 'green', value: '86 %' },
+  { label: 'Cancelados', color: 'red', value: '14 %' },
+]" />
+```

package/docs/sui-chart-legend-dot/README.md

@@ -0,0 +1,118 @@
+---
+name: sui-chart-legend-dot
+selector: sui-chart-legend-dot
+resumen: Punto de color de una serie de gráfico, para atar un número de una fila o una tabla con su color en el gráfico
+alternativas: [sui-chart-legend (la leyenda completa, que ya trae sus puntos), sui-color-dot (elegir un color, no nombrar una serie), sui-badge with-dot (un estado vivo)]
+---
+
+# sui-chart-legend-dot
+
+Story: [Molecules/Chart/Chart Legend Dot](https://sui-design-system.web.app/?path=/docs/molecules-chart-chart-legend-dot--docs)
+
+## Cuándo usarlo / cuándo no
+
+**Úsalo** suelto cuando una fila o una tabla **habla de una serie del gráfico** y el color la ata:
+«● Delivery 64 %» en el resumen bajo una dona, la columna de una tabla que repite las barras.
+
+**No lo uses** para:
+
+- La leyenda de un gráfico: `sui-chart-legend` ya trae sus puntos.
+- Elegir un color (variantes de un producto): `sui-color-dot`.
+- Marcar un estado vivo («Abierto», «En línea»): `sui-badge` con `type="with-dot"`.
+- La línea de tiempo de una actividad: `sui-activity-feed`.
+
+## Qué variante usar
+
+> La guía del DS no tiene página para este componente: sale del Figma del DS (set «Chart Legend
+> Dots»). Todo lo de abajo es **propuesta**, salvo lo marcado «según el componente» o «canon».
+>
+> Uso medido el 03-10-2026 en `master-pedidos/src/app`: **0 usos sueltos** (sí dentro de la única
+> `sui-chart-legend`), y **3 puntos de serie hechos a mano** fuera de una leyenda.
+
+### `color`
+
+Cada color apunta al mismo estado de la paleta que en `sui-badge`. En un gráfico manda una regla:
+**el mismo color que la serie en el gráfico**.
+
+| color | estado de la paleta | cuándo | fuente |
+|---|---|---|---|
+| `blue` | information | Primera serie de categorías sin carga (el orden automático arranca aquí). | según el componente (orden) |
+| `orange` | warning | Pendiente; o segunda serie de categorías. | canon (significado del badge) · como serie de categorías: propuesta |
+| `red` | error | Cancelado, rechazado, fallido. | canon (significado del badge) |
+| `green` | success | Entregado, pagado, aprobado. | canon (significado del badge) |
+| `yellow` | away | En pausa; o una serie más de categorías. | canon (significado del badge) · como serie de categorías: propuesta |
+| `purple` | feature | Lo nuevo; o una serie más de categorías. | canon (significado del badge) · como serie de categorías: propuesta |
+| `sky` · `pink` · `teal` | verified · highlighted · stable | Series de categorías a partir de la séptima. | propuesta |
+| `gray` (default) | faded | «Otros» o «Sin categoría»: lo que no se reparte. | propuesta |
+| `light-gray` | — | No usar: es el mismo gris del apagado. **Cuándo sí:** el resto de una barra de progreso partida («lo que falta»). | propuesta |
+| `disabled` | — | Una serie sin datos o apagada. Dentro de `sui-chart-legend` va por `disabled: true`, no por color. | según el componente |
+| `customColor` | el color que ya usa el gráfico | Solo si el gráfico tiene paleta propia; gana sobre `color`. | propuesta |
+
+### `size`
+
+| size | cuándo | fuente |
+|---|---|---|
+| `small` (16 px) | Junto a texto de 12 (como en la leyenda, que lo usa siempre). | según el componente |
+| `medium` (20 px, default) | Junto a texto de 14: filas y tablas. | propuesta |
+
+El círculo de color mide 12 px en los dos tamaños: lo que cambia es el aire alrededor.
+
+### Usos de hoy que romperían la regla
+
+- **3 puntos de serie hechos a mano** (`<span>` con `[style.background]`) → `sui-chart-legend-dot`:
+  `components/customer-retention/customer-retention.html:17`,
+  `components/order-fulfillment/order-fulfillment.html:17`,
+  `components/cancellation-rate/cancellation-rate.html:33`.
+- Las 5 leyendas hechas a mano están contadas en `sui-chart-legend`.
+
+## Tamaño en mobile y en web
+
+Es decorativo y no se toca: no tiene mínimo para el dedo.
+
+| uso | mobile | web | fuente |
+|---|---|---|---|
+| fila de resumen o tabla | `medium` (20) | `medium` (20) | propuesta |
+| junto a texto de 12 | `small` (16) | `small` (16) | según el componente |
+
+No cambia por plataforma: va con el tamaño del texto que acompaña, no con la pantalla.
+
+## «No usar»: por qué no hoy y cuándo sí
+
+| qué | por qué no hoy | cuándo sí, en un flujo nuevo |
+|---|---|---|
+| `light-gray` | es el gris del apagado | el resto de una barra partida |
+| `sky`, `pink`, `teal` | ningún gráfico pasa de 6 series | un gráfico por distrito o por local con 7 series o más |
+
+## API
+
+<!-- api:inicio -->
+<!-- generada: no editar a mano — `npm run docs` -->
+
+| input | tipo | default |
+|---|---|---|
+| `color` | `'gray' \| 'light-gray' \| 'blue' \| 'orange' \| 'red' \| 'green' \| 'yellow' \| 'purple' \| 'sky' \| 'pink' \| 'teal' \| 'disabled'` | `'gray'` |
+| `size` | `'medium' \| 'small'` | `'medium'` |
+| `customColor` | `string \| null` | `null` |
+
+Outputs: ninguno.
+<!-- api:fin -->
+
+Constantes exportadas: `SUI_CHART_LEGEND_COLORS` (los 11 colores en el orden del Figma),
+`SUI_CHART_SERIES_COLORS` (el orden automático: azul, naranja, rojo, verde…) y
+`SUI_CHART_LEGEND_HEX` (color → hex, para darle la misma paleta a ECharts).
+
+## Trampas
+
+- **El default es `gray`**, no un color de serie: sin `color` todos los puntos salen grises.
+- `size` arranca en `medium` aquí, pero la leyenda usa siempre `small`.
+- El punto lleva un anillo blanco y una sombra para separarse del gráfico: sobre un fondo blanco
+  se ve un poco más chico que un círculo plano del mismo tamaño.
+- `SUI_CHART_LEGEND_HEX` tiene los hex del modo claro: en modo oscuro no se invierten.
+- Es decorativo (`aria-hidden`): el significado lo dice el texto de al lado.
+
+## Ejemplo
+
+```html
+<span class="fila"><sui-chart-legend-dot color="green" /> Entregados <b>86 %</b></span>
+<span class="fila"><sui-chart-legend-dot color="red" /> Cancelados <b>14 %</b></span>
+```

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

@@ -0,0 +1,150 @@
+---
+name: sui-checkbox-card
+selector: sui-checkbox-card
+resumen: Opción con tarjeta (ícono o foto, título, descripción y la casilla) para elegir VARIAS que se guardan después
+alternativas: [sui-checkbox-label (la misma casilla sin tarjeta, en un formulario denso), sui-switch-card (un ajuste que se aplica al toque, sin «Guardar»), sui-radio-card (se elige solo una), sui-tag-input (valores que la persona escribe)]
+---
+
+# sui-checkbox-card
+
+Story: [Molecules/Card/Checkbox Card](https://sui-design-system.web.app/?path=/docs/molecules-card-checkbox-card--docs)
+
+## Cuándo usarlo / cuándo no
+
+**Úsalo** para elegir varias opciones que se suman y que se confirman con «Guardar»: las formas
+de entrega del local («Recojo en tienda» + «Delivery»), los métodos de pago que acepta, los días
+de atención.
+
+**No lo uses** para:
+
+- Un ajuste que tiene efecto al toque, sin botón de guardar: `sui-switch-card`.
+- Elegir una sola: `sui-radio-card`.
+- Una lista larga de casillas en un formulario: `sui-checkbox-label` (sin tarjeta, ocupa menos).
+- Aceptar términos o confirmar algo: `sui-checkbox-label`.
+
+Regla corta: **varias que se guardan después → checkbox-card · se aplica al toque → switch-card ·
+una → radio-card.**
+
+## Qué variante usar
+
+> **La guía del DS no tiene página de la checkbox card.** De la guía sale solo lo del checkbox que
+> lleva adentro: **«para selecciones simples y múltiples»**. La frontera con el switch («se
+> confirma después con Guardar → checkbox») ya es canon desde el README de `sui-switch-label`.
+>
+> Uso medido el 03-10-2026 en `master-pedidos/src/app` (misma exclusión que `sui-card`): **3
+> checkbox-cards en 2 archivos**, los 3 `left-icon` con ícono y descripción (formas de entrega en
+> mi-negocio y en locales administrados). 2 con `bp.controlSize()`, 1 sin `size`. Hay **5
+> `sui-switch-card` que deberían ser este componente** (los métodos de pago de mi-negocio).
+
+### `type` (el leading)
+
+| type | cuándo | fuente |
+|---|---|---|
+| `left-icon` (`icon`, `emoji` o `iconSrc`) | Lo normal: un ícono que dice de qué va la opción. | propuesta (los 3 de hoy) |
+| `basic` | Ver «No usar». | propuesta |
+| `avatar` (`imageUrl`) | Ver «No usar». | propuesta |
+| `card-provider`, `brand`, `company` | Ver «No usar». El logo lo proyectas tú con `slot="leading"`. | propuesta |
+
+### Las piezas
+
+| prop | cuándo | fuente |
+|---|---|---|
+| `label` | Siempre. El nombre de la opción: «Delivery». | propuesta |
+| `description` | Lo que significa elegirla: «Llevas los pedidos a la dirección del cliente». | propuesta (los 3 de hoy) |
+| `sublabel` | Precisión corta entre paréntesis. | propuesta |
+| `badge` | Marca una opción frente a las otras («Nuevo»). Con string sale azul `light`. | propuesta |
+| `indeterminate` | Una casilla que resume a otras («Todos los días» con algunos marcados). | propuesta |
+| `disabled` | La opción no aplica hoy; di por qué en la `description`. | propuesta |
+| `checked` | `[checked]` + `(checkedChange)`, o `[(checked)]`, o `formControlName`. | propuesta |
+
+### `size` (la casilla de adentro)
+
+| size | cuándo | fuente |
+|---|---|---|
+| `xlarge` | Mobile, vía `bp.controlSize()`. | canon (aprobado por el dueño, 28-09-2026: «componentes grandes») |
+| `large` | Desktop, vía `bp.controlSize()`. | canon (aprobado por el dueño, 28-09-2026) |
+| `medium` (default), `small` | No usar en pantallas nuevas. | canon (aprobado por el dueño, 28-09-2026) |
+
+**Usos de hoy que rompen las reglas:**
+
+- **1 sin `size`**: `pages/super-admin/master-administrados/master-administrados.html:172`.
+- **5 `sui-switch-card` que se guardan con «Guardar cambios»** y por lo tanto van aquí: los métodos
+  de pago de `pages/mi-negocio/mi-negocio.html:1181`, `:1190`, `:1199`, `:1208`, `:1217`
+  («Puedes seleccionar varias», dice la misma pantalla).
+
+## Tamaño en mobile y en web
+
+La card entera es el área táctil (≥ 72 con descripción): llega al piso de 44 sola. El `size`
+cambia solo la casilla.
+
+| uso | mobile | web |
+|---|---|---|
+| toda checkbox-card | `xlarge` | `large` |
+
+```html
+<sui-checkbox-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 |
+|---|---|---|
+| `type="basic"` (0 usos) | las opciones de hoy llevan ícono | opciones de texto que se suman (los días de atención, los tamaños de un producto) |
+| `type="avatar"` (0 usos) | no se elige gente de a varios | elegir a varios repartidores para mandarles un aviso |
+| `type="brand"` / `"company"` / `"card-provider"` (0 usos) | no hay integraciones ni tarjetas | prender varias integraciones a la vez (logo proyectado), varias sucursales de un local |
+| `size="medium"` / `"small"` | la casilla 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` | `'small' \| 'medium' \| 'large' \| 'xlarge'` | `'medium'` |
+| `label` | `string` | `''` |
+| `sublabel` | `string \| null` | `null` |
+| `description` | `string \| null` | `null` |
+| `icon` | `string \| null` | `null` |
+| `emoji` | `SuiEmojiName \| null` | `null` |
+| `iconSrc` | `string \| null` | `null` |
+| `imageUrl` | `string \| null` | `null` |
+| `badge` | `SuiBadgeConfig \| string \| null` | `null` |
+| `indeterminate` | `boolean` | `false` |
+| `disabled` | `boolean` | `false` |
+| `checked` · model, `[(checked)]` | `boolean` | `false` |
+
+| output | payload |
+|---|---|
+| `checkedChange2` | `boolean` |
+<!-- api:fin -->
+
+Slot: `[slot=leading]` (solo para `card-provider`, `brand` y `company`). Implementa
+`ControlValueAccessor` (valor `boolean`).
+
+## Trampas
+
+- **Hay dos outputs con el mismo dato**: `checkedChange` (lo crea el `model`) y `checkedChange2`
+  (el explícito, nombre de compatibilidad). Usa `(checkedChange)` o `[(checked)]`, como la app.
+- **Es no controlada**: el toque cambia el estado adentro aunque no actualices nada afuera (al
+  revés que `sui-switch-card`). Si tu señal no se entera, el visual y tu estado se separan.
+- **El leading de `card-provider`, `brand` y `company` se proyecta** con `slot="leading"`
+  (atributo `slot=`, no `sui-…-leading` como en la switch-card). Sin proyección queda el hueco.
+- Con `avatar`, si `imageUrl` falla salen las iniciales del `label`.
+- El leading de 40 × 40 ya trae `box-sizing: border-box` (el proyecto no tiene reset global): si
+  proyectas una imagen con padding o borde propios, ponle `box-sizing` tú.
+- `badge` con string sale **azul `light` `small`**.
+
+## Ejemplo
+
+```html
+<sui-checkbox-card
+  [size]="bp.controlSize()"
+  type="left-icon"
+  icon="store-2-line"
+  label="Recojo en tienda"
+  description="El cliente recoge su pedido en tu local"
+  [checked]="ofreceRecojo()"
+  (checkedChange)="ofreceRecojo.set($event)" />
+```