@ajuarezso/sui-design-system 0.19.0 → 0.20.0

package/docs/sui-fancy-button/README.md

@@ -0,0 +1,148 @@
+---
+name: sui-fancy-button
+selector: sui-fancy-button
+resumen: Botón con brillo y degradé para el CTA de una landing o campaña
+alternativas: [sui-button (toda acción dentro de la app), sui-app-store-badge (descargar la app desde una landing)]
+---
+
+# sui-fancy-button
+
+Story: [Atoms/Button/Fancy Button](https://sui-design-system.web.app/?path=/docs/atoms-button-fancy-button--docs)
+
+## Cuándo usarlo / cuándo no
+
+**Hoy no se usa** (0 usos en la app). Es el mismo botón que `sui-button` con un acabado de
+marketing: brillo arriba, borde interior claro y un anillo del color del botón.
+
+**Cuándo sí, en un flujo nuevo**: el CTA principal de una landing (`/empresas`, `/repartidores`),
+«Mejorar plan» o una campaña puntual. Uno por pantalla.
+
+**No lo uses** para:
+
+- **Cualquier acción dentro de la app**: `sui-button`. Al lado de botones normales, el fancy
+  compite con todo y rompe la jerarquía.
+- **Una acción destructiva**: `sui-button` `color="error"`.
+- **Descargar la app**: `sui-app-store-badge`.
+
+## Qué variante usar
+
+> **La guía del DS no dice cuándo usar cada tipo.** Su página lo presenta como «botones normales
+> con una apariencia vistosa» y muestra los cuatro tipos, los tres tamaños, los íconos y el
+> deshabilitado, sin do/don't. Todo el componente está en **«no usar» (canon, aprobado por el
+> dueño, 03-10-2026)**; la tabla dice dónde iría cada tipo si aparece el caso.
+>
+> Uso medido el 03-10-2026 en `master-pedidos/src/app`: **0** fancy-buttons, sin contar
+> prototipos ni vitrinas.
+
+### Lo que sí dice la guía del DS
+
+- **Para qué es**: un botón normal con un acabado más vistoso.
+- **Default**: `neutral` (negro) en la guía; **`primary` en SUI**.
+- **Tamaños**: `medium` (40), `small` (36) y `xsmall` (32). No hay más grandes.
+- **Hover**: el brillo se aclara, no se oscurece. `basic` pasa a fondo gris plano.
+- **Deshabilitado**: fondo gris plano, sin brillo, sin anillo ni sombra, igual en los cuatro tipos.
+
+### `type` (el relleno)
+
+| type | dónde iría, en un flujo nuevo | ejemplo de copy | fuente |
+|---|---|---|---|
+| `primary` (default SUI) | El CTA principal de una landing o una campaña. Uno por pantalla. | «Empieza gratis», «Mejorar plan» | no usar hoy · cuándo sí: canon (aprobado por el dueño, 03-10-2026) |
+| `neutral` (default de la guía) | El CTA de una landing sobre una sección clara donde el naranja ya se usó arriba. | «Ver planes» | no usar hoy (en la app va `sui-button`) · cuándo sí: propuesta |
+| `basic` | El secundario al lado de un fancy `primary` en la misma landing. | «Saber más» | no usar hoy (en la app va `sui-button`) · cuándo sí: propuesta |
+| `destructive` | Ninguno a la vista: una acción destructiva nunca es marketing. | — | no usar (en la app va `sui-button` `error`) · canon (aprobado por el dueño, 03-10-2026) |
+
+### `size`
+
+| size | cuándo | fuente |
+|---|---|---|
+| `medium` (40, default) | El CTA de la landing en desktop. | escala y default según la guía del DS · cuándo: propuesta |
+| `small` (36) | Un CTA dentro de una card de la landing (la card de un plan). | escala según la guía del DS · cuándo: propuesta |
+| `xsmall` (32) | Sin caso: en una landing el CTA nunca es tan chico. | escala según la guía del DS · cuándo: propuesta |
+
+### Íconos y `disabled`
+
+| prop | cuándo | fuente |
+|---|---|---|
+| `rightIcon` (`arrow-right-line`) | El CTA lleva a otra página: «Empieza gratis →». | propuesta |
+| `leftIcon` | El ícono dice la acción (descargar, WhatsApp). | propuesta |
+| `disabled` | Casi nunca: un CTA de marketing no se deshabilita, se esconde. | cómo se ve: según la guía del DS · cuándo: propuesta |
+| `href` | El CTA navega (lo normal en una landing): pinta un `<a>`; `rel` ya viene en `'noopener noreferrer'`. | propuesta |
+
+## 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):
+`[size]="bp.isMobile() ? 'large' : 'small'"`, 27 usos hoy en `master-pedidos` (16 `large`/`small`,
+9 `large`/`medium`, 2 `medium`/`xsmall`). Regla del dueño, 03-10-2026.
+
+| uso | mobile | web | fuente |
+|---|---|---|---|
+| CTA principal de una landing | no usar fancy: `sui-button` `large` (48) | `medium` (40) | propuesta |
+| CTA dentro de la card de un plan | no usar fancy: `sui-button` `large` | `small` (36) | propuesta |
+
+```html
+@if (bp.isMobile()) {
+  <sui-button size="large">Empieza gratis</sui-button>
+} @else {
+  <sui-fancy-button type="primary" size="medium">Empieza gratis</sui-fancy-button>
+}
+```
+
+**El fancy no tiene un tamaño táctil**: el más grande mide 40, por debajo de 44. En mobile el CTA
+va con `sui-button` `large`. Hoy no hay usos (todo el componente está en «no usar»).
+
+## «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 |
+|---|---|---|
+| `sui-fancy-button` (los 4 tipos) | Es estilo de marketing (brillo, degradé); en la app compite con todo | el CTA principal de una landing (`/empresas`, `/repartidores`), «Mejorar plan» o una campaña |
+| `type="destructive"` | Una acción destructiva va con `sui-button` `error` | no se ve un caso: una destructiva no es marketing |
+
+## API
+
+<!-- api:inicio -->
+<!-- generada: no editar a mano — `npm run docs` -->
+
+| input | tipo | default |
+|---|---|---|
+| `type` | `'primary' \| 'neutral' \| 'basic' \| 'destructive'` | `'primary'` |
+| `size` | `'medium' \| 'small' \| 'xsmall'` | `'medium'` |
+| `leftIcon` | `string \| null` | `null` |
+| `rightIcon` | `string \| null` | `null` |
+| `disabled` | `boolean` | `false` |
+| `href` | `string \| null` | `null` |
+| `target` | `string \| null` | `null` |
+| `rel` | `string \| null` | `'noopener noreferrer'` |
+| `htmlType` | `'button' \| 'submit' \| 'reset'` | `'button'` |
+| `ariaLabel` | `string \| null` | `null` |
+
+| output | payload |
+|---|---|
+| `clicked` | `MouseEvent` |
+<!-- api:fin -->
+
+El clic se escucha con `(clicked)`. Slots: `<ng-content>` (el texto).
+
+## Trampas
+
+- **`type` es el relleno**, no el `type` HTML: ese se llama **`htmlType`**. `type="submit"` no
+  compila (no es un tipo válido) y no hace un submit.
+- **El radio es 10 px, no pill.** Al lado de un `sui-button` (pill en SUI) se ven de dos familias.
+- **No hay `large` ni `xlarge`**: el más grande mide 40. En mobile, donde el CTA de la app es de
+  48, un fancy queda más bajo.
+- **El default es `primary`**; en la guía es `neutral`.
+- El anillo del `neutral` es un hex crudo (`#242628`): no hay token para ese gris.
+- Ya trae el arreglo de iOS para el `:active` pegado: no lo agregues.
+
+## Ejemplo
+
+```html
+<!-- Solo en una landing: el CTA principal -->
+<sui-fancy-button type="primary" rightIcon="arrow-right-line" href="/auth/empresa/registro">
+  Empieza gratis
+</sui-fancy-button>
+```

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

@@ -0,0 +1,103 @@
+---
+name: sui-file-icon
+selector: sui-file-icon
+resumen: El ícono de un archivo con su extensión (PDF, XLSX, JPG…) en el color de su tipo
+alternativas: [sui-file-upload-card (el archivo que se está subiendo, con progreso), sui-icon (un ícono genérico de documento)]
+---
+
+# sui-file-icon
+
+Story: [Atoms/Icon/File Icon](https://sui-design-system.web.app/?path=/docs/atoms-icon-file-icon--docs)
+
+## Cuándo usarlo / cuándo no
+
+**Úsalo** en una **lista de archivos**: comprobantes, documentos del repartidor, un reporte para
+descargar. La etiqueta con la extensión le dice a la persona qué va a abrir.
+
+**No lo uses** para:
+
+- Un archivo que se está subiendo: `sui-file-upload-card` (ya lo trae adentro).
+- Una foto: si se puede ver, se muestra la miniatura.
+- Un ícono de «documento» en general, sin archivo detrás: `sui-icon`.
+
+## Qué variante usar
+
+> **La guía del DS no tiene página para este componente.** Todo es **propuesta, falta
+> aprobación**.
+>
+> Uso medido el 03-10-2026 en `master-pedidos/src/app`: **0 usos directos**. Lo usa por dentro
+> `sui-file-upload-card`.
+
+### `filename`, `extension`, `color`
+
+| input | cuándo | fuente |
+|---|---|---|
+| `filename` | Siempre que haya nombre: saca la extensión y el color solo (`comprobante.pdf` → PDF en rojo). | propuesta |
+| `extension` | Solo si el nombre no la trae (un archivo de Storage sin extensión). | propuesta |
+| `color` | No usar: el color dice el tipo y forzarlo miente (un CSV en rojo parece PDF). | propuesta |
+
+Colores automáticos: PDF rojo · Word y texto azul · Excel y CSV verde · PowerPoint naranja ·
+imágenes rosa · video morado · audio celeste · comprimidos amarillo · el resto gris.
+
+### `size`
+
+| valor | px | cuándo | fuente |
+|---|---|---|---|
+| `medium` (default) | 40 | Lista de documentos. | propuesta |
+| `xsmall` | 32 | Filas densas, tablas. | 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 |
+|---|---|---|
+| fila de una lista | `medium` (40) | `xsmall` (32) |
+
+```html
+<sui-file-icon [filename]="doc.nombre" [size]="bp.isMobile() ? 'medium' : 'xsmall'" />
+```
+
+El ícono no se toca: si la fila abre el archivo, la fila da los 44 px. `medium` es el tamaño más
+grande que tiene.
+
+## «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) | no hay listas de archivos | los documentos del repartidor (DNI, licencia, SOAT) o un reporte para descargar en CSV |
+| `color` | el color dice el tipo; forzarlo miente | ninguno: si la extensión no se reconoce, sale gris y está bien |
+
+## API
+
+<!-- api:inicio -->
+<!-- generada: no editar a mano — `npm run docs` -->
+
+| input | tipo | default |
+|---|---|---|
+| `filename` | `string` | `''` |
+| `extension` | `string` | `''` |
+| `size` | `'xsmall' \| 'medium'` | `'medium'` |
+| `color` | `'red' \| 'orange' \| 'yellow' \| 'green' \| 'teal' \| 'blue' \| 'purple' \| 'pink' \| 'gray' \| ''` | `''` |
+
+Outputs: ninguno.
+<!-- api:fin -->
+
+## Trampas
+
+- **La extensión se corta a 4 letras** y va en mayúsculas: `.jpeg` → `JPEG`, `.numbers` → `NUMB`.
+- **`extension` gana sobre `filename`.**
+- **El nombre para el lector de pantalla está en inglés** («File: PDF») y no se puede cambiar.
+- `size` es `xsmall` o `medium`: no hay `small` ni `large`.
+
+## Ejemplo
+
+```html
+<sui-file-icon filename="comprobante-yape.pdf" />
+<sui-file-icon filename="ventas-setiembre.csv" size="xsmall" />
+```

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" />
+```