@ajuarezso/sui-design-system 0.21.0 → 0.22.0

package/docs/sui-command-menu-footer/README.md

@@ -0,0 +1,100 @@
+---
+name: sui-command-menu-footer
+selector: sui-command-menu-footer
+resumen: Pie del buscador ⌘K (command menu) con las teclas para moverse y elegir, y un link de ayuda
+alternativas: [sui-modal-footer (botones de un modal), sui-kbd (una tecla suelta), sui-dropdown-caption (texto de pie de un menú flotante)]
+---
+
+# sui-command-menu-footer
+
+Story: [Organisms/Command Menu/Command Menu Footer](https://sui-design-system.web.app/?path=/docs/organisms-command-menu-command-menu-footer--docs)
+
+La última de las tres piezas del command menu (ver README de `sui-command-menu-item`): dos grupos
+de teclas (↑ ↓ «Navegar», ↵ «Seleccionar») y a la derecha un texto con un link de ayuda.
+
+## Cuándo usarlo / cuándo no
+
+**Úsalo** al pie de un command menu **en desktop**, para enseñar las teclas.
+
+**No lo uses** para:
+
+- Mobile: no hay teclado físico; las teclas no dicen nada (README de `sui-kbd`). No se pinta.
+- Un command menu que **no** se mueve con flechas: si el pie dice «↑ ↓ Navegar», las flechas tienen
+  que funcionar. `sui-command-menu-item` no las trae; las cablea quien arma el menú.
+- Botones de un modal: `sui-modal-footer`.
+
+Regla corta: **command menu en desktop con flechas cableadas → footer · mobile → nada.**
+
+## Qué variante usar
+
+> **La guía del DS lo pone como parte opcional del command menu**: un pie para mostrar atajos de
+> teclado o información extra. No trae do/don't. Todo lo de abajo es **propuesta, falta
+> aprobación**, salvo lo marcado canon.
+>
+> Uso medido el 03-10-2026 en `master-pedidos/src/app` (misma exclusión que `sui-dropdown-menu`):
+> **0 usos**.
+
+No tiene variantes. Se decide el copy y si va el bloque de ayuda.
+
+| prop | regla | fuente |
+|---|---|---|
+| `navigateLabel` · `selectLabel` | **Siempre en español**: «Moverte» y «Abrir» (o «Elegir»). Los defaults son `'Navigate'` y `'Select'`. | canon (CANON-SUI §5: copy en español, tuteo) |
+| `helpText` + `helpLink` | Solo si hay adónde mandar a la persona (el WhatsApp de soporte). Si no, `[helpText]="null"` saca el bloque entero. Los defaults están en inglés. | propuesta |
+| `helpLink` como objeto | `{ label, href, target }` dibuja un `<a>` de verdad; con `target: '_blank'` pone `rel="noopener noreferrer"` solo. | API |
+
+## Tamaño en mobile y en web
+
+No tiene tamaños: 48 px de alto, textos 12/16, hasta 600 px de ancho.
+
+| uso | mobile | web | fuente |
+|---|---|---|---|
+| pie del command menu | no se pinta | 48 px | canon para mobile (README de `sui-kbd`: en mobile las teclas no se muestran) |
+
+```html
+@if (!bp.isMobile()) {
+  <sui-command-menu-footer navigateLabel="Moverte" selectLabel="Abrir" [helpText]="null" />
+}
+```
+
+## API
+
+<!-- api:inicio -->
+<!-- generada: no editar a mano — `npm run docs` -->
+
+| input | tipo | default |
+|---|---|---|
+| `navigateLabel` | `string` | `'Navigate'` |
+| `selectLabel` | `string` | `'Select'` |
+| `helpText` | `string \| null` | `"Not what you're looking for? Try the"` |
+| `helpLink` | `SuiLinkConfig \| string \| null` | `'Help Center'` |
+
+| output | payload |
+|---|---|
+| `helpClicked` | `MouseEvent` |
+<!-- api:fin -->
+
+`helpLink` como string dibuja un botón que solo emite `helpClicked`; como `SuiLinkConfig`
+(`{ label, href?, target?, rel? }`) dibuja un `<a>`, y un `href` interno navega dentro de la app.
+
+## Trampas
+
+- **Los cuatro textos vienen en inglés.** Si no se pasan, el pie dice «Navigate», «Select», «Not
+  what you're looking for? Try the» y «Help Center».
+- **`helpText: null` saca también el link**; `helpLink: null` saca solo el link y deja el texto.
+- **Promete flechas que nadie cablea**: ni `sui-command-menu-item` ni el modal mueven la selección
+  con ↑ ↓.
+- Hasta 600 px el texto de ayuda se oculta (queda solo el link): pasa en un modal angosto aunque sea
+  desktop.
+- Las teclas son íconos fijos (↑ ↓ ↵); no se pueden cambiar.
+
+## Ejemplo
+
+```html
+@if (!bp.isMobile()) {
+  <sui-command-menu-footer
+    navigateLabel="Moverte"
+    selectLabel="Abrir"
+    helpText="¿No es lo que buscas? Escríbenos por"
+    [helpLink]="{ label: 'WhatsApp', href: 'https://wa.me/51931819925', target: '_blank' }" />
+}
+```

package/docs/sui-command-menu-item/README.md

@@ -0,0 +1,140 @@
+---
+name: sui-command-menu-item
+selector: sui-command-menu-item
+resumen: Fila de resultado del buscador ⌘K (command menu) que lleva a una pantalla, un pedido o una persona
+alternativas: [sui-dropdown-item (fila de un menú de acciones anclado a un botón), sui-filter-item (fila de un panel de filtros), sui-content-card (resultado que se ve en una lista de la pantalla)]
+---
+
+# sui-command-menu-item
+
+Story: [Organisms/Command Menu/Command Menu Item](https://sui-design-system.web.app/?path=/docs/organisms-command-menu-command-menu-item--docs)
+
+**SUI no tiene un componente «command menu» entero.** Se arma con tres piezas dentro de un
+`sui-modal`: `sui-command-menu-search` arriba, la lista de `sui-command-menu-item` en el medio
+(con cabeceras de grupo `sui-content-divider`) y `sui-command-menu-footer` abajo. Quien lo arma pone
+el filtrado, el teclado y el atajo ⌘K.
+
+## Cuándo usarlo / cuándo no
+
+**Úsalo** para los resultados de un buscador que **lleva a algún lado**: abrir un pedido, ir a una
+pantalla del panel, abrir la ficha de un repartidor o un local. Es el patrón del super admin o del
+panel del local **en desktop**, donde hay teclado.
+
+**No lo uses** para:
+
+- Acciones sobre algo concreto (editar, archivar): `sui-dropdown-item` dentro de un
+  `sui-dropdown-menu`.
+- Elegir un valor de un formulario: `sui-select`.
+- La lista de resultados de una pantalla de búsqueda (la del cliente buscando tiendas): ahí van las
+  cards de la pantalla, no filas de palette.
+- Un menú en mobile: el ⌘K es un patrón de teclado.
+
+Regla corta: **buscar y saltar → command menu · actuar sobre algo → dropdown · elegir un valor →
+select.** La tabla completa está en el README de `sui-dropdown-menu`.
+
+## Qué variante usar
+
+> **La guía del DS define el command menu como el buscador que deja saltar rápido desde cualquier
+> pantalla**, armado dentro de un diálogo, con input, lista, grupos con título, items y un pie con
+> teclas. El item tiene dos tamaños, `small` (default) y `medium`, y el elegido se marca con fondo
+> `bg-weak-50`. No trae do/don't. Lo demás es **propuesta, falta aprobación**.
+>
+> Uso medido el 03-10-2026 en `master-pedidos/src/app` (misma exclusión que `sui-dropdown-menu`):
+> **0 usos**. Solo aparece en la vitrina `master-preview`.
+
+### `type` — qué va a la izquierda
+
+| type | cuándo | fuente |
+|---|---|---|
+| `left-icon` | Ir a una **pantalla** o una sección: «Pedidos», «Mi negocio», «Recargas». | según la guía del DS (item con ícono); el cuándo es propuesta |
+| `avatar` | Una **persona**: repartidor, cliente, dueño de local (`avatar` con `src` o `initials`). | propuesta |
+| `company` | Un **local**: su logo en `avatar.src`. | propuesta |
+| `basic` (default) | Una búsqueda reciente o un resultado sin imagen («Pedido #1234»). | propuesta |
+| `brand` | Un servicio externo con su logo (Yape, WhatsApp), proyectado en `slot="brand"`. | propuesta |
+| `country` | No usar hoy: todo es Perú. | propuesta |
+
+### `size` y los extras
+
+| prop | cuándo | fuente |
+|---|---|---|
+| `size="small"` (default, 40) | Listas de resultados de una línea (`title` + `sublabel`). | según la guía del DS (default `small`) |
+| `size="medium"` (64) | Cuando el resultado necesita una segunda línea (`description`) para distinguirse: «Pedido #1234» · «Juan Pérez · S/ 45.00». | según la guía del DS (existe); el cuándo es propuesta |
+| `badge` | Un estado corto que ayuda a elegir («Pendiente», «Cerrado»). String = gris `lighter`; objeto `SuiBadgeConfig` para color. | propuesta |
+| `shortcut` | El atajo de esa acción (`sui-kbd`). Solo web. | canon (README de `sui-kbd`: en mobile no se pinta) |
+| `showButton` | Una flecha a la derecha cuando el resultado abre otra pantalla. | propuesta |
+
+## Tamaño en mobile y en web
+
+El command menu es un patrón de desktop. En mobile no hay ⌘K ni flechas; si se reusa la lista en un
+buscador de mobile, la fila `small` mide 40 y queda debajo de los 44 del dedo.
+
+| uso | mobile | web | fuente |
+|---|---|---|---|
+| resultado de una línea | `medium` (64) | `small` (40) | propuesta, falta aprobación |
+| resultado con descripción | `medium` (64) | `medium` (64) | propuesta |
+
+```html
+<sui-command-menu-item [size]="bp.isMobile() ? 'medium' : 'small'" … />   <!-- bp = BreakpointsService -->
+```
+
+## API
+
+<!-- api:inicio -->
+<!-- generada: no editar a mano — `npm run docs` -->
+
+| input | tipo | default |
+|---|---|---|
+| `type` | `'basic' \| 'left-icon' \| 'avatar' \| 'brand' \| 'company' \| 'country'` | `'basic'` |
+| `size` | `'small' \| 'medium'` | `'small'` |
+| `title` | `string` | — (requerido) |
+| `sublabel` | `string \| null` | `null` |
+| `description` | `string \| null` | `null` |
+| `icon` | `string \| null` | `null` |
+| `avatar` | `SuiAvatarConfig \| string \| null` | `null` |
+| `flagName` | `SuiFlagName \| null` | `null` |
+| `badge` | `SuiBadgeConfig \| string \| null` | `null` |
+| `shortcut` | `string \| null` | `null` |
+| `showButton` | `boolean` | `false` |
+
+| output | payload |
+|---|---|
+| `clicked` | `MouseEvent` |
+| `buttonClicked` | `MouseEvent` |
+<!-- api:fin -->
+
+Slot: `[slot=brand]` (solo con `type="brand"`). `avatar` acepta un string (la URL) o
+`SuiAvatarConfig` (`{ src?, initials?, color? }`).
+
+## Trampas
+
+- **`(clicked)` nunca sale.** El componente declara el output pero no lo conecta a ningún clic (el
+  host no escucha `click` y el template no llama a `onClick`; el spec no lo prueba). Escucha el
+  `(click)` nativo del host: `<sui-command-menu-item (click)="ir(r)" … />`.
+- **Enter y Espacio no hacen nada.** Tiene `role="button"` y `tabindex="0"`, así que se enfoca con
+  Tab, pero activarlo con teclado lo tiene que cablear quien lo usa (`(keydown.enter)`).
+- **No hay estado «elegido»** para la navegación con flechas: el fondo `weak-50` sale con hover y
+  con `:focus-visible`. Para mover la selección con ↑ ↓ hay que mover el foco entre filas.
+- `description` solo se ve en `medium`.
+- `showButton` pinta una flecha con `ariaLabel="Abrir"` fijo, y su clic sale por `buttonClicked`
+  (no burbujea al item).
+- `type="left-icon"` sin `icon` en `small` cae al ícono `apps-line`; en `medium` queda el círculo vacío.
+- Mide como máximo 600 px de ancho.
+- El host borra el atributo `title` nativo (no aparece el tooltip gris del navegador).
+
+## Ejemplo
+
+```html
+<sui-modal [(open)]="buscadorAbierto" size="large" [fullscreen]="true">
+  <sui-command-menu-search [(value)]="q" placeholder="Busca pedidos, locales o repartidores…"
+                           [shortcut]="!bp.isMobile()" />
+  <sui-content-divider type="text" text="Pantallas" />
+  @for (p of pantallas(); track p.ruta) {
+    <sui-command-menu-item type="left-icon" [icon]="p.icono" [title]="p.nombre"
+                           [size]="bp.isMobile() ? 'medium' : 'small'"
+                           (click)="ir(p.ruta)" (keydown.enter)="ir(p.ruta)" />
+  }
+  @if (!bp.isMobile()) {
+    <sui-command-menu-footer navigateLabel="Moverte" selectLabel="Abrir" [helpText]="null" />
+  }
+</sui-modal>
+```

package/docs/sui-command-menu-search/README.md

@@ -0,0 +1,105 @@
+---
+name: sui-command-menu-search
+selector: sui-command-menu-search
+resumen: Campo de arriba del buscador ⌘K (command menu), sin caja y con borde inferior
+alternativas: [sui-input type="search" (buscador de una pantalla), sui-dropdown-search (filtrar los items de un menú flotante)]
+---
+
+# sui-command-menu-search
+
+Story: [Organisms/Command Menu/Command Menu Search](https://sui-design-system.web.app/?path=/docs/organisms-command-menu-command-menu-search--docs)
+
+Es la primera de las tres piezas del command menu (ver README de `sui-command-menu-item`): el
+campo, el chip ⌘K y un botón para limpiar. **No busca**: emite el texto y quien lo usa filtra.
+
+## Cuándo usarlo / cuándo no
+
+**Úsalo** arriba de un command menu armado dentro de un `sui-modal`: el buscador que salta a
+pedidos, locales, repartidores o pantallas del panel en desktop.
+
+**No lo uses** para:
+
+- El buscador de una pantalla o de una lista a la vista: `sui-input type="search"` (ya lleva
+  `enterkeyhint="search"`, tamaños y label).
+- Filtrar las opciones de un menú anclado a un botón: `sui-dropdown-search`.
+- Fuera del command menu: no tiene caja, solo un borde abajo; suelto parece texto.
+
+Regla corta: **buscar en toda la app → command-menu-search · buscar en una pantalla → sui-input
+search · filtrar un menú → dropdown-search.**
+
+## Qué variante usar
+
+> **La guía del DS define el command menu como el buscador que deja saltar rápido desde cualquier
+> pantalla**; el input es su primera parte. No dice nada del chip ni del botón de la derecha (salen
+> del Figma del DS). Todo lo de abajo es **propuesta, falta aprobación**, salvo lo marcado canon.
+>
+> Uso medido el 03-10-2026 en `master-pedidos/src/app` (misma exclusión que `sui-dropdown-menu`):
+> **0 usos**.
+
+Los tres estados salen solos del `value`: vacío (lupa gris, placeholder gris), hover (placeholder
+más oscuro) y con texto (lupa naranja, X para limpiar).
+
+| prop | regla | fuente |
+|---|---|---|
+| `placeholder` | **Siempre**, en español y diciendo qué se busca: «Busca pedidos, locales o repartidores…». El default es `'Search or jump to'`. | canon (CANON-SUI §5: copy en español, elipsis `…`) |
+| `shortcut` | `true` solo en web; en mobile `false` (no hay teclado físico). | canon (README de `sui-kbd`) |
+| `button` | Déjalo en `true`: la X de limpiar ahorra borrar a mano. El ícono de info del estado vacío no hace nada. | propuesta |
+
+## Tamaño en mobile y en web
+
+No tiene tamaños: 48 px de alto (14 + 20 + 13 + 1 de borde), texto 14/20, hasta 600 px de ancho.
+
+| uso | mobile | web | fuente |
+|---|---|---|---|
+| buscador del command menu | igual, sin chip ⌘K | igual, con chip ⌘K | canon para el chip (README de `sui-kbd`); el resto, propuesta |
+
+```html
+<sui-command-menu-search [(value)]="q" placeholder="Busca pedidos, locales o repartidores…"
+                         [shortcut]="!bp.isMobile()" />   <!-- bp = BreakpointsService -->
+```
+
+## API
+
+<!-- api:inicio -->
+<!-- generada: no editar a mano — `npm run docs` -->
+
+| input | tipo | default |
+|---|---|---|
+| `value` | `string` | `''` |
+| `placeholder` | `string` | `'Search or jump to'` |
+| `shortcut` | `boolean` | `true` |
+| `button` | `boolean` | `true` |
+
+| output | payload |
+|---|---|
+| `valueChange` | `string` |
+| `cleared` | `void` |
+<!-- api:fin -->
+
+`value` no es `model`, pero el par `value` + `valueChange` permite `[(value)]`. La X emite
+`valueChange('')` y `cleared`, y devuelve el foco al campo.
+
+## Trampas
+
+- **Sin `[(value)]` no funciona bien.** El componente no guarda lo que se escribe: solo lo emite. Si
+  no se le devuelve el `value`, la X nunca aparece y la lupa no cambia: el estado «con texto» sale
+  del input `value`, no de lo escrito.
+- **El chip dice ⌘K, fijo.** En Windows el atajo es Ctrl+K y el chip no cambia; tampoco hay atajo
+  real: el `keydown` global lo cablea quien arma el command menu.
+- **iOS hace zoom al enfocarlo**: el campo está en 14 px y la regla de la app pide 16 px en los
+  inputs de mobile (CLAUDE.md, «Responsive mobile»).
+- **El teclado no trae la lupa**: el `<input>` es `type="text"` sin `enterkeyhint="search"` (CLAUDE.md,
+  «La lupa del teclado»).
+- **El campo no tiene nombre accesible**: solo placeholder, sin `aria-label`.
+- No tiene `disabled`.
+- El ícono de info del estado vacío es decorativo: no abre ayuda ni tiene `aria-label`.
+
+## Ejemplo
+
+```html
+<sui-command-menu-search
+  [(value)]="q"
+  placeholder="Busca pedidos, locales o repartidores…"
+  [shortcut]="!bp.isMobile()"
+  (cleared)="resultados.set([])" />
+```

package/docs/sui-compact-select/README.md

@@ -53,7 +53,10 @@ Regla corta: **filtro suelto en una barra, ancho al texto → compact · campo c
 
 Tiene los tres tamaños de la guía —`medium` (40), `small` (36), `xsmall` (32)— y **`large` (48)**,
 extensión SUI para mobile: mide lo mismo que un `sui-button` `large` de la misma barra. En `large`
-crece el aire (padding 14 · 12, radio 12); el texto y los íconos siguen en 14/20 y 20.
+crece el aire (padding 12 a los lados, radio 12) y los íconos siguen en 20.
+
+En large y xlarge el texto sube a 16 px (regla del 03-10-2026): el valor y las opciones del menú
+van en 16/24 en `large` y el padding vertical baja para que el alto siga en 48 (trigger) y 44 (opción).
 
 Las opciones del menú siguen al `size` como en `sui-select`: 36 hasta `medium`, **44 en `large`**, y
 **44 en mobile (≤ 767 px) con cualquier tamaño**.

package/docs/sui-compact-select-for-input/README.md

@@ -51,6 +51,9 @@ contiene**: el selector ocupa todo el alto interior del campo (46 · 38 · 34 ·
 toca (y su hover) cubre el campo de arriba a abajo. Sus opciones miden 44 en `large` y en mobile
 (≤ 767 px); 36 en el resto, como en `sui-select`.
 
+En large y xlarge el texto sube a 16 px (regla del 03-10-2026): en `large` el valor y las opciones van
+en 16/24, igual que el valor del `sui-input` large; el alto no cambia (46 dentro del campo, 44 la opción).
+
 | size del input y del selector | campo | fuente |
 |---|---|---|
 | `large` | 48 | canon (aprobado por el dueño, 03-10-2026), extensión SUI |

package/docs/sui-counter-input/README.md

@@ -70,6 +70,9 @@ dentro de la píldora). El ícono es de 20 hasta `large` y de 24 en `xlarge`.
 | `medium` (default) · `small` · `xsmall` | 40 · 36 · 32 | 24 | según la guía del DS |
 | `2xsmall` | 28 | 24 | extensión SUI |
 
+En large y xlarge el texto sube a 16 px (regla del 03-10-2026): el número va en 16/24; el alto del
+campo no cambia (lo ponen los botones).
+
 | uso | mobile | web | fuente |
 |---|---|---|---|
 | cantidad junto al CTA (detalle del producto) | `large` (48), igual que el botón | `large` | propuesta (ya es práctica en `restaurant-menu.html:480`) |

package/docs/sui-datepicker/README.md

@@ -100,6 +100,10 @@ el teléfono el footer del rango pone el resumen «Rango: …» arriba y los dos
 | flechas de mes | 24 | 40 | 40 | canon (aprobado por el dueño, 03-10-2026), extensión SUI |
 | Cancelar / Aplicar | 36 | 48 | 48 | canon (aprobado por el dueño, 03-10-2026), extensión SUI |
 
+En large y xlarge el texto sube a 16 px (regla del 03-10-2026): con `large`, la fecha del campo (y
+su placeholder) va en 16/24. El calendario no cambia: los días, el mes y el resumen del rango siguen
+en 14.
+
 ```html
 <!-- Web: popover. Mobile: en línea dentro de un sui-modal fullscreen. -->
 @if (bp.isMobile()) {

package/docs/sui-dropdown-caption/README.md

@@ -0,0 +1,92 @@
+---
+name: sui-dropdown-caption
+selector: sui-dropdown-caption
+resumen: Texto gris de pie dentro de un menú flotante (una pista, la versión, cuándo se actualizó)
+alternativas: [sui-content-divider (cabecera de un grupo de items), sui-form-hint (ayuda debajo de un campo), sui-empty-state (el menú no tiene resultados)]
+---
+
+# sui-dropdown-caption
+
+Story: [Organisms/Dropdown/Dropdown Caption](https://sui-design-system.web.app/?path=/docs/organisms-dropdown-dropdown-caption--docs)
+
+Una línea de texto `soft-400` 14/20 con 8 px de aire, pensada para el **pie** del panel de un
+`sui-dropdown-menu`. No tiene inputs: el texto se proyecta.
+
+## Cuándo usarlo / cuándo no
+
+**Úsalo** para un dato accesorio al final del menú, que nadie tiene que leer para usarlo: una
+pista («Presiona Enter para agregar»), la versión, «Actualizado hace 5 min».
+
+**No lo uses** para:
+
+- La cabecera de un grupo de items («Negocios», «Sucursales»): `sui-content-divider` `text`.
+- Algo que la persona necesita para decidir: el gris `soft-400` es el de los metadatos y
+  placeholders (CANON-SUI §0); lo importante va en el `description` del item.
+- Decir que la búsqueda no encontró nada: un texto de vacío con la voz del CANON («No encontramos
+  nada con ese filtro»), sin CTA.
+- Fuera de un menú: en una pantalla, el metadato es texto con `paragraph-xs` + `soft-400`.
+
+Regla corta: **pie del menú → caption · cabecera de grupo → content-divider · ayuda de un campo →
+form-hint.**
+
+## Qué variante usar
+
+> **La guía del DS no tiene una pieza «caption»** en su dropdown: tiene etiqueta de grupo y
+> separador. La caption sale del Figma del DS («Dropdown Misc Items»). Todo lo de abajo es
+> **propuesta, falta aprobación**.
+>
+> Uso medido el 03-10-2026 en `master-pedidos/src/app` (misma exclusión que `sui-dropdown-menu`):
+> **0 usos**.
+
+No tiene variantes. Lo único que se decide es el texto:
+
+| qué | regla | fuente |
+|---|---|---|
+| largo | Una línea; si no entra, corta palabra y salta de línea (`word-break: break-word`). | propuesta |
+| copy | Sentence case, con punto solo si son dos frases. Tuteo: «Presiona Enter para agregar». | canon (CANON-SUI §5, `docs/VOZ-Y-ESCRITURA.md`) |
+| posición | Al final del panel, después del último item. | propuesta |
+
+**Candidatos de hoy:** las cabeceras de grupo a mano del switcher del sidebar
+(`components/sidebar/sidebar.html:67`, `:88`, `:104`) **no** son caption: son cabeceras de grupo y van
+con `sui-content-divider`.
+
+## Tamaño en mobile y en web
+
+No tiene tamaños: 14/20 con 8 px de padding en los dos. No se toca, así que no le aplica el mínimo
+de 44 px del dedo.
+
+| uso | mobile | web | fuente |
+|---|---|---|---|
+| pie de un menú | igual (14/20) | igual (14/20) | propuesta |
+
+## API
+
+<!-- api:inicio -->
+<!-- generada: no editar a mano — `npm run docs` -->
+
+Inputs: ninguno.
+
+Outputs: ninguno.
+<!-- api:fin -->
+
+Slot: el contenido por defecto (`<ng-content />`) es el texto.
+
+## Trampas
+
+- **No es una cabecera de grupo.** Es gris claro y va al pie; para «Negocios» / «Sucursales» se usa
+  `sui-content-divider`.
+- Tiene fondo blanco propio (`bg-white-0`) y ocupa todo el ancho: sobre un panel de otro color se nota
+  la caja.
+- No lleva `role`: el lector de pantalla lo lee como texto suelto dentro del menú.
+
+## Ejemplo
+
+```html
+<ng-template suiDropdownPanel>
+  <sui-dropdown-search [(value)]="busqueda" placeholder="Buscar etiqueta…" />
+  @for (e of etiquetasFiltradas(); track e) {
+    <sui-dropdown-item [label]="e" (clicked)="menu.close(); elegir(e)" />
+  }
+  <sui-dropdown-caption>Presiona Enter para crear «{{ busqueda() }}»</sui-dropdown-caption>
+</ng-template>
+```

package/docs/sui-dropdown-item/README.md

@@ -0,0 +1,163 @@
+---
+name: sui-dropdown-item
+selector: sui-dropdown-item
+resumen: Fila de un menú flotante o de una lista de opciones, con ícono, bandera, avatar o logo a la izquierda y badge o atajo a la derecha
+alternativas: [sui-command-menu-item (fila del buscador ⌘K), sui-filter-item (fila de un panel de filtros), sui-sidebar (navegación lateral, con sus items), sui-radio-label (opciones fijas a la vista en un formulario)]
+---
+
+# sui-dropdown-item
+
+Story: [Organisms/Dropdown/Dropdown Item](https://sui-design-system.web.app/?path=/docs/organisms-dropdown-dropdown-item--docs)
+
+Va **dentro** de algo que lo contiene: el panel de un `sui-dropdown-menu`, la lista de un
+`sui-select` (que lo arma solo) o el panel del header de `sui-sidebar`. Suelto en una pantalla no
+tiene sentido: para una lista a la vista hay otros componentes.
+
+## Cuándo usarlo / cuándo no
+
+**Úsalo** para cada fila de un menú de acciones (`mode="menuitem"`, el default) o de una lista
+donde se elige un valor y el elegido queda marcado (`mode="option"`): el ⋮ de una sección, el
+switcher de negocio y sucursal del sidebar.
+
+**No lo uses** para:
+
+- Las opciones de un `sui-select` o `sui-compact-select`: el select ya las pinta con este mismo
+  componente; se le pasan `options`, no items.
+- Una lista de navegación lateral: `sui-sidebar` y sus items (`SuiSidebarItem`).
+- Las filas del buscador ⌘K: `sui-command-menu-item` (otra altura y otro marcado).
+- Opciones fijas que deberían verse todas en un formulario: `sui-radio-label` / `sui-radio-card`.
+
+Regla corta: **hace algo → `menuitem` · elige y queda marcado → `option`.** Ver la relación entre
+dropdown, select y command menu en el README de `sui-dropdown-menu`.
+
+## Qué variante usar
+
+> **La guía del DS lo arma por partes** (item + ícono, y adentro bandera, avatar, badge o atajo),
+> con una prop `inset` para alinear los que no llevan ícono. No dice cuándo va cada tamaño ni cada
+> modo. Lo que sigue es **propuesta, falta aprobación**, salvo lo marcado.
+>
+> Uso medido el 03-10-2026 en `master-pedidos/src/app` (misma exclusión que `sui-dropdown-menu`):
+> **10 usos, los 10 en `size="large"`**. 7 `mode="option"` en los switchers del sidebar
+> (`components/sidebar/sidebar.html:69`, `:89`, `:96`, `:106`, `layouts/customer/customer-layout.html:27`,
+> `layouts/driver/driver-layout.html:25`, `layouts/master/master-layout.html:27`) y 3 `menuitem` con
+> `leadingFramed` en el ⋮ de `components/option-sections-manager/option-sections-manager.html:40`, `:43`, `:46`.
+
+### `mode` — qué es la fila
+
+| mode | cuándo | ejemplo real de la app | fuente |
+|---|---|---|---|
+| `menuitem` (default) | La fila **hace algo**: editar, archivar, ir a otra pantalla. `selected` no pinta nada. | `option-sections-manager.html:40` («Editar») | propuesta |
+| `option` | La fila **es un valor** y el elegido queda marcado (fondo `primary-alpha-10` + check a la derecha). El contenedor lleva `role="listbox"`. | `sidebar.html:69` (el negocio actual) | propuesta (ya es práctica) |
+
+### `size`
+
+| size | alto | cuándo | fuente |
+|---|---|---|---|
+| `small` (default) | 36 | Menú de acciones en web, una línea (label + `sublabel` en la misma línea). | según la guía del DS (Figma: Small 36) |
+| `large` | 56 | Toda fila en mobile; en web, cuando hay segunda línea (`description`) o el ícono va enmarcado. | según la guía del DS (Figma: Large 56); el cuándo es propuesta |
+| `xlarge` | 76 | Extensión SUI. Sin uso hoy. | — |
+
+### Las piezas
+
+| prop / slot | cuándo | fuente |
+|---|---|---|
+| `slot="leading"` | `sui-icon` (20), `sui-flag`, `sui-avatar` (`xs`), `sui-brand-logo` o `sui-checkbox`. El tipo de la fila sale de lo que se proyecta. | según la guía del DS (se arma por partes) |
+| `leadingFramed` | Solo con un `sui-icon` en `large`/`xlarge`: lo mete en un círculo de 40 con borde. Nunca con avatar, bandera o logo (ya traen forma). | según la guía del DS (Figma Large, tipo basic) |
+| `sublabel` | Dato corto al lado del label en `small` («(es)», «@juan»). | según la guía del DS |
+| `description` | Segunda línea en `large`: la aclaración que ayuda a elegir. **En `small` no se ve.** | según la guía del DS |
+| `shortcut` | Solo web (en mobile no hay teclado físico, ver README de `sui-kbd`). | canon (README de `sui-kbd`) |
+| `slot="trailing"` | Badge primero, después el atajo (lo pone el componente), al final un switch o botón. | según la guía del DS (orden del Figma) |
+| `disabled` | Existe pero hoy no se puede: queda gris claro y no recibe toques. | según la guía del DS |
+| `highlighted` | Lo usa el select para la navegación con flechas. A mano no hace falta. | propuesta |
+
+**Usos de hoy que romperían la propuesta:**
+
+- **4 filas de «Cambiar de rol» en `mode="option"` que nunca marcan `selected`**:
+  `customer-layout.html:27`, `driver-layout.html:25`, `master-layout.html:27` (y `sidebar.html:106`).
+  Cambiar de rol es una acción, no un valor elegido: o se marca el rol actual con `selected`, o
+  pasan a `menuitem` con el contenedor en `role="menu"`. **A discutir.**
+- **`sublabel` en `large`** en esos mismos switchers: en `large` el sublabel cae abajo en 12/16
+  `soft-400` (gris claro). Para la segunda línea de `large` el componente tiene `description`
+  (`sub-600`, se lee mejor).
+- **Íconos de 18 dentro de `leadingFramed`**: `option-sections-manager.html:41`, `:44`, `:47`. El
+  círculo está medido para un ícono de 20 (20 + 10 + 10 = 40); con 18 queda de 38.
+
+## Tamaño en mobile y en web
+
+El item **no cambia solo en mobile**: no tiene `@media`. El 44 de mobile que tienen las opciones de
+`sui-select` lo pone el panel del select, no el item. Suelto, un `small` mide 36 también en el
+celular: queda debajo de los 44 del dedo.
+
+| uso | mobile | web | fuente |
+|---|---|---|---|
+| menú de acciones (⋮) | `large` (56) | `small` (36) | propuesta, falta aprobación |
+| switcher con segunda línea (negocio + dirección) | `large` (56) | `large` (56) | propuesta (ya es práctica en el sidebar) |
+| opciones de un select | las pone el select (44) | las pone el select (36–48) | canon (README de `sui-select`, aprobado 03-10-2026) |
+
+```html
+<sui-dropdown-item label="Editar" [size]="bp.isMobile() ? 'large' : 'small'" … />   <!-- bp = BreakpointsService -->
+```
+
+En large y xlarge el texto sube a 16 px (regla del 03-10-2026). El label va en Label/Medium 16/24
+(el nodo de Figma del large lo dibuja en 14); la description no cambia en large (12) y el alto
+sigue en 56: el padding-y bajó de 8 a 6.
+
+## API
+
+<!-- api:inicio -->
+<!-- generada: no editar a mano — `npm run docs` -->
+
+| input | tipo | default |
+|---|---|---|
+| `label` | `string` | — (requerido) |
+| `sublabel` | `string \| null` | `null` |
+| `description` | `string \| null` | `null` |
+| `size` | `'small' \| 'large' \| 'xlarge'` | `'small'` |
+| `leadingFramed` | `boolean` | `false` |
+| `mode` | `'menuitem' \| 'option'` | `'menuitem'` |
+| `selected` | `boolean` | `false` |
+| `highlighted` | `boolean` | `false` |
+| `disabled` | `boolean` | `false` |
+| `shortcut` | `string \| null` | `null` |
+
+| output | payload |
+|---|---|
+| `clicked` | `Event` |
+<!-- api:fin -->
+
+Slots: `[slot=leading]` y `[slot=trailing]`. `clicked` sale con clic, Enter y Espacio, y no sale si
+está `disabled`.
+
+## Trampas
+
+- **No cierra el menú.** Dentro de un `sui-dropdown-menu` hay que cerrarlo en el handler:
+  `(clicked)="menu.close(); editar()"`.
+- **`selected` en `menuitem` no se ve.** El set del Figma no le da fondo al seleccionado de un menú;
+  solo `mode="option"` pinta fondo naranja suave + check. Si la fila tiene que verse marcada, es
+  `option`.
+- **CANON-SUI §4.2 mezcla los dos modos**: dice que la opción de lista «no lleva fondo de selección»
+  y a la vez que se marca con `primary-alpha-10`. Lo que hace el código: `menuitem` seleccionado =
+  sin fondo; `option` seleccionado = `primary-alpha-10` + check (hover `primary-alpha-16`).
+- **`description` solo existe en `large`/`xlarge`.** En `small` se descarta sin avisar.
+- **`leadingFramed` solo hace algo en `large`/`xlarge`.**
+- `role="option"` necesita un padre con `role="listbox"` (los switchers lo ponen a mano).
+- `disabled` no usa opacidad: baja el texto y el ícono a `disabled-300`; un avatar o una bandera
+  quedan al 48 %.
+- El label corta con `…` en una línea: no hace salto de línea.
+- Ya trae los listeners `touchstart`/`touchend` para el `:active` pegado de iOS.
+
+## Ejemplo
+
+```html
+<!-- Acción en un menú -->
+<sui-dropdown-item label="Archivar" [size]="bp.isMobile() ? 'large' : 'small'"
+                   (clicked)="menu.close(); archivar()">
+  <sui-icon slot="leading" name="archive-line" [size]="20" />
+</sui-dropdown-item>
+
+<!-- Valor elegido en un switcher (el contenedor lleva role="listbox") -->
+<sui-dropdown-item [label]="local.name" [description]="local.address" mode="option" size="large"
+                   [selected]="local.id === localActual()" (clicked)="cambiarLocal(local.id)">
+  <sui-avatar slot="leading" size="xs" [src]="local.imageUrl" [initials]="local.name.charAt(0)" />
+</sui-dropdown-item>
+```