@ajuarezso/sui-design-system 0.21.0 → 0.23.0

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 sin texto de 20 a 40 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 fijo (el compact va de 20 a 40 según `size`, 24 por defecto) 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())" />
+```