@ajuarezso/sui-design-system 0.20.0 → 0.22.0

package/docs/sui-tooltip/README.md

@@ -0,0 +1,201 @@
+---
+name: sui-tooltip
+selector: "[suiTooltip], [suiTooltipLarge]"
+resumen: Directiva que muestra una ayuda corta al pasar el mouse o al enfocar un elemento; solo web, no sirve con el dedo
+alternativas: [sui-form-hint (ayuda visible bajo un campo), sui-modal-sheet (explicación que se abre al tocar, en mobile), sui-popover (panel que señala algo y pide una acción)]
+---
+
+# sui-tooltip
+
+Story: [Molecules/Tooltip](https://sui-design-system.web.app/?path=/docs/molecules-tooltip--docs)
+
+Es una **directiva**, no una etiqueta: se pone sobre el elemento que explica
+(`<button suiTooltip="Editar">`). El globo lo dibuja `sui-tooltip-panel` en el overlay del CDK.
+
+## Cuándo usarlo / cuándo no
+
+**Úsalo** en **web** para dar contexto a algo que se puede tocar o enfocar: el nombre de un botón
+de solo ícono («Editar», «Exportar»), o qué significa un término al lado de un dato («Tarifa de
+servicio»). Es un extra: la pantalla tiene que entenderse sin él.
+
+**No lo uses** para:
+
+- **Mobile.** No hay hover: la directiva solo escucha `mouseenter` y `focus`. Con el dedo depende de
+  cómo el navegador imite el mouse: a veces abre, se cierra al hacer scroll y no se cierra al tocar
+  afuera. En las pantallas del cliente y del repartidor, la explicación va **visible** (una línea bajo
+  el dato, `sui-form-hint`) o en un `sui-modal-sheet` que se abre al tocar el ícono.
+- Información que hace falta para decidir (un precio, una condición): eso se escribe en la pantalla.
+- Un elemento que no se puede enfocar (`<svg>`, `<span>`): con teclado nunca aparece. El host tiene
+  que ser un botón.
+- Algo que pide una acción («Siguiente», «Entendido»): eso es `sui-popover`.
+
+## Qué variante usar
+
+> La guía del DS dice para qué es y cómo se llaman sus tamaños, pero no cuándo va cada uno. Lo
+> marcado «según la guía del DS» sale de su texto o su código publicado; el resto es **propuesta**.
+>
+> Uso medido el 03-10-2026 en `master-pedidos/src/app` (sin prototipos ni vitrinas): **6 tooltips**
+> en 6 archivos — 2 `suiTooltip` de texto en el panel del local y 4 `suiTooltipLarge` en el flujo de
+> compra del cliente.
+
+### Lo que sí dice la guía del DS
+
+- **Para qué es**: agrega contexto a elementos **interactivos** y aparece al pasar el mouse o con el
+  **foco del teclado**. Por eso no sirve con el dedo.
+- **Tres tamaños**, con nombres corridos un paso respecto a SUI (tabla abajo).
+- **Default**: tema `dark` y tamaño intermedio. SUI arranca en tema `light`.
+- La flecha siempre está; la posición sigue al espacio disponible.
+
+### `size` (input `suiTooltipSize`) — equivalencia con la guía
+
+| SUI | guía | qué es | cuándo | fuente |
+|---|---|---|---|---|
+| `small` (24 px de alto, texto 12) | `xsmall` | texto de una línea, chico | El nombre de un ícono en una tabla o barra densa. | escala según la guía del DS · cuándo: propuesta |
+| `medium` (34 px, texto 14) — default SUI | `small` (default de la guía) | texto de una línea | Lo normal: una frase corta que explica. | escala según la guía del DS · cuándo: propuesta |
+| `large` (280 px, título + descripción + ícono) | `medium` | contenido rico | Explicar un término con título y una o dos frases. Se activa solo al usar `[suiTooltipLarge]`. | escala según la guía del DS · cuándo: propuesta |
+| `xlarge` (320 px) | — | rico, más ancho | No usar hoy. Extensión de SUI. **Cuándo sí:** una explicación rica que en 280 px queda en más de cuatro líneas. | propuesta |
+
+### Contenido: `suiTooltip` o `suiTooltipLarge`
+
+| input | cuándo | ejemplo real de la app | fuente |
+|---|---|---|---|
+| `suiTooltip="…"` | Una frase, sin punto final. | `components/customer-segments/customer-segments.html:8` («Ingresos por tipo de cliente») | propuesta |
+| `[suiTooltipLarge]="{ title, description, icon }"` | Un término que necesita título y explicación. | `core/service-fee.ts:33` («Tarifa de servicio») | propuesta |
+| `suiTooltipLarge.dismissible: true` | No usar hoy: lo deja abierto hasta tocar la X o Escape, que es lo que hace un popover. **Cuándo sí:** en web, una explicación larga que la persona lee con calma mientras mueve el mouse. | `core/service-fee.ts:39` (hoy en `true`, en pantallas solo de mobile) | propuesta |
+
+### `theme`, `position` y el resto
+
+| prop | valor | cuándo | fuente |
+|---|---|---|---|
+| `theme` | `auto` | **Siempre.** Oscuro sobre la app en claro (lo que pide la guía) y claro sobre la app en oscuro. | propuesta (la guía: `dark` por default) |
+| `theme` | `dark` | Igual que `auto` en modo claro, pero no se invierte en modo oscuro. Hoy lo usan los 4 del cliente. | según la guía del DS (default) |
+| `theme` | `light` (default SUI) | No usar hoy: sobre una página clara parece una card más. **Cuándo sí:** ya lo da `auto` en modo oscuro. | propuesta |
+| `position` | `top` (default) | Siempre que haya espacio. Si no lo hay, el CDK lo da vuelta solo. | propuesta |
+| `position` | `right` · `left` | Íconos de una barra lateral angosta (el sidebar colapsado). | propuesta |
+| `position` | `bottom` · `*-start` · `*-end` | Un elemento pegado al borde de arriba o a un costado de la pantalla. | propuesta |
+| `delay` | `200` (default) | Siempre: evita que se abra al cruzar con el mouse. | propuesta |
+| `delay` | otro valor | No usar hoy. **Cuándo sí:** ninguno previsto. | propuesta |
+| `disabled` | `true` | Cuando lo que dice ya está a la vista (el sidebar expandido muestra el nombre). | propuesta |
+| `showArrow` | `true` (default) | Siempre: la flecha dice de qué elemento habla. | según la guía del DS |
+| `showArrow` | `false` | No usar hoy. **Cuándo sí:** sobre un punto de un gráfico, donde la flecha tapa el dato. | propuesta |
+
+### Usos de hoy que rompen la regla
+
+- **4 tooltips en pantallas que solo existen en el celular** (la explicación de la tarifa de
+  servicio del cliente): `pages/customer/cart/cart.html:177`, `pages/customer/checkout/checkout.html:366`,
+  `pages/customer/confirmation/confirmation.html:188`, `pages/customer/order-tracking/order-tracking.html:684`.
+  Rompen la guía (hover o foco). Pasarían a un `sui-modal-sheet` al tocar el ícono, con el mismo
+  texto de `core/service-fee.ts`.
+- **2 tooltips sobre un `<svg>` que no se puede enfocar** (y con `#a3a3a3` suelto):
+  `components/customer-segments/customer-segments.html:8`, `components/product-categories/product-categories.html:8`.
+  Ni el teclado ni el dedo llegan. El host pasaría a un botón de solo ícono con `aria-label`.
+
+## Tamaño en mobile y en web
+
+| uso | mobile | web | fuente |
+|---|---|---|---|
+| nombre de un ícono | no aplica: el ícono lleva el nombre escrito o `aria-label` | `small` | propuesta |
+| frase que explica | no aplica: el texto va visible bajo el dato (`sui-form-hint`) | `medium` | propuesta |
+| explicación con título | no aplica: `sui-modal-sheet` al tocar el ícono | `large` (automático con `[suiTooltipLarge]`) | propuesta |
+
+En pantallas que se usan en los dos (panel del local, super admin), el tooltip se apaga en mobile
+y la ayuda se muestra de otra forma:
+
+```html
+<button class="info" type="button" aria-label="Qué es la tarifa de servicio"
+  [suiTooltipLarge]="tarifa" theme="auto" [disabled]="bp.isMobile()"
+  (click)="bp.isMobile() && abrirExplicacion()">
+  <sui-icon name="information-line" [size]="16" />
+</button>
+```
+
+## «No usar»: por qué no hoy y cuándo sí
+
+| qué | por qué no hoy | cuándo sí, en un flujo nuevo |
+|---|---|---|
+| cualquier tooltip en mobile | no hay hover; con el dedo abre de casualidad | nunca: texto visible o un sheet |
+| `suiTooltipSize="xlarge"` | 280 px alcanzan para lo que hay | una explicación rica que en 280 px pasa de cuatro líneas |
+| `dismissible: true` | queda abierto como un popover | en web, una explicación larga para leer con calma |
+| `theme="light"` | sobre página clara parece una card | ya lo da `auto` en modo oscuro |
+| `showArrow=false` | la flecha dice de qué habla | sobre un punto de un gráfico |
+| `delay` distinto de 200 | se abriría al cruzar con el mouse | ninguno previsto |
+
+## API
+
+<!-- api:inicio -->
+<!-- generada: no editar a mano — `npm run docs` -->
+
+### `[suiTooltip], [suiTooltipLarge]`
+
+| input | tipo | default |
+|---|---|---|
+| `suiTooltip` | `string` | `''` |
+| `suiTooltipLarge` | `SuiTooltipLargeData \| null` | `null` |
+| `position` | `'top' \| 'top-start' \| 'top-end' \| 'right' \| 'bottom' \| 'bottom-start' \| 'bottom-end' \| 'left'` | `'top'` |
+| `suiTooltipSize` (propiedad `size`) | `'small' \| 'medium' \| 'large' \| 'xlarge'` | `'medium'` |
+| `theme` | `'light' \| 'dark' \| 'auto'` | `'light'` |
+| `delay` | `number` | `200` |
+| `disabled` | `boolean` | `false` |
+| `showArrow` | `boolean` | `true` |
+
+Outputs: ninguno.
+
+### `sui-tooltip-panel`
+
+| input | tipo | default |
+|---|---|---|
+| `text` | `string` | `''` |
+| `position` | `'top' \| 'top-start' \| 'top-end' \| 'right' \| 'bottom' \| 'bottom-start' \| 'bottom-end' \| 'left'` | `'top'` |
+| `size` | `'small' \| 'medium' \| 'large' \| 'xlarge'` | `'medium'` |
+| `theme` | `'light' \| 'dark'` | `'light'` |
+| `showArrow` | `boolean` | `true` |
+| `title` | `string \| null` | `null` |
+| `description` | `string \| null` | `null` |
+| `icon` | `string \| null` | `null` |
+| `dismissible` | `boolean` | `false` |
+
+| output | payload |
+|---|---|
+| `dismissed` | `void` |
+<!-- api:fin -->
+
+```ts
+interface SuiTooltipLargeData {
+  title: string;
+  description?: string;
+  icon?: string;          // RemixIcon sin el prefijo ri-
+  dismissible?: boolean;  // true = se queda abierto hasta la X o Escape
+}
+```
+
+`SuiTooltipPanel` (`sui-tooltip-panel`) es el globo que monta la directiva; también se exporta, pero
+no se usa directo en pantallas.
+
+## Trampas
+
+- **El tamaño se pasa como `suiTooltipSize`**, no como `size`: así no choca con el `size` del
+  componente que lo lleva (`<sui-button size="small" suiTooltip="…">`).
+- **`position`, `theme`, `delay` y `disabled` sí se llaman así, sin prefijo**: si el host es un
+  componente con un input del mismo nombre (`disabled` de `sui-button`), el valor llega a los dos.
+- **`suiTooltipSize="large"` con `suiTooltip` de texto dibuja una caja vacía**: el tamaño rico solo
+  lee `suiTooltipLarge`. Con `[suiTooltipLarge]` el tamaño pasa a `large` solo.
+- **Defaults distintos a la guía**: tema `light` (la guía, `dark`) y nombres de tamaño corridos un paso.
+- Se cierra al hacer scroll en cualquier contenedor y con Escape. Con `dismissible`, no se cierra al
+  sacar el mouse.
+- Pone `aria-describedby` en el host y le borra el `title` nativo (si no, saldría además el globo
+  gris del navegador).
+- En `dark`, el ícono del tooltip rico usa un gris fijo del `.scss`, no un token.
+
+## Ejemplo
+
+```html
+<!-- Nombre de un botón de solo ícono, en web -->
+<sui-compact-button icon="download-2-line" ariaLabel="Exportar" suiTooltip="Exportar" theme="auto" />
+
+<!-- Término con explicación, en web -->
+<button type="button" aria-label="Qué es la tarifa de servicio"
+  [suiTooltipLarge]="{ title: 'Tarifa de servicio', description: 'Nos ayuda a mantener la plataforma funcionando.', icon: 'information-line' }"
+  theme="auto">
+  <sui-icon name="information-line" [size]="16" />
+</button>
+```

package/docs/sui-topbar/README.md

@@ -0,0 +1,153 @@
+---
+name: sui-topbar
+selector: sui-topbar
+resumen: Barra de navegación horizontal de escritorio — logo, secciones, buscador, íconos de acción y el chip de la cuenta
+alternativas: [sui-sidebar (la navegación de los roles de la app, con cajón en mobile), sui-page-header (el título de UNA pantalla, sin navegación), sui-topbar-item / sui-topbar-button / sui-topbar-user (las piezas sueltas, para una cabecera armada a mano)]
+---
+
+# sui-topbar
+
+Story: [Organisms/Topbar](https://sui-design-system.web.app/?path=/docs/organisms-topbar--docs)
+
+## Cuándo usarlo / cuándo no
+
+**Úsalo** para una **web de escritorio** que navega por arriba en vez de por una columna:
+una landing con secciones, un panel interno con pocas secciones y mucho ancho para datos.
+Compone las tres piezas de la familia (`sui-topbar-item`, `sui-topbar-button`,
+`sui-topbar-user`) y el atajo con `sui-kbd`.
+
+**No lo uses** para:
+
+- La navegación de los roles de la app (empresa, cliente, repartidor, super admin): es
+  `sui-sidebar`, y en el teléfono la barra inferior. Hoy la topbar tiene **0 usos** en la app.
+- El título de una pantalla con sus acciones: `sui-page-header`.
+- Nada que se vea en un teléfono: el componente no tiene versión mobile (ver «Tamaño»).
+
+Regla corta: **navegación de la app → sidebar · título de pantalla → page header · web de escritorio
+navegada por arriba → topbar.**
+
+## Qué variante usar
+
+> **La guía del DS no tiene página de la topbar.** El componente sale del Figma de SUI (Topbar
+> [Navigation], frame 3814:25274, cuatro ejemplos: con y sin íconos, con buscador abierto o en
+> botón). Sin uso en la app, **todo lo de abajo es propuesta, falta aprobación**, salvo lo que el
+> componente ya fija.
+>
+> Uso medido el 03-10-2026 en `master-pedidos/src/app`: `sui-topbar`, `sui-topbar-item` y
+> `sui-topbar-user` tienen 0 usos; `sui-topbar-button`, 1 en la vitrina de variantes.
+
+| decisión | opción | cuándo | fuente |
+|---|---|---|---|
+| items | sin `icon` | El caso normal: 3-6 secciones con nombre corto. | propuesta, falta aprobación |
+| items | con `icon` | Si **todos** llevan ícono. Mezclar con y sin se lee desordenado. | propuesta, falta aprobación |
+| item con `rightIcon: 'arrow-down-s-line'` | — | Un «Más ⌄» que abre un menú. El menú lo pones tú (`sui-dropdown-menu`) al escuchar `(itemClicked)`. | propuesta, falta aprobación |
+| `search` | objeto con `placeholder` | Buscador abierto de 232 px cuando buscar es la acción principal. | Figma (Type=Default) |
+| `search` | `{ compact: true }` | Ícono de lupa en la zona de acciones; tú abres el buscador real (`sui-modal` o una paleta de comandos) en `(searchClicked)`. | Figma (Type=With Icon) |
+| `actions` | 1-3 íconos | Avisos, ayuda, acciones rápidas. `dot: true` = hay algo nuevo. | propuesta, falta aprobación |
+| `user` | config | El chip abre el menú de la cuenta: pásale `[userOpen]` mientras el menú está abierto. | Figma |
+| `accent` | `brand` (default) | Siempre. `information` es el azul del Figma original. | canon del DS (accent = marca) |
+
+## Tamaño en mobile y en web
+
+La topbar **no tiene `size`** ni ningún breakpoint. Mide 80 de alto (20 + 40 + 20), con
+`padding: 20px 44px` fijo, el buscador abierto en 232 fijos y la navegación con scroll lateral
+oculto si no entra.
+
+| uso | mobile | web | fuente |
+|---|---|---|---|
+| navegación de una web de escritorio | **no usar** | `sui-topbar` | propuesta, falta aprobación |
+
+**Qué pasa en mobile:** nada se adapta. Los 44 px laterales se comen el ancho, los items se
+esconden detrás de un scroll lateral sin pista visual, el buscador no se achica y no hay
+`safe-area-inset-top` (en la app nativa queda debajo del notch). En mobile se usa el patrón de la
+app: barra inferior + cajón `sui-sidebar`. Si algún día hace falta topbar en el teléfono, primero
+hay que agregarle al componente un modo mobile (menú hamburguesa, buscador en botón, safe area).
+
+## «No usar»: por qué no hoy y cuándo sí
+
+| qué | por qué no hoy | cuándo sí, en un flujo nuevo |
+|---|---|---|
+| `sui-topbar` entero | la app navega con sidebar + barra inferior | una landing o un panel solo de escritorio (un tablero para pantalla grande en el local) |
+| `accent="information"` | el activo es naranja de marca | nunca en esta app |
+| `badge` «NEW» en un item | un «nuevo» que nunca se apaga se vuelve ruido | anunciar una sección recién lanzada, y se quita a las dos semanas |
+
+## API
+
+<!-- api:inicio -->
+<!-- generada: no editar a mano — `npm run docs` -->
+
+| input | tipo | default |
+|---|---|---|
+| `items` | `SuiTopbarEntry[]` | `[]` |
+| `activeValue` | `string \| null` | `null` |
+| `accent` | `'brand' \| 'information'` | `'brand'` |
+| `search` | `SuiTopbarSearchConfig \| boolean \| null` | `false` |
+| `searchValue` · model, `[(searchValue)]` | `string` | `''` |
+| `actions` | `SuiTopbarAction[]` | `[]` |
+| `user` | `SuiTopbarUserConfig \| string \| null` | `null` |
+| `userOpen` | `boolean` | `false` |
+
+| output | payload |
+|---|---|
+| `itemClicked` | `SuiTopbarEntry` |
+| `actionClicked` | `SuiTopbarAction` |
+| `userClicked` | `void` |
+| `searchClicked` | `void` |
+| `searchSubmitted` | `string` |
+<!-- api:fin -->
+
+```ts
+interface SuiTopbarEntry {
+  value: string;                     // lo emite (itemClicked) y se compara con activeValue
+  label: string;
+  icon?: string;                     // RemixIcon izquierdo
+  rightIcon?: string;                // típico 'arrow-down-s-line'
+  badge?: SuiBadgeConfig | string;   // «NEW»
+  count?: number;                    // número rojo
+  href?: string;                     // con href se dibuja <a>; sin href, <button>
+  target?: string;
+}
+interface SuiTopbarAction { value: string; icon: string; ariaLabel?: string; dot?: boolean; }
+interface SuiTopbarSearchConfig { placeholder?: string; shortcut?: string; compact?: boolean; }
+interface SuiTopbarUserConfig { name?: string; avatar?: SuiAvatarConfig | string; verified?: boolean; }
+```
+
+Slot: `<ng-content select="[topbar-logo]">` — el logo (una `<img>` directa se normaliza a 40×40 redonda).
+
+## Trampas
+
+- **No navega sola.** Los items no usan `routerLink`: el activo lo dice `activeValue` y tú navegas
+  en `(itemClicked)`. Excepción: con `href` el item es un `<a>` que, si la ruta es interna, navega
+  por el router (SPA) con el clic principal. Es una diferencia deliberada con `sui-sidebar`, que sí
+  usa `routerLink`.
+- `activeValue` es **una igualdad exacta** con `value`, no un prefijo de ruta: en `/pedidos/123`
+  tienes que calcular tú que el activo es `'pedidos'`.
+- Si `actions[].ariaLabel` falta, el lector de pantalla lee el `value` (`'notifications'`): pásalo
+  siempre en español.
+- El buscador no busca: expone `[(searchValue)]` y `(searchSubmitted)` con Enter. El placeholder
+  por defecto es «Buscar...» (en `sui-sidebar` es «Search...»).
+- El chip de usuario no abre ningún menú: emite `(userClicked)` y solo cambia de aspecto con
+  `userOpen`.
+- El host lleva `role="banner"`: una sola por página.
+
+## Ejemplo
+
+```html
+<sui-topbar
+  [items]="[
+    { value: 'tablero', label: 'Tablero' },
+    { value: 'pedidos', label: 'Pedidos', count: pendientes() },
+    { value: 'mas', label: 'Más', rightIcon: 'arrow-down-s-line' }
+  ]"
+  [activeValue]="seccion()"
+  [search]="{ placeholder: 'Buscar pedidos', shortcut: '⌘K' }"
+  [(searchValue)]="busqueda"
+  [actions]="[{ value: 'avisos', icon: 'notification-3-line', ariaLabel: 'Avisos', dot: hayAvisos() }]"
+  [user]="{ name: usuario().nombre, avatar: usuario().avatarUrl }"
+  [userOpen]="menuCuenta()"
+  (itemClicked)="ir($event.value)"
+  (actionClicked)="abrirAvisos()"
+  (userClicked)="menuCuenta.set(!menuCuenta())">
+  <img topbar-logo src="assets/app-icon.png" alt="Master Pedidos" />
+</sui-topbar>
+```

package/docs/sui-topbar-button/README.md

@@ -0,0 +1,95 @@
+---
+name: sui-topbar-button
+selector: sui-topbar-button
+resumen: Botón de solo ícono de 40×40 para la barra superior, con punto rojo de «hay algo nuevo»
+alternativas: [sui-button con onlyIcon (un botón de ícono en cualquier otro lugar), sui-compact-button (ícono chico de 20-28 en filas y barras apretadas), sui-topbar (la barra completa, que ya lo compone)]
+---
+
+# sui-topbar-button
+
+Story: [Organisms/Topbar](https://sui-design-system.web.app/?path=/docs/organisms-topbar--docs) —
+no tiene story propia: se ve en la página de la topbar, en la story «Icon Button — estados».
+
+## Cuándo usarlo / cuándo no
+
+**Úsalo** para los íconos de acción **de una barra superior**: avisos, ayuda, acciones rápidas.
+Dentro de `sui-topbar` no se escribe a mano: sale de `[actions]`. Suelto sirve para una cabecera
+armada a mano que quiera verse como la topbar.
+
+**No lo uses** para:
+
+- Un botón de ícono en una card, una fila o un formulario: `sui-button` con `onlyIcon`, o
+  `sui-compact-button` si el espacio es chico.
+- Una acción con texto: no lo tiene.
+
+## Qué variante usar
+
+> **La guía del DS no tiene página de este botón.** Sale del Figma de SUI (Topbar Item Button
+> [Topbar], set 3814:25156: Default, Hover, Active). Uso medido el 03-10-2026: **0 usos** en la
+> app, 1 en la vitrina de variantes (`master-preview/_guia-variantes`). Lo de abajo es
+> **propuesta, falta aprobación**.
+
+| prop | cuándo | fuente |
+|---|---|---|
+| `dot` | Hay algo nuevo detrás del ícono (avisos sin leer). Se apaga cuando la persona lo abre. Si el número importa, no alcanza: va un contador en otro lado. | propuesta, falta aprobación |
+| `active` | Mientras el panel que abre el botón está abierto (pinta el ícono naranja y `aria-pressed`). | Figma (State=Active) |
+| `accent` | `brand` (default). `information` es el azul del Figma original: no usar. | canon del DS (accent = marca) |
+
+## Tamaño en mobile y en web
+
+**No tiene `size`**: mide siempre 40×40 (padding 10 + ícono de 20), radio 10. En mobile 40 es el
+mínimo táctil aceptable, pero el botón vive en la topbar, que hoy es solo de escritorio (ver
+`sui-topbar`).
+
+| uso | mobile | web | fuente |
+|---|---|---|---|
+| ícono de la barra superior | no usar (no hay topbar en mobile) | 40×40 | propuesta, falta aprobación |
+
+## «No usar»: por qué no hoy y cuándo sí
+
+| qué | por qué no hoy | cuándo sí, en un flujo nuevo |
+|---|---|---|
+| `sui-topbar-button` (0 usos) | las barras de la app tienen sus íconos propios | si se unifica la barra superior del admin con la del DS |
+| `accent="information"` | el activo es naranja de marca | nunca en esta app |
+
+## API
+
+<!-- api:inicio -->
+<!-- generada: no editar a mano — `npm run docs` -->
+
+| input | tipo | default |
+|---|---|---|
+| `icon` | `string` | — (requerido) |
+| `ariaLabel` | `string` | — (requerido) |
+| `dot` | `boolean` | `false` |
+| `active` | `boolean` | `false` |
+| `accent` | `'brand' \| 'information'` | `'brand'` |
+
+| output | payload |
+|---|---|
+| `clicked` | `void` |
+<!-- api:fin -->
+
+`icon` es el nombre RemixIcon sin `ri-`.
+
+## Trampas
+
+- **`ariaLabel` es obligatorio** (a diferencia de `sui-button`, que no tiene ese input). En
+  español: «Avisos», no `notifications`.
+- El evento es `(clicked)`. Un `(click)` en el host también llega, pero no es la API.
+- No es un `sui-compact-button`: mide 40 (no 24) y su radio es 10 (no 6). No los mezcles en la
+  misma barra.
+- El punto rojo (4×4, con aro blanco) va arriba a la derecha y es solo visual: no lo lee el lector
+  de pantalla. Si importa, dilo en `ariaLabel` («Avisos, hay nuevos»).
+- Ya trae el arreglo de iOS para el `:active` pegado.
+
+## Ejemplo
+
+```html
+<sui-topbar-button
+  icon="notification-3-line"
+  ariaLabel="Avisos"
+  [dot]="hayAvisos()"
+  [active]="panelAvisos()"
+  (clicked)="panelAvisos.set(!panelAvisos())" />
+```

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

@@ -0,0 +1,97 @@
+---
+name: sui-topbar-item
+selector: sui-topbar-item
+resumen: Una sección de la navegación horizontal — texto, ícono opcional, badge o contador — con estado activo
+alternativas: [sui-topbar (la barra completa: lo compone desde [items]), sui-tab-menu-horizontal (pestañas dentro de UNA pantalla), sui-tab-chips (filtros), sui-link-button (un link suelto en un texto)]
+---
+
+# sui-topbar-item
+
+Story: [Organisms/Topbar](https://sui-design-system.web.app/?path=/docs/organisms-topbar--docs) —
+no tiene story propia: se ve en la página de la topbar, en la story «Topbar Item — estados».
+
+## Cuándo usarlo / cuándo no
+
+**Úsalo** como cada sección de una navegación horizontal de escritorio. Dentro de `sui-topbar`
+no se escribe a mano: sale de `[items]`. Suelto sirve para armar una barra propia que se vea
+igual.
+
+**No lo uses** para:
+
+- Pestañas que cambian el contenido de la misma pantalla: `sui-tab-menu-horizontal`.
+- Filtros que se prenden y apagan: `sui-tab-chips`.
+- Navegación de los roles de la app: `sui-sidebar`.
+
+## Qué variante usar
+
+> **La guía del DS no tiene página de este item.** Sale del Figma de SUI (Topbar Items [Topbar],
+> set 3802:24588: Default, Hover, Active). Uso medido el 03-10-2026: **0 usos** en la app. Lo de
+> abajo es **propuesta, falta aprobación**.
+
+| prop | cuándo | fuente |
+|---|---|---|
+| solo `label` | El caso normal. Una o dos palabras, sentence case. | propuesta, falta aprobación |
+| `icon` | Si **todos** los items de la barra lo llevan. | propuesta, falta aprobación |
+| `rightIcon: 'arrow-down-s-line'` | El item abre un menú («Más ⌄»). El menú lo pones tú. | Figma |
+| `count` | Pendientes que piden acción («3» pedidos por aceptar). Número rojo. | Figma (notification=true) |
+| `badge` | Un «Nuevo» temporal en una sección recién lanzada. String = badge naranja `light` `small`. | Figma (badge=true) |
+| `href` | El item es un link: con ruta interna navega por el router; con `target="_blank"` abre otra pestaña con `rel` seguro. | propuesta, falta aprobación |
+| sin `href` | Es un `<button>`: navegas tú en `(clicked)`. | propuesta, falta aprobación |
+| `active` | La sección actual (fondo gris, texto oscuro, ícono naranja y `aria-current="page"`). Uno solo por barra. | Figma (State=Active) |
+
+## Tamaño en mobile y en web
+
+**No tiene `size`**: alto 36 (padding 8 + línea de 20), texto 14/500, íconos de 20. Vive en la
+topbar, que hoy es solo de escritorio.
+
+| uso | mobile | web | fuente |
+|---|---|---|---|
+| sección de la barra superior | no usar (no hay topbar en mobile) | tamaño único | propuesta, falta aprobación |
+
+En mobile, 36 de alto queda por debajo del área táctil cómoda (44): si algún día se usa ahí, la
+barra tendría que darle más aire.
+
+## API
+
+<!-- api:inicio -->
+<!-- generada: no editar a mano — `npm run docs` -->
+
+| input | tipo | default |
+|---|---|---|
+| `label` | `string` | — (requerido) |
+| `icon` | `string \| null` | `null` |
+| `rightIcon` | `string \| null` | `null` |
+| `badge` | `SuiBadgeConfig \| string \| null` | `null` |
+| `count` | `number \| null` | `null` |
+| `active` | `boolean` | `false` |
+| `accent` | `'brand' \| 'information'` | `'brand'` |
+| `href` | `string \| null` | `null` |
+| `target` | `string \| null` | `null` |
+
+| output | payload |
+|---|---|
+| `clicked` | `void` |
+<!-- api:fin -->
+
+`SuiTopbarAccent` (`'brand' | 'information'`) se exporta desde este archivo y lo usan también
+`sui-topbar` y `sui-topbar-button`.
+
+## Trampas
+
+- `count` en `0` **se muestra** («0» rojo): solo `null` lo oculta. Pasa `pendientes() || null`.
+- `badge` en string toma naranja `light` `small`; para otro color, el objeto `SuiBadgeConfig`.
+- `active` no se calcula solo: ni por ruta ni por `href`. Lo decides tú.
+- Con `href`, `(clicked)` igual se emite: no navegues dos veces.
+- `accent="information"` es el azul del Figma original: en esta app no se usa.
+- Ya trae el arreglo de iOS para el `:active` pegado.
+
+## Ejemplo
+
+```html
+<nav class="mi-barra">
+  <sui-topbar-item label="Tablero" [active]="seccion() === 'tablero'" (clicked)="ir('tablero')" />
+  <sui-topbar-item label="Pedidos" [count]="pendientes() || null"
+                   [active]="seccion() === 'pedidos'" (clicked)="ir('pedidos')" />
+  <sui-topbar-item label="Más" rightIcon="arrow-down-s-line" (clicked)="abrirMenu()" />
+</nav>
+```

package/docs/sui-topbar-user/README.md

@@ -0,0 +1,83 @@
+---
+name: sui-topbar-user
+selector: sui-topbar-user
+resumen: Chip de la cuenta en la barra superior — avatar, nombre y flecha — que abre el menú de la cuenta
+alternativas: [sui-topbar (la barra completa: lo compone desde [user]), el perfil del pie de sui-sidebar (la cuenta en la navegación lateral), sui-avatar (solo la foto, sin nombre ni menú)]
+---
+
+# sui-topbar-user
+
+Story: [Organisms/Topbar](https://sui-design-system.web.app/?path=/docs/organisms-topbar--docs) —
+no tiene story propia: se ve en la página de la topbar, en la story «User Chip — estados».
+
+## Cuándo usarlo / cuándo no
+
+**Úsalo** a la derecha de una barra superior para la **cuenta de quien mira**: su foto, su
+nombre y un menú (perfil, cambiar de rol, salir). Dentro de `sui-topbar` sale de `[user]`.
+
+**No lo uses** para:
+
+- Mostrar a **otra** persona (el cliente de un pedido, el repartidor asignado): `sui-avatar` con
+  su nombre al lado. El chip es un botón con flecha: promete un menú.
+- La cuenta dentro de la navegación lateral: ya va en `profile` de `sui-sidebar`.
+
+## Qué variante usar
+
+> **La guía del DS no tiene página de este chip.** Sale del Figma de SUI (User Profile [Topbar],
+> set 3814:24667: Default, Hover, Active). Uso medido el 03-10-2026: **0 usos** en la app. Lo de
+> abajo es **propuesta, falta aprobación**, salvo lo que es canon de la app.
+
+| prop | cuándo | fuente |
+|---|---|---|
+| `avatar` (string) | La URL de la foto. Siempre de `avatarUrl`, nunca de `photoURL`. | canon (CLAUDE.md, «Fotos de otra persona») |
+| `avatar` (objeto) | Sin foto: `{ initials, color }` para que las iniciales tengan contraste. | propuesta, falta aprobación |
+| `name` | El nombre corto («Sophia», no el correo). Vacío = chip solo con la foto, para barras angostas. | Figma (name=false) |
+| `verified` | No usar hoy: la app no verifica cuentas de personas. | propuesta, falta aprobación |
+| `open` | Mientras el menú de la cuenta está abierto (flecha hacia arriba, `aria-expanded`). | Figma (State=Active) |
+
+## Tamaño en mobile y en web
+
+**No tiene `size`**: alto 40 (avatar 32 + 4 arriba y abajo), radio 10, nombre 14/500. Vive en la
+topbar, que hoy es solo de escritorio.
+
+| uso | mobile | web | fuente |
+|---|---|---|---|
+| cuenta en la barra superior | no usar (en mobile la cuenta va en el cajón del sidebar) | con nombre | propuesta, falta aprobación |
+
+## API
+
+<!-- api:inicio -->
+<!-- generada: no editar a mano — `npm run docs` -->
+
+| input | tipo | default |
+|---|---|---|
+| `name` | `string` | `''` |
+| `avatar` | `SuiAvatarConfig \| string \| null` | `null` |
+| `verified` | `boolean` | `false` |
+| `open` | `boolean` | `false` |
+
+| output | payload |
+|---|---|
+| `clicked` | `void` |
+<!-- api:fin -->
+
+## Trampas
+
+- **No abre ningún menú.** Emite `(clicked)` y lleva `aria-haspopup="menu"`: el menú
+  (`sui-dropdown-menu`) lo pones tú y le pasas `[open]` mientras está abierto.
+- Sin `avatar` (o con `null`) igual dibuja el avatar con la silueta genérica gris: pasa al menos
+  las iniciales.
+- El nombre no se corta: uno largo empuja el resto de la barra. Usa el nombre de pila.
+- La foto de Google (`lh3.googleusercontent.com`) solo carga con las cookies de su dueño; en la
+  barra de quien mira funciona, pero sigue siendo regla usar `avatarUrl`.
+- Ya trae el arreglo de iOS para el `:active` pegado.
+
+## Ejemplo
+
+```html
+<sui-topbar-user
+  [name]="usuario().nombre"
+  [avatar]="usuario().avatarUrl || { initials: usuario().iniciales, color: 'orange' }"
+  [open]="menuCuenta()"
+  (clicked)="menuCuenta.set(!menuCuenta())" />
+```