@ajuarezso/sui-design-system 0.21.0 → 0.23.0

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

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

@@ -0,0 +1,196 @@
+---
+name: sui-dropdown-menu
+selector: sui-dropdown-menu, ng-template[suiDropdownPanel]
+resumen: Menú flotante anclado a un botón (el kebab ⋮ de una card, un avatar) con acciones sobre eso; también es el overlay que usan por dentro los selects
+alternativas: [sui-select (elegir un valor de un formulario), sui-modal-sheet (más de 5 acciones o una lista larga en mobile), sui-popover (explicar algo con una flecha, sin anclaje propio), sui-tooltip (ayuda corta al pasar el mouse), sui-command-menu-item (buscar y saltar con ⌘K en desktop)]
+---
+
+# sui-dropdown-menu
+
+Story: [Organisms/Dropdown/Dropdown Menu](https://sui-design-system.web.app/?path=/docs/organisms-dropdown-dropdown-menu--docs)
+
+Es **solo el contenedor**: abre y cierra el panel, lo ancla al trigger (CDK Overlay), lo cierra al
+tocar afuera o con Escape y lo hace seguir al scroll. Lo que va adentro se arma con las piezas
+hermanas: `sui-dropdown-item` (las filas), `sui-dropdown-search` (el buscador de arriba) y
+`sui-dropdown-caption` (el texto de pie).
+
+## Cuándo usarlo / cuándo no
+
+**Úsalo** para un puñado de **acciones sobre algo concreto** que no merecen estar siempre a la
+vista: el ⋮ de una card («Editar», «Aplicar a productos», «Archivar»), el menú de una fila, un
+cambio de cuenta. También para anclar un panel chico a un botón cuando `sui-popover` no sirve
+(no se ancla solo).
+
+**No lo uses** para:
+
+- Elegir un valor de un formulario (distrito, categoría): `sui-select`, que ya es un
+  `sui-dropdown-menu` por dentro con su campo, su teclado y su `ControlValueAccessor`. Armar un
+  select a mano con este componente es rehacer lo que el select ya resuelve.
+- Una sola acción: un botón con su ícono (lápiz, tacho). Un ⋮ que abre un menú de un solo item es
+  un toque de más.
+- Acciones que la persona usa todo el rato: van a la vista, como botones.
+- Buscar en toda la app: el command menu (`sui-command-menu-search` + `-item` + `-footer`).
+- Explicar algo: `sui-tooltip` (web) o `sui-popover`.
+
+Regla corta: **acciones sobre algo → dropdown-menu · elegir un valor → select · buscar y saltar →
+command menu · explicar → tooltip/popover.**
+
+## Dropdown, select y command menu: cuál va
+
+Los tres muestran una lista flotante, pero responden a preguntas distintas.
+
+| pregunta de la persona | componente | items | rol ARIA | fuente |
+|---|---|---|---|---|
+| «¿qué hago con esto?» (editar, archivar, compartir) | `sui-dropdown-menu` | `sui-dropdown-item` (default `mode="menuitem"`) | `menu` (default) | según la guía del DS («un menú con un conjunto de acciones, abierto desde un botón») |
+| «¿cuál de estos valores elijo?» | `sui-select` / `sui-compact-select` | los arma el select: `sui-dropdown-item mode="option"` | `listbox` | según la guía del DS (el select es el control de una opción) |
+| «¿dónde está X?» (buscar y saltar a cualquier lado) | command menu: `sui-command-menu-search` + `sui-command-menu-item` + `sui-command-menu-footer` dentro de un `sui-modal` | `sui-command-menu-item` | lo arma quien lo usa | según la guía del DS (el command menu vive dentro de un diálogo) |
+
+Por dentro, `sui-select`, `sui-compact-select`, `sui-compact-select-for-input`, `sui-inline-select`,
+`sui-time-picker` y `sui-color-picker` usan este mismo componente con `[origin]` (el trigger es su
+propio campo, que ya lleva su `aria-haspopup`: `listbox` en los selects, `dialog` en los pickers). Por
+eso un arreglo del overlay los toca a todos. Con `[origin]`, `popupRole` no se usa: el wrapper del
+trigger no se dibuja.
+
+## Qué variante usar
+
+> **La guía del DS lo define como el menú de acciones que abre un botón** y lo arma por partes:
+> item con ícono, grupo con su etiqueta, separador, items con casilla o radio y submenús. No trae
+> variantes ni do/don't; el panel arranca en 300 px de ancho y 8 px separado del trigger. Lo
+> demás es **propuesta, falta aprobación**, salvo lo marcado canon.
+>
+> Uso medido el 03-10-2026 en `master-pedidos/src/app` (sin `master-preview`, `master-prototipos`,
+> `mockup-sheets-*`, `dx/*`, `master-rutina`, `master-medico`, `master-ejercicios`, `dev-index` ni las
+> copias de `components/sui/`): **2 usos**. `components/option-sections-manager/option-sections-manager.html:37`
+> (el ⋮ de una sección de opciones, con 3 acciones) y `components/option-image/option-image.ts:52`
+> (panel con un campo para pegar un link, `popupRole="true"`).
+
+### Lo que sí dice la guía del DS
+
+- **Para qué es**: mostrar un menú de acciones o funciones, abierto desde un botón.
+- **Se arma por partes**, no por tipos: el ícono, la bandera, el avatar, el badge o el atajo van
+  dentro del item. En SUI eso es el slot `leading` / `trailing` de `sui-dropdown-item`.
+- **Grupos**: la guía tiene etiqueta de grupo y separador. SUI no trae una pieza propia para la
+  etiqueta: se usa `sui-content-divider` (`text`) para la cabecera y `sui-divider` para el separador.
+- **Submenús, items con casilla y con radio**: existen en la guía; SUI no los tiene armados.
+
+### Las props que importan
+
+| prop | cuándo | fuente |
+|---|---|---|
+| sin props (default) | El caso normal: un ⋮ o un botón con 2 a 5 acciones. El panel se ajusta al contenido. | propuesta |
+| `matchWidth` | El panel debe medir lo mismo que el trigger (un botón ancho que abre opciones). | propuesta |
+| `minWidth` | El trigger es un ícono chico y el panel quedaría angosto: 200 a 240 px. | propuesta |
+| `position="above"` | El trigger vive pegado al borde de abajo (una barra inferior). Con `auto` ya cae arriba si no entra. | propuesta |
+| `popupRole="listbox"` | **Solo** si los items son `mode="option"`. El rol tiene que coincidir con el de los items. | según ARIA (documentado en el `.ts`) |
+| `popupRole="true"` | El panel no es un menú: un campo, un formulario chico (`option-image.ts:52`). | propuesta (ya es práctica) |
+| `origin` | El trigger lo maneja el padre (los selects del DS). En la app no hace falta. | propuesta |
+| `push` | No usar: un panel empujado queda fijo y **se despega del trigger al scrollear**. | canon (comentario del `.ts`, bug real del color picker 21-07-2026) |
+| `flexibleDimensions=false` | Solo paneles de tamaño fijo que no pueden encogerse (el color picker). | propuesta |
+
+**Usos de hoy que rompen la propuesta:**
+
+- **Un ⋮ que no abre menú**: `pages/products/products.html:229` pinta `more-2-fill` («Opciones») y al
+  tocarlo abre la edición directo. O se cambia el ícono por el lápiz, o se abre un menú con las
+  acciones del producto.
+- **Cabeceras de grupo a mano** en el switcher del sidebar: `components/sidebar/sidebar.html:67`,
+  `:88` y `:104` usan `<span class="sidebar-switcher__label">` («Negocios», «Sucursales», «Cambiar
+  de rol») → `sui-content-divider` `text`.
+
+## Tamaño en mobile y en web
+
+El menú **no tiene `size`**: el alto lo ponen los items. El panel mide lo que su contenido, con
+8 px de padding, 4 px entre items y hasta 400 px de alto (después scrollea).
+
+| uso | mobile | web | fuente |
+|---|---|---|---|
+| items de un menú de acciones | `sui-dropdown-item size="large"` (56) | `size="small"` (36) | propuesta; hoy los 3 items del ⋮ van en `large` en las dos |
+| trigger ⋮ | `sui-compact-button` de 40 o más | `sui-compact-button` `large` | propuesta (ver README de `sui-compact-button`) |
+| más de 5 acciones, o alguna destructiva que pide confirmar | `sui-modal-sheet` | `sui-dropdown-menu` | propuesta, falta aprobación |
+
+```html
+<sui-dropdown-item [size]="bp.isMobile() ? 'large' : 'small'" … />   <!-- bp = BreakpointsService -->
+```
+
+## API
+
+<!-- api:inicio -->
+<!-- generada: no editar a mano — `npm run docs` -->
+
+### `sui-dropdown-menu`
+
+| input | tipo | default |
+|---|---|---|
+| `matchWidth` | `boolean` | `false` |
+| `flexibleDimensions` | `boolean` | `true` |
+| `push` | `boolean` | `false` |
+| `minWidth` | `number \| null` | `null` |
+| `position` | `'auto' \| 'below' \| 'above'` | `'auto'` |
+| `viewportMargin` | `number` | `8` |
+| `panelClass` | `string` | `''` |
+| `disabled` | `boolean` | `false` |
+| `popupRole` | `'menu' \| 'listbox' \| 'true'` | `'menu'` |
+| `origin` | `ElementRef<HTMLElement> \| HTMLElement \| null` | `null` |
+
+| output | payload |
+|---|---|
+| `openedChange` | `boolean` |
+
+### `ng-template[suiDropdownPanel]`
+
+Inputs: ninguno.
+
+Outputs: ninguno.
+<!-- api:fin -->
+
+`exportAs: 'suiDropdownMenu'`. Métodos públicos: `open()`, `close()`, `toggle()`. Signal pública:
+`isOpen` (`signal(false)`).
+
+Slots: el trigger se proyecta con el atributo `trigger` (`<sui-compact-button trigger … />`); el
+panel va en un `<ng-template suiDropdownPanel>` (hay que importar `SuiDropdownPanel` junto con
+`SuiDropdownMenu`).
+
+## Trampas
+
+- **El paquete npm no envía estilos.** La caja del panel (fondo, borde, radio, sombra, padding,
+  `max-height`) vive en `src/styles/_sui-dropdown-menu-overlay.scss` del DS, y la app tiene que
+  importar su propia copia (`master-pedidos/src/styles.scss:13`). **La copia de la app está
+  desfasada**: usa `radius-16` + `regular-shadow-medium`; el DS ya va en `radius-10` + `x-small`
+  (alineado al Figma del dropdown).
+- **El item no cierra el menú.** Hay que cerrarlo en el handler:
+  `#menu="suiDropdownMenu"` y `(clicked)="menu.close(); editar()"`.
+- **El panel tiene que ir en `<ng-template suiDropdownPanel>`.** Si los items se ponen directo
+  dentro del `sui-dropdown-menu`, no se proyectan en ningún lado y el menú abre vacío (o no abre:
+  `open()` sale sin panel).
+- **El trigger necesita el atributo `trigger`.** Sin él no se proyecta.
+- **El primer toque afuera solo cierra**: el backdrop es transparente y se come ese toque; no le
+  llega al elemento de abajo.
+- **No hay flechas entre items.** Enter, Espacio y Flecha abajo abren el menú desde el trigger,
+  pero adentro se navega con Tab. Y al abrir, el foco **se queda en el trigger**.
+- `disabled` no abre el menú pero **no pinta nada**: deshabilita también el trigger.
+- El lado (arriba o abajo) se decide al abrir y queda fijo mientras está abierto; si el trigger
+  está pegado al borde derecho, el panel abre hacia la izquierda.
+- Se cierra solo al cambiar de ruta (`disposeOnNavigation`).
+- **El `z-index` del overlay también es de esa hoja.** El DS sube `.cdk-overlay-container` a 1100
+  (encima de `sui-modal`, 1000/1001, y debajo de los toasts); con el 1000 del CDK, un menú abierto
+  dentro de un modal queda detrás. La copia de la app no trae ese bloque: no se verificó en la
+  app, pero es lo primero que hay que mirar si un menú «no abre» dentro de un modal.
+- El host es `display: contents`: no ocupa caja. Para alinearlo, se alinea el trigger.
+
+## Ejemplo
+
+```html
+<sui-dropdown-menu #menu="suiDropdownMenu">
+  <sui-compact-button trigger icon="more-2-line" variantStyle="ghost" size="large"
+                      ariaLabel="Opciones de la sección" />
+  <ng-template suiDropdownPanel>
+    <sui-dropdown-item label="Editar" [size]="bp.isMobile() ? 'large' : 'small'"
+                       (clicked)="menu.close(); editar()">
+      <sui-icon slot="leading" name="pencil-line" [size]="20" />
+    </sui-dropdown-item>
+    <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>
+  </ng-template>
+</sui-dropdown-menu>
+```

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

@@ -0,0 +1,113 @@
+---
+name: sui-dropdown-search
+selector: sui-dropdown-search
+resumen: Buscador sin caja que va arriba del panel de un menú flotante para filtrar sus items
+alternativas: [sui-input type="search" (buscador de una pantalla o una lista a la vista), sui-command-menu-search (buscador del ⌘K), sui-select (elegir de una lista corta, sin buscar)]
+---
+
+# sui-dropdown-search
+
+Story: [Organisms/Dropdown/Dropdown Search](https://sui-design-system.web.app/?path=/docs/organisms-dropdown-dropdown-search--docs)
+
+Es solo el campo: **no filtra nada**. Quien lo usa recibe el texto (`[(value)]`) y decide qué items
+pinta debajo.
+
+## Cuándo usarlo / cuándo no
+
+**Úsalo** arriba del panel de un `sui-dropdown-menu` cuando la lista es larga para scrollear y la
+persona sabe lo que busca: más de ~10 opciones (un repartidor entre 40, un país, una etiqueta).
+
+**No lo uses** para:
+
+- El buscador de una pantalla o de una lista que ya está a la vista: `sui-input type="search"`
+  (con caja, label y tamaños).
+- El ⌘K que busca en toda la app: `sui-command-menu-search`.
+- Una lista corta: con 6 opciones el buscador estorba.
+- Fuera de un panel: no tiene borde ni radio, se pierde en la pantalla.
+
+Regla corta: **filtrar los items de un menú → dropdown-search · buscar en una pantalla → sui-input
+search · buscar en toda la app → command-menu-search.**
+
+`sui-select` **no tiene buscador**. Si un select necesita buscar, hoy se arma con
+`sui-dropdown-menu` + este buscador + `sui-dropdown-item mode="option"` (es lo que muestra su story
+«En contexto»), sabiendo que se pierde el `ControlValueAccessor` del select. Propuesta, falta
+aprobación.
+
+## Qué variante usar
+
+> **La guía del DS no tiene buscador en su dropdown**; el buscador de lista vive en su command
+> menu. Este sale del Figma del DS («Dropdown Misc Items», estados Default / Hover / Active). 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. Los estados salen solos: sin texto, lupa gris; con texto, lupa oscura y una X
+para limpiar.
+
+| prop | regla | fuente |
+|---|---|---|
+| `placeholder` | **Siempre**, en español y con elipsis: «Buscar repartidor…». El default genérico es `'Buscar…'`. | canon (CANON-SUI §5: copy en español, elipsis `…`) |
+| `[(value)]` | El texto; con él se filtra la lista. | API |
+| `disabled` | Extensión SUI, no está en el Figma. Sin caso hoy. | — |
+
+## Tamaño en mobile y en web
+
+No tiene tamaños: 36 px de alto (8 + 20 + 8), texto 14/20, en los dos.
+
+| uso | mobile | web | fuente |
+|---|---|---|---|
+| buscador del menú | igual (36) | igual (36) | propuesta |
+
+En mobile tiene dos problemas que el componente no resuelve (ver «Trampas»): el texto de 14 px hace
+que iOS haga zoom al enfocarlo, y el teclado no muestra la lupa. Para buscar en una lista larga en
+mobile, mejor un `sui-modal-sheet` con `sui-input type="search"` arriba. Propuesta, falta aprobación.
+
+## API
+
+<!-- api:inicio -->
+<!-- generada: no editar a mano — `npm run docs` -->
+
+| input | tipo | default |
+|---|---|---|
+| `value` · model, `[(value)]` | `string` | `''` |
+| `placeholder` | `string` | `'Buscar…'` |
+| `disabled` | `boolean` | `false` |
+
+| output | payload |
+|---|---|
+| `cleared` | `void` |
+| `valueChanged` | `string` |
+<!-- api:fin -->
+
+`valueChanged` sale con cada tecla (lo mismo que `value`, como evento). `cleared` sale al tocar la X,
+que además deja `value` en `''`.
+
+## Trampas
+
+- **No filtra.** Hay que filtrar la lista con el `value` (un `computed` sobre las opciones).
+- **El default del placeholder es genérico** (`'Buscar…'`, en español desde el 04-10-2026): pásalo siempre diciendo qué se busca.
+- **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»). Hoy no hay forma de cambiarlo desde afuera.
+- **El teclado no trae la lupa**: el `<input>` es `type="text"` sin `enterkeyhint="search"` (la regla
+  de la app para buscadores, CLAUDE.md «La lupa del teclado»).
+- **El campo no tiene nombre accesible**: solo placeholder, sin `aria-label`.
+- **Al abrir el menú el foco no entra al buscador**: quien quiera escribir de una tiene que enfocarlo
+  a mano.
+- El `<input>` no tiene `(keydown)`: Enter no hace nada salvo que quien lo usa lo escuche.
+
+## Ejemplo
+
+```html
+<sui-dropdown-menu #menu="suiDropdownMenu" [minWidth]="280">
+  <sui-button trigger variant="stroke" color="neutral">Asignar repartidor</sui-button>
+  <ng-template suiDropdownPanel>
+    <sui-dropdown-search [(value)]="busqueda" placeholder="Buscar repartidor…" />
+    @for (r of repartidoresFiltrados(); track r.uid) {
+      <sui-dropdown-item [label]="r.nombre" (clicked)="menu.close(); asignar(r.uid)">
+        <sui-avatar slot="leading" size="xs" [src]="r.avatarUrl" [initials]="r.nombre.charAt(0)" />
+      </sui-dropdown-item>
+    }
+  </ng-template>
+</sui-dropdown-menu>
+```

package/docs/sui-emoji/README.md

@@ -11,8 +11,8 @@ Story: [Atoms/Emoji](https://sui-design-system.web.app/?path=/docs/atoms-emoji--
 
 ## Cuándo usarlo / cuándo no
 
-**Úsalo** donde la pantalla tiene que **sentirse**, no solo funcionar: un estado vacío, «¡Pedido
-confirmado!», los pasos de una landing, la barra de calificación.
+**Úsalo** donde la pantalla tiene que **sentirse**, no solo funcionar: un estado vacío, «Pedido
+confirmado», los pasos de una landing, la barra de calificación.
 
 **No lo uses** para:
 
@@ -32,10 +32,10 @@ confirmado!», los pasos de una landing, la barra de calificación.
 
 | caso | cómo | fuente |
 |---|---|---|
-| Estados vacíos y celebraciones | Emoji animado, uno solo, en `xl`. Nada de íconos genéricos en un estado vacío. | canon (preferencia del dueño: emojis animados en los estados vacíos) |
+| Estados vacíos y celebraciones | Emoji animado, uno solo, en `xl`. Nada de íconos genéricos en un estado vacío. | canon (CANON-SUI §5.6) para los estados vacíos · propuesta, falta aprobación para celebraciones y el `xl` |
 | Pasos de una landing | `lg`, uno por paso. | propuesta |
 | Junto a un título o dentro de un texto | `md` o `sm`, como acento. | propuesta |
-| Como ícono de un botón | No: el botón lleva `leftIcon`. | propuesta |
+| Como ícono de un botón | No: el botón lleva `leftIcon`. | derivado de CANON-SUI §5.7 (emojis solo en contenido escrito por un usuario; botones con `leftIcon`), falta confirmación |
 
 ### `size`
 
@@ -59,12 +59,12 @@ confirmado!», los pasos de una landing, la barra de calificación.
 
 **Usos de hoy que romperían la propuesta:**
 
-- **2 emojis como ícono de botón**: «Encargarme yo» en `pages/orders/orders.html:322` y `:353` → `leftIcon`.
+- **2 emojis como ícono de botón**: «Encargarme yo» en `pages/orders/orders.html:323` y `:354` → `leftIcon`.
 - **5 animados a la vez** en `pages/public/landing-customers/landing-customers.html:160`–`:184`
   (más otro en `:56`). No tienen copia estática: o se acepta el peso en la landing o se generan
   las copias.
 - **Un catálogo paralelo**: `core/fluent-emoji.ts` arma sus propias URLs (otro CDN incluido) y lo
-  importan 8 archivos (`components/permission-prime-modal/permission-prime-modal.ts`,
+  importan 11 archivos (medido el 04-10-2026) (`components/permission-prime-modal/permission-prime-modal.ts`,
   `pages/role-selector/role-selector.ts`, `pages/customer/order-tracking/order-tracking.ts`…).
 - **10 `<img>` con un emoji**, fuera del componente: `pages/products/add-product/add-product.html:122`
   (la URL del paquete escrita a mano, y 3 más en el mismo archivo),