@ajuarezso/sui-design-system 0.20.0 → 0.21.0

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

@@ -0,0 +1,160 @@
+---
+name: sui-radio-card
+selector: sui-radio-card
+resumen: Opción con tarjeta (ícono o foto, título, descripción y el radio) para elegir UNA de una lista corta
+alternativas: [sui-radio-label (la misma elección sin tarjeta, en un formulario denso), sui-select (lista larga o que no entra en pantalla), sui-segmented-control (2–4 vistas de la misma pantalla), sui-checkbox-card (se pueden elegir varias), sui-switch-card (se prende o se apaga un ajuste)]
+---
+
+# sui-radio-card
+
+Story: [Molecules/Card/Radio Card](https://sui-design-system.web.app/?path=/docs/molecules-card-radio-card--docs)
+
+## Cuándo usarlo / cuándo no
+
+**Úsalo** para elegir una sola opción de una lista corta cuando cada opción merece explicarse:
+«Delivery / Recojo en tienda», cómo cobrar («A mi saldo / Por Yape»), el medio de pago, el motivo
+de una cancelación, el modo de asignación de repartidores.
+
+**No lo uses** para:
+
+- Varias opciones que se suman: `sui-checkbox-card`.
+- Un ajuste que se prende o se apaga: `sui-switch-card`.
+- Una lista larga (más de 6–7 opciones) o que crece con los datos: `sui-select`.
+- Cambiar de vista dentro de la misma pantalla: `sui-segmented-control` o tabs.
+
+Regla corta: **una de pocas, con explicación → radio-card · una de muchas → select · varias →
+checkbox-card.**
+
+## Qué variante usar
+
+> **La guía del DS no tiene página de la radio card.** De la guía sale solo lo del radio que lleva
+> adentro: **«para elegir una sola opción de una lista corta»**. El resto es práctica de la app
+> («propuesta») o regla ya aprobada («canon»).
+>
+> Uso medido el 03-10-2026 en `master-pedidos/src/app` (misma exclusión que `sui-card`): **31
+> radio-cards en 14 archivos**. Tipos: 23 `left-icon` (3 de ellos con emoji animado por
+> `iconSrc`), 6 `basic`, 1 `avatar`, 1 `company`. Tamaños: 24 `bp.controlSize()`, 4 `medium`, 1
+> `xlarge` fijo, 1 dinámico, 1 sin `size`. 6 con `sublabel`, 3 con `disabled`, 1 con `badge`.
+
+### `type` (el leading)
+
+| type | cuándo | fuente |
+|---|---|---|
+| `left-icon` con `icon` | Lo normal: un ícono Remix que dice de qué va la opción (`truck-line` Delivery, `store-2-line` Recojo). | propuesta (práctica de la app) |
+| `left-icon` con `iconSrc` | Emoji animado cuando la elección es de las grandes del rol (el vehículo del repartidor, el rol al registrarse, el tipo de mandadito). Los emojis van de `assets/emojis/` o `FLUENT_EMOJI_ANIM`. | propuesta |
+| `left-icon` con `emoji` | Lo mismo con un nombre de `SuiEmoji` en vez de una URL. Hoy 0 usos; vale igual. | propuesta |
+| `basic` | Opciones de texto puro: motivos de cancelación, quién paga el envío, los premios de una meta. | propuesta |
+| `avatar` (`imageUrl`) | El logo redondo de un medio de pago (Yape, Plin, efectivo en el checkout). | propuesta |
+| `company` (`imageUrl`) | Elegir entre tus locales (cambiar de negocio en mi-negocio). | propuesta |
+| `brand`, `card-provider` | Ver «No usar». | propuesta |
+
+### Las piezas
+
+| prop | cuándo | fuente |
+|---|---|---|
+| `value` (obligatorio) | Siempre, aunque no haya grupo. Es lo que emite `selected`. | propuesta |
+| `label` | Siempre. El nombre de la opción, corto: «Delivery», «Lo antes posible». | propuesta |
+| `description` | Casi siempre: la consecuencia de elegirla («Lo revisamos y te transferimos. Puede tardar unas horas.»). | propuesta |
+| `sublabel` | Una precisión corta entre paréntesis («(canal estable)», «(sin OTA)»). Nunca la explicación: eso es `description`. | propuesta |
+| `badge` | Marca una opción frente a las otras: «Por defecto». Con string sale azul `light`; pasa el objeto con el color que corresponda según el badge (un «Por defecto» es `gray`). | propuesta |
+| `disabled` | La opción existe pero hoy no se puede: di por qué en la `description` («El local está cerrado ahora»). | propuesta |
+| `checked` / `[(ngModel)]` / `sui-radio-group` | El estado: `[checked]` + `(selected)` sueltos (lo normal en la app), o `ngModel` con `name` (checkout), o dentro de un `sui-radio-group`. | propuesta |
+
+### `size` (el radio de adentro)
+
+| size | cuándo | fuente |
+|---|---|---|
+| `xlarge` (28) | Mobile, vía `bp.controlSize()`. | canon (aprobado por el dueño, 28-09-2026: «componentes grandes») |
+| `large` (24) | Desktop, vía `bp.controlSize()`. | canon (aprobado por el dueño, 28-09-2026) |
+| `medium` (20, default) | No usar en pantallas nuevas. | canon (aprobado por el dueño, 28-09-2026) |
+
+**Usos de hoy que rompen las reglas:**
+
+- **5 sin el size del breakpoint**: `components/por-cobrar-card/por-cobrar-card.html:38` y `:48`,
+  `pages/driver/driver-dashboard/driver-dashboard.html:581`,
+  `pages/super-admin/master-orders/master-orders.html:720` (los cuatro en `medium`) y
+  `pages/mi-negocio/mi-negocio.html:22` (sin `size`). Además `pages/customer/mandadito/mandadito.html:30`
+  va en `xlarge` fijo (en web debería ser `large`).
+- **A revisar:** `pages/super-admin/master-orders/master-orders.html:720` lista a los repartidores
+  candidatos, una lista que crece con la flota (con muchos, `sui-select` o una lista con búsqueda).
+  `pages/role-selector/role-selector.html:24` usa la radio como botón: elegir ya avanza, sin
+  `[checked]`.
+
+## Tamaño en mobile y en web
+
+La card entera es el área táctil (≥ 72 de alto con descripción, 16 de padding): llega al piso de
+44 sola. El `size` cambia solo el radio.
+
+| uso | mobile | web |
+|---|---|---|
+| toda radio-card | `xlarge` (radio 28) | `large` (radio 24) |
+
+```html
+<sui-radio-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="brand"` (0 usos) | no hay servicios de terceros que elegir | elegir el canal por el que te contactamos (WhatsApp, correo) con su logo (`brand`) |
+| `type="card-provider"` (0 usos) | no hay pago con tarjeta guardada | elegir una tarjeta guardada en el checkout, cuando entre Culqi / Niubiz |
+| `size="medium"` | el radio de 20 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` | `'medium' \| 'large' \| 'xlarge'` | `'medium'` |
+| `value` | `string` | — (requerido) |
+| `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` |
+| `brand` | `SuiBrandLogoCompany \| null` | `null` |
+| `badge` | `SuiBadgeConfig \| string \| null` | `null` |
+| `disabled` | `boolean` | `false` |
+| `checked` · model, `[(checked)]` | `boolean` | `false` |
+
+| output | payload |
+|---|---|
+| `selected` | `string` |
+<!-- api:fin -->
+
+Implementa `ControlValueAccessor` (el valor del form es el `value` elegido). Dentro de un
+`sui-radio-group`, el grupo decide cuál está marcada.
+
+## Trampas
+
+- **`value` es obligatorio** aunque la uses suelta: sin él Angular tira error de input requerido.
+- **Precedencia del leading en `left-icon`: `icon` > `emoji` > `iconSrc`.** Si pasas `icon` y
+  `iconSrc`, gana el ícono.
+- Con `iconSrc` el círculo pasa a modo «relleno» (sin padding): el emoji ocupa los 40 × 40.
+- `avatar`, `company` y `card-provider` leen la imagen de **`imageUrl`**; `brand` lee `brand` (o
+  `imageUrl` si la marca no está en el catálogo). No hay slot para proyectar el leading (a
+  diferencia de `sui-checkbox-card`).
+- Suelta (sin grupo), elegirla la marca pero **no desmarca a las otras**: el padre tiene que
+  bindear `[checked]` de todas a la misma señal.
+- `badge` con string sale **azul `light` `small`** (en `sui-content-label` sale naranja).
+- `size` cambia solo el radio, no el padding ni el alto de la card.
+
+## Ejemplo
+
+```html
+<sui-radio-card
+  [size]="bp.controlSize()"
+  type="left-icon"
+  value="pickup"
+  icon="store-2-line"
+  label="Recojo en tienda"
+  description="Lo recoges en el local"
+  [checked]="modo() === 'pickup'"
+  (selected)="modo.set('pickup')" />
+```

package/docs/sui-rating/README.md

@@ -90,11 +90,11 @@ lista cargada, que viene con tope. La fórmula depende de `n`: otro denominador
 | `reviewCount` | número | **No usar** (ver abajo). | propuesta, falta aprobación |
 | `emojis` | lista | Dejar el default (cinco caras, de triste a feliz). Cambiarlo rompe la lectura de la escala. | propuesta, falta aprobación |
 | `ariaLabel` | texto | Decir qué se califica: «Califica al repartidor», «Nota del local». El default es «Calificación». | propuesta, falta aprobación |
-| `reason` / `reasonPlaceholder` / `reasonRows` | — | Solo en `bar-area`. **El placeholder va siempre en español**: el default está en inglés. | propuesta, falta aprobación |
+| `reason` / `reasonPlaceholder` / `reasonRows` | — | Solo en `bar-area`. El placeholder por defecto es «Cuéntanos por qué» (03-10-2026). | propuesta, falta aprobación |
 
 **Usos de hoy que rompen la regla:**
 
-- **1 `reviewCount`** (pinta «Ratings» en inglés):
+- **1 `reviewCount`** (hasta el 03-10-2026 pintaba «Ratings» en inglés; ahora «calificaciones»):
   `pages/super-admin/master-users/master-user-sheet.html:142`.
 - **1 rating usado como ícono** (`type="heart"` con `max=1` para los favoritos):
   `components/ratings-detail/ratings-detail.html:45`. Va `sui-icon name="heart-3-fill"`.
@@ -110,7 +110,7 @@ lista cargada, que viene con tope. La fórmula depende de `n`: otro denominador
 | `type="heart"` | La app califica con estrellas; el corazón es favoritos. | «¿Cuánto te gustó?» de una campaña, donde una estrella se leería como la nota del local. |
 | `type="number"` | No hay encuestas de 1 a 10. | «¿Qué tan probable es que nos recomiendes?» con `max=10` (ocupa 640 px de ancho). |
 | `showValue` | Escribe «4.7» con punto; la app escribe «4,7». | Si el DS formatea en `es-PE`. |
-| `reviewCount` | Agrega la palabra «Ratings» en inglés y abrevia «1.2K». | Si el DS traduce la etiqueta. |
+| `reviewCount` | Abrevia «1.2K calificaciones» (la etiqueta está en español desde 03-10-2026). | Una lista de locales donde el conteo exacto no importa. |
 | `alignment="vertical"` | Solo ordena `showValue` y `reviewCount`, que no se usan. | Junto con esos dos, si se arreglan. |
 
 ## Tamaño en mobile y en web
@@ -160,7 +160,7 @@ plataforma solo se elige en `inline`.
 | `emojis` | `string[]` | `[ 'pensive-face', 'confused-face', 'neutral-face', 'slightly-smiling-face', 'grinning-face-smiling-eyes', ]` |
 | `ariaLabel` | `string` | `'Calificación'` |
 | `reason` · model, `[(reason)]` | `string` | `''` |
-| `reasonPlaceholder` | `string` | `'Tell us why!'` |
+| `reasonPlaceholder` | `string` | `'Cuéntanos por qué'` |
 | `reasonRows` | `number` | `3` |
 
 | output | payload |
@@ -175,8 +175,9 @@ Implementa `ControlValueAccessor` sobre `value` (sirve con `formControlName`). `
 
 - **`showValue`, `reviewCount` y `reviewLink` solo se ven con `alignment="horizontal"` o
   `"vertical"`.** Con el default `inline` no aparecen.
-- **`reviewCount` agrega «Ratings» en inglés** y `showValue` formatea con punto.
-- **`reasonPlaceholder` viene en inglés** («Tell us why!»).
+- **`reviewCount` agrega «calificaciones»** (en singular con 1; antes «Ratings») y `showValue`
+  formatea con punto.
+- **`reasonPlaceholder` por defecto dice «Cuéntanos por qué»** (hasta el 03-10-2026, «Tell us why!»).
 - **`halfStep` solo funciona en `inline` + `readonly`.** En un input no hay medias.
 - **En `bar` el `size` no hace nada** (íconos de 20, celdas de 64); en `cell` los íconos miden 32.
 - **En `bar` y `bar-area` se pinta solo la celda elegida**, no las anteriores: no es una fila de

package/docs/sui-rich-editor/README.md

@@ -0,0 +1,114 @@
+---
+name: sui-rich-editor
+selector: sui-rich-editor
+resumen: Barra de formato (negrita, cursiva, alineación, enlace) con un área de texto editable opcional
+alternativas: [sui-textarea (todo texto libre de la app hoy, sin formato)]
+---
+
+# sui-rich-editor
+
+Story: [Molecules/Rich Editor](https://sui-design-system.web.app/?path=/docs/molecules-rich-editor--docs)
+
+## Cuándo usarlo / cuándo no
+
+**Úsalo** solo si un texto **necesita formato** y se va a mostrar con ese formato: negritas,
+listas o enlaces en un texto largo que se publica en la web.
+
+**No lo uses** para:
+
+- Notas, motivos, descripciones de productos, mensajes y avisos: `sui-textarea`. Todo eso se
+  guarda y se muestra como texto plano.
+- Un push o un aviso del celular: no muestran formato.
+
+Regla corta: **hoy, siempre `sui-textarea`.**
+
+## Qué variante usar
+
+> **La guía del DS no tiene página para este componente.** Viene del Figma («Rich Editor»), donde
+> solo está la barra de formato. Todo lo de abajo es **propuesta, falta aprobación**.
+>
+> Uso medido el 03-10-2026 en `master-pedidos/src/app`: **0 usos**.
+
+| prop / evento | cuándo | fuente |
+|---|---|---|
+| `layout="full"` (default) | Título, tamaño, B I U S, alineación, comentario, enlace, mención. | API |
+| `layout="formatting"` | Solo B I U S y alineación: lo único que el editor aplica solo. | propuesta, falta aprobación |
+| `layout="compact"` | Solo título y tamaño (los dos son avisos a la pantalla, no formato real). | — |
+| `layout="social"` | Comentario, enlace, mención (también avisos). | — |
+| `showMore` | El botón ⋮ al final. Apagarlo si no hay más acciones. | API |
+| `editable` | `true` para tener el área donde se escribe; `false` deja solo la barra. | API |
+| `placeholder` | «Escribe algo…» (default) o algo del contexto. | API |
+| `value` | El contenido, **en HTML**. | API |
+| `headingLabel` · `fontSizeLabel` | Lo que dicen los botones de título y tamaño («Header», «14px» por default). | API |
+| `(action)` | Cada botón de la barra: la pantalla tiene que resolver título, tamaño, enlace, comentario y mención. | API |
+
+## Tamaño en mobile y en web
+
+**No tiene `size`.** Los botones de la barra son de 28 px: **no tiene tamaño suficiente para
+mobile**. Si alguna vez se usa, que sea en el panel web.
+
+## «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) | ningún texto de la app lleva formato | una página de ayuda o de términos que se escribe desde el super admin y se muestra en la web |
+| `layout` `full`, `compact`, `social` | título, tamaño, enlace, comentario y mención no los hace el editor: solo avisa | si se monta un editor completo (Tiptap) detrás |
+
+## API
+
+<!-- api:inicio -->
+<!-- generada: no editar a mano — `npm run docs` -->
+
+### `sui-rich-editor`
+
+| input | tipo | default |
+|---|---|---|
+| `layout` | `'full' \| 'compact' \| 'formatting' \| 'social'` | `'full'` |
+| `showMore` | `boolean` | `true` |
+| `editable` | `boolean` | `false` |
+| `placeholder` | `string` | `'Escribe algo…'` |
+| `value` · model, `[(value)]` | `string` | `''` |
+| `headingLabel` | `string` | `'Header'` |
+| `fontSizeLabel` | `string` | `'14px'` |
+
+| output | payload |
+|---|---|
+| `action` | `SuiRichEditorAction` |
+| `valueChange` | `string` |
+
+### `sui-rich-editor-item`
+
+| input | tipo | default |
+|---|---|---|
+| `type` | `'text' \| 'dropdown' \| 'icon' \| 'color'` | `'icon'` |
+| `state` | `'default' \| 'hover' \| 'active'` | `'default'` |
+| `label` | `string` | `''` |
+| `icon` | `string` | `''` |
+| `color` | `'gray' \| 'blue' \| 'orange' \| 'red' \| 'green' \| 'yellow' \| 'purple' \| 'sky' \| 'pink' \| 'teal'` | `'gray'` |
+| `colorHex` | `string \| null` | `null` |
+| `ariaLabel` | `string` | `''` |
+| `disabled` | `boolean` | `false` |
+
+| output | payload |
+|---|---|
+| `clicked` | `void` |
+<!-- api:fin -->
+
+Sub-componente: `sui-rich-editor-item` (cada botón de la barra).
+
+## Trampas
+
+- **`value` es HTML.** Mostrarlo con `[innerHTML]` sin limpiarlo abre la puerta a código ajeno.
+  Limpiarlo en el servidor antes de guardar.
+- **Solo B I U S y alineación funcionan solos** (usa `document.execCommand`, que está en desuso).
+  Título, tamaño, enlace, comentario y mención solo emiten `(action)`: la pantalla tiene que hacer
+  el resto.
+- Por default muestra solo la barra: sin `[editable]="true"` no hay dónde escribir.
+- Labels por default en inglés o técnicos («Header», «14px»).
+
+## Ejemplo
+
+```html
+<sui-rich-editor layout="formatting" [showMore]="false" [editable]="true"
+                 placeholder="Escribe la respuesta…" [(value)]="html" />
+```

package/docs/sui-select/README.md

@@ -0,0 +1,180 @@
+---
+name: sui-select
+selector: sui-select
+resumen: Campo que despliega una lista para elegir UNA opción (distrito, repartidor, categoría, motivo)
+alternativas: [sui-radio-label / sui-radio-card (2 a 6 opciones fijas a la vista), sui-segmented-control (2 a 4 modos que se aplican al instante), sui-compact-select (filtro chico que se ajusta al texto), sui-compact-select-for-input (elegir moneda o país dentro de un campo), sui-tag-input (varios valores)]
+---
+
+# sui-select
+
+Story: [Molecules/Select/Select](https://sui-design-system.web.app/?path=/docs/molecules-select-select--docs)
+
+## Cuándo usarlo / cuándo no
+
+**Úsalo** para elegir **una** opción de una lista que **sale de datos** (departamento, provincia,
+distrito, repartidor, categoría, plan) o que tiene **más de 6 opciones fijas**.
+
+**No lo uses** para:
+
+- 2 a 6 opciones fijas dentro de un formulario: se ven todas de una con `sui-radio-label` (web) o
+  `sui-radio-card` (mobile). Abrir un menú para elegir entre «Casa» y «Trabajo» es un toque de más.
+- 2 a 4 modos de la vista que se aplican al tocar (Hoy · Semana · Mes): `sui-segmented-control`.
+- **Buscar** dentro de la lista: `sui-select` **no tiene buscador**. Con 40 distritos se scrollea.
+- Elegir **varias**: no es múltiple. Varias opciones fijas → casillas; valores libres → `sui-tag-input`.
+- Una lista con foto o bandera por opción: las opciones solo muestran texto (ver «Trampas»).
+
+Regla corta: **sale de datos o son más de 6 → select · 2–6 fijas → radio · modos de la vista → segmented.**
+
+## Qué variante usar
+
+> **La guía del DS lo define como el control para elegir una sola opción de un menú** y muestra
+> label y hint, íconos, tamaños, país, método de pago, usuario y deshabilitado. Trae además tres
+> variantes que en SUI son componentes aparte: `compact` (`sui-compact-select`), `inline`
+> (`sui-inline-select`) y `compactForInput` (`sui-compact-select-for-input`). No dice cuándo va cada una.
+>
+> Uso medido el 03-10-2026 en `master-pedidos/src/app` (misma exclusión que `sui-badge`, más
+> `master-ejercicios`): **57 usos en 26 archivos**. Todos `type="basic"` y sin ícono. Tamaños:
+> 39 sin `size` (`medium`), 11 `large`, 3 `bp.isMobile() ? 'large' : 'small'`, 2 `medium`,
+> 1 `small`, 1 `bp.controlSize()`. 29 pasan `placeholder`.
+
+### Qué elegir según las opciones
+
+| caso | componente | fuente |
+|---|---|---|
+| La lista sale de datos (ubigeo, repartidores, categorías, planes) | `sui-select` | según la guía del DS (elegir una opción de un menú) |
+| Más de ~6 opciones fijas | `sui-select` | canon (README de `sui-radio`, aprobado 03-10-2026) |
+| 2 a 6 opciones fijas en un formulario | `sui-radio-label` / `sui-radio-card` | propuesta, falta aprobación (sale del umbral de `sui-radio`) |
+| 2 a 4 modos que se aplican al instante | `sui-segmented-control` | canon (README de `sui-segmented-control`, aprobado 03-10-2026) |
+| Filtro de una barra con 5 o más opciones | `sui-select` sin label (o `sui-compact-select` en web) | propuesta, falta aprobación |
+
+**Candidatos de hoy** (no rompen nada; se verían mejor con radios o segmented):
+
+- **6 selects con 2 opciones fijas**: `components/add-product-modal/add-product-modal.html:246`,
+  `pages/drivers/drivers.html:373` y `pages/drivers/add-driver/add-driver.html:111` («Tipo de pago»),
+  `pages/super-admin/master-gastos/master-gastos.html:185` y `:200`,
+  `pages/super-admin/master-sonidos-push/master-sonidos-push.html:85`.
+- **15 con 3 a 6 opciones fijas en un formulario**: `components/address-form-modal/address-form-modal.html:11`
+  («Etiqueta»), `pages/customer/profile/profile.html:249` («Género»), `pages/drivers/drivers.html:359`
+  («Tipo de vehículo»), `pages/discounts/discounts.html:139`.
+- **2 filtros de período de 3 opciones** → segmented: `pages/overview/overview.html:46`,
+  `pages/discounts/discounts.html:48`.
+
+### `type`, `leadingIcon`, `imageUrl`, `flag`, `badge`
+
+| prop | cuándo | fuente |
+|---|---|---|
+| `type="basic"` (default) sin ícono | Todo select de la app hoy. | según la guía del DS |
+| `type="avatar"` + `imageUrl` | Elegir un **repartidor**: la foto de quien quedó elegido en el campo. Hoy `pages/orders/orders.html:256` muestra solo el nombre. | según la guía del DS (ejemplo «User»); el caso es propuesta |
+| `type="provider"` + `imageUrl` | Método de pago con logo (Yape, Plin). | según la guía del DS (ejemplo «Payment Method»); el caso es propuesta |
+| `leadingIcon` (`true` o nombre RemixIcon) | Un ícono que ayuda a reconocer el campo en un formulario largo. Hoy sin caso. | según la guía del DS (ejemplo «Icons») |
+| `type="country"` + `flag` | No usar hoy: todo es Perú. | según la guía del DS (ejemplo «Country») |
+| `type="brand"` / `"company"` | No usar hoy. | — |
+| `badge` | No usar hoy. | — |
+
+### Las piezas
+
+| prop | cuándo | fuente |
+|---|---|---|
+| `label` | Siempre en formularios. Sin label solo en un filtro de barra donde el valor se explica solo («Todos los roles»). | según la guía del DS (ejemplo con label y hint) |
+| `placeholder` | **Siempre**, en imperativo con tuteo: «Elige el motivo», «Elige tu distrito». El default es «Seleccionar...». | canon (CANON-SUI §5.3) |
+| `required` · `sublabel` · `tooltip` · `hint` | Igual que `sui-input`: asterisco, «(Opcional)» con paréntesis, aclaración, ayuda de una línea. Hoy 1 sin paréntesis: `pages/customer/profile/profile.html:249`. | según la guía del DS |
+| `error` + `errorMessage` | No eligió en un campo obligatorio: «Elige tu distrito». | según la guía del DS |
+| `disabled` | Selects en cascada: provincia hasta elegir departamento, distrito hasta elegir provincia. | según la guía del DS (ejemplo deshabilitado); el caso ya es práctica (`components/address-form-modal/address-form-modal.html:87`) |
+| `options` | `SuiSelectOption<T>[]`: `{ value, label, disabled? }`. `disabled` en la opción para lo que existe pero hoy no se puede elegir. | API |
+
+**Usos de hoy que rompen la regla:**
+
+- **28 sin `placeholder`** muestran «Seleccionar...» si arrancan vacíos.
+- **16 placeholders «Seleccionar…» o «Selecciona…»** (y 4 que ya dicen «Elige…») → «Elige…»: «Seleccionar departamento»
+  (`components/address-form-modal/address-form-modal.html:77`), «Seleccionar tipo»,
+  «Selecciona una categoría».
+
+## Tamaño en mobile y en web
+
+El campo sigue la escala del input y del botón (`large` 48 y `xlarge` 52 son extensión de SUI;
+la guía tiene `medium` 40, `small` 36 y `xsmall` 32). **La lista acompaña al campo**: las opciones
+miden 36 hasta `medium` (las de la guía), 44 en `large` y 48 en `xlarge`, y **en mobile (≤ 767 px)
+nunca bajan de 44**, sea cual sea el `size`. El texto de la opción queda en 14/20, el mismo del
+valor del campo.
+
+| size del campo | opción en web | opción en mobile | fuente |
+|---|---|---|---|
+| `xsmall` · `small` · `medium` | 36 | 44 | 36: según la guía del DS · 44 en mobile: canon (aprobado por el dueño, 03-10-2026), extensión SUI |
+| `large` | 44 | 44 | canon (aprobado por el dueño, 03-10-2026), extensión SUI |
+| `xlarge` | 48 | 48 | canon (aprobado por el dueño, 03-10-2026), extensión SUI |
+
+| uso | mobile | web | fuente |
+|---|---|---|---|
+| campo de formulario | `large` (48) | `medium` (40) | propuesta, falta aprobación (igual que `sui-input`) |
+| filtro de una barra | `large` (48) | `small` (36) | propuesta (ya es práctica en `pages/orders/orders.html:256`) |
+| dentro de una tabla densa | no aplica | `xsmall` (32) | según la guía del DS |
+| `xlarge` (52) | no usar | no usar | propuesta: queda más alto que el botón `large` del footer |
+
+```html
+<sui-select [size]="bp.isMobile() ? 'large' : 'medium'" label="Distrito" … />   <!-- bp = BreakpointsService -->
+```
+
+## «No usar»: por qué no hoy y cuándo sí
+
+| qué | por qué no hoy | cuándo sí, en un flujo nuevo |
+|---|---|---|
+| `type="country"` + `flag` | todo es Perú | si se abren repartidores o locales en otro país |
+| `type="brand"` / `"company"` | no hay listas de marcas o empresas | elegir la marca de un producto envasado o la empresa de una flota |
+| `leadingIcon` | ningún formulario lo necesita para reconocerse | un formulario largo del panel con varios selects seguidos |
+| `badge` | no hay valores que marcar | marcar el plan elegido como «Recomendado» |
+| `size="xsmall"` | no hay selects dentro de tablas | cambiar el estado de una fila sin abrir el detalle |
+| `size="xlarge"` | queda más alto que el botón del footer | un select solo, como acción principal de la pantalla |
+
+## API
+
+<!-- api:inicio -->
+<!-- generada: no editar a mano — `npm run docs` -->
+
+| input | tipo | default |
+|---|---|---|
+| `size` | `'xsmall' \| 'small' \| 'medium' \| 'large' \| 'xlarge'` | `'medium'` |
+| `placeholder` | `string` | `'Seleccionar...'` |
+| `options` | `SuiSelectOption<T>[]` | `[]` |
+| `disabled` | `boolean` | `false` |
+| `error` | `boolean` | `false` |
+| `errorMessage` | `string \| null` | `null` |
+| `label` | `string \| null` | `null` |
+| `hint` | `string \| null` | `null` |
+| `type` | `'basic' \| 'country' \| 'avatar' \| 'provider' \| 'brand' \| 'company'` | `'basic'` |
+| `leadingIcon` | `string \| boolean` | `false` |
+| `flag` | `SuiFlagName \| null` | `null` |
+| `imageUrl` | `string \| null` | `null` |
+| `badge` | `SuiBadgeConfig \| string \| null` | `null` |
+| `sublabel` | `string \| null` | `null` |
+| `required` | `boolean` | `false` |
+| `tooltip` | `string \| null` | `null` |
+| `value` · model, `[(value)]` | `T \| null` | `null` |
+
+Outputs: ninguno.
+<!-- api:fin -->
+
+`value` es `model<T | null>`. Implementa `ControlValueAccessor`. Slot `[slot=leading]` para una
+decoración propia del campo (gana sobre ícono, imagen y bandera).
+
+## Trampas
+
+- **No busca y no es múltiple.** Con 40 opciones la lista se scrollea; con varias a elegir no sirve.
+- **Las opciones solo llevan texto**: `SuiSelectOption` no tiene ícono, foto ni bandera. El
+  `type="avatar"` o `"country"` decora **el campo**, no la lista.
+- **El default del placeholder es «Seleccionar...»**: genérico y con `...`. Pásalo siempre.
+- El `valueChange` puede traer `null`: los usos de hoy hacen `$event ?? ''`.
+- `T` arranca en `any`: tipa las opciones (`SuiSelectOption<string>[]`) para no arrastrar `any`
+  a la pantalla.
+- Con 44 px por opción en mobile el panel muestra unas 4 opciones antes de scrollear (el alto
+  máximo del panel no cambió).
+- El label también abre la lista al tocarlo.
+
+## Ejemplo
+
+```html
+<sui-select label="Distrito" [required]="true" placeholder="Elige tu distrito"
+            [options]="distritos()" [disabled]="!provinciaId()"
+            [error]="intentado() && !distritoId()" errorMessage="Elige tu distrito"
+            [size]="bp.isMobile() ? 'large' : 'medium'"
+            [value]="distritoId()" (valueChange)="distritoId.set($event ?? '')" />
+```

package/docs/sui-stepper/README.md

@@ -0,0 +1,166 @@
+---
+name: sui-stepper
+selector: sui-stepper
+resumen: Indica en qué paso de un flujo con orden está la persona, cuánto hizo y cuánto le falta
+alternativas: [sui-progress-bar (importa el porcentaje, no los pasos), sui-pagination (páginas de una lista), sui-tab-menu-horizontal (secciones sin orden)]
+---
+
+# sui-stepper
+
+Story: [Molecules/Stepper](https://sui-design-system.web.app/?path=/docs/molecules-stepper--docs)
+
+Ojo: es el **indicador de pasos** de un proceso. El «− 1 +» de cantidad es otra cosa
+(`sui-counter-input` o los botones del producto).
+
+## Cuándo usarlo / cuándo no
+
+**Úsalo** cuando un flujo tiene **pasos con nombre y orden** y ayuda saber cuántos faltan: el alta
+del local («Tu local → Producto»), del cliente («Ubicación → Teléfono»), del repartidor («Datos →
+Vehículo → Listo»).
+
+**No lo uses** para:
+
+- Un avance que es porcentaje (subida de un archivo, perfil completo al 70 %): `sui-progress-bar`.
+- Un pedido en curso (preparando, en camino, entregado): ese seguimiento tiene su propia línea de
+  tiempo y estados que no son pasos que la persona completa.
+- Secciones que se visitan en cualquier orden: `sui-tab-menu-horizontal`.
+- Un solo paso: no hay nada que indicar.
+
+Regla corta: **pasos con nombre y orden → stepper · porcentaje → progress-bar · secciones sin orden → tab menu.**
+
+## Qué variante usar
+
+> **Lo que dice la guía del DS**: tiene tres piezas. El **de puntos**, «muy mínimo, usado a menudo
+> como puntos de carrusel», con tamaños `small` y `xsmall`. El **horizontal**, «una guía visual de
+> procesos secuenciales». El **vertical**, el mismo indicador «para layouts diversos», con una
+> flecha en el paso activo. Estados de cada paso: `default`, `active`, `completed`. No trae do/don't.
+>
+> Uso medido el 03-10-2026 en `master-pedidos/src/app` (misma exclusión que `sui-badge`):
+> **7 usos en 7 archivos**, los 7 en los onboardings: todos `variant="horizontal"`, sin `size`
+> (`small`), sin `interactive`, de 2 o 3 pasos.
+
+### `variant`
+
+| variant | cuándo | ejemplo real de la app | fuente |
+|---|---|---|---|
+| `horizontal` (default) | Flujo de **2 a 4 pasos** con nombre, arriba del contenido del paso. Mobile y web. | `pages/driver-onboarding/step-info/step-info.html:3` («Datos → Vehículo → Listo») | según la guía del DS (procesos secuenciales); el límite de pasos es propuesta |
+| `vertical` | Flujo de **5+ pasos** en web, en una columna al costado del formulario. | (sin uso) | según la guía del DS (la pieza existe); el cuándo es propuesta |
+| `dot` | Pantallas que se pasan de a una sin nombre: carrusel de bienvenida, fotos. | (sin uso) | según la guía del DS (puntos de carrusel) |
+
+### `size`
+
+| size | qué cambia | cuándo | fuente |
+|---|---|---|---|
+| `small` (default) | punto de 8 · indicador de 20 · texto 14 | Web. | según la guía del DS (`small` es su default) |
+| `xsmall` | solo el punto: 4 px. Horizontal y vertical quedan igual que `small`. | Puntos sobre una foto o un banner chico, donde 8 px tapan. | según la guía del DS (el tamaño existe); el cuándo es propuesta |
+| `medium` | punto de 10 · indicador de 24 · texto 16 · card vertical de 44 | Mobile. **Está en el repo del DS (03-10-2026), no en la versión publicada 0.19.0.** | canon (dueño: tamaño por plataforma, 03-10-2026) |
+
+### Estado de cada paso (`currentStep`, `errorStep`)
+
+| estado | cómo se logra | cuándo | fuente |
+|---|---|---|---|
+| `completed` | índice menor que `currentStep` | pasos ya hechos (check verde) | según la guía del DS |
+| `active` | índice igual a `currentStep` | el paso en pantalla | según la guía del DS |
+| `default` | índice mayor que `currentStep` | lo que falta | según la guía del DS |
+| todos `completed` | `currentStep` = cantidad de pasos | la pantalla final («Listo») | propuesta, falta aprobación |
+| `error` | `errorStep` = índice | un flujo que se cortó en ese paso (pago rechazado, documento no aprobado). Extensión de SUI. | propuesta, falta aprobación |
+
+### `interactive`
+
+| valor | cuándo | fuente |
+|---|---|---|
+| `false` (default) | Los onboardings: se avanza con el botón «Continuar», no tocando el paso. | propuesta, falta aprobación |
+| `true` | Solo si los pasos hechos se pueden **volver a editar** y en web (el área tocable es chica, ver Tamaño). | propuesta, falta aprobación |
+
+### `steps`, `count`, `ariaLabel`
+
+| input | cuándo | fuente |
+|---|---|---|
+| `steps` | Siempre en `horizontal` y `vertical`, con `label` en cada uno. | propuesta, falta aprobación |
+| `count` | Solo en `dot`, cuando los pasos no tienen nombre. Si pasas `steps`, `count` se ignora. | según el código |
+| `ariaLabel` | Default «Progreso». Cámbialo si hay más de un stepper en la pantalla («Pasos del registro»). | propuesta, falta aprobación |
+
+**Usos de hoy que rompen las reglas:**
+
+- **0 de variante o estado**: los 7 son horizontales de 2 o 3 pasos, y `step-complete` usa
+  `currentStep = stepLabels.length` para marcar todo hecho (`pages/driver-onboarding/step-complete/step-complete.html:3`).
+- **7 sin tamaño por plataforma** (el `medium` todavía no está publicado): los onboardings se hacen
+  en el teléfono. Cuando se publique, `[size]="bp.isMobile() ? 'medium' : 'small'"`. Ejemplos:
+  `pages/customer-onboarding/step-phone/step-phone.html:3`, `pages/business-onboarding/step-info/step-info.html:3`.
+
+## Tamaño en mobile y en web
+
+| uso | mobile | web | fuente |
+|---|---|---|---|
+| horizontal arriba de un paso | `medium` (indicador 24, texto 16) | `small` (indicador 20, texto 14) | canon (dueño: tamaño por plataforma, 03-10-2026) |
+| vertical al costado | no se usa (no entra al lado del formulario) | `small` | propuesta, falta aprobación |
+| puntos de carrusel | `medium` (10) | `small` (8) | propuesta, falta aprobación |
+
+```html
+<sui-stepper [steps]="pasos" [currentStep]="paso - 1" [size]="bp.isMobile() ? 'medium' : 'small'" />
+```
+
+Sin `interactive` el tamaño solo afecta lo que se lee. Con `interactive`, **ningún tamaño llega a
+44 px tocables** en horizontal (24 de alto con `medium`) ni en puntos (10 px): por eso
+`interactive` queda para web. La card vertical `medium` sí llega a 44.
+
+## «No usar»: por qué no hoy y cuándo sí
+
+| qué | por qué no hoy | cuándo sí, en un flujo nuevo |
+|---|---|---|
+| `vertical` | ningún flujo tiene 5+ pasos | un alta de local completa en web (datos, carta, horario, pagos, repartidores) |
+| `dot` | ningún carrusel usa el componente | un carrusel de bienvenida o de fotos del producto |
+| `xsmall` | no hay puntos sobre fotos | puntos sobre el banner del carrusel del home |
+| `errorStep` | ningún flujo muestra dónde se cortó | el estado de una solicitud de repartidor rechazada en el paso «Documentos» |
+| `interactive` | en los onboardings se avanza con el botón | un formulario largo en web donde se vuelve a corregir un paso hecho |
+
+## API
+
+<!-- api:inicio -->
+<!-- generada: no editar a mano — `npm run docs` -->
+
+| input | tipo | default |
+|---|---|---|
+| `variant` | `'dot' \| 'horizontal' \| 'vertical'` | `'horizontal'` |
+| `steps` | `SuiStepperItem[]` | `[]` |
+| `count` | `number` | `0` |
+| `currentStep` | `number` | `0` |
+| `errorStep` | `number \| null` | `null` |
+| `size` | `'small' \| 'xsmall' \| 'medium'` | `'small'` |
+| `interactive` | `boolean` | `false` |
+| `ariaLabel` | `string` | `'Progreso'` |
+
+| output | payload |
+|---|---|
+| `stepClick` | `number` |
+<!-- api:fin -->
+
+```ts
+interface SuiStepperItem {
+  label?: string;   // sin label sale «Paso N»
+}
+type SuiStepperVariant = 'dot' | 'horizontal' | 'vertical';
+type SuiStepperSize = 'small' | 'xsmall' | 'medium';   // medium: repo del DS, no en 0.19.0
+```
+
+## Trampas
+
+- **`currentStep` arranca en 0.** La app numera los pasos desde 1: por eso los onboardings pasan
+  `currentStep - 1`.
+- **Un paso sin `label` dice «Paso 2»** (hasta el 03-10-2026 decía «Step 2»).
+- **`xsmall` solo achica los puntos**: en horizontal y vertical se ve igual que `small`.
+- **El horizontal hace `flex-wrap`**: con muchos pasos o nombres largos baja a otra línea en vez de
+  cortarse. Con 4+ pasos en mobile, revisa a 390 px.
+- **`stepClick` solo sale con `interactive`**; sin él los pasos son `div` y no responden.
+- `errorStep` gana sobre `currentStep`: los anteriores quedan hechos y los siguientes por hacer.
+- El activo usa `--sui-primary-base`, que en la app es naranja.
+
+## Ejemplo
+
+```html
+<sui-stepper
+  variant="horizontal"
+  [steps]="[{ label: 'Datos' }, { label: 'Vehículo' }, { label: 'Listo' }]"
+  [currentStep]="1"
+  [size]="bp.isMobile() ? 'medium' : 'small'" />
+```