@ajuarezso/sui-stencil 0.0.0-stage → 0.1.0

package/docs/sui-filter-panel-header/README.md

@@ -0,0 +1,237 @@
+---
+name: sui-filter-panel-header
+selector: sui-filter-panel-header
+resumen: La cabecera del panel, con un link «Limpiar» opcional
+alternativas: [sui-segmented-control (2 a 4 vistas que se aplican al instante), sui-compact-select (un filtro suelto), sui-tab-chips (filtros rápidos con chips), sui-activity-filter (filtro del feed de actividad), sui-modal-sheet (el panel de filtros en mobile)]
+---
+
+# sui-filter-panel-header
+
+<!-- generado por scripts/gen-docs.mjs — no editar a mano; `npm run docs` -->
+
+> **De dónde sale este doc.** El criterio es el de la familia `sui-filter` del SUI Angular (una sola página para todas sus piezas; aquí no hay un `sui-filter`); la API es la de `sui-filter-panel-header`, leída del código. Los ejemplos se pasaron de Angular de forma mecánica: lo literal va como
+> atributo (`only-icon`, `size="large"`), lo dinámico entre llaves (`size={expr}` → `el.size = expr`)
+> y los eventos como `onValueChange={…}` → `el.addEventListener('valueChange', …)`. `@if`, `@for` y
+> `<ng-template>` quedan como en Angular: se leen como pseudocódigo.
+
+Story: [Organisms/Filter Bar](https://sui-design-system.web.app/?path=/docs/organisms-filter-bar--docs)
+
+Son **cuatro componentes** en una carpeta, sin uno llamado `sui-filter`:
+
+- `sui-filter-bar`: la **barra horizontal** arriba de una tabla. Es solo layout: un lado
+  izquierdo (`slot="start"`) y uno derecho (`slot="end"`); los controles se proyectan.
+- `sui-filter-item`: una **fila** del panel vertical (una categoría de filtro: «Estado», «Local»).
+- `sui-filter-panel-header`: la **cabecera** del panel, con un link «Limpiar» opcional.
+- `sui-filter-panel-footer`: el **pie** del panel, con «Limpiar» y «Aplicar».
+
+El panel vertical **no existe como contenedor**: se arma con header + items + footer dentro de un
+`sui-dropdown-menu` (web) o de un `sui-modal-sheet` (mobile).
+
+## Cuándo usarlo / cuándo no
+
+**Úsalo** en las listas y tablas del panel del local o del super admin que necesitan filtrar
+(pedidos, productos, repartidores): la barra arriba con el buscador, la vista y el orden; el panel
+cuando hay varias categorías de filtro que se combinan y se aplican juntas.
+
+**No lo uses** para:
+
+- 2 a 4 vistas que se aplican al tocar (Hoy · Semana · Mes): `sui-segmented-control` solo, sin barra.
+- Un único filtro: un `sui-compact-select` o `sui-select` suelto.
+- Filtros rápidos de un toque en mobile (Todos · Pendientes · Entregados): `sui-tab-chips`.
+- El feed de actividad: `sui-activity-filter`.
+
+Regla corta: **barra arriba de una tabla → filter-bar · varias categorías que se aplican juntas →
+panel (header + items + footer) · un filtro suelto → compact-select.**
+
+## Qué variante usar
+
+> **La guía del DS no tiene página de filtros**: estas piezas salen solo del Figma del DS
+> («Filters»: HorizontalFilter y VerticalFilter). Las reglas marcadas canon están aprobadas; lo
+> que sigue **pendiente** (el área de 44 de `sui-filter-item` en mobile, P19) espera decisión.
+>
+> Uso medido el 03-10-2026 en `master-pedidos/src/app` (misma exclusión que `sui-dropdown-menu`):
+> **0 usos**. Solo aparecen en la vitrina `master-preview`.
+
+### `sui-filter-bar`
+
+| variant | cuándo | fuente |
+|---|---|---|
+| `table` (default) | Arriba de una tabla: a la izquierda la vista (`sui-segmented-control`), a la derecha el buscador (`sui-input type="search"`) y el orden (`sui-select` o `sui-compact-select`). | canon (aprobado por el dueño, 05-10-2026, bloque B9), composición del Figma |
+| `calendar` | Arriba de una vista por fechas: a la izquierda «Hoy» + el rango (`sui-button-group`), a la derecha el buscador. | canon (aprobado por el dueño, 05-10-2026, bloque B9), composición del Figma |
+
+`variant` solo marca el host (`data-sui-variant`): **no cambia el layout**. Lo que se ve lo deciden
+los controles que se proyectan.
+
+### El panel: `sui-filter-item` + header + footer
+
+| pieza | regla | fuente |
+|---|---|---|
+| `sui-filter-item` `active` | La categoría abierta (la que muestra sus opciones al lado): fondo gris, texto negro, flecha a la derecha. | según el código (estados del Figma) |
+| `sui-filter-item` `leftIcon` | Un ícono por categoría si ayuda a ubicarla («Estado», «Local», «Repartidor»). | canon (aprobado por el dueño, 05-10-2026, bloque B9) |
+| `sui-filter-panel-header` `clear` | `clear=true` dice «Limpiar» (en español desde el 04-10-2026); un string lo cambia. | canon (CANON-SUI §5: copy en español) |
+| `sui-filter-panel-footer` | «Limpiar» a la izquierda (`stroke neutral`), «Aplicar» a la derecha (`filled primary`), mitad y mitad. | canon (orden de `sui-modal-footer`, CLAUDE.md «Botones») |
+| «Limpiar» en header **y** footer | Elegir uno. Con el footer, el header va sin link. | canon (aprobado por el dueño, 05-10-2026, bloque B9) |
+| `applyButton` deshabilitado | `{ label: 'Aplicar', disabled: !cambio() }` mientras no se toca nada. | canon (aprobado por el dueño, 05-10-2026, bloque B8) |
+
+## Tamaño en mobile y en web
+
+Ninguna pieza cambia sola en mobile, salvo la barra, que apila sus dos lados por debajo de 640 px.
+
+| pieza | mobile | web | fuente |
+|---|---|---|---|
+| `sui-filter-bar` | sin tamaño; los controles adentro van `large` (48) | sin tamaño; los controles `medium` (40) | canon (D16, dueño 05-10-2026) |
+| `sui-filter-item` | 36 de alto, no se puede cambiar: debajo de los 44 del dedo | 36 | pendiente (P19: área invisible de 44 o no usarlo en mobile) |
+| `sui-filter-panel-footer` | `large` (48, desde 0.26.0); o el panel en un `sui-modal-sheet` con `sui-modal-footer` (48) | `medium` (40, el default desde 0.26.0) | canon para el 48 de mobile (CLAUDE.md: footer de modal `large`, piso de 44); web `medium` (40): canon (dueño, 05-10-2026, D16), reemplaza el `small` del bloque B1 |
+| `sui-filter-panel-header` | sin tamaño | sin tamaño | — |
+
+```html
+<sui-filter-bar>
+  <sui-segmented-control slot="start" size={bp.tactil() ? '2xlarge' : 'medium'} … />
+  <div slot="end">
+    <sui-input type="search" size={bp.sizeControl()} placeholder="Buscar pedido…" … />
+  </div>
+</sui-filter-bar>
+```
+
+### Por dispositivo (D16)
+
+Las piezas no tienen un `size` propio (salvo el pie): lo que cambia por dispositivo son los
+controles que se proyectan en la barra. Fuente: D16, dueño 05-10-2026 (fila `filter`).
+
+| dispositivo | size | nota |
+|---|---|---|
+| celular chico (< 380) | sin regla en la tabla (`—`) | la fila `filter` de D16 no lo define; `bp.sizeControl()` da `large`, igual que en el celular, mientras el DS no estire a 44 el área de los `medium` |
+| celular (380–767) | controles `large` · segmented `2xlarge` | el panel va en un `sui-modal-sheet` con `sui-modal-footer` (48), no con este pie; el área de 44 de `sui-filter-item` está pendiente (P19) |
+| tablet táctil (`pointer: coarse`) | controles `large` · segmented `2xlarge` · pie `large` | se toca como un celular: el pie va en `large` (48) o el panel lleva `sui-modal-footer`. D16 no fija el pie en la tablet; esto sigue la columna «mobile» de arriba. El área de 44 de `sui-filter-item` está pendiente (P19), igual que en el celular |
+| computadora (`pointer: fine`) | controles `medium` · `sui-filter-panel-footer` `medium` | `medium` es el default del pie desde 0.26.0 (antes era `small` y había que pasarlo) |
+
+En el ultrawide, igual que en la computadora: el espacio extra va al ancho de la tabla, no a
+controles más grandes.
+
+En master-pedidos: `size={bp.sizeControl()}` en el `sui-input`, `sui-select` o
+`sui-compact-select` de la barra, `size={bp.tactil() ? '2xlarge' : 'medium'}` en el
+`sui-segmented-control` (no tiene helper) y `size={bp.tactil() ? 'large' : 'medium'}` en
+`sui-filter-panel-footer` (`large` existe desde 0.26.0; con la versión anterior, `size="medium"` fijo y
+`sui-modal-footer` en táctil). No uses `bp.isMobile() ? 'large' : 'medium'`: deja la tablet táctil en
+`medium`. Los botones del pie van separados 12 px, como todo grupo de botones (canon de
+`sui-modal-footer`; el Figma dibuja 16).
+
+## API
+
+<!-- api:inicio -->
+<!-- generada: no editar a mano — `npm run docs` -->
+
+| prop | atributo | tipo | default |
+|---|---|---|---|
+| `clear` | `clear` | `boolean \| string` | `false` |
+| `label` | `label` | `string` | `''` |
+| `leftIcon` | `left-icon` | `null \| string` | `null` |
+
+| evento | `event.detail` |
+|---|---|
+| `clearClick` | `void` |
+
+### Diferencias con el SUI Angular
+
+Ninguna en nombres de props, eventos y valores.
+<!-- api:fin -->
+
+<!-- textos:inicio -->
+### Textos
+
+Lo que el componente escribe solo sale de `provideSuiTextos` (español por defecto, se cambia en vivo; ver `docs/TEXTOS.md`). El input de la última columna le gana al texto global.
+
+| clave | por defecto | se pisa con |
+|---|---|---|
+| `filtro.limpiar` | Limpiar | `clearButton` · `clear` del header |
+| `filtro.aplicar` | Aplicar | `applyButton` |
+<!-- textos:fin -->
+
+Slots de `sui-filter-bar`: `[slot=start]`, `[slot=end]` y el contenido por defecto (fila única si no
+se usan los slots). El label de `sui-filter-item` es su contenido proyectado. `clearButton` y
+`applyButton` aceptan un string o `SuiFooterButtonConfig` (`{ label, disabled? }`, la misma interfaz
+de `sui-drawer-footer`).
+
+## Trampas
+
+- Los textos por defecto son «Limpiar» y «Aplicar» en el footer y «Limpiar» en el header con
+  `clear=true` (en español desde el 04-10-2026).
+- **La barra apila a 640 px; la app cambia a mobile a 767.** Entre 641 y 767 px la app ya está en
+  mobile y la barra sigue en una fila.
+- **Varios controles en un lado van en un contenedor.** Cada slot es una fila con 12 px de separación,
+  pero un solo elemento por `slot` queda más ordenado (`<div slot="end">`), como en el Figma.
+- **`sui-filter-item` tiene `role="option"`**: el contenedor tiene que llevar `role="listbox"`.
+- **`active` no es «elegido»**: marca la categoría abierta, no un valor aplicado. Para decir que una
+  categoría tiene un filtro puesto no hay prop (un `sui-badge` en el label es lo más cercano).
+- **El footer separa sus botones 16 px** (del Figma); el canon de la app entre botones hermanos es 12
+  (CANON-SUI §0, `sui-modal-footer`).
+- El footer no llega a `large`: en mobile queda más chico que el footer de cualquier modal.
+- `disabled` del item usa opacidad (no está en el Figma).
+
+## Bien y mal
+
+> Hoy no hay usos de estas piezas fuera de la vitrina `master-preview`: los pares salen de las
+> trampas de este README.
+
+Pie del panel
+
+```html
+<!-- ❌ mal: small (36) no se usa en ningún dispositivo (D16) -->
+<sui-filter-panel-footer size="small" onClear={() => limpiar()} onApply={() => aplicar()} />
+```
+
+```html
+<!-- ✅ bien: medium en la computadora, large (48) donde se toca -->
+<sui-filter-panel-footer size={bp.tactil() ? 'large' : 'medium'} onClear={() => limpiar()} onApply={() => aplicar()} />
+```
+
+«Limpiar» en dos lugares
+
+```html
+<!-- ❌ mal: «Limpiar» en la cabecera y en el pie; se elige uno -->
+<sui-filter-panel-header label="Filtros" clear onClearClick={() => limpiar()} />
+<sui-filter-panel-footer size="medium" onClear={() => limpiar()} onApply={() => aplicar()} />
+```
+
+```html
+<!-- ✅ bien -->
+<sui-filter-panel-header label="Filtros" left-icon="equalizer-line" />
+<sui-filter-panel-footer size="medium" onClear={() => limpiar()} onApply={() => aplicar()} />
+```
+
+Buscador de la barra
+
+```html
+<!-- ❌ mal: isMobile deja la tablet táctil en medium (40), debajo de los 44 -->
+<sui-filter-bar>
+  <sui-input slot="end" type="search" size={bp.isMobile() ? 'large' : 'medium'} />
+</sui-filter-bar>
+```
+
+```html
+<!-- ✅ bien -->
+<sui-filter-bar>
+  <sui-input slot="end" type="search" size={bp.sizeControl()} placeholder="Buscar pedido…" />
+</sui-filter-bar>
+```
+
+## Ejemplo
+
+```html
+<!-- Panel de filtros en web, anclado a un botón «Filtros» -->
+<sui-dropdown-menu #filtros="suiDropdownMenu" min-width="320">
+  <sui-button trigger variant="stroke" color="neutral" size="medium">Filtros</sui-button>
+  <ng-template suiDropdownPanel>
+    <sui-filter-panel-header label="Filtros" left-icon="equalizer-line" />
+    <div role="listbox" aria-label="Categorías de filtro">
+      <sui-filter-item left-icon="checkbox-circle-line" active={cat() === 'estado'}
+                       onSelected={() => cat.set('estado')}>Estado</sui-filter-item>
+      <sui-filter-item left-icon="store-2-line" active={cat() === 'local'}
+                       onSelected={() => cat.set('local')}>Local</sui-filter-item>
+    </div>
+    <sui-filter-panel-footer clear-button="Limpiar"
+                             applyButton={{ label: 'Aplicar', disabled: !cambio() }}
+                             onClear={() => limpiar()} onApply={() => { filtros.close(); aplicar() }} />
+  </ng-template>
+</sui-dropdown-menu>
+```

package/docs/sui-flag/README.md

@@ -0,0 +1,177 @@
+---
+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
+
+<!-- generado por scripts/gen-docs.mjs — no editar a mano; `npm run docs` -->
+
+> **De dónde sale este doc.** El criterio es el del SUI Angular (`sui-flag`); la API es la de este
+> paquete, leída del código. Los ejemplos se pasaron de Angular de forma mecánica: lo literal va como
+> atributo (`only-icon`, `size="large"`), lo dinámico entre llaves (`size={expr}` → `el.size = expr`)
+> y los eventos como `onValueChange={…}` → `el.addEventListener('valueChange', …)`. `@if`, `@for` y
+> `<ng-template>` quedan como en Angular: se leen como pseudocódigo.
+
+Story: [Atoms/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.** Las reglas marcadas canon están aprobadas y las de
+> «según el código» describen el componente; lo que sigue en **propuesta** espera decisió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-compact-select-for-input`, `sui-inline-select`,
+> `sui-dropdown-item` y `sui-command-menu-item`. `sui-tag` no la trae: la recibe proyectada en
+> `slot="start"`.
+
+### `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. | canon (aprobado por el dueño, 05-10-2026, bloque B1) |
+| `lg` | 32 | Dentro de una card. | propuesta |
+| `xl` | 48 | No usar hoy. | canon (aprobado por el dueño, 05-10-2026, bloque B6) |
+| `full` | 100 % | Llena su caja (la caja manda). | según el código |
+
+### `name` y `ariaLabel`
+
+| input | cuándo | fuente |
+|---|---|---|
+| `name` | El slug en inglés y en kebab-case: `peru`, `venezuela`, `united-states`. Son 262. | según el código |
+| `ariaLabel` | El nombre del país en español, si no está escrito al lado. Sin él, es decorativa. | canon (aprobado por el dueño, 05-10-2026, bloque B5) |
+
+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. No se toca, así que la tablet va
+con el valor de web, y el celular chico (< 380 px) también (D16).
+Es **canon (dueño, 05-10-2026, P1 b)**: un paso más grande en el celular que en computadora, y
+se migra todo ahora, no solo al tocar cada pantalla.
+
+| 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.celular() ? 'sm' : 'xs'} aria-label="Perú" />
+```
+
+La bandera no se toca: el área táctil es la del select que la contiene.
+
+### Por dispositivo (D16)
+
+La bandera no se toca: sube un paso **solo en el celular de 380 px o más**. Fuente: D16, dueño
+05-10-2026 (P1 b).
+
+| dispositivo | size | nota |
+|---|---|---|
+| celular chico (< 380) | valor «web» (`xs` en el prefijo, `sm` en una fila) | no se toca: no sube aunque sea un celular |
+| celular (380–767) | valor «mobile» (`sm` en el prefijo, `md` en una fila) | un paso más que en la computadora |
+| tablet táctil (`pointer: coarse`) | valor «web» (`xs` / `sm`) | no se toca: el puntero no cambia nada |
+| computadora (`pointer: fine`) | valor «web» (`xs` / `sm`) | |
+
+En el ultrawide, igual que en la computadora: el espacio extra va a más columnas, no a banderas
+más grandes.
+
+En master-pedidos no hay helper: `size={bp.celular() ? 'sm' : 'xs'}` en el prefijo y
+`size={bp.celular() ? 'md' : 'sm'}` en una fila. No uses `bp.isMobile()`: incluye el celular
+chico, que va con el valor de web. Dentro de un select o un compact-select no se pasa nada: el
+componente elige el tamaño de su bandera.
+
+## «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` -->
+
+| prop | atributo | tipo | default |
+|---|---|---|---|
+| `ariaLabel` | `aria-label` | `null \| string` | `null` |
+| `name` | `name` | `"abkhazia" \| "afghanistan" \| "aland-islands" \| "albania" \| "algeria" \| "american-samoa" \| "andorra" \| "angola" \| "anguilla" \| "antigua-and-barbuda" \| "argentina" \| "armenia" \| "aruba" \| "australia" \| "austria" \| "azerbaijan" \| "azores-islands" \| "bahamas" \| "bahrain" \| "balearic-islands" \| "bangladesh" \| "barbados" \| "basque-country" \| "belarus" \| "belgium" \| "belize" \| "benin" \| "bermuda" \| "bhutan" \| "bolivia" \| "bonaire" \| "bosnia-and-herzegovina" \| "botswana" \| "brazil" \| "british-columbia" \| "british-indian-ocean-territory" \| "british-virgin-islands" \| "brunei" \| "bulgaria" \| "burkina-faso" \| "burundi" \| "cambodia" \| "cameroon" \| "canada" \| "canary-islands" \| "cape-verde" \| "cayman-islands" \| "central-african-republic" \| "ceuta" \| "chad" \| "chile" \| "china" \| "christmas-island" \| "cocos-island" \| "colombia" \| "comoros" \| "cook-islands" \| "corsica" \| "costa-rica" \| "croatia" \| "cuba" \| "curacao" \| "cyprus" \| "czech-republic" \| "democratic-republic-of-congo" \| "denmark" \| "djibouti" \| "dominica" \| "dominican-republic" \| "east-timor" \| "ecuador" \| "egypt" \| "el-salvador" \| "england" \| "equatorial-guinea" \| "eritrea" \| "estonia" \| "ethiopia" \| "european-union" \| "falkland-islands" \| "faroe-islands" \| "fiji" \| "finland" \| "france" \| "french-polynesia" \| "gabon" \| "galapagos-islands" \| "gambia" \| "georgia" \| "germany" \| "ghana" \| "gibraltar" \| "greece" \| "greenland" \| "grenada" \| "guam" \| "guatemala" \| "guernsey" \| "guinea" \| "guinea-bissau" \| "guyana" \| "haiti" \| "hawaii" \| "honduras" \| "hong-kong" \| "hungary" \| "iceland" \| "india" \| "indonesia" \| "iran" \| "iraq" \| "ireland" \| "isle-of-man" \| "israel" \| "italy" \| "ivory-coast" \| "jamaica" \| "japan" \| "jersey" \| "jordan" \| "kazakhstan" \| "kenya" \| "kiribati" \| "kosovo" \| "kuwait" \| "kyrgyzstan" \| "laos" \| "latvia" \| "lebanon" \| "lesotho" \| "liberia" \| "libya" \| "liechtenstein" \| "lithuania" \| "luxembourg" \| "macao" \| "madagascar" \| "madeira" \| "malawi" \| "malaysia" \| "maldives" \| "mali" \| "malta" \| "marshall-island" \| "martinique" \| "mauritania" \| "mauritus" \| "melilla" \| "mexico" \| "micronesia" \| "moldova" \| "monaco" \| "mongolia" \| "montenegro" \| "montserrat" \| "morocco" \| "mozambique" \| "myanmar" \| "namibia" \| "nato" \| "nauru" \| "nepal" \| "netherlands" \| "new-zealand" \| "nicaragua" \| "niger" \| "nigeria" \| "niue" \| "norfolk-island" \| "north-korea" \| "northern-cyprus" \| "northern-marianas-islands" \| "norway" \| "oman" \| "orkney-islands" \| "ossetia" \| "pakistan" \| "palau" \| "palestine" \| "panama" \| "papua-new-guinea" \| "paraguay" \| "peru" \| "philippines" \| "pitcairn-islands" \| "poland" \| "portugal" \| "puerto-rico" \| "qatar" \| "rapa-nui" \| "republic-of-macedonia" \| "republic-of-the-congo" \| "romania" \| "russia" \| "rwanda" \| "saba-island" \| "sahrawi-arab-democratic-republic" \| "saint-kitts-and-nevis" \| "samoa" \| "san-marino" \| "sao-tome-and-prince" \| "sardinia" \| "saudi-arabia" \| "scotland" \| "senegal" \| "serbia" \| "seychelles" \| "sierra-leone" \| "singapore" \| "sint-eustatius" \| "sint-maarten" \| "slovakia" \| "slovania" \| "solomon-islands" \| "somalia" \| "somaliland" \| "south-africa" \| "south-korea" \| "south-sudan" \| "spain" \| "sri-lanka" \| "st-barts" \| "st-lucia" \| "st-vincent-and-the-grenadines" \| "sudan" \| "suriname" \| "swaziland" \| "sweden" \| "switzerland" \| "syria" \| "taijikistan" \| "taiwan" \| "tanzania" \| "thailand" \| "tibet" \| "togo" \| "tokelau" \| "tonga" \| "transnistria" \| "trinidad-and-tobago" \| "tunisia" \| "turkey" \| "turkmenistan" \| "turks-and-caicos" \| "tuvalu" \| "uganda" \| "ukraine" \| "united-arab-emirates" \| "united-kingdom" \| "united-nations" \| "united-states" \| "uruguay" \| "uzbekistan" \| "vanuatu" \| "vatican-city" \| "venezuela" \| "vietnam" \| "virgin-islands" \| "wales" \| "yemen" \| "zambia" \| "zimbabwe"` | — (requerido) |
+| `size` | `size` | `"full" \| "lg" \| "md" \| "sm" \| "xl" \| "xs"` | `'md'` |
+
+Eventos: ninguno.
+
+### Diferencias con el SUI Angular
+
+Ninguna en nombres de props, eventos y valores.
+<!-- 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.
+
+## Bien y mal
+
+> Hoy no hay usos directos fuera de la vitrina `master-preview`: los pares salen de las reglas
+> de este README.
+
+Bandera de adorno
+
+```html
+<!-- ❌ mal: la app es solo Perú; la bandera no le dice nada a nadie -->
+<p><sui-flag name="peru" size="sm" /> Delivery en todo el Perú</p>
+```
+
+```html
+<!-- ✅ bien -->
+<p>Delivery en todo el Perú</p>
+```
+
+País sin nombre al lado
+
+```html
+<!-- ❌ mal: sin ariaLabel es decorativa y el lector de pantalla no dice el país -->
+<sui-flag name="venezuela" size={bp.celular() ? 'md' : 'sm'} />
+```
+
+```html
+<!-- ✅ bien -->
+<sui-flag name="venezuela" size={bp.celular() ? 'md' : 'sm'} aria-label="Venezuela" />
+```
+
+Tamaño por dispositivo
+
+```html
+<!-- ❌ mal: isMobile sube la bandera también en el celular chico (< 380), que va con el valor de web -->
+<sui-flag name="peru" size={bp.isMobile() ? 'sm' : 'xs'} aria-label="Perú" />
+```
+
+```html
+<!-- ✅ bien -->
+<sui-flag name="peru" size={bp.celular() ? 'sm' : 'xs'} aria-label="Perú" />
+```
+
+## Ejemplo
+
+```html
+<sui-flag name="peru" size="sm" aria-label="Perú" />
+```

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

@@ -0,0 +1,189 @@
+---
+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
+
+<!-- generado por scripts/gen-docs.mjs — no editar a mano; `npm run docs` -->
+
+> **De dónde sale este doc.** El criterio es el del SUI Angular (`sui-form-hint`); la API es la de este
+> paquete, leída del código. Los ejemplos se pasaron de Angular de forma mecánica: lo literal va como
+> atributo (`only-icon`, `size="large"`), lo dinámico entre llaves (`size={expr}` → `el.size = expr`)
+> y los eventos como `onValueChange={…}` → `el.addEventListener('valueChange', …)`. `@if`, `@for` y
+> `<ng-template>` quedan como en Angular: se leen como pseudocódigo.
+
+Story: [Atoms/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`; las cifras
+> siguen iguales el 04-10-2026, las líneas de abajo se revisaron el 06-10-2026):
+> **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`. Sin punto final si es una frase corta; con punto si son dos oraciones. | canon (`docs/CANON-SUI.md` §5.4 el largo; `docs/VOZ-Y-ESCRITURA.md` el punto) |
+| `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…»). | canon (aprobado por el dueño, 05-10-2026, bloque B9) (2 usos hoy) |
+| `icon={null}` | Quita el ícono también en `error`. No usar: el error necesita algo más que el color. | canon (aprobado por el dueño, 05-10-2026, bloque B5) |
+
+**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:92`.
+- **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:68` (26 palabras),
+  `pages/orders/orders.html:590` (23), `pages/driver/driver-order-detail/driver-order-detail.html:898` (23),
+  `pages/envios/envios.html:402` (15).
+- **Al menos 14 hints a mano** con clases propias. Ejemplos: `pages/discounts/discounts.html:205`
+  (`discounts__form-hint`), `components/settings-panel/settings-panel.html:95`,
+  `pages/promociones/promociones.html:181`.
+
+## 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.
+
+### Por dispositivo (D16)
+
+No aplica: no tiene `size` (la letra es fija de 12/16 px y no se toca), así que es la misma en el
+celular chico, el celular, la tablet táctil, la computadora y el ultrawide. En master-pedidos no
+lleva `bp`.
+
+## «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` -->
+
+| prop | atributo | tipo | default |
+|---|---|---|---|
+| `icon` | `icon` | `null \| string \| undefined` | `undefined` |
+| `message` | `message` | `null \| string` | `null` |
+| `variant` | `variant` | `"disabled" \| "error" \| "neutral"` | `'neutral'` |
+
+Eventos: ninguno.
+
+### Diferencias con el SUI Angular
+
+Ninguna en nombres de props, eventos y valores.
+<!-- 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.
+- `variant="error"` con mensaje lleva `role="alert"`: el lector lo anuncia al aparecer
+  (04-10-2026). Para enlazarlo a un control propio, pon `id` en el host y apúntalo con
+  `aria-describedby`; los campos del DS ya lo hacen solos.
+
+## Bien y mal
+
+Ayuda debajo de un campo de texto
+
+```html
+<!-- ❌ mal: sui-input ya trae su hint (pages/driver-onboarding/step-info/step-info.html:50) -->
+<sui-input size={bp.sizeControl()} errorMessage={nameError() || null} … />
+@if (!nameError()) { <sui-form-hint message="Como aparece en tu DNI." /> }
+```
+
+```html
+<!-- ✅ bien -->
+<sui-input size={bp.sizeControl()} hint="Como aparece en tu DNI"
+           error={!!nameError()} errorMessage={nameError() || null} … />
+```
+
+Subtítulo de una card
+
+```html
+<!-- ❌ mal: no es ayuda de un campo, es el texto de la sección (pages/schedule/schedule.html:17) -->
+<h2 class="schedule__card-title">Estado de la sucursal</h2>
+<sui-form-hint message="Pausa tu sucursal sin perder el horario que ya configuraste." />
+```
+
+```html
+<!-- ✅ bien -->
+<h2 class="schedule__card-title">Estado de la sucursal</h2>
+<p class="schedule__card-subtitle">Pausa tu sucursal sin perder el horario que ya configuraste.</p>
+```
+
+Explicación de dos oraciones
+
+```html
+<!-- ❌ mal: 23 palabras; pasa las 8 del hint (pages/orders/orders.html:590) -->
+<sui-form-hint message="Si eliges un motivo de la lista, el cliente lo verá. Si escribes uno propio, verá “El local no pudo preparar tu pedido”." />
+```
+
+```html
+<!-- ✅ bien -->
+<sui-alert variant="info"
+           description="Si eliges un motivo de la lista, el cliente lo verá. Si escribes uno propio, verá «El local no pudo preparar tu pedido»." />
+```
+
+## Ejemplo
+
+```html
+<!-- Grupo sin hint propio -->
+<sui-form-label label="Método de pago" required />
+<sui-radio-group ngModel={metodo} onNgModelChange={(e) => (metodo = e.detail)}>…</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'} />
+```