@ajuarezso/sui-design-system 0.19.0 → 0.21.0

package/docs/sui-file-upload/README.md

@@ -0,0 +1,154 @@
+---
+name: sui-file-upload
+selector: sui-file-upload
+resumen: Área para arrastrar o elegir archivos que no son una foto (PDF, Excel, CSV)
+alternativas: [sui-image-upload (una sola imagen con vista previa: logo, portada, comprobante), sui-image-upload-profile (foto de perfil con botones Subir/Cambiar/Eliminar), sui-file-upload-card (el archivo ya elegido, con su progreso)]
+---
+
+# sui-file-upload
+
+Story: [Molecules/Upload/File Upload](https://sui-design-system.web.app/?path=/docs/molecules-upload-file-upload--docs)
+
+## Cuándo usarlo / cuándo no
+
+**Úsalo** para subir **documentos**: un PDF, un Excel, un CSV, o varios archivos a la vez. La
+persona arrastra el archivo o toca para buscarlo.
+
+**No lo uses** para:
+
+- **Una imagen** (logo, portada, foto del producto, captura del Yape): `sui-image-upload`, que
+  muestra la vista previa y se integra con el recortador y el compresor de la app.
+- Una foto de perfil con botones: `sui-image-upload-profile`.
+- Mostrar el archivo que ya se eligió: va `sui-file-upload-card` debajo.
+
+Regla corta: **foto → image-upload · documento o varios archivos → file-upload · el archivo ya
+elegido → file-upload-card.**
+
+## Qué variante usar
+
+> **Lo que dice la guía del DS** (página del file upload): es la forma de **arrastrar y soltar, o
+> buscar en el equipo**, para subir un archivo. Su ejemplo arma el texto así: una línea que invita
+> («Elige un archivo o arrástralo aquí»), una línea con **formatos y tamaño máximo** («JPEG, PNG,
+> PDF y MP4, hasta 50 MB») y el botón **«Buscar archivo»**. Trae aparte el ícono por tipo de
+> archivo (en SUI, `sui-file-icon`). No dice cuándo usar cada tamaño. El resto es **propuesta,
+> falta aprobación**.
+>
+> Uso medido el 03-10-2026 en `master-pedidos/src/app`: **0 usos**. Hoy todo lo que se sube es
+> imagen y va con `sui-image-upload` (13) o con un `<input type="file">` a mano (3: `renewal-modal`,
+> `add-product` y la miniatura de `option-image`; ver el README de `sui-image-upload`).
+
+### Textos: `title`, `subtitle`, `browseLabel`
+
+| input | cuándo | fuente |
+|---|---|---|
+| `title` | Qué se sube, en la voz de la persona: «Sube tu carta en PDF», «Arrastra tu Excel aquí». Si se omite, sale «Arrastra y suelta el archivo aquí». | guía (línea que invita) |
+| `subtitle` | **Formatos y tamaño máximo**, siempre: «PDF o Excel, hasta 10 MB». El default «o haz clic para seleccionar» no dice nada que el área no diga. | guía (formatos y tamaño) |
+| `browseLabel` | El default ya es «Buscar archivo»; se pasa solo para otro texto («Elegir foto»). | guía (el botón) · el texto es propuesta |
+
+### `accept`, `multiple`, `maxSize`
+
+| input | cuándo | fuente |
+|---|---|---|
+| `accept` | Siempre, con lo mismo que dice el `subtitle`: `".pdf,.xlsx,.csv"`. Si el texto y el filtro no coinciden, la persona elige un archivo que se rechaza. | propuesta |
+| `multiple` | Varios archivos del mismo tipo (las boletas del mes). Con `multiple` cada archivo va en su `sui-file-upload-card`. | propuesta |
+| `maxSize` | Siempre, en **bytes** (`10 * 1024 * 1024`), y el mismo número en el `subtitle`. | propuesta |
+
+### `size`
+
+| valor | padding | cuándo | fuente |
+|---|---|---|---|
+| `small` | 24 | En mobile y dentro de un modal o una card. | propuesta |
+| `medium` (default) | 32 | En web, en una página o un modal ancho. | guía (es el único tamaño que muestra) |
+| `large` | 40 | Cuando subir el archivo es lo único de la pantalla (importar la carta). | propuesta |
+| `xlarge` | 48 | No usar: más aire no ayuda a soltar el archivo. | no usar |
+
+### Estados: `error`, `errorMessage`, `disabled`
+
+| input | cuándo | fuente |
+|---|---|---|
+| `error` + `errorMessage` | El archivo se subió y el servidor lo rechazó («El PDF está protegido con clave»). Lo de tamaño y tipo ya lo avisa solo. | propuesta |
+| `disabled` | Mientras se sube, o si ya se llegó al máximo de archivos. | propuesta |
+
+Usos de hoy que rompen la regla: **0** (no hay file-upload).
+
+## Tamaño en mobile y en web
+
+En mobile se toca con el dedo: lo que se toca mide **44 px o más**. Aquí **toda el área se toca**
+(abre el selector), así que pasa en cualquier tamaño; en el celular no se arrastra, por eso va
+más compacta. En pantallas de los dos, con el servicio de breakpoints de la app (`bp`, en
+`services/breakpoints.service.ts`).
+
+| uso | mobile | web | fuente |
+|---|---|---|---|
+| subir un documento en un formulario o modal | `small` | `medium` | propuesta |
+| subir es lo único de la pantalla | `medium` | `large` | propuesta |
+
+```html
+<sui-file-upload [size]="bp.isMobile() ? 'small' : 'medium'"
+                 title="Sube tu carta en PDF" subtitle="PDF, hasta 10 MB"
+                 accept=".pdf" [maxSize]="10 * 1024 * 1024" (filesSelected)="subir($event)" />
+```
+
+Llena el ancho del contenedor (antes 400 fijo; extensión SUI, 03-10-2026). El botón «Buscar
+archivo» mide 32 px (`xsmall`) en todos los tamaños: solo, en mobile **no
+llegaría**; pasa porque el área entera también abre el selector.
+
+## «No usar»: por qué no hoy y cuándo sí
+
+Nada se borra del DS. Lo marcado «no usar» no tiene caso en la app de hoy; si un flujo nuevo cae
+en la columna de la derecha, se usa (aprobado por el dueño, 03-10-2026).
+
+| qué | por qué no hoy | cuándo sí, en un flujo nuevo |
+|---|---|---|
+| todo el componente (0 usos) | todo lo que se sube hoy es una imagen | la carta del local en PDF o Excel para cargarla, la ficha RUC, los documentos del repartidor escaneados en PDF |
+| `multiple` | no hay subidas de varios archivos | las boletas del mes de un gasto, varias fotos de un reclamo |
+| `size="xlarge"` | más aire no ayuda | ninguno |
+| para imágenes | no muestra la vista previa ni pasa por el recortador | — |
+
+## API
+
+<!-- api:inicio -->
+<!-- generada: no editar a mano — `npm run docs` -->
+
+| input | tipo | default |
+|---|---|---|
+| `accept` | `string` | `''` |
+| `multiple` | `boolean` | `false` |
+| `maxSize` | `number` | `0` |
+| `title` | `string \| null` | `null` |
+| `subtitle` | `string \| null` | `null` |
+| `browseLabel` | `string` | `'Buscar archivo'` |
+| `disabled` | `boolean` | `false` |
+| `error` | `boolean` | `false` |
+| `errorMessage` | `string \| null` | `null` |
+| `size` | `'small' \| 'medium' \| 'large' \| 'xlarge'` | `'medium'` |
+
+| output | payload |
+|---|---|
+| `filesSelected` | `File[]` |
+| `errorEvent` | `string` |
+<!-- api:fin -->
+
+## Trampas
+
+- `browseLabel` dice «Buscar archivo» por defecto (antes «Browse File»).
+- **Llena el ancho del contenedor** desde el 03-10-2026 (antes medía 400 fijo y había que forzar
+  `style="width: 100%"`). Las pantallas que lo dejaban en 400 en un contenedor ancho ahora se
+  estiran; para un ancho fijo, se lo pone el consumer al host.
+- **`maxSize` va en bytes**, no en MB. `0` = sin límite.
+- **Emite solo los archivos válidos**: si de tres uno pesa de más, `filesSelected` trae dos y
+  `errorEvent` avisa del tercero (con el texto ya armado: «"x.pdf" supera el tamaño máximo (10.0 MB)»).
+- Sin `multiple`, aunque se suelten varios, **emite solo el primero**.
+- `accept` filtra al elegir **y** al soltar, por extensión (`.pdf`) o por tipo (`image/*`).
+- El error interno queda pegado hasta el próximo intento válido; `errorMessage` gana sobre él.
+- **No sube nada**: entrega los `File` y la subida (y el progreso en `sui-file-upload-card`) la
+  hace quien lo usa.
+- El atributo `title` del host se borra solo (no sale el tooltip gris del navegador).
+
+## Ejemplo
+
+```html
+<sui-file-upload title="Sube tu carta en PDF o Excel" subtitle="PDF o Excel, hasta 10 MB"
+                 browseLabel="Buscar archivo" accept=".pdf,.xlsx" [maxSize]="10 * 1024 * 1024"
+                 (filesSelected)="subirCarta($event)" (errorEvent)="avisar($event)" />
+```

package/docs/sui-file-upload-card/README.md

@@ -0,0 +1,129 @@
+---
+name: sui-file-upload-card
+selector: sui-file-upload-card
+resumen: La fila de un archivo que se está subiendo, con su progreso, listo o error para reintentar
+alternativas: [sui-file-upload (el área para elegir el archivo), sui-image-upload (una imagen: muestra la vista previa en vez de la fila), sui-file-icon (un archivo en una lista, sin subida)]
+---
+
+# sui-file-upload-card
+
+Story: [Molecules/Upload/File Upload Card](https://sui-design-system.web.app/?path=/docs/molecules-upload-file-upload-card--docs)
+
+## Cuándo usarlo / cuándo no
+
+**Úsalo** debajo de un `sui-file-upload`, una fila por archivo, para mostrar **cómo va la subida**:
+subiendo con su barra, listo, o falló con «Reintentar».
+
+**No lo uses** para:
+
+- Una imagen: `sui-image-upload` muestra la vista previa, que dice más que un nombre de archivo.
+- Una lista de archivos ya guardados (sin subida): `sui-file-icon` en una fila normal.
+- Un progreso que no es de un archivo: `sui-progress-bar`.
+
+## Qué variante usar
+
+> **La guía del DS no tiene página para este componente** (su página del file upload solo muestra
+> el área y el ícono por tipo). Todo es **propuesta, falta aprobación**.
+>
+> Uso medido el 03-10-2026 en `master-pedidos/src/app`: **0 usos**. Las subidas de hoy son de
+> imágenes y avisan con el `subtitle` del image-upload («Procesando…») o lo deshabilitan.
+
+### `state`
+
+| valor | cuándo | qué muestra | fuente |
+|---|---|---|---|
+| `in-progress` (default) | Mientras sube. Va con `progress`. | barra azul, ícono de carga, X para cancelar | propuesta |
+| `success` | Subió. | check verde, tacho para quitar | propuesta |
+| `error` | Falló. Va con `statusText` que diga por qué. | ícono rojo, «Reintentar», tacho | propuesta |
+
+### Textos y datos
+
+| input | cuándo | fuente |
+|---|---|---|
+| `file` | El nombre real del archivo (`'carta-octubre.pdf'`). La extensión da el ícono y el color. | propuesta |
+| `description` | **Siempre** se pasa: el default es un texto de ejemplo («0 KB de 120 KB»). Subiendo: «1,2 MB de 3,4 MB»; listo: «3,4 MB». | propuesta |
+| `progress` | 0–100, solo en `in-progress`. | propuesta |
+| `statusText` | Los defaults ya están en español («Subiendo…», «Completado», «Falló»); en error, mejor el motivo: «Se cortó la conexión». | propuesta |
+| `showStatus=false` | Solo en `success`, cuando el check sobra porque la lista ya dice «Archivos subidos». | propuesta |
+| `retryLabel` | El default ya es «Reintentar». | propuesta |
+
+Usos de hoy que rompen la regla: **0**.
+
+## Tamaño en mobile y en web
+
+**No tiene `size`.** Llena el ancho del contenedor (antes 400 fijo) y la X o el tacho de la derecha
+es un `sui-compact-button` `2xlarge` de **32 px** (Figma: 24), que con el aire de la tarjeta (16 de
+padding, 72 de alto mínimo) se toca bien con el dedo. «Reintentar» sigue siendo un link de 20 px de
+alto: en mobile conviene que la fila entera también reintente.
+
+| pieza | mobile | web | fuente |
+|---|---|---|---|
+| ancho | el del contenedor | el del contenedor | canon (aprobado por el dueño, 03-10-2026), extensión SUI |
+| X / tacho | 32 px | 32 px | canon (aprobado por el dueño, 03-10-2026), extensión SUI |
+| «Reintentar» | link de 20 px — **no llega** | link | medido |
+
+```html
+<sui-file-upload-card [file]="a.nombre" [state]="a.estado" [progress]="a.pct"
+                      [description]="a.peso" (actionClicked)="quitar(a)" (retryClicked)="reintentar(a)" />
+```
+
+## «No usar»: por qué no hoy y cuándo sí
+
+Nada se borra del DS. Lo marcado «no usar» no tiene caso en la app de hoy; si un flujo nuevo cae
+en la columna de la derecha, se usa (aprobado por el dueño, 03-10-2026).
+
+| qué | por qué no hoy | cuándo sí, en un flujo nuevo |
+|---|---|---|
+| todo el componente (0 usos) | todo lo que se sube es una imagen y se ve con su vista previa | junto a `sui-file-upload`: la carta en PDF, varias boletas de un gasto, documentos del repartidor |
+| para imágenes | la vista previa dice más que el nombre del archivo | — |
+
+## API
+
+<!-- api:inicio -->
+<!-- generada: no editar a mano — `npm run docs` -->
+
+| input | tipo | default |
+|---|---|---|
+| `file` | `SuiFileUploadCardFile \| string` | `'file.pdf'` |
+| `description` | `string` | `'0 KB de 120 KB'` |
+| `state` | `'in-progress' \| 'success' \| 'error'` | `'in-progress'` |
+| `progress` | `number` | `10` |
+| `statusText` | `string \| null` | `null` |
+| `showStatus` | `boolean` | `true` |
+| `cancelLabel` | `string` | `'Cancelar subida'` |
+| `removeLabel` | `string` | `'Quitar archivo'` |
+| `progressLabel` | `string` | `'Progreso de la subida'` |
+| `retryLabel` | `string` | `'Reintentar'` |
+
+| output | payload |
+|---|---|
+| `actionClicked` | `void` |
+| `retryClicked` | `void` |
+<!-- api:fin -->
+
+```ts
+interface SuiFileUploadCardFile { filename: string; extension?: string; }
+```
+
+## Trampas
+
+- Los textos de fábrica están en español desde el 03-10-2026: «0 KB de 120 KB», «Subiendo…»,
+  «Completado», «Falló», «Reintentar», y para el lector de pantalla «Cancelar subida», «Quitar
+  archivo» y «Progreso de la subida» (estos tres, con `cancelLabel`, `removeLabel` y
+  `progressLabel`).
+- Llena el ancho del contenedor, igual que `sui-file-upload` (antes 400 fijo).
+- **`progress` arranca en 10**, no en 0.
+- **`actionClicked` significa dos cosas**: cancelar mientras sube y quitar cuando terminó. Quien lo
+  usa mira `state` para saber cuál.
+- La barra de progreso es azul, no naranja.
+- No sube nada: refleja el estado que le pasan.
+
+## Ejemplo
+
+```html
+<sui-file-upload-card file="carta-octubre.pdf" state="in-progress" [progress]="45"
+                      description="1,2 MB de 2,6 MB" statusText="Subiendo…" />
+<sui-file-upload-card file="carta-octubre.pdf" state="error" description="2,6 MB"
+                      statusText="Se cortó la conexión" retryLabel="Reintentar"
+                      (retryClicked)="reintentar()" (actionClicked)="quitar()" />
+```

package/docs/sui-flag/README.md

@@ -0,0 +1,99 @@
+---
+name: sui-flag
+selector: sui-flag
+resumen: La bandera circular de un país
+alternativas: [sui-emoji (un emoji con emoción), sui-icon (un ícono funcional)]
+---
+
+# sui-flag
+
+Story: [Atoms/Flag](https://sui-design-system.web.app/?path=/docs/atoms-flag--docs)
+
+## Cuándo usarlo / cuándo no
+
+**Úsalo** cuando el **país** es un dato que la persona elige o tiene que reconocer: el prefijo
+de un teléfono, la nacionalidad, un selector de país.
+
+**No lo uses** para decorar: en una app que funciona solo en Perú, una bandera sola no le dice
+nada a nadie.
+
+## Qué variante usar
+
+> **La guía del DS no tiene este componente.** Todo es **propuesta, falta aprobación**.
+>
+> Uso medido el 03-10-2026 en `master-pedidos/src/app`: **0 usos directos**. Lo usan por dentro
+> `sui-select`, `sui-compact-select`, `sui-inline-select`, `sui-dropdown-item`, `sui-tag` y
+> `sui-command-menu-item`.
+
+### `size`
+
+| valor | px | cuándo | fuente |
+|---|---|---|---|
+| `xs` | 16 | Dentro de un select o un tag (así lo usa el DS). | propuesta |
+| `sm` | 20 | El prefijo de un teléfono. | propuesta |
+| `md` (default) | 24 | Fila de una lista. | propuesta |
+| `lg` | 32 | Dentro de una card. | propuesta |
+| `xl` | 48 | No usar hoy. | propuesta |
+| `full` | 100 % | Llena su caja (la caja manda). | propuesta |
+
+### `name` y `ariaLabel`
+
+| input | cuándo | fuente |
+|---|---|---|
+| `name` | El slug en inglés y en kebab-case: `peru`, `venezuela`, `united-states`. Son 262. | propuesta |
+| `ariaLabel` | El nombre del país en español, si no está escrito al lado. Sin él, es decorativa. | propuesta |
+
+Usos de hoy que rompen la regla: **0**.
+
+## 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 |
+|---|---|---|
+| prefijo de un teléfono | `sm` (20) | `xs` (16) |
+| fila de una lista | `md` (24) | `sm` (20) |
+
+```html
+<sui-flag name="peru" [size]="bp.isMobile() ? 'sm' : 'xs'" ariaLabel="Perú" />
+```
+
+La bandera no se toca: el área táctil es la del select que la contiene.
+
+## «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 directos) | la app es solo Perú | la nacionalidad del repartidor que se registra con carné de extranjería, o el prefijo del teléfono si se abre a otro país |
+| `size` `xl` | sin caso | una pantalla de elegir país |
+
+## API
+
+<!-- api:inicio -->
+<!-- generada: no editar a mano — `npm run docs` -->
+
+| input | tipo | default |
+|---|---|---|
+| `name` | `SuiFlagName` | — (requerido) |
+| `size` | `'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| 'full'` | `'md'` |
+| `ariaLabel` | `string \| null` | `null` |
+
+Outputs: ninguno.
+<!-- api:fin -->
+
+## Trampas
+
+- **Los SVG no vienen en el paquete npm.** Se piden a `assets/flags/<pais>.svg` (ruta relativa):
+  la app tiene que tener la carpeta copiada en `src/assets/flags/` (hoy la tiene, 262 archivos).
+- **Ya es circular**: el círculo está dentro del SVG. No le pongas `border-radius`.
+- **El nombre va en inglés** y con las grafías del set (`slovania`, `mauritus`, `taijikistan`):
+  copia el slug de `SUI_FLAG_NAMES`, no lo escribas de memoria.
+
+## Ejemplo
+
+```html
+<sui-flag name="peru" size="sm" ariaLabel="Perú" />
+```

package/docs/sui-form-hint/README.md

@@ -0,0 +1,124 @@
+---
+name: sui-form-hint
+selector: sui-form-hint
+resumen: Una línea de ayuda o de error debajo de un campo o de un grupo de controles
+alternativas: [el hint propio de sui-input / sui-select / sui-textarea (campo de texto), sui-alert (un aviso de la pantalla o algo que salió bien), sui-tooltip (ayuda escondida tras un toque), sui-form-label (el rótulo de arriba)]
+---
+
+# sui-form-hint
+
+Story: [Atoms/Form/Form Hint](https://sui-design-system.web.app/?path=/docs/atoms-form-form-hint--docs)
+
+## Cuándo usarlo / cuándo no
+
+**Úsalo** para una línea debajo de un campo o grupo **que no trae la suya**: cómo se llena
+(«Como aparece en tu DNI.»), un contador («120/200»), o qué falló («Selecciona un método de
+pago»). Va pegado al control que explica.
+
+**No lo uses** para:
+
+- **Debajo de un `sui-input`, `sui-select` o `sui-textarea`**: tienen `[hint]` y `[errorMessage]`.
+- Algo que salió bien («Link disponible»): `sui-alert` `success`. El hint no tiene variante positiva.
+- Un párrafo o algo con un link: `sui-alert`.
+- El subtítulo de una sección o de una card: eso es texto de la sección (`sui-page-header`,
+  `paragraph-xs` en `--sui-text-sub-600`), no ayuda de un campo.
+
+Regla corta: **ayuda o error de un control sin hint propio → form-hint · campo de texto → su `[hint]` · éxito o párrafo → alert.**
+
+## Qué variante usar
+
+> **La guía del DS lo define como información o guía «debajo de inputs, selects y textareas»** y
+> trae tres estados: normal, deshabilitado y con error (`hasError`). El ícono es una pieza aparte
+> y opcional. No da reglas de largo ni de copy.
+>
+> Uso medido el 03-10-2026 en `master-pedidos/src/app` (misma exclusión que `sui-badge`):
+> **36 usos en 18 archivos**: 11 `error`, 25 `neutral` (24 por default y 1 explícito), 0
+> `disabled`; 2 con `icon` propio (`information-line`). Hay además **al menos 14 hints escritos a
+> mano** con clases propias (`__form-hint`, `__hint`).
+
+### `variant`
+
+| variant | cuándo | fuente |
+|---|---|---|
+| `neutral` (default) | Ayuda: cómo se llena, formato, contador. Sin ícono por defecto. | según la guía del DS |
+| `error` | Qué falló y cómo arreglarlo, después de intentar seguir. Trae ícono. | según la guía del DS (`hasError`) |
+| `disabled` | El campo de arriba está deshabilitado; el hint se apaga con él. | según la guía del DS |
+
+### `message` e `icon`
+
+| qué | regla | fuente |
+|---|---|---|
+| `message` | Hasta 8 palabras (mediana 6). Si no cabe, es un `sui-alert`. Con punto final si es una oración. | canon (`docs/CANON-SUI.md` §5.4) |
+| `icon` sin pasar | El de la variante (ninguno en `neutral`, info en `error` y `disabled`). | según la guía del DS (ícono opcional); default de SUI |
+| `icon="…"` en `neutral` | Solo cuando la ayuda es una advertencia que conviene notar («No reconocimos el distrito…»). | propuesta, falta aprobación (2 usos hoy) |
+| `[icon]="null"` | Quita el ícono también en `error`. No usar: el error necesita algo más que el color. | propuesta, falta aprobación |
+
+**Usos de hoy que rompen las reglas:**
+
+- **8 debajo de un campo que ya tiene `[hint]` / `[errorMessage]` → pasar al campo:**
+  `pages/driver-onboarding/step-info/step-info.html:50` («Como aparece en tu DNI.»), `:71`, `:92`;
+  `pages/driver-onboarding/step-vehicle/step-vehicle.html:56`, `:69`; y los errores bajo
+  `sui-select` de `pages/customer-onboarding/step-address/step-address.html:82`, `:100`, `:119`.
+  Bien usado, en cambio, `step-vehicle.html:43`: el error de un grupo de `sui-radio-card`.
+- **4 como subtítulo de una sección, no de un campo:** `pages/schedule/schedule.html:17`
+  («Pausa tu sucursal…», bajo el título de la card), `:61`, `pages/drivers/drivers.html:29`,
+  `pages/driver/driver-schedule/driver-schedule.html:94`.
+- **12 de más de 8 palabras** (4 son los subtítulos de arriba) → acortar, o `sui-alert` si de
+  verdad hace falta todo: `pages/super-admin/master-users/master-users.html:66` (26 palabras),
+  `pages/orders/orders.html:587` (23), `pages/driver/driver-order-detail/driver-order-detail.html:834` (23),
+  `pages/envios/envios.html:399` (15).
+- **Al menos 14 hints a mano** con clases propias. Ejemplos: `pages/discounts/discounts.html:196`
+  (`discounts__form-hint`), `components/settings-panel/settings-panel.html:93`,
+  `pages/promociones/promociones.html:180`.
+
+## Tamaño en mobile y en web
+
+| uso | mobile | web |
+|---|---|---|
+| ayuda o error | 12 px (no hay `size`) | 12 px |
+
+Es texto que no se toca: el mismo tamaño en las dos plataformas está bien.
+
+## «No usar»: por qué no hoy y cuándo sí
+
+| qué | por qué no hoy | cuándo sí, en un flujo nuevo |
+|---|---|---|
+| `variant="disabled"` (0 usos) | ningún grupo con form-hint se deshabilita | un grupo de opciones que se apaga según otra elección («Horario propio» apagado) |
+| `[icon]="null"` en `error` | el error se distingue por color y por ícono; sin ícono queda solo el rojo | nunca en `error`; en `neutral` ya viene sin ícono |
+
+## API
+
+<!-- api:inicio -->
+<!-- generada: no editar a mano — `npm run docs` -->
+
+| input | tipo | default |
+|---|---|---|
+| `message` | `string \| null` | `null` |
+| `variant` | `'neutral' \| 'error' \| 'disabled'` | `'neutral'` |
+| `icon` | `string \| null \| undefined` | `undefined` |
+
+Outputs: ninguno.
+<!-- api:fin -->
+
+## Trampas
+
+- **`icon` tiene tres estados**: sin pasar = el de la variante; `null` = sin ícono; `"mail-line"` =
+  ese. Un string vacío no está contemplado.
+- **`neutral` no trae ícono.** Si quieres uno, pásalo.
+- **No hay `success` ni `warning`** (se quitaron el 22-07-2026) ni `size` (era un no-op). Si las ves
+  en un ejemplo, es una versión vieja.
+- **Sin `message` no ocupa lugar**: no hace falta envolverlo en `@if`.
+- En `error` el ícono es `information-fill` en rojo, no `error-warning-line`.
+- Letra fija de 12/16 px; el ícono mide 16 px y se alinea con la primera línea.
+
+## Ejemplo
+
+```html
+<!-- Grupo sin hint propio -->
+<sui-form-label label="Método de pago" [required]="true" />
+<sui-radio-group [(ngModel)]="metodo">…</sui-radio-group>
+<sui-form-hint variant="error" [message]="intento() && !metodo ? 'Selecciona un método de pago' : null" />
+
+<!-- Contador -->
+<sui-form-hint [message]="comentario().length + '/200'" />
+```

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

@@ -0,0 +1,148 @@
+---
+name: sui-form-label
+selector: sui-form-label
+resumen: Rótulo de un campo o de un grupo de controles que no traen el suyo (asterisco, opcional, ayuda y link)
+alternativas: [el label propio de sui-input / sui-select / sui-textarea (campo de texto), sui-checkbox-label / sui-radio-label / sui-switch-label (un control con su texto), sui-page-header o sui-content-label (título de sección), sui-form-hint (la ayuda debajo)]
+---
+
+# sui-form-label
+
+Story: [Atoms/Form/Form Label](https://sui-design-system.web.app/?path=/docs/atoms-form-form-label--docs)
+
+## Cuándo usarlo / cuándo no
+
+**Úsalo** para titular un campo **que no tiene label propio**: un grupo de `sui-radio-card`
+(«¿Cómo quieres recibir tu pedido?»), un bloque de casillas («Permisos»), un `sui-image-upload`
+(«Logo»), el punto en el mapa («Tu punto en el mapa»), una fila de chips.
+
+**No lo uses** para:
+
+- **Encima de un `sui-input`, `sui-select` o `sui-textarea`**: esos ya dibujan su label, asterisco,
+  sublabel y tooltip con `[label]`, `[required]`, `[sublabel]`, `[tooltip]`. Ponerle uno afuera
+  duplica la pieza y pierde el `for`.
+- El texto de un solo checkbox, radio o switch: `sui-checkbox-label`, `sui-radio-label`,
+  `sui-switch-label`.
+- Un título de sección o de card («Datos personales»): `sui-page-header`, `sui-content-label` o
+  un heading.
+- Una explicación larga: va debajo, en `sui-form-hint`.
+
+Regla corta: **campo de texto → su propio `[label]` · grupo o control sin label → form-label · sección → heading.**
+
+## Qué variante usar
+
+> **La guía del DS dice que el label «da contexto a lo que la persona ingresa»** y trae tres
+> piezas: el label, el asterisco (campo obligatorio) y el sub (texto complementario). Su ejemplo
+> es «Last Name*(Optional)»: el opcional va **entre paréntesis** en el sub. Tiene un solo tamaño y
+> un estado deshabilitado. Info (tooltip) y el link de la derecha vienen del Figma del componente.
+>
+> Uso medido el 03-10-2026 en `master-pedidos/src/app` (misma exclusión que `sui-badge`):
+> **37 usos en 13 archivos**: 13 con `required`, 5 con `sublabel="Opcional"`, 2 con `link`
+> («Cambiar»), 0 con `tooltip`, 0 con `disabled`; 6 con `size="medium"` explícito, el resto en el
+> default (`medium`).
+
+### Las piezas
+
+| prop | cuándo | fuente |
+|---|---|---|
+| `label` | Siempre. Una a tres palabras, sentence case, sin dos puntos ni punto final. | según la guía del DS (pieza); largo y forma según `docs/CANON-SUI.md` §5.4 |
+| `required` | Campo obligatorio: asterisco **rojo** (`state-error-base`). | según la guía del DS (asterisco = obligatorio); el color es canon (`docs/CANON-SUI.md` §4: excepción documentada) |
+| `sublabel` | «(Opcional)» en un formulario donde casi todo es obligatorio. Nunca el «opcional» dentro del `label`. | según la guía del DS (ejemplo «(Optional)») |
+| `tooltip` | Ayuda corta que no cabe en la pantalla y no hace falta para llenar el campo. Si hace falta, va visible en `sui-form-hint`. | propuesta, falta aprobación |
+| `link` | Una acción sobre el campo, a la derecha: «Cambiar» (el distrito). | propuesta (ya es práctica de la app: 2 usos) |
+| `disabled` | El campo de abajo está deshabilitado. | según la guía del DS |
+| `for` | Siempre que el control de abajo tenga `id`. | propuesta, falta aprobación |
+
+### `size`
+
+| size | cuándo | fuente |
+|---|---|---|
+| `medium` (default) | Lo normal. | según la guía del DS (único tamaño) |
+| `small` | Es **idéntico** a `medium` (mismo CSS). No aporta. | — |
+| `xsmall` | Junto a un campo `xsmall` en una tabla o filtro denso (12 px). | propuesta, falta aprobación |
+
+La regla de controles grandes del dueño (28-09-2026) no aplica aquí: el `size` del label es
+tipografía, no área táctil.
+
+**Usos de hoy que rompen las reglas:**
+
+- **8 encima de un campo que ya trae su label → pasar a `[label]` del campo:**
+  `pages/driver-onboarding/step-info/step-info.html:37` («Nombre completo»), `:56`, `:77`;
+  `pages/customer-onboarding/step-address/step-address.html:70` («Departamento», sobre
+  `sui-select`), `:87`, `:106`; `pages/driver-onboarding/step-vehicle/step-vehicle.html:49`, `:62`.
+  En esos mismos campos el `sui-form-hint` de abajo también es el `[hint]` del input.
+- **5 con `sublabel="Opcional"` sin paréntesis** → se lee «ImagenOpcional» (1 px de separación).
+  Pasar a «(Opcional)»: `components/add-product-modal/add-product-modal.html:42`, `:195`;
+  `pages/promociones/promociones.html:200`; `pages/business-onboarding/step-info/step-info.html:41`, `:54`.
+- **2 con «(opcional)» dentro del label → `sublabel`:** `pages/driver-onboarding/step-vehicle/step-vehicle.html:49`
+  («Placa del vehículo (opcional)») y `:62`.
+- **2 como título de sección → heading o `sui-content-label`:** `pages/customer/checkout/checkout.html:187`
+  («Datos personales») y `:35` («Recoges en el local»).
+- **5 con el número de paso dentro del label** («1. Imagen del banner»…«5. Comprobante de pago»):
+  `pages/promociones/promociones.html:179`, `:200`, `:210`, `:230`, `:264`. Los pasos van en un
+  `sui-stepper` o en el título de la sección; el label queda «Imagen del banner». Además `:200`
+  («2. Descripción») está encima de un `sui-textarea`, que ya trae su `[label]`.
+- **1 en Title Case:** `pages/drivers/drivers.html:28` («Modo de Asignación» → «Modo de asignación»).
+- **3 con un switch armado a mano al lado → `sui-switch-label`:** `pages/discounts/discounts.html:195`,
+  `:299`; `components/add-product-modal/add-product-modal.html:195`.
+
+## Tamaño en mobile y en web
+
+| uso | mobile | web |
+|---|---|---|
+| rótulo de un grupo o control | `medium` (14 px) | `medium` (14 px) |
+| junto a un campo `xsmall` en una tabla o filtro denso | no aplica | `xsmall` (12 px) |
+
+No necesita `bp`: es texto, no se toca. Lo único tocable es el `link` («Cambiar»), un
+`sui-link-button` de 12 px **sin tamaño para mobile**: su área táctil es la del texto. Si en
+mobile esa acción importa, conviene un botón aparte.
+
+## «No usar»: por qué no hoy y cuándo sí
+
+| qué | por qué no hoy | cuándo sí, en un flujo nuevo |
+|---|---|---|
+| `size="small"` | dibuja igual que `medium` | nunca, hasta que el DS lo diferencie |
+| `tooltip` (0 usos) | toda la ayuda que hoy existe hace falta para llenar el campo, y va visible | un dato de contexto que la mayoría no necesita («¿Por qué pedimos tu DNI?») |
+| `disabled` (0 usos) | ningún grupo con form-label se deshabilita | un grupo de opciones que depende de otra elección previa |
+
+## API
+
+<!-- api:inicio -->
+<!-- generada: no editar a mano — `npm run docs` -->
+
+| input | tipo | default |
+|---|---|---|
+| `label` | `string` | — (requerido) |
+| `sublabel` | `string \| null` | `null` |
+| `required` | `boolean` | `false` |
+| `tooltip` | `string \| null` | `null` |
+| `link` | `SuiLinkConfig \| string \| null` | `null` |
+| `size` | `'xsmall' \| 'small' \| 'medium'` | `'medium'` |
+| `disabled` | `boolean` | `false` |
+| `for` | `string \| null` | `null` |
+
+| output | payload |
+|---|---|
+| `linkClick` | `MouseEvent` |
+<!-- api:fin -->
+
+## Trampas
+
+- **`small` y `medium` se ven igual** (los dos 14 px). Solo `xsmall` cambia (12 px), y solo la letra.
+- **El sublabel no pone paréntesis**: escribe «(Opcional)» con paréntesis o queda pegado al label
+  (el espacio entre piezas es de 1 px).
+- **El asterisco es rojo**, no el naranja de marca (la guía lo pinta con el primario).
+- Los ejes del Figma se llaman distinto aquí: «Info» es `tooltip` y «Button» es `link`.
+- `link` como string emite `linkClick`; como objeto con `href` es un `<a>` real (con `_blank` agrega
+  `rel="noopener noreferrer"`). Se pinta en gris, empujado a la derecha.
+- El ícono de info es gris muy claro a propósito (baja jerarquía); se oscurece al pasar el mouse.
+
+## Ejemplo
+
+```html
+<!-- Grupo de opciones sin label propio -->
+<sui-form-label label="Método de pago" [required]="true" />
+<sui-radio-group [(ngModel)]="metodo">…</sui-radio-group>
+
+<!-- Campo de texto: el label va en el propio input, no en un form-label -->
+<sui-input label="Placa del vehículo" sublabel="(Opcional)" [(value)]="placa" />
+```