@ajuarezso/sui-stencil 0.0.0-stage → 0.1.0

package/docs/sui-select/README.md

@@ -0,0 +1,288 @@
+---
+name: sui-select
+selector: sui-select
+resumen: Campo que despliega una lista para elegir UNA opción (distrito, repartidor, categoría, motivo)
+alternativas: [sui-radio-label / sui-radio-card (2 a 6 opciones fijas a la vista), sui-segmented-control (2 a 4 modos que se aplican al instante), sui-compact-select (filtro chico que se ajusta al texto), sui-compact-select-for-input (elegir moneda o país dentro de un campo), sui-tag-input (varios valores)]
+---
+
+# sui-select
+
+<!-- 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-select`); 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: [Molecules/Select/Select](https://sui-design-system.web.app/?path=/docs/molecules-select-select--docs)
+
+## Cuándo usarlo / cuándo no
+
+**Úsalo** para elegir **una** opción de una lista que **sale de datos** (departamento, provincia,
+distrito, repartidor, categoría, plan) o que tiene **más de 6 opciones fijas**.
+
+**No lo uses** para:
+
+- 2 a 6 opciones fijas dentro de un formulario: se ven todas de una con `sui-radio-label` (web) o
+  `sui-radio-card` (mobile). Abrir un menú para elegir entre «Casa» y «Trabajo» es un toque de más.
+- 2 a 4 modos, períodos o filtros fijos que se aplican al tocar (Hoy · Semana · Mes): `sui-segmented-control`.
+  Con 5 o más que se aplican al tocar: `sui-tab-chips`. **Período o filtro con 2 a 4 opciones excluyentes → `sui-segmented-control`; con 5 o más, o si no caben y tienen que deslizarse → `sui-tab-chips`** (canon, dueño 04-10-2026).
+- **Buscar** dentro de la lista: `sui-select` **no tiene buscador**. Con 40 distritos se scrollea.
+- Elegir **varias**: no es múltiple. Varias opciones fijas → casillas; valores libres → `sui-tag-input`.
+- Una lista con foto o bandera por opción: las opciones solo muestran texto (ver «Trampas»).
+
+Regla corta: **sale de datos o son más de 6 → select · 2–6 fijas → radio · modos de la vista → segmented.**
+
+## Qué variante usar
+
+> **La guía del DS lo define como el control para elegir una sola opción de un menú** y muestra
+> label y hint, íconos, tamaños, país, método de pago, usuario y deshabilitado. Trae además tres
+> variantes que en SUI son componentes aparte: `compact` (`sui-compact-select`), `inline`
+> (`sui-inline-select`) y `compactForInput` (`sui-compact-select-for-input`). No dice cuándo va cada una.
+>
+> Uso medido el 04-10-2026 en `master-pedidos/src/app` (misma exclusión que `sui-badge`, más
+> `master-ejercicios`): **54 usos en 26 archivos**. Todos `type="basic"` y sin ícono. Tamaños:
+> 23 `bp.isMobile() ? 'large' : 'medium'`, 13 sin `size` (`medium`), 11 `large`,
+> 3 `bp.isMobile() ? 'large' : 'small'`, 2 `medium`, 1 `small`, 1 `bp.controlSize()`. Los 54 pasan
+> `placeholder` (46 «Elige…»; los 8 restantes son filtros sin label: «Filtrar», «Rol», «Estado»…).
+
+### Qué elegir según las opciones
+
+| caso | componente | fuente |
+|---|---|---|
+| La lista sale de datos (ubigeo, repartidores, categorías, planes) | `sui-select` | según la guía del DS (elegir una opción de un menú) |
+| Más de ~6 opciones fijas | `sui-select` | derivado del README de `sui-radio` («más de ~6 → select»), falta confirmación |
+| 2 a 6 opciones fijas en un formulario | `sui-radio-label` / `sui-radio-card` | propuesta, falta aprobación (sale del umbral de `sui-radio`) |
+| 2 a 4 modos que se aplican al instante | `sui-segmented-control` | según la guía del DS («aplicarla de inmediato», ver README de `sui-segmented-control`); el tope de 4: canon (decisión del dueño 04-10-2026: 2 a 4 opciones excluyentes → segmented, 5 o más → tab-chips) |
+| Filtro de una barra con 5 o más opciones | `sui-select` sin label (o `sui-compact-select` en web) | propuesta, falta aprobación |
+
+**Candidatos de hoy** (no rompen nada; se verían mejor con radios o segmented):
+
+- **5 selects con 2 opciones fijas**: `components/add-product-modal/add-product-modal.html:255`,
+  `pages/drivers/drivers.html:376` y `pages/drivers/add-driver/add-driver.html:111` («Tipo de pago»),
+  `pages/super-admin/master-gastos/master-gastos.html:186` («Estado») y `:203` («Moneda»).
+- **Unos 15 con 3 a 6 opciones fijas en un formulario** (cifra aproximada, no recontada el 04-10): `components/address-form-modal/address-form-modal.html:11`
+  («Etiqueta»), `pages/customer/profile/profile.html:252` («Género»), `pages/drivers/drivers.html:360`
+  («Tipo de vehículo»), `pages/discounts/discounts.html:142`,
+  `pages/super-admin/master-sonidos-push/master-sonidos-push.html:85` (6 opciones).
+- **2 filtros de período de 3 opciones** → `sui-segmented-control`: `pages/overview/overview.html:44`,
+  `pages/discounts/discounts.html:49`. Decidido (canon, dueño 04-10-2026): período o filtro de 2 a 4
+  opciones excluyentes → segmented; 5 o más o que deslizan → tab-chips. Los README de tab-chips,
+  datepicker, period-range y date-selector ya dicen lo mismo.
+
+### `type`, `leadingIcon`, `imageUrl`, `flag`, `badge`
+
+| prop | cuándo | fuente |
+|---|---|---|
+| `type="basic"` (default) sin ícono | Todo select de la app hoy. | según la guía del DS |
+| `type="avatar"` + `imageUrl` | Elegir un **repartidor**: la foto de quien quedó elegido en el campo. Hoy `pages/orders/orders.html:257` muestra solo el nombre. | según la guía del DS (ejemplo «User»); el caso es propuesta |
+| `type="provider"` + `imageUrl` | Método de pago con logo (Yape, Plin). | según la guía del DS (ejemplo «Payment Method»); el caso, canon (aprobado por el dueño, 05-10-2026, bloque B2) |
+| `leadingIcon` (`true` o nombre RemixIcon) | Un ícono que ayuda a reconocer el campo en un formulario largo. Hoy sin caso. | según la guía del DS (ejemplo «Icons») |
+| `type="country"` + `flag` | No usar hoy: todo es Perú. | según la guía del DS (ejemplo «Country») |
+| `type="brand"` / `"company"` | No usar hoy. | canon (aprobado por el dueño, 05-10-2026, bloque B6) |
+| `badge` | No usar hoy. | canon (aprobado por el dueño, 05-10-2026, bloque B6) |
+
+### Las piezas
+
+| prop | cuándo | fuente |
+|---|---|---|
+| `label` | Siempre en formularios. Sin label solo en un filtro de barra donde el valor se explica solo («Todos los roles»). | según la guía del DS (ejemplo con label y hint) |
+| `placeholder` | **Siempre**, en imperativo con tuteo: «Elige…» o «Elige el distrito» cuando el sustantivo ayuda. El default genérico es «Elige…» (04-10-2026). | canon (CANON-SUI §5.7, decisión del dueño 03-10-2026) |
+| `required` · `sublabel` · `tooltip` · `hint` | Igual que `sui-input`: asterisco, «(Opcional)» con paréntesis, aclaración, ayuda de una línea. | según la guía del DS |
+| `error` + `errorMessage` | No eligió en un campo obligatorio: «Elige tu distrito». | según la guía del DS |
+| `disabled` | Selects en cascada: provincia hasta elegir departamento, distrito hasta elegir provincia. | según la guía del DS (ejemplo deshabilitado); el caso ya es práctica (`components/address-form-modal/address-form-modal.html:97`) |
+| `options` | `SuiSelectOption<T>[]`: `{ value, label, disabled? }`. `disabled` en la opción para lo que existe pero hoy no se puede elegir. | API |
+
+**Usos de hoy que rompen la regla:** 0 sin `placeholder` y 0 «Seleccionar…» (medido el
+04-10-2026; el 03-10 eran 28 y 16, ya corregidos en la app). Los 8 que no dicen «Elige…» son
+filtros sin label donde el placeholder hace de label («Rol», «Estado», «Período»).
+
+## Tamaño en mobile y en web
+
+El campo sigue la escala del input y del botón (`large` 48 y `xlarge` 52 son extensión de SUI;
+la guía tiene `medium` 40, `small` 36 y `xsmall` 32). **La lista acompaña al campo**: las opciones
+miden 36 hasta `medium` (las de la guía), 44 en `large` y 48 en `xlarge`, y **en mobile (≤ 767 px)
+nunca bajan de 44**, sea cual sea el `size`. El texto de la opción es el mismo del valor del
+campo: 14/20 hasta `medium` y 16/24 en `large` y `xlarge`.
+
+En large y xlarge el texto sube a 16 px (regla del 03-10-2026). Vale para el valor, el placeholder
+y las opciones de la lista; el alto no cambia (las opciones bajan 2 de padding para seguir en 44/48).
+
+| size del campo | opción en web | opción en mobile | fuente |
+|---|---|---|---|
+| `xsmall` · `small` · `medium` | 36 | 44 | 36: según la guía del DS · 44 en mobile: canon (aprobado por el dueño, 03-10-2026), extensión SUI |
+| `large` | 44 | 44 | canon (aprobado por el dueño, 03-10-2026), extensión SUI |
+| `xlarge` | 48 | 48 | canon (aprobado por el dueño, 03-10-2026), extensión SUI |
+
+| uso | mobile | web | fuente |
+|---|---|---|---|
+| campo de formulario | `large` (48) | `medium` (40) | mobile `large`: canon (decisión del dueño 04-10-2026, piso táctil 44: `medium` 40 no llega y `large` 48 es el primer size que sí) · web `medium`: canon (aprobado por el dueño, 05-10-2026, bloque B1) |
+| filtro de una barra | `large` (48) | `medium` (40) | mobile `large`: canon (decisión del dueño 04-10-2026, piso táctil 44: `large` 48 es el primer size que llega) · web `medium`: canon (dueño, 05-10-2026, D16) (el `small` de `pages/orders/orders.html:257` ya se migró a `bp.sizeControl()`) |
+| dentro de una tabla | no aplica | `medium` (40) | canon (dueño, 05-10-2026, D16): nada en `xsmall` (la guía del DS lo usa en tablas densas) |
+| `xlarge` (52) | no usar | no usar | canon (aprobado por el dueño, 05-10-2026, bloque B6): queda más alto que el botón `large` del footer |
+
+```html
+<sui-select size={bp.sizeControl()} label="Distrito" … />   <!-- bp = BreakpointsService · D16, dueño 05-10-2026 -->
+```
+
+### Por dispositivo (D16)
+
+Fila `select` de la tabla D16 (dueño, 05-10-2026): se decide por el tipo de puntero además del ancho.
+
+| dispositivo | size | nota |
+|---|---|---|
+| celular chico (< 380 px) | `large` (48) | interino: D16 pide `medium` con área tocable de 44; hasta que el DS la estire, se queda el grande (nota ¹ de D16) |
+| celular (380–767 px) | `large` (48) | el primer size que llega al piso táctil de 44 |
+| tablet táctil (`pointer: coarse`) | `large` (48) | Apple pide 44 pt también en iPad; con `bp.isMobile()` el iPad quedaba en `medium` 40 |
+| computadora (`pointer: fine`) | `medium` (40) | también en filtros de barra y dentro de tablas; nunca `small` ni `xsmall` |
+
+Ultrawide (≥ 1920 px): igual que la computadora, `medium`. El espacio extra va a ancho máximo y columnas, no a un campo más alto.
+
+En master-pedidos: `size={bp.sizeControl()}`. Re-medido el 06-10-2026: 52 de 56 `<sui-select>` ya lo usan. Faltan 4:
+
+- `pages/driver/driver-dashboard/driver-dashboard.html:1507`: `size="large"` fijo por pedido del dueño (22-09-2026),
+  pendiente de confirmar si D16 lo reemplaza.
+- `pages/super-admin/master-preview/master-preview.html:807` y `:813`: sin `size`, salen en `medium` (el default) en
+  todos los dispositivos. Es la vitrina del super admin.
+- `pages/super-admin/master-preview/_ruta-pedido/ruta-pedido.html:12`: sin `size`, sale en `medium`. Es la pantalla de
+  diagnóstico `/dx/ruta-pedido` (auditor de rutas del super admin), no una vitrina.
+
+## «No usar»: por qué no hoy y cuándo sí
+
+| qué | por qué no hoy | cuándo sí, en un flujo nuevo |
+|---|---|---|
+| `type="country"` + `flag` | todo es Perú | si se abren repartidores o locales en otro país |
+| `type="brand"` / `"company"` | no hay listas de marcas o empresas | elegir la marca de un producto envasado o la empresa de una flota |
+| `leadingIcon` | ningún formulario lo necesita para reconocerse | un formulario largo del panel con varios selects seguidos |
+| `badge` | no hay valores que marcar | marcar el plan elegido como «Recomendado» |
+| `size="xsmall"` | es chico (D16, 05-10-2026) | nunca: cambiar el estado de una fila va con un select `medium` |
+| `size="xlarge"` | queda más alto que el botón del footer | un select solo, como acción principal de la pantalla |
+
+## API
+
+<!-- api:inicio -->
+<!-- generada: no editar a mano — `npm run docs` -->
+
+| prop | atributo | tipo | default |
+|---|---|---|---|
+| `badge` | `badge` | `SuiSelectBadgeConfig \| null \| string` | `null` |
+| `disabled` | `disabled` | `boolean` | `false` |
+| `error` | `error` | `boolean` | `false` |
+| `errorMessage` | `error-message` | `null \| string` | `null` |
+| `flag` | `flag` | `"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" \| null` | `null` |
+| `hint` | `hint` | `null \| string` | `null` |
+| `imageUrl` | `image-url` | `null \| string` | `null` |
+| `label` | `label` | `null \| string` | `null` |
+| `leadingIcon` | `leading-icon` | `boolean \| null \| string` | `false` |
+| `options` | — (solo por propiedad JS) | `SuiSelectOption[]` | `[]` |
+| `placeholder` | `placeholder` | `string` | `'Elige…'` |
+| `required` | `required` | `boolean` | `false` |
+| `size` | `size` | `"large" \| "medium" \| "small" \| "xlarge" \| "xsmall"` | `'medium'` |
+| `sublabel` | `sublabel` | `null \| string` | `null` |
+| `tooltip` | `tooltip` | `null \| string` | `null` |
+| `type` | `type` | `"avatar" \| "basic" \| "brand" \| "company" \| "country" \| "provider"` | `'basic'` |
+| `value` | `value` | `string` | `''` |
+
+| evento | `event.detail` |
+|---|---|
+| `valueChange` | `string` |
+
+| método | firma |
+|---|---|
+| `closeMenu` | `closeMenu() => Promise<void>` |
+| `openMenu` | `openMenu() => Promise<void>` |
+| `toggleMenu` | `toggleMenu() => Promise<void>` |
+
+Slots: `leading`.
+
+### 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 |
+|---|---|---|
+| `comun.elige` | Elige… | `placeholder` |
+<!-- textos:fin -->
+
+`value` es `model<T | null>`. Implementa `ControlValueAccessor`. Slot `[slot=leading]` para una
+decoración propia del campo (gana sobre ícono, imagen y bandera).
+
+## Trampas
+
+- **No busca y no es múltiple.** Con 40 opciones la lista se scrollea; con varias a elegir no sirve.
+- **Las opciones solo llevan texto**: `SuiSelectOption` no tiene ícono, foto ni bandera. El
+  `type="avatar"` o `"country"` decora **el campo**, no la lista.
+- **El default del placeholder es «Elige…»** (genérico, desde el 04-10-2026): pásalo con el sustantivo cuando ayude («Elige el distrito»).
+- El `valueChange` puede traer `null`: los usos de hoy hacen `$event ?? ''`.
+- `T` arranca en `any`: tipa las opciones (`SuiSelectOption<string>[]`) para no arrastrar `any`
+  a la pantalla.
+- Con 44 px por opción en mobile el panel muestra unas 4 opciones antes de scrollear (el alto
+  máximo del panel no cambió).
+- El label también abre la lista al tocarlo.
+- **Accesibilidad (04-10-2026)**: el combobox se nombra con el `label` (`aria-labelledby`; sin
+  label, con el placeholder), apunta al listbox abierto (`aria-controls`) y anuncia la opción
+  resaltada con las flechas (`aria-activedescendant`). Hint y error van en `aria-describedby`.
+
+## Bien y mal
+
+**Filtro de período con 3 opciones**
+
+```html
+<!-- ❌ mal: 3 opciones excluyentes que se aplican al tocar, escondidas en un menú (pages/discounts/discounts.html:49) -->
+<sui-select size={bp.sizeControl()} placeholder="Período"
+            options={periodOptions} value={selectedPeriod()}
+            onValueChange={(e) => selectedPeriod.set(e.detail ?? '7days')} />
+```
+
+```html
+<!-- ✅ bien: 2 a 4 opciones excluyentes → sui-segmented-control (canon, dueño 04-10-2026) -->
+<sui-segmented-control size={bp.tactil() ? '2xlarge' : 'medium'}
+                       tabs={periodos} active={periodo} onActiveChange={(e) => (periodo = e.detail)} />
+```
+
+**El valor que vuelve del select**
+
+```html
+<!-- ❌ mal: `$any` es un `any` disfrazado y además deja pasar el `null` (pages/super-admin/super-admin.html:317) -->
+<sui-select size={bp.sizeControl()} label="Plan" placeholder="Elige…"
+            options={planSelectOptions()} value={subPlan()}
+            onValueChange={(e) => subPlan.set($any(e.detail))} />
+```
+
+```html
+<!-- ✅ bien: opciones tipadas (SuiSelectOption<string>[]) y el null resuelto en el template -->
+<sui-select size={bp.sizeControl()} label="Plan" placeholder="Elige…"
+            options={planSelectOptions()} value={subPlan()}
+            onValueChange={(e) => subPlan.set(e.detail ?? 'crecimiento')} />
+```
+
+**El size por dispositivo**
+
+```html
+<!-- ❌ mal: solo mira el ancho; el iPad (≥ 768, táctil) recibe `medium` 40, bajo el piso de 44 -->
+<sui-select size={bp.isMobile() ? 'large' : 'medium'} label="Distrito"
+            placeholder="Elige el distrito" options={distritos()} />
+```
+
+```html
+<!-- ✅ bien: el helper de D16 (`large` en celular y tablet táctil, `medium` en la computadora) -->
+<sui-select size={bp.sizeControl()} label="Distrito"
+            placeholder="Elige el distrito" options={distritos()} />
+```
+
+## Ejemplo
+
+```html
+<sui-select label="Distrito" required placeholder="Elige tu distrito"
+            options={distritos()} disabled={!provinciaId()}
+            error={intentado() && !distritoId()} error-message="Elige tu distrito"
+            size={bp.sizeControl()}
+            value={distritoId()} onValueChange={(e) => distritoId.set(e.detail ?? '')} />
+```

package/docs/sui-sidebar/README.md

@@ -0,0 +1,304 @@
+---
+name: sui-sidebar
+selector: sui-sidebar
+resumen: Navegación principal de un rol — columna fija a la izquierda en web y cajón que entra desde la izquierda en mobile
+alternativas: [la barra inferior nativa del layout (las 4-5 secciones más usadas en el teléfono), sui-topbar (navegación arriba, sin columna lateral), sui-tab-menu-vertical (secciones dentro de UNA pantalla, como ajustes), sui-dropdown-menu (acciones de una cuenta o un botón)]
+---
+
+# sui-sidebar
+
+<!-- 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-sidebar`); 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: [Organisms/Sidebar](https://sui-design-system.web.app/?path=/docs/organisms-sidebar--docs)
+
+## Cuándo usarlo / cuándo no
+
+**Úsalo** como **la** navegación de un layout de rol: una por layout, montada en el layout y no
+en las páginas. En la app hay 4 y cubren los roles: empresa (`components/sidebar/sidebar.html:43`,
+dentro del shell), repartidor (`layouts/driver/driver-layout.html:4`), super admin y central
+(`layouts/master/master-layout.html:5`) y cliente (`layouts/customer/customer-layout.html:5`).
+
+**No lo uses** para:
+
+- Navegar entre secciones **de una sola pantalla** (las pestañas de Ajustes, los pasos de un
+  formulario): `sui-tab-menu-vertical` o `sui-tab-chips`.
+- Un menú de acciones (editar, eliminar, cerrar sesión de un item): `sui-dropdown-menu`.
+- Reemplazar la barra inferior en el teléfono. En mobile, las secciones de todos los días van en la
+  barra inferior (nativa en iOS) y el sidebar es el cajón de «Más».
+
+Regla corta: **navegación del rol → sidebar · secciones de una pantalla → tab menu · acciones → dropdown.**
+
+## Qué variante usar
+
+> **La guía del DS no tiene página del sidebar.** El componente sale del Figma de SUI (Sidebar
+> [Navigation], node 3802:11759) y el cajón de mobile no existe en ese Figma: se portó del layout
+> del super admin. Lo de abajo es **práctica de la app** (los 4 usos están homologados desde el
+> 25-07-2026) o **propuesta, falta aprobación**; lo marcado «canon» sale de `docs/CANON-SUI.md`,
+> de `master-pedidos/CLAUDE.md` o de la aprobación del dueño del 05-10-2026.
+>
+> Uso medido el 03-10-2026 en `master-pedidos/src/app`: **4 sidebars**, sin contar vitrinas
+> (`master-preview` tiene el quinto).
+
+### La composición (igual en los 4 layouts)
+
+| pieza | cómo | fuente |
+|---|---|---|
+| `brand` | `{ name: 'Master Pedidos', subtitle: '<Rol>', logo: 'assets/app-icon.png', fallback: 'M' }`. En empresa, el nombre del local. | práctica de la app (4 de 4) |
+| `showHeaderButton` + `headerButtonActive` + panel `[header-panel]` | El botón del header abre el **cambio de rol** (o de negocio/sucursal en empresa). El panel se proyecta con `<div header-panel>` y adentro van `sui-dropdown-item mode="option" size="large"`. El cliente lo muestra solo en mobile. | práctica de la app (4 de 4) |
+| tres secciones con rótulo | `items` + `itemsLabel` (lo de todos los días), `secondaryItems` + `secondaryItemsLabel` (dinero o crecimiento), `supportingItems` + `supportingItemsLabel` (cuenta, administración: va anclado abajo). Rótulos en sentence case: «Operación», «Dinero», «Cuenta». | práctica de la app (4 de 4) |
+| `activeRoute` | No hace falta si los items de navegación llevan `route`: el `<a>` usa `routerLinkActive` y marca por prefijo (`/cliente/pedidos/123` deja «Mis pedidos» activo). `activeRoute` solo marca items **sin** `route`, y por `value` exacto (`activeRoute="pedidos"`), para demos sin router (`sui-sidebar.ts:369-412`). Los 4 layouts pasan `activeRoute={currentUrl()}`, pero no cambia nada: todos sus items de navegación tienen `route` y la URL nunca es igual al `value` de un item-acción. | comportamiento del `.ts` · práctica de la app (4 de 4 lo pasan, sin efecto) |
+| `profile` | Nombre + `avatarUrl` (nunca `photoURL`) + correo. | canon (CLAUDE.md, «Fotos de otra persona»: el campo correcto es `avatarUrl`) |
+| cerrar sesión | Hoy **ningún** item usa `action: 'logout'`: el cierre real vive en el selector de rol y el «salir» del panel solo cambia de rol (`components/sidebar/sidebar.ts:367`). Los 4 layouts dejan `logoutClicked` conectado por si se agrega. | práctica de la app |
+| `mobileOpen` + `mobileOpenChange` + `closeOnItemClick` | Siempre los dos (`closeOnItemClick` ya es `true` por defecto; los 4 layouts lo pasan explícito). Más `cerrarAlNavegar(...)` en el constructor del layout (ver Trampas). | canon (CANON-SUI §1.1) |
+| `search` | `{ shortcut: '⌘K' }` (el placeholder por defecto ya es «Buscar…», con elipsis) y el layout **filtra** los items con `searchValue` (el componente no filtra). | buscador: práctica de la app (4 de 4) · `shortcut: '⌘K'`: práctica de la app (3 de 4; el cliente no lo pasa, `layouts/customer/customer-layout.html:12`) · la elipsis «…»: canon (CANON-SUI, copy); los 4 layouts todavía pasan «Buscar...» (ver «Bien y mal») |
+| `indicatorColor` | Default `brand` (naranja). No se cambia. | canon del DS (accent = marca) |
+| `collapsed` | Solo el cliente lo usa, con un item «colapsar», y **solo en web**: `collapsed={colapsado() && !bp.isMobile()}`. | práctica de la app (1 uso) |
+
+### El item (`SuiSidebarItem`)
+
+| prop | cuándo | fuente |
+|---|---|---|
+| `icon` | Siempre, RemixIcon `-line`. Sin ícono, el modo colapsado queda vacío. | canon (aprobado por el dueño, 05-10-2026, bloque B9) |
+| `route` | Navegación normal (usa `routerLink`). | práctica de la app |
+| sin `route` | Acción, no navegación (abrir Configuración, colapsar): `action` o solo `value`, y se escucha `itemClicked`. | práctica de la app |
+| `badge` | Un contador que pide acción: notificaciones sin leer, con tope «99+» (`components/sidebar/sidebar.ts:129`). Nunca un «NEW» decorativo. | práctica de la app · el «nunca NEW»: canon (aprobado por el dueño, 05-10-2026, bloque B9) |
+| `variant: 'danger'` | Solo «Cerrar sesión» o salidas destructivas. | «Cerrar sesión» en rojo: canon (decisión del dueño 04-10-2026, salida destructiva en `color error` aunque sea un link; `danger` pinta `--sui-state-error-base`) · el «solo» (ningún otro item en rojo): canon (aprobado por el dueño, 05-10-2026, bloque B3) |
+| `shortcut`, `colorDot` | No usar (ver «No usar»). | canon (aprobado por el dueño, 05-10-2026, bloque B6) |
+
+## Tamaño en mobile y en web
+
+El sidebar **no tiene `size`**. El ancho lo decide el viewport:
+
+| estado | ancho | fuente |
+|---|---|---|
+| web (> 767 px) | 272 fijo, alto `100dvh` | Figma |
+| web colapsado (`collapsed`) | 80, solo íconos; los rótulos siguen visibles y cada item tiene tooltip nativo con su label | Figma |
+| mobile `drawer` (default) | `min(86vw, 360px)`, entra desde la izquierda con fondo oscuro | extensión SUI (no está en el Figma) |
+| mobile `sheet` | `100vw - 40px`, se siente casi a pantalla completa | extensión SUI |
+
+| uso | mobile | web | fuente |
+|---|---|---|---|
+| navegación del rol | cajón `drawer`, cerrado por defecto | columna fija de 272 | práctica de la app (4 de 4) |
+| colapsar | nunca (`!bp.isMobile()`) | opcional, a pedido de la persona | práctica de la app |
+| `sheet` | no usar (0 usos) | — | canon (aprobado por el dueño, 05-10-2026, bloque B6) |
+
+**Qué pasa en mobile (≤ 767 px):** el sidebar sale del flujo y queda `position: fixed` fuera de la
+pantalla. Lo abre la acción `toggle-sidebar` de la **barra inferior** («Más»), que el layout
+traduce a `mobileOpen = true` (`layouts/shell/shell.ts:326`, `customer-layout.ts:322`). Se cierra
+con el fondo, con Escape, al tocar un item (`closeOnItemClick`) y —por el helper del proyecto—
+al terminar cualquier navegación. Cerrado queda `inert` y `aria-hidden`: el foco no se mete.
+Respeta las safe areas de arriba, izquierda y abajo.
+
+### Por dispositivo (D16)
+
+El sidebar **no tiene `size`**: D16 (dueño, 05-10-2026) no le da un tamaño que pasar. El alto de los items lo pone el DS por
+ancho: 52 en el cajón (≤ 767 px, `padding: 14px` + ícono 24) y 36 en la columna (> 767 px). Hueco conocido: una tablet táctil
+(iPad, ≥ 768 px y `pointer: coarse`) recibe la columna con items de 36, bajo el piso de 44 que D16 pide para lo que se toca.
+Queda **pendiente del DS** (el mixin `sui-tactil` de la propuesta de D16, que todavía espera el sí del dueño); desde la app no
+se corrige.
+
+En master-pedidos: no se pasa `size`; lo único que depende del dispositivo es `collapsed={colapsado() && !bp.isMobile()}`.
+
+## «No usar»: por qué no hoy y cuándo sí
+
+| qué | por qué no hoy | cuándo sí, en un flujo nuevo |
+|---|---|---|
+| `indicatorColor="information"` | el activo es naranja de marca en toda la app | nunca en esta app (es el azul del Figma original) |
+| `mobileMode="sheet"` | el `drawer` deja ver la página detrás y se entiende que es un cajón | un rol con muchísimos items donde 360 px quedan cortos |
+| `shortcut` en items | no hay atajos de teclado por sección | si se agregan atajos tipo `⌘1` en el panel web |
+| `colorDot` | no hay «favoritos» ni etiquetas de color | proyectos o locales favoritos fijados por la persona |
+| `profileDropdown` | el perfil se abre desde «Cuenta» | si el perfil pasa a tener menú propio (cambiar cuenta, idioma) |
+| feature card (`[feature-card]`) | no hay promo dentro de la navegación | invitar a mejorar el plan en el panel de empresa |
+| `showBackdrop` en `false` | sin fondo, el cajón parece pegado a la página | nunca en mobile |
+
+## API
+
+<!-- api:inicio -->
+<!-- generada: no editar a mano — `npm run docs` -->
+
+| prop | atributo | tipo | default |
+|---|---|---|---|
+| `activeRoute` | `active-route` | `null \| string` | `null` |
+| `brand` | — (solo por propiedad JS) | `SuiSidebarBrandConfig \| null` | `null` |
+| `closeOnItemClick` | `close-on-item-click` | `boolean` | `true` |
+| `collapsed` | `collapsed` | `boolean` | `false` |
+| `headerButtonActive` | `header-button-active` | `boolean` | `false` |
+| `indicatorColor` | `indicator-color` | `"brand" \| "information"` | `'brand'` |
+| `items` | — (solo por propiedad JS) | `SuiSidebarItem[]` | `[]` |
+| `itemsLabel` | `items-label` | `null \| string` | `null` |
+| `mobileMode` | `mobile-mode` | `"drawer" \| "sheet"` | `'drawer'` |
+| `mobileOpen` | `mobile-open` | `boolean` | `false` |
+| `profile` | — (solo por propiedad JS) | `SuiSidebarProfile \| null` | `null` |
+| `profileDropdown` | `profile-dropdown` | `boolean` | `false` |
+| `search` | `search` | `SuiSidebarSearchConfig \| boolean \| null` | `false` |
+| `searchValue` | `search-value` | `string` | `''` |
+| `secondaryItems` | — (solo por propiedad JS) | `SuiSidebarItem[]` | `[]` |
+| `secondaryItemsLabel` | `secondary-items-label` | `null \| string` | `null` |
+| `showBackdrop` | `show-backdrop` | `boolean` | `true` |
+| `showHeaderButton` | `show-header-button` | `boolean` | `false` |
+| `supportingAnchorBottom` | `supporting-anchor-bottom` | `boolean` | `true` |
+| `supportingItems` | — (solo por propiedad JS) | `SuiSidebarItem[]` | `[]` |
+| `supportingItemsLabel` | `supporting-items-label` | `null \| string` | `null` |
+
+| evento | `event.detail` |
+|---|---|
+| `backdropClicked` | `void` |
+| `headerButtonClicked` | `void` |
+| `itemClicked` | `SuiSidebarItem` |
+| `logoutClicked` | `void` |
+| `mobileOpenChange` | `boolean` |
+| `profileClicked` | `void` |
+| `searchSubmitted` | `string` |
+| `searchValueChange` | `string` |
+
+Slots: `header-panel`, `feature-card`.
+
+### 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 |
+|---|---|---|
+| `navegacion.cambiarWorkspace` | Cambiar workspace | — |
+| `comun.limpiarBusqueda` | Limpiar búsqueda | — |
+| `comun.verificado` | Verificado | — |
+| `navegacion.opcionesPerfil` | Opciones de perfil | — |
+| `comun.buscar` | Buscar… | `search.placeholder` |
+<!-- textos:fin -->
+
+```ts
+interface SuiSidebarItem {
+  value: string;              // lo emite (itemClicked)
+  label: string;
+  icon?: string;              // RemixIcon sin 'ri-'
+  route?: string;             // routerLink; sin route solo emite
+  external?: boolean;
+  variant?: 'default' | 'danger';
+  action?: 'logout' | string; // cualquier action anula el route
+  badge?: string | number;
+  shortcut?: string;
+  colorDot?: string;          // reemplaza el ícono por un punto de color
+  tooltip?: string;           // tooltip en colapsado; default = label
+}
+interface SuiSidebarBrandConfig { name: string; subtitle?: string; subtitleAsBadge?: boolean; logo?: string; fallback?: string; }
+interface SuiSidebarSearchConfig { placeholder?: string; ariaLabel?: string; shortcut?: string; }
+interface SuiSidebarProfile { name: string; avatarUrl?: string; initials?: string; status?: SuiAvatarStatus; email?: string; verified?: boolean; }
+```
+
+Slots: `[header-panel]` (debajo del header: el switcher), `[feature-card]` (al fondo del contenido).
+
+## Trampas
+
+- **El cajón no se cierra solo al navegar desde afuera.** Se cierra con el fondo, Escape y el toque
+  en un item; cualquier otra navegación (atrás, un push, `router.navigate`, una ruta cacheada que
+  vuelve) lo deja abierto tapando la página siguiente. Mientras el DS no traiga `closeOnNavigate`,
+  cada layout llama `cerrarAlNavegar(menuAbierto, switcherAbierto)`
+  (`core/services/cerrar-al-navegar.ts`). Canon: CANON-SUI §1.1.
+- **El buscador no filtra nada.** Solo expone `searchValue` + `searchValueChange` y `searchSubmitted`; el layout
+  filtra los items (`master-layout.ts:125`). Su placeholder por defecto es «Buscar…» (en español desde el 04-10-2026).
+- El campo del buscador lleva `enterkeyhint="search"` (lupa en el teclado), sin `inputmode` (D14), y
+  sube a 16 px en ≤ 767 px para que iOS no haga zoom en el cajón; su nombre accesible es
+  `ariaLabel` o, si no viene, el placeholder. Las tres cosas desde 0.26.0.
+- **`collapsed` no mira el viewport.** Con `collapsed` en `true`, el cajón de mobile también sale
+  de 80 px. Condiciónalo: `collapsed={colapsado() && !bp.isMobile()}`.
+- Un item con `route` (y sin `action`) queda activo **solo** por `routerLinkActive`, por prefijo:
+  `isItemActive()` devuelve `false` para todo item con `route` (`sui-sidebar.ts:411`), así que
+  `activeRoute` no lo toca. Un item sin `route` solo por `activeRoute`, y por `value` exacto
+  (`sui-sidebar.ts:379`): pasarle la URL actual no lo marca nunca.
+- Cualquier `action` (no solo `'logout'`) anula el `route`: el item se pinta como `<button>`, no navega y
+  tampoco se marca activo (tiene `route`, así que `isItemActive()` da `false`, y no hay `routerLinkActive`).
+- El `title` nativo del host se borra (sin tooltip gris); en colapsado el tooltip va en cada item.
+- El cajón tiene `z-index: 300` sobre la barra inferior (200). Mientras está abierto el layout
+  esconde la barra (`customer-layout.ts:66`); si armas un layout nuevo, haz lo mismo.
+- El comentario de cabecera del `.ts` todavía dice 240 px; el ancho real es 272 (`sui-sidebar.scss:50`).
+- Los items ya traen el arreglo de iOS del `:active` pegado: no lo agregues.
+
+## Bien y mal
+
+**El buscador**
+
+```html
+<!-- ❌ mal: tres puntos sueltos en vez de elipsis. Así en components/sidebar/sidebar.html:48, layouts/driver/driver-layout.html:9 y layouts/master/master-layout.html:10; layouts/customer/customer-layout.html:12 pasa el mismo «Buscar...» sin `shortcut` -->
+<sui-sidebar search={{ placeholder: 'Buscar...', shortcut: '⌘K' }}
+             searchValue={busqueda} onSearchValueChange={(e) => (busqueda = e.detail)} items={items()} />
+```
+
+```html
+<!-- ✅ bien: sin placeholder sale «Buscar…»; el layout filtra `items()` con `busqueda` -->
+<sui-sidebar search={{ shortcut: '⌘K' }}
+             searchValue={busqueda} onSearchValueChange={(e) => (busqueda = e.detail)} items={items()} />
+```
+
+**Colapsar**
+
+```html
+<!-- ❌ mal: `collapsed` no mira el viewport; el cajón de mobile también sale de 80 px, solo íconos -->
+<sui-sidebar collapsed={colapsado()} items={items()} mobileOpen={menuAbierto} onMobileOpenChange={(e) => (menuAbierto = e.detail)} />
+```
+
+```html
+<!-- ✅ bien: se colapsa solo en web (layouts/customer/customer-layout.html:7) -->
+<sui-sidebar collapsed={colapsado() && !bp.isMobile()} items={items()} mobileOpen={menuAbierto} onMobileOpenChange={(e) => (menuAbierto = e.detail)} />
+```
+
+**El item activo**
+
+```ts
+// ❌ mal: navegar con `action` + `itemClicked` y `router.navigate`. El item se pinta como `<button>`,
+// no como `<a routerLink>`, y nunca queda activo: sin `route`, `activeRoute` solo lo marca si es igual
+// a su `value` (`sui-sidebar.ts:379`), y `activeRoute={currentUrl()}` nunca lo es
+{ value: 'pedidos', label: 'Mis pedidos', icon: 'time-line', action: 'ir-a-pedidos' }
+```
+
+```ts
+// ✅ bien: con `route` (y sin `action`) el item es un `<a routerLink>` y `routerLinkActive` lo marca por
+// prefijo: `/cliente/pedidos/123` deja «Mis pedidos» activo sin pasar `activeRoute`
+// (layouts/customer/customer-layout.ts:287)
+{ value: 'pedidos', label: 'Mis pedidos', icon: 'time-line', route: '/cliente/pedidos' }
+```
+
+## Ejemplo
+
+```html
+<sui-sidebar
+  brand={{ name: 'Master Pedidos', subtitle: 'Repartidor', logo: 'assets/app-icon.png', fallback: 'M' }}
+  show-header-button
+  headerButtonActive={switcherOpen()}
+  onHeaderButtonClicked={() => switcherOpen.set(!switcherOpen())}
+  search={{ shortcut: '⌘K' }}
+  searchValue={busqueda} onSearchValueChange={(e) => (busqueda = e.detail)}
+  items-label="Operación" items={items()}
+  secondary-items-label="Dinero" secondaryItems={itemsDinero()}
+  supporting-items-label="Cuenta" supportingItems={itemsCuenta()}
+  profile={perfil()}
+  mobileOpen={menuAbierto} onMobileOpenChange={(e) => (menuAbierto = e.detail)}
+  close-on-item-click
+  onLogoutClicked={() => logout()}>
+  @if (switcherOpen()) {
+    <div header-panel role="listbox" aria-label="Cambiar de rol">
+      @for (rol of roles; track rol.value) {
+        <sui-dropdown-item label={rol.label} sublabel={rol.sublabel} mode="option" size="large"
+                           onClicked={() => irARol(rol)} />
+      }
+    </div>
+  }
+</sui-sidebar>
+```
+
+```ts
+constructor() {
+  cerrarAlNavegar(this.menuAbierto, this.switcherOpen); // mientras el DS no cierre solo
+}
+```