@ajuarezso/sui-design-system 0.21.0 → 0.22.0

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 es `'Search...'`. | 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` | `'Search...'` |
+| `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 `'Search...'`**, en inglés y con tres puntos. Pásalo siempre.
+- **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-filter/README.md

@@ -0,0 +1,181 @@
+---
+name: sui-filter
+selector: sui-filter-bar, sui-filter-item, sui-filter-panel-header, sui-filter-panel-footer
+resumen: Piezas de filtros de una lista o tabla del panel; la barra horizontal (buscador, vista, orden) y el panel vertical (fila, cabecera con «Limpiar», pie con «Limpiar» / «Aplicar»)
+alternativas: [sui-segmented-control (2 a 4 vistas que se aplican al instante), sui-compact-select (un filtro suelto), sui-tab-chips (filtros rápidos con chips), sui-activity-filter (filtro del feed de actividad), sui-modal-sheet (el panel de filtros en mobile)]
+---
+
+# sui-filter
+
+Story: [Organisms/Filter Bar](https://sui-design-system.web.app/?path=/docs/organisms-filter-bar--docs)
+
+Son **cuatro componentes** en una carpeta, sin uno llamado `sui-filter`:
+
+- `sui-filter-bar`: la **barra horizontal** arriba de una tabla. Es solo layout: un lado
+  izquierdo (`slot="start"`) y uno derecho (`slot="end"`); los controles se proyectan.
+- `sui-filter-item`: una **fila** del panel vertical (una categoría de filtro: «Estado», «Local»).
+- `sui-filter-panel-header`: la **cabecera** del panel, con un link «Limpiar» opcional.
+- `sui-filter-panel-footer`: el **pie** del panel, con «Limpiar» y «Aplicar».
+
+El panel vertical **no existe como contenedor**: se arma con header + items + footer dentro de un
+`sui-dropdown-menu` (web) o de un `sui-modal-sheet` (mobile).
+
+## Cuándo usarlo / cuándo no
+
+**Úsalo** en las listas y tablas del panel del local o del super admin que necesitan filtrar
+(pedidos, productos, repartidores): la barra arriba con el buscador, la vista y el orden; el panel
+cuando hay varias categorías de filtro que se combinan y se aplican juntas.
+
+**No lo uses** para:
+
+- 2 a 4 vistas que se aplican al tocar (Hoy · Semana · Mes): `sui-segmented-control` solo, sin barra.
+- Un único filtro: un `sui-compact-select` o `sui-select` suelto.
+- Filtros rápidos de un toque en mobile (Todos · Pendientes · Entregados): `sui-tab-chips`.
+- El feed de actividad: `sui-activity-filter`.
+
+Regla corta: **barra arriba de una tabla → filter-bar · varias categorías que se aplican juntas →
+panel (header + items + footer) · un filtro suelto → compact-select.**
+
+## Qué variante usar
+
+> **La guía del DS no tiene página de filtros**: estas piezas salen solo del Figma del DS
+> («Filters»: HorizontalFilter y VerticalFilter). 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**. Solo aparecen en la vitrina `master-preview`.
+
+### `sui-filter-bar`
+
+| variant | cuándo | fuente |
+|---|---|---|
+| `table` (default) | Arriba de una tabla: a la izquierda la vista (`sui-segmented-control`), a la derecha el buscador (`sui-input type="search"`) y el orden (`sui-select` o `sui-compact-select`). | propuesta (composición del Figma) |
+| `calendar` | Arriba de una vista por fechas: a la izquierda «Hoy» + el rango (`sui-button-group`), a la derecha el buscador. | propuesta (composición del Figma) |
+
+`variant` solo marca el host (`data-sui-variant`): **no cambia el layout**. Lo que se ve lo deciden
+los controles que se proyectan.
+
+### El panel: `sui-filter-item` + header + footer
+
+| pieza | regla | fuente |
+|---|---|---|
+| `sui-filter-item` `active` | La categoría abierta (la que muestra sus opciones al lado): fondo gris, texto negro, flecha a la derecha. | propuesta (estados del Figma) |
+| `sui-filter-item` `leftIcon` | Un ícono por categoría si ayuda a ubicarla («Estado», «Local», «Repartidor»). | propuesta |
+| `sui-filter-panel-header` `clear` | Pásale texto (`clear="Limpiar"`), no `true`: con `true` dice «Clear». | canon (CANON-SUI §5: copy en español) |
+| `sui-filter-panel-footer` | «Limpiar» a la izquierda (`stroke neutral`), «Aplicar» a la derecha (`filled primary`), mitad y mitad. | canon (orden de `sui-modal-footer`, CLAUDE.md «Botones») |
+| «Limpiar» en header **y** footer | Elegir uno. Con el footer, el header va sin link. | propuesta |
+| `applyButton` deshabilitado | `{ label: 'Aplicar', disabled: !cambio() }` mientras no se toca nada. | propuesta |
+
+## Tamaño en mobile y en web
+
+Ninguna pieza cambia sola en mobile, salvo la barra, que apila sus dos lados por debajo de 640 px.
+
+| pieza | mobile | web | fuente |
+|---|---|---|---|
+| `sui-filter-bar` | sin tamaño; los controles adentro van `large` (48) | sin tamaño; los controles `small` (36) | propuesta (igual que `sui-compact-select` en una barra) |
+| `sui-filter-item` | 36 de alto, no se puede cambiar: debajo de los 44 del dedo | 36 | propuesta |
+| `sui-filter-panel-footer` | `medium` (40) es lo más grande que tiene; en mobile, mejor `sui-modal-footer` (48) dentro de un `sui-modal-sheet` | `small` (36, default) | canon para el 48 de mobile (CLAUDE.md: footer de modal `large`); el resto, propuesta |
+| `sui-filter-panel-header` | sin tamaño | sin tamaño | — |
+
+```html
+<sui-filter-bar>
+  <sui-segmented-control slot="start" … />
+  <div slot="end">
+    <sui-input type="search" [size]="bp.isMobile() ? 'large' : 'small'" placeholder="Buscar pedido…" … />
+  </div>
+</sui-filter-bar>
+```
+
+## API
+
+<!-- api:inicio -->
+<!-- generada: no editar a mano — `npm run docs` -->
+
+### `sui-filter-bar`
+
+| input | tipo | default |
+|---|---|---|
+| `variant` | `'calendar' \| 'table'` | `'table'` |
+
+Outputs: ninguno.
+
+### `sui-filter-item`
+
+| input | tipo | default |
+|---|---|---|
+| `active` | `boolean` | `false` |
+| `disabled` | `boolean` | `false` |
+| `leftIcon` | `string \| null` | `null` |
+| `activeIcon` | `string` | `'arrow-right-s-line'` |
+
+| output | payload |
+|---|---|
+| `selected` | `Event` |
+
+### `sui-filter-panel-footer`
+
+| input | tipo | default |
+|---|---|---|
+| `clearButton` | `SuiFooterButtonConfig \| string` | `'Clear'` |
+| `applyButton` | `SuiFooterButtonConfig \| string` | `'Apply'` |
+| `size` | `'small' \| 'medium'` | `'small'` |
+
+| output | payload |
+|---|---|
+| `clear` | `void` |
+| `apply` | `void` |
+
+### `sui-filter-panel-header`
+
+| input | tipo | default |
+|---|---|---|
+| `label` | `string` | `''` |
+| `leftIcon` | `string \| null` | `null` |
+| `clear` | `string \| boolean` | `false` |
+
+| output | payload |
+|---|---|
+| `clearClick` | `void` |
+<!-- api:fin -->
+
+Slots de `sui-filter-bar`: `[slot=start]`, `[slot=end]` y el contenido por defecto (fila única si no
+se usan los slots). El label de `sui-filter-item` es su contenido proyectado. `clearButton` y
+`applyButton` aceptan un string o `SuiFooterButtonConfig` (`{ label, disabled? }`, la misma interfaz
+de `sui-drawer-footer`).
+
+## Trampas
+
+- **Los textos por defecto están en inglés**: «Clear» y «Apply» en el footer, «Clear» en el header con
+  `clear=true`. Pásalos siempre.
+- **La barra apila a 640 px; la app cambia a mobile a 767.** Entre 641 y 767 px la app ya está en
+  mobile y la barra sigue en una fila.
+- **Varios controles en un lado van en un contenedor.** Cada slot es una fila con 12 px de separación,
+  pero un solo elemento por `slot` queda más ordenado (`<div slot="end">`), como en el Figma.
+- **`sui-filter-item` tiene `role="option"`**: el contenedor tiene que llevar `role="listbox"`.
+- **`active` no es «elegido»**: marca la categoría abierta, no un valor aplicado. Para decir que una
+  categoría tiene un filtro puesto no hay prop (un `sui-badge` en el label es lo más cercano).
+- **El footer separa sus botones 16 px** (del Figma); el canon de la app entre botones hermanos es 12
+  (CANON-SUI §0, `sui-modal-footer`).
+- El footer no llega a `large`: en mobile queda más chico que el footer de cualquier modal.
+- `disabled` del item usa opacidad (no está en el Figma).
+
+## Ejemplo
+
+```html
+<!-- Panel de filtros en web, anclado a un botón «Filtros» -->
+<sui-dropdown-menu #filtros="suiDropdownMenu" [minWidth]="320">
+  <sui-button trigger variant="stroke" color="neutral" size="small">Filtros</sui-button>
+  <ng-template suiDropdownPanel>
+    <sui-filter-panel-header label="Filtros" leftIcon="equalizer-line" />
+    <div role="listbox" aria-label="Categorías de filtro">
+      <sui-filter-item leftIcon="checkbox-circle-line" [active]="cat() === 'estado'"
+                       (selected)="cat.set('estado')">Estado</sui-filter-item>
+      <sui-filter-item leftIcon="store-2-line" [active]="cat() === 'local'"
+                       (selected)="cat.set('local')">Local</sui-filter-item>
+    </div>
+    <sui-filter-panel-footer clearButton="Limpiar"
+                             [applyButton]="{ label: 'Aplicar', disabled: !cambio() }"
+                             (clear)="limpiar()" (apply)="filtros.close(); aplicar()" />
+  </ng-template>
+</sui-dropdown-menu>
+```

package/docs/sui-href/README.md

@@ -0,0 +1,85 @@
+---
+name: sui-href
+selector: a[suiHref]
+resumen: Directiva para los <a> del DS que reciben un href configurable; los links internos navegan con el Router sin recargar la app
+alternativas: [routerLink (link interno escrito en la plantilla de la app), sui-link-button (acción con forma de link, ya usa suiHref por dentro)]
+---
+
+# sui-href
+
+Story: [Utilities/Href](https://sui-design-system.web.app/?path=/docs/utilities-href--docs)
+
+## Cuándo usarlo / cuándo no
+
+**Úsalo** dentro de un componente del DS que recibe un `href` por input y lo pinta en un `<a>`:
+en vez de `[attr.href]="href()"`, `[suiHref]="href()"`. Así un `href="/cliente/pedidos"` que
+viene de la app navega **sin recargar el WebView** (en Capacitor, una recarga pierde el estado y
+tarda segundos) y uno externo se abre normal.
+
+Ya lo usan `sui-link-button`, `sui-compact-button`, `sui-fancy-button`, `sui-social-button`,
+`sui-breadcrumb-item`, `sui-topbar-item`, `sui-brand-logo`, `sui-app-store-badge`, `sui-rating` y
+`sui-progress-bar-label`.
+
+**No lo uses** para:
+
+- Un link interno que escribes en una plantilla de la app: `routerLink`. Es lo que usa la app
+  (98 usos, 0 de `suiHref` el 03-10-2026) y además marca el link activo.
+- Un botón que ejecuta algo: `sui-button` o `sui-link-button` con `(clicked)`.
+
+## Qué variante usar
+
+> **No está en la guía del DS: es una utilidad de SUI**, sin Figma ni variantes.
+
+No tiene variantes. Lo que decide qué hace es la URL:
+
+| `suiHref` | qué hace al tocarlo | fuente |
+|---|---|---|
+| empieza con `/` (no `//`) | `router.navigateByUrl()`: navegación dentro de la app, conserva query y `#` | componente |
+| `https://…`, `mailto:`, `tel:`, `#…`, `//host` | lo que haga el navegador | componente |
+| cualquiera, con `target` distinto de `_self` | lo que haga el navegador (nueva pestaña) | componente |
+| cualquiera, con cmd/ctrl/shift/alt o botón del medio | lo que haga el navegador | componente |
+| `null` o `''` | el `<a>` queda **sin** `href` (no navegable) | componente |
+
+## Tamaño en mobile y en web
+
+No aplica: es una directiva, no dibuja nada. El tamaño es el del componente que la usa.
+
+## API
+
+<!-- api:inicio -->
+<!-- generada: no editar a mano — `npm run docs` -->
+
+| input | tipo | default |
+|---|---|---|
+| `suiHref` | `string \| null` | `null` |
+
+Outputs: ninguno.
+<!-- api:fin -->
+
+Solo se aplica a `<a>` (`selector: a[suiHref]`).
+
+## Trampas
+
+- **El atributo `href` real queda puesto**: el clic del medio, «copiar enlace» y «abrir en
+  pestaña nueva» siguen funcionando. Solo el clic normal se intercepta.
+- **Sin Router no intercepta nada**: en Storybook o en una app sin `provideRouter` es un `href`
+  común y corriente (recarga la página).
+- **Si el componente ya hizo `preventDefault()`** en su propio `(click)`, la directiva no navega.
+  Útil para un link que a veces solo emite un evento.
+- **No marca el link activo** (`routerLinkActive` no lo ve). Para menús de la app, `routerLink`.
+- Un `href` relativo sin `/` inicial (`pedidos/123`) **no** se intercepta: lo resuelve el
+  navegador contra la URL actual y recarga. Pasa rutas absolutas.
+
+## Ejemplo
+
+```html
+<!-- Dentro del template de un componente del DS -->
+<a class="sui-link-button" [suiHref]="href()" [attr.target]="target()">
+  <ng-content />
+</a>
+```
+
+```html
+<!-- Desde la app: el componente del DS ya lo resuelve -->
+<sui-link-button href="/cliente/pedidos">Ver mis pedidos</sui-link-button>
+```