@ajuarezso/sui-design-system 0.19.0 → 0.21.0

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

@@ -0,0 +1,143 @@
+---
+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
+
+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. **Pendiente de decisión:** no tiene `size` (20 px), así que en una pantalla nueva de
+mobile choca con la regla de controles grandes; hasta que el DS le sume `size`, en mobile
+`sui-checkbox-card` es la salida grande.
+
+**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 03-10-2026 en `master-pedidos/src/app` (sin prototipos ni vitrinas, misma lista
+> de exclusión que `sui-badge`): **0 usos**. Hay **5 casillas armadas a mano** que deberían ser
+> este componente (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 es propuesta |
+| `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. | propuesta, falta aprobación |
+| `indeterminate` | El «seleccionar todo» de un grupo, cuando hay algunas marcadas. Hoy no usar (ver abajo). | propuesta, falta aprobación |
+| `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 pasan a 14/20, el badge sin `size` propio sube a `medium` / `large` y el link a `medium`. 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 que deberían ser este componente (5):**
+
+- **4 `sui-checkbox` + `<label>` a mano:** `pages/settings/team/team.html:225` y `:294`
+  (permisos), `components/option-sections-manager/option-sections-manager.html:188` y `:210`.
+- **1 nativo:** `pages/sales-channels/facebook/facebook.html:69`.
+
+**Antes de migrarlos:** los 4 de `sui-checkbox` hoy están en 24/28 px (`bp.controlSize()`,
+regla de controles grandes del dueño, 28-09-2026). Desde el 03-10-2026 el label tiene `size`
+(`large` 24 / `xlarge` 28): al migrar se le pasa `[size]="bp.controlSize()"` y no se achican.
+
+## 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) | `large` (casilla 24, label 16/24) | canon (aprobado por el dueño, 03-10-2026) |
+| lista densa de desktop (tabla, filtros) | — | `medium` (casilla 20, label 14/20) | propuesta, falta aprobación |
+
+```html
+<sui-checkbox-label [size]="bp.controlSize()" label="Recordar mi dirección" [(active)]="recordar" />
+```
+
+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).
+
+## «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` -->
+
+| input | tipo | default |
+|---|---|---|
+| `label` | `string` | `''` |
+| `sublabel` | `string \| null` | `null` |
+| `description` | `string \| null` | `null` |
+| `badge` | `SuiBadgeConfig \| string \| null` | `null` |
+| `link` | `SuiLinkConfig \| string \| null` | `null` |
+| `size` | `'medium' \| 'large' \| 'xlarge'` | `'medium'` |
+| `flip` | `boolean` | `false` |
+| `disabled` | `boolean` | `false` |
+| `indeterminate` | `boolean` | `false` |
+| `active` · model, `[(active)]` | `boolean` | `false` |
+
+| output | payload |
+|---|---|
+| `linkClick` | `MouseEvent` |
+<!-- api:fin -->
+
+Implementa `ControlValueAccessor` (`[(ngModel)]`, `formControlName`).
+
+## Trampas
+
+- **El estado se llama `active`, no `checked`.** `[(checked)]` aquí no existe.
+- **No tiene `size`**: la casilla siempre mide 20 px.
+- **`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.
+- Deshabilitado baja la opacidad del bloque a 0.5 (convención del proyecto).
+
+## Ejemplo
+
+```html
+<sui-checkbox-label label="Gestionar productos" [(active)]="permisos.productos" />
+
+<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,131 @@
+---
+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
+
+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í; el resto es **propuesta,
+> falta aprobació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) · propuesta (cuándo) |
+| `64` (default SUI) | sí, 14 px | Mobile: en una fila o una card. | según la guía del DS (tamaño) · propuesta (cuándo) |
+| `72` | sí, 14 px | Web: lo principal de la pantalla. | según la guía del DS (tamaño) · propuesta (cuándo) |
+| `80` (default de la guía) | sí, 14 px | Mobile: lo principal de la pantalla. | según la guía del DS (tamaño) · propuesta (cuándo) |
+
+### `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. | propuesta, falta aprobación |
+| `strokeWidth` | número | **No usar** (ver abajo). | propuesta, falta aprobación |
+| `ariaLabel` | texto | Siempre: lo que mide («Perfil completado»). | propuesta, falta aprobación |
+
+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: **en mobile se lee y se toca con el dedo, así que va más grande; en web
+(desktop), más chico.** Mobile es `≤ 767 px`, el mismo corte de `BreakpointsService.isMobile()`
+en master-pedidos. Fuente: canon del dueño (03-10-2026), el mismo patrón que ya usan 27 controles
+de la app.
+
+| uso | mobile | web | fuente |
+|---|---|---|---|
+| Junto a un texto que ya dice el número | `48` | `48` | propuesta, falta aprobación |
+| En una fila o card | `64` | `56` | propuesta, falta aprobación |
+| Lo principal de la pantalla | `80` | `72` | propuesta, falta aprobación |
+
+```ts
+readonly bp = inject(BreakpointsService); // master-pedidos: src/app/services/breakpoints.service.ts
+```
+
+```html
+<sui-circular-progress-bar [value]="60" [size]="bp.isMobile() ? 64 : 56" ariaLabel="Perfil completado" />
+```
+
+`size` es un número: el ternario devuelve `64 : 56`, no `'64' : '56'`.
+
+## API
+
+<!-- api:inicio -->
+<!-- generada: no editar a mano — `npm run docs` -->
+
+| input | tipo | default |
+|---|---|---|
+| `value` | `number` | `0` |
+| `size` | `48 \| 56 \| 64 \| 72 \| 80` | `64` |
+| `color` | `'blue' \| 'green' \| 'orange' \| 'red' \| 'purple'` | `'blue'` |
+| `number` | `boolean` | `true` |
+| `strokeWidth` | `number \| null` | `null` |
+| `ariaLabel` | `string \| null` | `null` |
+
+Outputs: ninguno.
+<!-- api: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`.
+
+## Ejemplo
+
+```html
+<div class="perfil">
+  <sui-circular-progress-bar [value]="60" [size]="56" ariaLabel="Perfil completado" />
+  <span>Completa tu perfil para empezar a repartir</span>
+</div>
+```

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

@@ -0,0 +1,112 @@
+---
+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
+
+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 [withDot]="true"`, 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í; el resto es **propuesta, falta aprobació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:289` 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`. | propuesta, falta aprobación |
+| `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). | propuesta, falta aprobación |
+| `state` | `hover` | **No usar** (ver abajo). | propuesta, falta aprobación |
+| `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»). | propuesta, falta aprobación |
+
+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: **en mobile se lee y se toca con el dedo, así que va más grande; en web
+(desktop), más chico.** Mobile es `≤ 767 px`, el mismo corte de `BreakpointsService.isMobile()`
+en master-pedidos. Fuente: canon del dueño (03-10-2026), el mismo patrón que ya usan 27 controles
+de la app.
+
+| uso | mobile | web | fuente |
+|---|---|---|---|
+| Cualquiera | `large` (32 × 32) | `medium` (24 × 24) | canon (aprobado por el dueño, 03-10-2026) |
+| Separación entre dots | 12 px | 4 px | propuesta, falta aprobación |
+
+```html
+<sui-color-dot [color]="c" [size]="bp.isMobile() ? '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.
+
+## API
+
+<!-- api:inicio -->
+<!-- generada: no editar a mano — `npm run docs` -->
+
+| input | tipo | default |
+|---|---|---|
+| `color` | `'gray' \| 'blue' \| 'orange' \| 'red' \| 'green' \| 'yellow' \| 'purple' \| 'sky' \| 'pink' \| 'teal'` | `'gray'` |
+| `customHex` | `string \| null` | `null` |
+| `state` | `'default' \| 'hover' \| 'selected' \| 'disabled'` | `'default'` |
+| `size` | `'medium' \| 'large'` | `'medium'` |
+| `ariaLabel` | `string` | `''` |
+
+| output | payload |
+|---|---|
+| `clicked` | `void` |
+<!-- api: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.
+
+## Ejemplo
+
+```html
+@for (c of colores; track c) {
+  <sui-color-dot [color]="c" [state]="c === elegido() ? 'selected' : 'default'" (clicked)="elegido.set(c)" />
+}
+```

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

@@ -0,0 +1,124 @@
+---
+name: sui-color-picker
+selector: sui-color-picker
+resumen: Botón que abre un panel para elegir un color libre (espectro, matiz, hex) o uno de los recomendados
+alternativas: [sui-color-dot (un punto de color, para armar una grilla propia), sui-select o sui-radio-card (el color es una categoría con nombre, no un color libre)]
+---
+
+# sui-color-picker
+
+Story: [Atoms/Color/Color Picker](https://sui-design-system.web.app/?path=/docs/atoms-color-color-picker--docs)
+
+## Cuándo usarlo / cuándo no
+
+**Úsalo** cuando la persona tiene que **crear o elegir un color libre** y guardarlo como hex: el
+color de una variante de producto («Rojo», «Azul marino» en una polera), el color de una etiqueta.
+Se ve igual en iOS, Android y desktop porque no usa el selector del sistema.
+
+**No lo uses** para:
+
+- Elegir entre colores que son categorías con nombre (estados, tipos): `sui-select` o
+  `sui-radio-card`. El picker es para color **libre**.
+- Una grilla fija de colores siempre visible, sin botón: arma la grilla con `sui-color-dot`.
+- El selector nativo (`<input type="color">`): abre algo distinto en cada sistema.
+
+Regla corta: **color libre que se guarda → color-picker · una de N categorías → select · grilla siempre a la vista → color-dot.**
+
+## Qué variante usar
+
+> **La guía del DS lo define para «elegir o crear colores específicos»** y lo muestra de dos
+> formas: el panel a la vista y dentro de un popover con su botón («Pick Color»), con una
+> sección de colores recomendados. No dice cuándo va cada pieza.
+>
+> Uso medido el 03-10-2026 en `master-pedidos/src/app` (misma exclusión que `sui-badge`):
+> **0 usos**. Hay **1 `<input type="color">` nativo** que es exactamente su caso.
+
+### Las piezas
+
+| prop | cuándo | fuente |
+|---|---|---|
+| `value` | El hex guardado (`[(value)]`). Sin valor, el botón muestra el `placeholder`. | según la guía del DS (popover con botón) |
+| `placeholder` | «Elegir color» (default). Cambiarlo solo si el campo dice qué color es («Color de la variante»). | propuesta, falta aprobación |
+| `alpha` | **`false` por defecto en la app**: la base guarda 6 caracteres (`#rrggbb`). Con `true` (default del componente) puede emitir 8. | propuesta, falta aprobación |
+| `colors` | Acotar los recomendados a los que tengan sentido para el caso. Default: los 10 de SUI. | según la guía del DS (sección «Recommended Colors») |
+| `recommendedLabel` | «Colores recomendados» (default). | propuesta, falta aprobación |
+| `presetsOnly` | Solo la grilla de recomendados, sin espectro ni hex: cuando el color tiene que salir de la paleta. | propuesta, falta aprobación |
+| `eyedropper` | Dejar el default (`true`): solo aparece donde el navegador lo soporta (Chromium de escritorio). | propuesta, falta aprobación |
+| `showFormatLabel` | `false`: el «Hex» con flecha es decorativo, no cambia de formato. | propuesta, falta aprobación |
+| `disabled` | El campo existe pero no se puede tocar ahora. | propuesta, falta aprobación |
+| `ariaLabel` | Siempre que el botón no tenga un label al lado que diga qué color es. | propuesta, falta aprobación |
+
+**Usos de hoy que rompen la regla:**
+
+- **1 nativo → `sui-color-picker` con `[alpha]="false"`:**
+  `components/add-product-modal/add-product-modal.html:293` (color de cada opción cuando el grupo
+  se muestra «como colores»; guarda `swatchHex` de 6 caracteres).
+
+## Tamaño en mobile y en web
+
+| uso | mobile | web |
+|---|---|---|
+| botón que abre el panel | 32 px de alto (no hay `size`) | 32 px |
+
+**No tiene un tamaño grande para mobile.** El botón mide unos 32 px de alto y los puntos de
+color del panel 24 px. En mobile funciona, pero queda debajo de los 44 px de área táctil.
+Agrandarlo es una decisión del DS.
+
+## «No usar»: por qué no hoy y cuándo sí
+
+| qué | por qué no hoy | cuándo sí, en un flujo nuevo |
+|---|---|---|
+| `alpha` en `true` | el modelo de datos espera `#rrggbb`; con opacidad emite `#rrggbbaa` | un color de marca sobre imágenes donde la transparencia es parte del diseño (fondo de un banner) |
+| `presetsOnly` | el único caso de hoy (colores de una variante) necesita colores libres | el color de una etiqueta interna con paleta cerrada |
+| `showFormatLabel` en `true` | muestra «Hex» con una flecha que no hace nada | nunca, hasta que el DS soporte RGB o HSL |
+
+## API
+
+<!-- api:inicio -->
+<!-- generada: no editar a mano — `npm run docs` -->
+
+| input | tipo | default |
+|---|---|---|
+| `colors` | `readonly SuiColorDotColor[]` | `SUI_COLOR_DOT_COLORS` |
+| `value` · model, `[(value)]` | `string \| null` | `null` |
+| `placeholder` | `string` | `'Elegir color'` |
+| `recommendedLabel` | `string` | `'Colores recomendados'` |
+| `presetsOnly` | `boolean` | `false` |
+| `alpha` | `boolean` | `true` |
+| `eyedropper` | `boolean` | `true` |
+| `showFormatLabel` | `boolean` | `true` |
+| `disabled` | `boolean` | `false` |
+| `ariaLabel` | `string` | `'Seleccionar color'` |
+
+| output | payload |
+|---|---|
+| `change` | `string` |
+<!-- api:fin -->
+
+`SuiColorDotColor`: `'gray' | 'blue' | 'orange' | 'red' | 'green' | 'yellow' | 'purple' | 'sky' | 'pink' | 'teal'`.
+
+## Trampas
+
+- **`alpha` viene en `true`**: si la persona baja la opacidad, el valor pasa a 8 caracteres.
+  Pasa `[alpha]="false"` si lo guardas como `#rrggbb`.
+- **El «Hex» con flecha es decorativo**: solo lee y emite hex.
+- **El cuentagotas no aparece en iOS, Android, Safari ni Firefox**: no es un error.
+- El hex escrito a mano se aplica al salir del campo o con Enter; si es inválido, vuelve al anterior
+  sin avisar.
+- Acepta 3, 4, 6 u 8 caracteres con o sin `#`, y siempre emite con `#`.
+- El botón muestra el nombre en español si el color es uno de los 10 («Naranja»); si no, el hex
+  en mayúsculas.
+- Elegir un recomendado **cierra** el panel; arrastrar el espectro no.
+- El panel vive en un overlay del CDK: escapa a cualquier `overflow: hidden` del contenedor.
+- No implementa `ControlValueAccessor`: se usa con `[(value)]`.
+
+## Ejemplo
+
+```html
+<sui-color-picker
+  [alpha]="false"
+  [showFormatLabel]="false"
+  placeholder="Color de la variante"
+  [value]="opcion.swatchHex ?? null"
+  (valueChange)="cambiarColor(opcion, $event)" />
+```

package/docs/sui-compact-avatar-group/README.md

@@ -0,0 +1,103 @@
+---
+name: sui-compact-avatar-group
+selector: sui-compact-avatar-group
+resumen: Varias personas en una píldora baja con el «+N» en texto, para tablas y filas apretadas
+alternativas: [sui-avatar-group (la pila grande, para cards y cabeceras), sui-avatar (una sola persona)]
+---
+
+# sui-compact-avatar-group
+
+Story: [Atoms/Avatar/Compact Avatar Group](https://sui-design-system.web.app/?path=/docs/atoms-avatar-compact-avatar-group--docs)
+
+## Cuándo usarlo / cuándo no
+
+**Úsalo** cuando hay que mostrar varias personas **en poco alto**: una celda de tabla, una fila
+de lista. Es una píldora blanca con los avatares casi pegados y el «+N» como texto.
+
+**No lo uses** para:
+
+- Una card o una cabecera con espacio: `sui-avatar-group`.
+- Una sola persona: `sui-avatar`.
+
+## Qué variante usar
+
+> **La guía del DS dice qué es, sus tamaños y sus dos estilos, no cuándo usar cada uno.** Lo
+> marcado «según la guía del DS» sale de su texto o de su código; el resto es **propuesta,
+> falta aprobación**.
+>
+> Uso medido el 03-10-2026 en `master-pedidos/src/app`: **0 usos directos**. El DS lo usa dentro
+> de `sui-table`.
+
+### Lo que sí dice la guía del DS
+
+- **Para qué es**: la versión más compacta del avatar group.
+- **Tamaños**: 40, 32 y 24; el default de la guía es 40 (en SUI, `'32'`).
+- **Estilos**: `default` (píldora blanca con sombra) y `stroke` (además, un borde `stroke-soft-200`).
+
+### `size`, `appearance`, `max` y `count`
+
+| input | valor | cuándo | fuente |
+|---|---|---|---|
+| `size` | `'24'` | Celda de tabla. | propuesta |
+| `size` | `'32'` (default SUI) | Fila de una lista. | propuesta |
+| `size` | `'40'` (default de la guía) | Dentro de una card. | propuesta |
+| `appearance` | `default` | Sobre un fondo gris o de color: la sombra lo separa. | propuesta |
+| `appearance` | `stroke` | Sobre blanco, donde la sombra sola no alcanza a marcar el borde. | propuesta |
+| `max` | `3` (default) | Tres avatares visibles. | propuesta |
+| `count` | — | Solo si el total no está en `items` (vienen 3 caras pero son 12 personas): `count="+9"`. Si no, se calcula solo. | propuesta |
+
+Usos de hoy que rompen la regla: **0** (no hay usos).
+
+## Tamaño en mobile y en web
+
+En mobile se lee y se toca con el dedo, así que va más grande; en web, más chico. En las
+pantallas que se usan en los dos (panel del local, super admin) se elige con el servicio de
+breakpoints de la app (`bp`, en `services/breakpoints.service.ts`); en las que solo existen en
+el celular (cliente, repartidor) va directo el valor de mobile. Todo es **propuesta**.
+
+| uso | mobile | web |
+|---|---|---|
+| fila o celda de tabla | `'32'` | `'24'` |
+| dentro de una card | `'40'` | `'32'` |
+
+```html
+<sui-compact-avatar-group [size]="bp.isMobile() ? '32' : '24'" [items]="repartidores" />
+```
+
+## «No usar»: por qué no hoy y cuándo sí
+
+| qué | por qué no hoy | cuándo sí, en un flujo nuevo |
+|---|---|---|
+| todo el componente (0 usos) | no hay tablas con varias personas por fila | la columna «repartidores» en la tabla de locales del super admin |
+
+## API
+
+<!-- api:inicio -->
+<!-- generada: no editar a mano — `npm run docs` -->
+
+| input | tipo | default |
+|---|---|---|
+| `size` | `'24' \| '32' \| '40'` | `'32'` |
+| `appearance` | `'default' \| 'stroke'` | `'default'` |
+| `items` | `readonly SuiAvatarGroupItem[]` | `[]` |
+| `max` | `number` | `3` |
+| `count` | `string \| null` | `null` |
+
+Outputs: ninguno.
+<!-- api:fin -->
+
+`items` usa `SuiAvatarGroupItem` (ver `sui-avatar-group`).
+
+## Trampas
+
+- **`size` es un string**: `size="32"`, no `[size]="32"` (con número no compila).
+- **El estilo se llama `appearance`**, no `variant` ni `style` (el atributo `style` es del HTML).
+- **`size` no es el de `sui-avatar`**: `'24'` → avatar `sm`, `'32'` → `md`, `'40'` → `lg`.
+- **`count` gana sobre el cálculo**: si lo pasas, se muestra aunque no sobre nadie.
+- Las reglas de foto y color de cada persona son las de `sui-avatar`.
+
+## Ejemplo
+
+```html
+<sui-compact-avatar-group size="24" appearance="stroke" [items]="repartidoresDelLocal" />
+```