@ajuarezso/sui-stencil 0.0.0-stage → 0.1.0

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

@@ -0,0 +1,248 @@
+---
+name: sui-checkbox-label
+selector: sui-checkbox-label
+resumen: Casilla con su texto (y opcionalmente descripción, badge y link) para opciones que se suman
+alternativas: [sui-checkbox (la casilla sola, el texto vive en otra parte), sui-checkbox-card (cada opción es una tarjeta), sui-switch-label (se aplica al instante), sui-radio-label (una sola opción)]
+---
+
+# sui-checkbox-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-checkbox-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.
+>
+> **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: [Atoms/Checkbox, Radio & Switch/Checkbox Label](https://sui-design-system.web.app/?path=/docs/atoms-checkbox-radio-switch-checkbox-label--docs)
+
+## Cuándo usarlo / cuándo no
+
+**Úsalo** para toda casilla que tiene texto al lado: «Acepto los términos», cada permiso de un
+miembro del equipo, cada categoría de una lista. Toda la fila es clicable y se enchufa a un
+formulario. En el celular y la tablet va `xlarge` (casilla de 28 px) y en la computadora `large`,
+con `size={bp.controlSize()}`, como los demás controles (D16).
+
+**No lo uses** para:
+
+- Prender algo que se aplica ya, sin botón de guardar: `sui-switch-label`.
+- Elegir una sola opción: `sui-radio-label`.
+- Opciones con peso propio (ícono o logo, descripción larga, borde): `sui-checkbox-card`.
+- Listas de 10+ palabras sueltas (talles, etiquetas): se vuelve un muro; ahí va una grilla de
+  `sui-checkbox` pelados o chips, como los de la calificación del pedido.
+
+Regla corta: **casilla con texto → este · casilla sin texto → `sui-checkbox` · opción con peso → card.**
+
+## Qué variante usar
+
+> **La guía del DS muestra las piezas, no cuándo usarlas.** Su ejemplo «con label avanzado»
+> arma Label + (Sublabel) + badge «NEW» + descripción + Link Button, y la variante invertida
+> (casilla a la derecha). No trae do/don't. Lo marcado «según la guía del DS» sale de ese ejemplo.
+>
+> Uso medido el 06-10-2026 en `master-pedidos/src/app` (sin prototipos ni vitrinas, misma lista
+> de exclusión que `sui-badge`): **4 usos**, todos con `bp.controlSize()` o su equivalente
+> `ctrlSize()`. El 03-10-2026 eran 0: los 4 eran `sui-checkbox` dentro de un `<label>` a mano y se
+> migraron el 04-10-2026. Queda **1 casilla armada a mano** (ver abajo).
+
+### Las piezas
+
+| prop | cuándo | fuente |
+|---|---|---|
+| `label` | Siempre. Qué se marca, en una a tres palabras («Gestionar productos»). | según la guía del DS (pieza); largo según `docs/CANON-SUI.md` §5.4 |
+| `sublabel` | Una precisión corta entre paréntesis: «(opcional)», «(12)». Va con paréntesis en el texto: el componente no los pone. | según la guía del DS («Label(Sublabel)») |
+| `description` | Cuando la opción necesita una frase que explique qué pasa si se marca («Recibe un correo cada vez que entra un pedido»). Pasa el label a peso medio. | según la guía del DS (pieza); el «cuándo» es propuesta |
+| `badge` | Solo para algo **nuevo** («Nuevo», en `purple` como el badge de novedad). Con string sale naranja `light`: pásale el objeto. | según la guía del DS (pieza «NEW»); el color: canon (aprobado por el dueño, 05-10-2026, bloque B3) |
+| `link` | Un «Ver detalle» que abre más información sin marcar la casilla. **Solo se ve si hay `description`.** | según la guía del DS (pieza «Link Button») |
+| `flip` | No usar en formularios: la casilla va a la izquierda, como en la guía. | canon (aprobado por el dueño, 05-10-2026, bloque B9) |
+| `indeterminate` | El «seleccionar todo» de un grupo, cuando hay algunas marcadas. Hoy no usar (ver abajo). | canon (aprobado por el dueño, 05-10-2026, bloque B8) |
+| `disabled` | La opción existe pero no se puede tocar ahora; decir por qué en la descripción. | según la guía del DS |
+| `size` | `medium` (default, Figma): casilla 20, label 14/20. `large`: casilla 24, label 16/24. `xlarge`: casilla 28, label 16/24. En large y xlarge el sublabel y la descripción se quedan en 12/16 (canon, dueño 04-10-2026); el badge sin `size` propio sube a `medium` / `large` y el link a `medium`. `2xlarge`: casilla 28 con la fila a 44 (su uso por dispositivo está pendiente, ver D16). Se usa con `size={bp.controlSize()}`. | `medium`: según la guía del DS · `large` / `xlarge`: canon (aprobado por el dueño, 03-10-2026), extensión SUI |
+
+**Usos de hoy (4), todos con el size de D16:** `pages/settings/team/team.html:237` y `:309`
+(permisos, `bp.controlSize()`), `components/option-sections-manager/option-sections-manager.html:190`
+y `:212` (`ctrlSize()`, que hace lo mismo con `bp.isMobile()`). Hasta el 04-10-2026 eran
+`sui-checkbox` dentro de un `<label>` a mano: tocar el texto no marcaba nada.
+
+**Uso de hoy que debería ser este componente (1):** el nativo de
+`pages/sales-channels/facebook/facebook.html:66`. Al migrarlo se le pasa `size={bp.controlSize()}`.
+
+## Tamaño en mobile y en web
+
+En mobile se toca con el dedo: el área táctil tiene que medir **44 px o más**. En web, con mouse,
+va un tamaño más chico. La app ya lo resuelve con `BreakpointsService`
+(`src/app/services/breakpoints.service.ts`, mobile = hasta 767 px); para controles,
+`bp.controlSize()` devuelve `xlarge` en mobile y `large` en web (regla de controles grandes del
+dueño, 28-09-2026).
+
+| uso | mobile | web | fuente |
+|---|---|---|---|
+| casilla con texto en un formulario | `xlarge` (casilla 28, label 16/24; sin descripción la fila mide 28, no 44: `2xlarge` pendiente, ver D16) | `large` (casilla 24, label 16/24) | D16 (fila de checkbox, radio y switch; dueño 06-10-2026) |
+| lista densa de desktop (tabla, filtros) | — | `large` (casilla 24): no baja a `medium` | D16, dueño 06-10-2026 |
+
+```html
+<sui-checkbox-label size={bp.controlSize()} label="Recordar mi dirección" active={recordar} onActiveChange={(e) => (recordar = e.detail)} />
+```
+
+| size | casilla | label | sublabel / descripción | alto de la fila sin descripción |
+|---|---|---|---|---|
+| `medium` (default, Figma) | 20 | 14/20 | 12/16 | 20 |
+| `large` | 24 | 16/24 | 12/16 | 24 |
+| `xlarge` | 28 | 16/24 | 12/16 | 28 |
+| `2xlarge` | 28 | 16/24 | 12/16 | **44** (`min-height`) |
+
+`2xlarge` (canon, dueño 04-10-2026: piso táctil 44 en el teléfono) tiene la misma casilla de 28 y
+el mismo label que `xlarge`, pero la fila mide 44 como mínimo con todo centrado en vertical, y el
+texto secundario se queda en 12 (regla del 03-10). Con descripción la fila ya pasa de 44 y vuelve a
+alinearse arriba. Si reemplaza a `xlarge` en el celular y la tablet está **pendiente** (ver D16).
+
+Toda la fila se toca (el host recibe el click), así que el área táctil es la fila entera, no solo
+la casilla. Con `xlarge` el contenido baja 2 px para que la línea del label (24) quede centrada
+con la casilla (28).
+
+Sin descripción, la fila en `xlarge` mide 28 px (lo que mide la casilla), por debajo del piso de 44;
+`2xlarge` la lleva a 44 (pendiente, ver D16). Con descripción llega sola: 2 + 24 (label) + 4 + 16
+(descripción) = 46 px en `xlarge` y en `2xlarge`.
+
+**Regla de tamaños aplicada (canon, dueño 04-10-2026):** en `large` y `xlarge` el label sube a
+16/24 y el sublabel y la descripción se quedan en 12/16, igual que `sui-switch-label`. Antes subían
+a 14/20. El badge y el link siguen creciendo con el size.
+
+### Por dispositivo (D16)
+
+| dispositivo | size | nota |
+|---|---|---|
+| celular chico (< 380) | `xlarge` | casilla de 28 |
+| 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'`.
+
+**Pendiente: `2xlarge` en el celular y la tablet.** Sin descripción, `xlarge` deja la fila en 28 px,
+por debajo del piso de 44. El dueño aprobó `2xlarge` el 04-10-2026 justo para eso (fila de 44), pero
+la fila de D16 dice `xlarge` para toda la familia y ningún helper devuelve `2xlarge`. Falta que el
+dueño decida si en este componente el celular y la tablet pasan a `2xlarge` (y que D16 y
+`bp.controlSize()` lo recojan). Mientras no lo decida, manda la fila de D16: `xlarge`.
+
+## «No usar»: por qué no hoy y cuándo sí
+
+| qué | por qué no hoy | cuándo sí, en un flujo nuevo |
+|---|---|---|
+| `flip` | en un formulario la casilla va a la izquierda; a la derecha se confunde con un switch | una lista de ajustes donde las demás filas son switches a la derecha y una sola es casilla |
+| `badge` | ninguna opción marcable es nueva hoy | una opción recién agregada («Nuevo») en un formulario que el usuario ya conoce |
+| `link` | ninguna opción necesita abrir detalle | «Acepto los términos» con su «Ver términos» (con `description`) |
+| `indeterminate` | ninguna lista tiene «seleccionar todo» | el «Todos los permisos» arriba de la lista de permisos del equipo |
+
+## 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` |
+| `indeterminate` | `indeterminate` | `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` |
+|---|---|
+| `suiChange` | `boolean` |
+| `suiLinkClick` | `MouseEvent` |
+
+### Diferencias con el SUI Angular
+
+- **Eventos de Angular que aquí no existen:** `activeChange`, `linkClick`
+- **Eventos solo de aquí:** `suiChange`, `suiLinkClick`
+<!-- api:fin -->
+
+Implementa `ControlValueAccessor` (`ngModel` + `ngModelChange`, `formControlName`).
+
+## Trampas
+
+- **El estado se llama `active`, no `checked`.** `checked` + `checkedChange` aquí no existe.
+- **`size` arranca en `medium`** (casilla de 20 px): sin `size={bp.controlSize()}` queda chica
+  en el teléfono.
+- **`link` solo se dibuja si hay `description`.** Sin descripción desaparece sin avisar.
+- **`description` cambia el label de peso** (regular → medio) y abre el bloque en columna.
+- El badge con string sale **naranja `light`**; en `sui-checkbox-card` el default es azul.
+  Pasa `{ label, color, variant }` para que combinen.
+- `link` con `href` es un `<a>` real; con `target: '_blank'` agrega `rel="noopener noreferrer"`.
+  Sin `href`, emite `linkClick` y no marca la casilla.
+- `flip` cambia el orden con CSS `order`: el lector de pantalla y el Tab siguen viendo la casilla primero.
+- La casilla 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). Antes el lector decía
+  «casilla, no marcada» sin el texto.
+- Deshabilitado baja la opacidad del bloque a 0.5 (convención del proyecto).
+
+## Bien y mal
+
+Casilla suelta con el texto en un `<label>` aparte
+
+```html
+<!-- ❌ mal: tocar el texto no marcaba nada (así estaba pages/settings/team/team.html:237 hasta el 04-10-2026) -->
+<label class="team__permission-check">
+  <sui-checkbox size={bp.controlSize()} checked={hasPermission(perm)} onCheckedChange={() => togglePermission(perm)} />
+  <span>{PERMISSION_LABELS[perm]}</span>
+</label>
+```
+
+```html
+<!-- ✅ bien (como pages/settings/team/team.html:237 hoy) -->
+<sui-checkbox-label size={bp.controlSize()}
+  label={PERMISSION_LABELS[perm]} active={hasPermission(perm)} onActiveChange={() => togglePermission(perm)} />
+```
+
+Estado con el nombre de otro control
+
+```html
+<!-- ❌ mal: aquí el estado se llama active; [(checked)] no existe -->
+<sui-checkbox-label label="Gestionar productos" checked={permisos.productos} onCheckedChange={(e) => (permisos.productos = e.detail)} />
+```
+
+```html
+<!-- ✅ bien -->
+<sui-checkbox-label size={bp.controlSize()} label="Gestionar productos" active={permisos.productos} onActiveChange={(e) => (permisos.productos = e.detail)} />
+```
+
+Casilla con texto armada a mano
+
+```html
+<!-- ❌ mal: input nativo + label, sin tamaño ni foco del DS (pages/sales-channels/facebook/facebook.html:66) -->
+<label class="fb-channel__sync-item">
+  <input type="checkbox" checked={item.checked} onChange={() => toggleSync(item.id)} />
+  <span>{item.label}</span>
+</label>
+```
+
+```html
+<!-- ✅ bien -->
+<sui-checkbox-label size={bp.controlSize()}
+  label={item.label} active={item.checked} onActiveChange={() => toggleSync(item.id)} />
+```
+
+## Ejemplo
+
+```html
+<sui-checkbox-label label="Gestionar productos" active={permisos.productos} onActiveChange={(e) => (permisos.productos = e.detail)} />
+
+<sui-checkbox-label
+  label="Avisarme por correo"
+  sublabel="(opcional)"
+  description="Te escribimos cuando entra un pedido nuevo."
+  link={{ label: 'Ver ejemplo', href: '/ayuda/correos', target: '_blank' }}
+  formControlName="avisoCorreo" />
+```

package/docs/sui-circular-progress-bar/README.md

@@ -0,0 +1,216 @@
+---
+name: sui-circular-progress-bar
+selector: sui-circular-progress-bar
+resumen: El avance de algo en un anillo, para cuando cabe en un cuadrado al lado de un título
+alternativas: [sui-progress-bar-label (barra con título y número, cuando hay ancho), sui-progress-bar (barra pelada)]
+---
+
+# sui-circular-progress-bar
+
+<!-- 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-circular-progress-bar`); 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/Progress/Circular Progress Bar](https://sui-design-system.web.app/?path=/docs/atoms-progress-circular-progress-bar--docs)
+
+## Cuándo usarlo / cuándo no
+
+**Úsalo** cuando el avance tiene que entrar en **un cuadrado al lado de un título**, como un
+avatar: «Perfil 60 % completo» en el onboarding, los documentos al día de un repartidor, la meta
+del día en una card chica.
+
+**No lo uses** para:
+
+- Un avance con título y descripción, si hay ancho: `sui-progress-bar-label` se lee más rápido.
+- Varios avances en una lista: barras, que se comparan a simple vista; los anillos no.
+- Una espera sin porcentaje: un spinner.
+
+## Qué variante usar
+
+> **En la guía del DS se llama «Progress Circle»** («un gráfico simple para mostrar qué tan
+> completo está algo»). Trae cinco tamaños (80, 72, 64, 56 y 48; default 80), `value` y `max`,
+> y **un solo color** (el primario del DS, que en SUI es el azul de información). No dice cuándo
+> usar cada tamaño. Lo marcado «según la guía del DS» sale de ahí. Lo marcado canon está
+> aprobado; lo que sigue en **propuesta, falta aprobación** espera decisión.
+>
+> Uso medido el 03-10-2026 en `master-pedidos/src/app`: **0 usos**, sin contar prototipos ni
+> vitrinas (`master-preview`, `master-prototipos`, `mockup-sheets-*`, `dx/*`, `_guia-*`,
+> `master-rutina`, `master-medico`, `master-ejercicios`, `dev-index`).
+
+### `size`
+
+| size | número al centro | cuándo | fuente |
+|---|---|---|---|
+| `48` | no (solo el anillo) | Junto a un texto que ya dice el porcentaje. | según la guía del DS |
+| `56` | sí, 12 px | Web: en una fila o una card. | según la guía del DS (tamaño) · cuándo: canon (aprobado por el dueño, 05-10-2026, bloque B1) |
+| `64` (default SUI) | sí, 14 px | Mobile: en una fila o una card. | según la guía del DS (tamaño) · cuándo: canon (aprobado por el dueño, 05-10-2026, bloque B1) |
+| `72` | sí, 14 px | Web: lo principal de la pantalla. | según la guía del DS (tamaño) · cuándo: canon (aprobado por el dueño, 05-10-2026, bloque B1) |
+| `80` (default de la guía) | sí, 14 px | Mobile: lo principal de la pantalla. | según la guía del DS (tamaño) · cuándo: canon (aprobado por el dueño, 05-10-2026, bloque B1) |
+
+### `color` — misma regla que `sui-progress-bar`
+
+| color | cuándo | fuente |
+|---|---|---|
+| `blue` (default) | Avance neutro: perfil completado, pasos. | según la guía del DS (su único color) |
+| `green` | Se cumplió o va bien: documentos al día. | propuesta, falta aprobación |
+| `orange` | Va en curso y pide atención: meta del día a medias. | propuesta, falta aprobación |
+| `red` | Se perdió o se acabó: meta perdida. | propuesta, falta aprobación |
+| `purple` | **No usar** (ver abajo). | propuesta, falta aprobación |
+
+### El resto
+
+| propiedad | valor | cuándo | fuente |
+|---|---|---|---|
+| `number` | `true` (default) | Lo normal: el porcentaje al centro. | según la guía del DS |
+| `number` | `false` | El texto de al lado ya dice el número. | canon (aprobado por el dueño, 05-10-2026, bloque B9) |
+| `strokeWidth` | número | **No usar** (ver abajo). | canon (aprobado por el dueño, 05-10-2026, bloque B6) |
+| `ariaLabel` | texto | Siempre: lo que mide («Perfil completado»). | canon (aprobado por el dueño, 05-10-2026, bloque B5) |
+
+Usos de hoy que rompen la regla: **0** (no hay usos).
+
+## No usar: por qué no hoy y cuándo sí
+
+| qué | por qué no hoy | cuándo sí, en un flujo nuevo |
+|---|---|---|
+| El componente entero (0 usos) | Los avances de hoy tienen ancho para una barra con título. | «Perfil 60 % completo» en el onboarding del repartidor o del local. |
+| `color="purple"` | Extensión SUI sin caso, igual que en la barra. | El avance de una función en prueba. |
+| `strokeWidth` | El grosor por tamaño ya sale de la guía (8 % del diámetro; 14 % en 48). | Ninguno: si hace falta otro grosor, se pide al DS. |
+
+## Tamaño en mobile y en web
+
+Criterio de la app: **D16, tamaño por dispositivo** (canon, dueño, 05-10-2026), que reemplaza al
+«tamaño por plataforma» del 03-10-2026 (mobile grande, web chico). La columna «mobile» es el celular de
+380 px o más y, en lo que se toca, también la tablet (`pointer: coarse`). La columna «web» es la
+computadora (`pointer: fine`) y, en lo que no se toca, también la tablet. En el celular chico
+(< 380 px) va `medium` a la vista, sin achicar el área de 44 de lo que se toca. **Nada en `small` ni
+`xsmall`**, salvo lo que el componente solo tiene en chico. En la app, `BreakpointsService` ya
+tiene las señales de D16: `celular()` (380–767 px), `celularChico()`, `toque()` y `tactil()`.
+
+| uso | mobile | web | fuente |
+|---|---|---|---|
+| Junto a un texto que ya dice el número | `48` | `48` | canon (dueño, 05-10-2026, P1 b) |
+| En una fila o card | `64` | `56` | canon (dueño, 05-10-2026, P1 b) |
+| Lo principal de la pantalla | `80` | `72` | canon (dueño, 05-10-2026, P1 b) |
+
+```ts
+readonly bp = inject(BreakpointsService); // master-pedidos: src/app/services/breakpoints.service.ts
+```
+
+```html
+<sui-circular-progress-bar value="60" size={bp.celular() ? 64 : 56} aria-label="Perfil completado" />
+```
+
+`size` es un número: el ternario devuelve `64 : 56`, no `'64' : '56'`. Va `bp.celular()` y no
+`bp.isMobile()`: `isMobile()` también incluye el celular chico, que en lo que no se toca lleva el
+valor de web (D16, dueño 05-10-2026).
+
+### Por dispositivo (D16)
+
+No se toca: sube un paso solo en el celular de 380 px o más (P1 b). El celular chico y la tablet
+van con el valor de la computadora.
+
+| dispositivo | size | nota |
+|---|---|---|
+| celular chico (< 380 px) | `56` en fila o card · `72` lo principal · `48` junto al texto | valor «web» |
+| celular (380–767 px) | `64` en fila o card · `80` lo principal · `48` junto al texto | valor «mobile» |
+| tablet táctil (`pointer: coarse`) | `56` · `72` · `48` | valor «web»: no se toca, no necesita crecer |
+| computadora (`pointer: fine`) | `56` · `72` · `48` | |
+
+Ultrawide (≥ 1920 px): igual que la computadora; el espacio extra no agranda el anillo.
+
+En master-pedidos: no hay helper; `size={bp.celular() ? 64 : 56}` en una fila o card y
+`size={bp.celular() ? 80 : 72}` en lo principal. Junto a un texto, `size="48"` fijo.
+
+## API
+
+<!-- api:inicio -->
+<!-- generada: no editar a mano — `npm run docs` -->
+
+| prop | atributo | tipo | default |
+|---|---|---|---|
+| `ariaLabel` | `aria-label` | `null \| string` | `'Progreso'` |
+| `color` | `color` | `"blue" \| "green" \| "orange" \| "purple" \| "red"` | `'blue'` |
+| `number` | `number` | `boolean` | `true` |
+| `size` | `size` | `48 \| 56 \| 64 \| 72 \| 80` | `64` |
+| `strokeWidth` | `stroke-width` | `null \| number` | `null` |
+| `value` | `value` | `number` | `0` |
+
+Eventos: ninguno.
+
+### Diferencias con el SUI Angular
+
+Ninguna en nombres de props, eventos y valores.
+<!-- api:fin -->
+
+<!-- textos:inicio -->
+### Textos
+
+Lo que el componente escribe solo sale de `provideSuiTextos` (español por defecto, se cambia en vivo; ver `docs/TEXTOS.md`). El input de la última columna le gana al texto global.
+
+| clave | por defecto | se pisa con |
+|---|---|---|
+| `comun.progreso` | Progreso | `ariaLabel` |
+<!-- textos:fin -->
+
+## Trampas
+
+- **`size` es un número, no un texto**: `size="64"`, no `size="64"` (un string no tipa).
+- **En 48 no hay número**, aunque `number` sea `true`.
+- **No hay `max`**: `value` es un porcentaje de 0 a 100.
+- El default de SUI es **64**; el de la guía, **80**.
+- El porcentaje se redondea a entero.
+- El azul es `--sui-state-information-base`, no el naranja de `--sui-primary-base`.
+- Sin `ariaLabel` se anuncia «Progreso» (04-10-2026: antes quedaba sin nombre). Pasa uno que diga
+  qué avanza («Perfil completado»).
+
+## Bien y mal
+
+El tamaño es un número
+
+```html
+<!-- ❌ mal: un string no tipa con 48 | 56 | 64 | 72 | 80 -->
+<sui-circular-progress-bar value="60" size="64" aria-label="Perfil completado" />
+```
+
+```html
+<!-- ✅ bien -->
+<sui-circular-progress-bar value="60" size={bp.celular() ? 64 : 56} aria-label="Perfil completado" />
+```
+
+Anillo de 48 solo
+
+```html
+<!-- ❌ mal: en 48 no hay número al centro, y nada al lado dice cuánto va -->
+<sui-circular-progress-bar value="60" size="48" />
+```
+
+```html
+<!-- ✅ bien: el texto de al lado dice el número; el anillo dice qué mide -->
+<sui-circular-progress-bar value="60" size="48" aria-label="Perfil completado" />
+<span>Perfil 60 % completo</span>
+```
+
+Grosor a mano
+
+```html
+<!-- ❌ mal: strokeWidth pisa el grosor que ya sale de la guía por tamaño -->
+<sui-circular-progress-bar value="80" size="72" stroke-width="10" aria-label="Meta del día" />
+```
+
+```html
+<!-- ✅ bien -->
+<sui-circular-progress-bar value="80" size={bp.celular() ? 80 : 72} aria-label="Meta del día" />
+```
+
+## Ejemplo
+
+```html
+<div class="perfil">
+  <sui-circular-progress-bar value="60" size={bp.celular() ? 64 : 56} aria-label="Perfil completado" />
+  <span>Completa tu perfil para empezar a repartir</span>
+</div>
+```

package/docs/sui-color-dot/README.md

@@ -0,0 +1,204 @@
+---
+name: sui-color-dot
+selector: sui-color-dot
+resumen: Una opción de color para elegir (o mostrar el color elegido); no es un punto de estado
+alternativas: [sui-color-picker (el selector completo, con hex propio), sui-badge type="with-dot" (punto de estado vivo), sui-status-badge withDot (punto de estado de un ciclo)]
+---
+
+# sui-color-dot
+
+<!-- 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-color-dot`); 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/Color/Color Dot](https://sui-design-system.web.app/?path=/docs/atoms-color-color-dot--docs)
+
+## Cuándo usarlo / cuándo no
+
+**Úsalo** para que la persona **elija un color** de una fila de opciones, o para mostrar el color
+que ya eligió: el color de una variante de producto («Rojo vino»), el color de una etiqueta. Es
+un `<button role="radio">`: se toca.
+
+**No lo uses** para:
+
+- **Un estado** (en línea, abierto, pendiente): el color del dot es el color literal, sin
+  significado. Va `sui-badge type="with-dot"` o `sui-status-badge with-dot`, que pintan
+  con los tokens de estado.
+- Un punto decorativo o una leyenda de gráfico: un `<span>` con el token del color.
+- Elegir un color que no está en los 10: `sui-color-picker` (que usa este dot por dentro).
+
+## Qué variante usar
+
+> **En la guía del DS es la fila «Recommended Colors» del selector de color**: muestras para
+> elegir un color recomendado. No dice cuándo usar cada estado. Lo marcado «según la guía del
+> DS» sale de ahí. Lo marcado canon está aprobado; lo que sigue en **propuesta, falta aprobación**
+> espera decisión.
+>
+> Uso medido el 03-10-2026 en `master-pedidos/src/app`: **0 usos**, sin contar prototipos ni
+> vitrinas (`master-preview`, `master-prototipos`, `mockup-sheets-*`, `dx/*`, `_guia-*`,
+> `master-rutina`, `master-medico`, `master-ejercicios`, `dev-index`). Candidato:
+> `components/add-product-modal/add-product-modal.html:304` elige el color de una variante con
+> `<input type="color">`, que abre un selector distinto en iOS, Android y escritorio.
+
+| propiedad | valor | cuándo | fuente |
+|---|---|---|---|
+| `color` | los 10 (`gray`, `blue`, `orange`, `red`, `green`, `yellow`, `purple`, `sky`, `pink`, `teal`) | El color literal que se ofrece. **No significan nada**: son la paleta `-500`, no los tokens de estado del badge. Se ofrecen en ese orden. | según la guía del DS (colores recomendados) |
+| `customHex` | `#rrggbb` | Un color exacto que no está en los 10 (el de una variante de producto). Pisa a `color`. | canon (aprobado por el dueño, 05-10-2026, bloque B3) |
+| `state` | `default` | Opción disponible. | según la guía del DS |
+| `state` | `selected` | El color elegido. Uno solo por fila; lo setea la pantalla. | según la guía del DS |
+| `state` | `disabled` | Un color que no se puede elegir (agotado en esa variante). | canon (aprobado por el dueño, 05-10-2026, bloque B8) |
+| `state` | `hover` | **No usar** (ver abajo). | canon (aprobado por el dueño, 05-10-2026, bloque B6) |
+| `size` | `medium` (default) · `large` | `medium` 24 (Figma) en web; `large` 32 en mobile. En `large` el dot mide 22, 18 en hover y 16 seleccionado, con anillo de 24. | `medium`: según la guía del DS · `large`: canon (aprobado por el dueño, 03-10-2026), extensión SUI |
+| `ariaLabel` | texto | El nombre del color para el lector de pantalla. Por default dice «Rojo», «Celeste»; con `customHex`, el hex. Con hex propio, pasar el nombre («Rojo vino»). | canon (aprobado por el dueño, 05-10-2026, bloque B5) |
+
+Usos de hoy que rompen la regla: **0** (no hay usos).
+
+## No usar: por qué no hoy y cuándo sí
+
+| qué | por qué no hoy | cuándo sí, en un flujo nuevo |
+|---|---|---|
+| El componente entero (0 usos) | La app no ofrece colores para elegir. | El color de una variante de producto en `add-product-modal`, en lugar del selector nativo. |
+| `state="hover"` | El CSS ya lo pone al pasar el mouse. | Vitrinas y capturas del DS. |
+
+## Tamaño en mobile y en web
+
+Criterio de la app: **D16, tamaño por dispositivo** (canon, dueño, 05-10-2026), que reemplaza al
+«tamaño por plataforma» del 03-10-2026 (mobile grande, web chico). La columna «mobile» es el celular de
+380 px o más y, en lo que se toca, también la tablet (`pointer: coarse`). La columna «web» es la
+computadora (`pointer: fine`) y, en lo que no se toca, también la tablet. En el celular chico
+(< 380 px) va `medium` a la vista, sin achicar el área de 44 de lo que se toca. **Nada en `small` ni
+`xsmall`**, salvo lo que el componente solo tiene en chico. En la app, `BreakpointsService` ya
+tiene las señales de D16: `tactil()` (todo celular por ancho y toda pantalla `pointer: coarse`),
+`celular()`, `celularChico()` y `toque()`.
+
+| uso | mobile | web | fuente |
+|---|---|---|---|
+| Cualquiera | `large` (32 × 32) | `medium` (24 × 24) | canon (aprobado por el dueño, 03-10-2026) · «mobile» incluye la tablet táctil: D16, dueño 05-10-2026 |
+| Separación entre dots | 12 px | 4 px | propuesta, falta aprobación |
+
+```html
+<sui-color-dot color={c} size={bp.tactil() ? 'large' : 'medium'} state={c === elegido() ? 'selected' : 'default'} />
+```
+
+`large` mide 32, todavía por debajo de los 44 px del dedo: los 12 px de separación completan el
+área para no tocar el vecino.
+
+### Por dispositivo (D16)
+
+Fila de `color-dot` en la tabla de D16 (dueño, 05-10-2026): se toca.
+
+| dispositivo | size | nota |
+|---|---|---|
+| celular chico (< 380 px) | `large` (32), interino | D16 pide `medium` con área tocable de 44, pero el DS todavía no la estira (P20, pendiente). Hasta entonces se queda `large` |
+| celular (380–767 px) | `large` (32) | separación de 12 px entre dots |
+| tablet táctil (`pointer: coarse`) | `large` (32) | separación de 12 px; con `isMobile()` el iPad caía en `medium` |
+| computadora (`pointer: fine`) | `medium` (24) | separación de 4 px |
+
+Ultrawide (≥ 1920 px): igual que la computadora, `medium`.
+
+En master-pedidos: `size={bp.tactil() ? 'large' : 'medium'}` (da lo mismo que `bp.sizeControl()`,
+el helper de botón y campo).
+
+## API
+
+<!-- api:inicio -->
+<!-- generada: no editar a mano — `npm run docs` -->
+
+| prop | atributo | tipo | default |
+|---|---|---|---|
+| `ariaLabel` | `aria-label` | `string` | `''` |
+| `color` | `color` | `"blue" \| "gray" \| "green" \| "orange" \| "pink" \| "purple" \| "red" \| "sky" \| "teal" \| "yellow"` | `'gray'` |
+| `customHex` | `custom-hex` | `null \| string` | `null` |
+| `size` | `size` | `"large" \| "medium"` | `'medium'` |
+| `state` | `state` | `"default" \| "disabled" \| "hover" \| "selected"` | `'default'` |
+
+| evento | `event.detail` |
+|---|---|
+| `clicked` | `void` |
+
+### Diferencias con el SUI Angular
+
+Ninguna en nombres de props, eventos y valores.
+<!-- api:fin -->
+
+<!-- textos:inicio -->
+### Textos
+
+Lo que el componente escribe solo sale de `provideSuiTextos` (español por defecto, se cambia en vivo; ver `docs/TEXTOS.md`). El input de la última columna le gana al texto global.
+
+| clave | por defecto | se pisa con |
+|---|---|---|
+| `selectorColor.color` | Color {hex} | `ariaLabel` |
+| `selectorColor.gris` | Gris | `ariaLabel` |
+| `selectorColor.azul` | Azul | `ariaLabel` |
+| `selectorColor.naranja` | Naranja | `ariaLabel` |
+| `selectorColor.rojo` | Rojo | `ariaLabel` |
+| `selectorColor.verde` | Verde | `ariaLabel` |
+| `selectorColor.amarillo` | Amarillo | `ariaLabel` |
+| `selectorColor.morado` | Morado | `ariaLabel` |
+| `selectorColor.celeste` | Celeste | `ariaLabel` |
+| `selectorColor.rosado` | Rosado | `ariaLabel` |
+| `selectorColor.turquesa` | Turquesa | `ariaLabel` |
+<!-- textos:fin -->
+
+Output: `clicked`, solo si no está `disabled`. El dot no cambia su propio `state`: la pantalla
+lo pasa a `selected`.
+
+## Trampas
+
+- **Es un botón**: dentro de otro botón o de un link, rompe el HTML y el foco.
+- **El dot no se marca solo** al tocarlo: `clicked` avisa y la pantalla setea `state`.
+- `disabled` pinta el dot gris claro, no el color atenuado.
+- Con `customHex`, el `color` se ignora.
+- `medium` mide 24 × 24 y `large` 32 × 32: los dos quedan por debajo de los 44 del dedo. En mobile va `large` con 12 px de separación entre dots.
+
+## Bien y mal
+
+Un estado no es un color
+
+```html
+<!-- ❌ mal: el dot es un botón para elegir color, no dice «en línea» -->
+<sui-color-dot color="green" aria-label="En línea" />
+```
+
+```html
+<!-- ✅ bien -->
+<sui-badge type="with-dot" color="green" size={bp.sizeBadge()}>En línea</sui-badge>
+```
+
+El dot no se marca solo
+
+```html
+<!-- ❌ mal: avisa el toque pero nadie le pasa el state; nunca se ve elegido -->
+<sui-color-dot color={c} size={bp.tactil() ? 'large' : 'medium'} onClicked={() => elegido.set(c)} />
+```
+
+```html
+<!-- ✅ bien -->
+<sui-color-dot color={c} size={bp.tactil() ? 'large' : 'medium'}
+  state={c === elegido() ? 'selected' : 'default'} onClicked={() => elegido.set(c)} />
+```
+
+Color propio sin nombre
+
+```html
+<!-- ❌ mal: con customHex el lector de pantalla dice «Color #7b2d3a» -->
+<sui-color-dot custom-hex="#7b2d3a" size={bp.tactil() ? 'large' : 'medium'} />
+```
+
+```html
+<!-- ✅ bien -->
+<sui-color-dot custom-hex="#7b2d3a" aria-label="Rojo vino" size={bp.tactil() ? 'large' : 'medium'} />
+```
+
+## Ejemplo
+
+```html
+@for (c of colores; track c) {
+  <sui-color-dot color={c} state={c === elegido() ? 'selected' : 'default'} onClicked={() => elegido.set(c)} />
+}
+```