@ajuarezso/sui-design-system 0.21.0 → 0.22.0

package/docs/sui-table/README.md

@@ -0,0 +1,264 @@
+---
+name: sui-table
+selector: sui-table
+resumen: Tabla de datos — una fila por registro, una columna por dato — para comparar y recorrer listas en web
+alternativas: [tarjetas en grilla con sui-card (la misma lista cuando no entran las columnas), sui-empty-state (no hay nada que listar todavía), sui-pagination (paginar por número de página, debajo de la tabla), sui-activity-feed (historial de quién hizo qué)]
+---
+
+# sui-table
+
+Story: [Organisms/Table](https://sui-design-system.web.app/?path=/docs/organisms-table--docs)
+
+## Cuándo usarlo / cuándo no
+
+**Úsalo** cuando la persona tiene que **comparar varios registros por las mismas columnas**:
+pedidos, repartidores, gastos, recargas. La tabla sirve si leer en vertical una columna
+(«¿cuál es el monto más alto?», «¿quién no tiene repartidor?») es parte de la decisión.
+
+**No lo uses** para:
+
+- Una lista donde cada registro se lee solo (sin comparar con el de al lado): tarjetas.
+- Pantallas del cliente o del repartidor en el teléfono: ahí la lista va en tarjetas o
+  filas de una columna. La tabla es de las pantallas de gestión (empresa, super admin, central).
+- Un historial de acciones con autor y hora: `sui-activity-feed`.
+- «Todavía no hay nada» a página completa: `sui-empty-state`. La tabla tiene su propio
+  vacío (`emptyMessage`), que es otro registro (ver abajo).
+
+Regla corta: **comparar por columnas → tabla · leer de a uno → tarjetas · historial → activity feed.**
+
+## Qué variante usar
+
+> **La guía del DS casi no dice cuándo ni cómo usar la tabla.** Su página la define como «una
+> estructura de dos dimensiones donde cada fila es un ítem y cada columna un dato del ítem»,
+> muestra un solo ejemplo (un directorio de personas **con selección por checkbox**), le pone
+> `overflow-x-auto` al contenedor y deriva el orden, la selección y la paginación a una
+> librería externa. No trae do/don't, tamaños ni comportamiento en mobile. Casi todo lo de
+> abajo es **práctica de la app** o **propuesta, falta aprobación**; lo marcado «canon» sale de
+> `master-pedidos/CLAUDE.md` o de `docs/CANON-SUI.md`.
+>
+> Uso medido el 03-10-2026 en `master-pedidos/src/app`: **9 tablas** en 7 pantallas, sin contar
+> prototipos ni vitrinas (`master-preview`, `master-prototipos`, `mockup-sheets-*`, `dx/*`,
+> `master-rutina`, `master-medico`, `dev-index`). `sortable`, `selectable` y `striped`: 0 usos.
+> `sticky`: 1, en una vitrina.
+
+### Lo que sí dice la guía del DS
+
+- **Qué es**: filas = ítems, columnas = datos del ítem.
+- **Partes**: cabecera, filas con hover, celdas con esquinas redondeadas y un **divisor entre
+  filas**. SUI lo replica (header gris `bg-weak-50`, filas con radio 12 y divisor de 1 px).
+- **Ancho**: el contenedor scrollea en horizontal (`overflow-x-auto`). En SUI eso pasa solo
+  **hasta 767 px** o con una columna `sticky` (ver Trampas).
+- **Selección**: su único ejemplo trae checkbox por fila. En SUI es `selectable`.
+
+### Las columnas (`SuiTableColumn`)
+
+| prop de columna | cuándo | ejemplo real de la app | fuente |
+|---|---|---|---|
+| `priority: 'leading'` + `descriptionKey` | La **primera** columna: el dato que identifica la fila arriba (14/500) y un dato de apoyo debajo (12/400). Se usa en vez de una plantilla propia para la columna principal. | `pages/orders/orders.ts:278` (pedido + «hace 12 min») · `pages/super-admin/master-orders/master-orders.ts:390` | práctica de la app (7 de 9 tablas) |
+| `priority: 'passive'` | Datos de contexto que no deciden nada: fecha, número de comprobante. Se leen en gris (`text-sub-600`). | `pages/super-admin/master-overview/master-overview.ts:192` | propuesta, falta aprobación |
+| `priority: 'none'` | Columna de acciones (íconos) sin texto propio. Con `label: ''` y `width` fijo. | `pages/super-admin/master-gastos/master-gastos.ts:143` | práctica de la app |
+| `align: 'right'` | Montos. Así se comparan en vertical. | `pages/central/central-gastos/central-gastos.ts:82` | propuesta, falta aprobación |
+| `width` | Columnas de largo fijo: monto, estado, fecha, acciones. | `central-gastos.ts:82-83` | práctica de la app |
+| `minWidth` | Columnas de texto que crecen (nombre, concepto): el piso para que no se aplasten. | `master-orders.ts:392` | práctica de la app |
+| `maxWidth` + `truncate` | Nombres que pueden ser muy largos: corta con «…» y el valor completo sale en tooltip. | `master-overview.ts:193` | práctica de la app |
+
+**Una ID nunca es el título de la fila** (`CLAUDE.md`, «Pasada de UX/UI»): la columna `leading`
+lleva el nombre o el número legible del pedido, no el uid.
+
+### Plantillas por columna (`suiTableCell`)
+
+Si una celda necesita algo más que texto, se proyecta un `<ng-template suiTableCell="<key>" let-row>`.
+Dentro va un componente SUI, no HTML a mano:
+
+| contenido | componente | fuente |
+|---|---|---|
+| estado o categoría | `<sui-badge variant="lighter" size="small">` | canon (CANON-SUI §0: «Chip de estado») |
+| acciones de la fila | `<sui-button variant="ghost" color="neutral" size="2xsmall" [onlyIcon]="true">` | canon (README de `sui-button`: tabla densa = `2xsmall`) |
+| prender/apagar | `<sui-switch>` | propuesta, falta aprobación |
+| calificación | `<sui-rating>` de solo lectura | propuesta, falta aprobación |
+
+Si la columna tiene plantilla, `descriptionKey` y `truncate` **no se aplican**: solo funcionan en
+el render de texto plano. Por eso `orders.html:94` deja la columna del pedido sin plantilla.
+
+### Cargar las filas: cuenta + página por cursor
+
+**Canon** (`master-pedidos/CLAUDE.md`, «Performance — Firestore reads»): una pantalla con tabla
+**no baja la colección entera** para mostrar 30 filas. Los totales salen de `getCount`, las filas
+de `getCollectionPage` con cursor, y debajo de la tabla va un «Cargar más»
+(`sui-button variant="stroke" color="neutral"`). Referencia: `pages/orders/orders.ts:716`
+(`loadMore`) y `orders.html:132`.
+
+- El orden de la tabla lo fija la consulta (`orderBy`). **No uses `sortable`** sobre una lista
+  paginada: ordenaría solo lo cargado y mentiría sobre el resto.
+- `sui-pagination` (números de página) no calza con cursor: Firestore no salta a «la página 7».
+
+### Vacío y carga
+
+- `loading` pinta 5 filas esqueleto con las columnas reales. Úsalo mientras llega la primera
+  página. Canon (memoria del proyecto: skeleton obligatorio en pantalla nueva).
+- `emptyMessage` es una línea con un ícono de bandeja, sin ilustración ni botón. **Canon**
+  (CANON-SUI §5.6): no se mezcla con `sui-empty-state`. Escríbelo como en la app, una frase con
+  punto: «Nadie recargó en este período.», «Sin gastos registrados todavía.». El default
+  `'No hay datos'` no dice nada: siempre se pasa uno propio (los 9 usos lo hacen).
+
+## Tamaño en mobile y en web
+
+`size` cambia **el alto mínimo de la fila**, no la letra (14 px en todos):
+
+| size | alto | nombre en el Figma | fuente |
+|---|---|---|---|
+| `small` | 48 | Large | Figma |
+| `medium` (default) | 64 | X-Large | Figma |
+| `large` | 80 | — | extensión SUI |
+| `xlarge` | 96 | — | extensión SUI |
+
+Uso de hoy: 2 `medium` explícitos (`orders`, `drivers`), 1 `small` (`master-overview`, una tabla
+secundaria dentro de un tablero) y 6 sin `size` (o sea `medium`).
+
+| uso | mobile | web | fuente |
+|---|---|---|---|
+| tabla principal de una pantalla | `medium` | `medium` | práctica de la app |
+| tabla secundaria dentro de un tablero | `small` | `small` | práctica de la app (1 uso) |
+| filas con dos líneas y un badge | `medium` | `medium` | propuesta, falta aprobación |
+
+El patrón `[size]="bp.isMobile() ? 'large' : 'medium'"` de los botones **no aplica aquí**: la fila
+ya mide 64 y el toque es sobre toda la fila. `large`/`xlarge` no tienen uso hoy.
+
+**Qué pasa en mobile (≤ 767 px):** la tabla scrollea en horizontal dentro de sí misma; la
+cabecera y el cuerpo miden lo mismo y la barra de scroll se oculta. En la app conviven dos
+salidas, y las dos son práctica, no regla:
+
+| salida | dónde | cuándo elegirla (propuesta) |
+|---|---|---|
+| la misma tabla, con scroll lateral | `orders`, `master-orders`, `central-gastos`, `central-ingresos` | 3-4 columnas, y la primera (`leading`) ya dice casi todo |
+| tarjetas en grilla por debajo de 1350 px | `drivers` (`drivers.ts:282`), `master-gastos` | 6+ columnas: con el sidebar abierto no entran ni en laptop ni en iPad |
+
+**Android (canon del componente, no se repite en la página):** un contenedor con
+`overflow-x: auto` se queda con el gesto vertical y la página deja de scrollear sobre la tabla.
+Ningún `touch-action` solo lo arregla (probado en device). `sui-table` lo resuelve **por dentro y
+solo en Android**: pone `touch-action: pan-x` por JS para que el scroll horizontal sea el nativo,
+y mueve él mismo la página con el gesto vertical (con inercia). En iOS no hace nada: WebKit delega
+el vertical solo. Por eso la página **no** agrega `touch-action` ni un wrapper con `overflow-x`.
+
+## «No usar»: por qué no hoy y cuándo sí
+
+| qué | por qué no hoy | cuándo sí, en un flujo nuevo |
+|---|---|---|
+| `sortable` | toda tabla de la app es una lista paginada por cursor: el orden lo da la consulta | una tabla chica que se carga entera (≤ 50 filas, un reporte del mes) |
+| `selectable` | no hay acciones en lote | aprobar o rechazar varias recargas de una vez, exportar filas elegidas |
+| `striped` | con divisor entre filas ya se lee la fila; las rayas suman ruido | tablas de muchas columnas numéricas (un reporte contable) |
+| `sticky` | la columna fija tapó otra en 375 px (`central-gastos.ts:80`) | una tabla ancha en desktop donde la primera columna es la única referencia |
+| `large` / `xlarge` | 64 ya alcanza al dedo | filas con avatar grande y tres líneas |
+
+## API
+
+<!-- api:inicio -->
+<!-- generada: no editar a mano — `npm run docs` -->
+
+### `sui-table`
+
+| input | tipo | default |
+|---|---|---|
+| `columns` | `SuiTableColumn<T>[]` | — (requerido) |
+| `rows` | `T[]` | — (requerido) |
+| `size` | `'small' \| 'medium' \| 'large' \| 'xlarge'` | `'medium'` |
+| `loading` | `boolean` | `false` |
+| `emptyMessage` | `string` | `'No hay datos'` |
+| `striped` | `boolean` | `false` |
+| `selectable` | `boolean` | `false` |
+| `rowKey` | `keyof T \| ((row: T) => any)` | `undefined` |
+| `selectedRows` · model, `[(selectedRows)]` | `Set<any>` | `new Set()` |
+| `sortKey` · model, `[(sortKey)]` | `string \| null` | `null` |
+| `sortDir` · model, `[(sortDir)]` | `'asc' \| 'desc' \| null` | `null` |
+
+| output | payload |
+|---|---|
+| `rowClicked` | `T` |
+| `sortChanged` | `{ key: string; dir: 'asc' \| 'desc' \| null }` |
+
+### `[suiTableCell]`
+
+| input | tipo | default |
+|---|---|---|
+| `suiTableCell` | `string` | — (requerido) |
+
+Outputs: ninguno.
+<!-- api:fin -->
+
+```ts
+interface SuiTableColumn<T = any> {
+  key: string;                 // campo de la fila; único
+  label: string;               // '' para la columna de acciones
+  width?: string;              // ancho fijo ('100px', '20%')
+  minWidth?: string;           // piso (manda en el scroll de mobile)
+  maxWidth?: string;
+  align?: 'left' | 'center' | 'right';
+  sortable?: boolean;
+  disabled?: boolean;          // cabecera apagada, sin orden
+  priority?: 'regular' | 'leading' | 'passive' | 'none';
+  descriptionKey?: string;     // segunda línea (solo texto plano)
+  truncate?: boolean;          // «…» + tooltip (solo texto plano)
+  misc?: SuiTableCellMisc;     // documental: qué componente va en la plantilla
+  sticky?: boolean;            // fija la columna y activa el scroll lateral en cualquier ancho
+}
+```
+
+`SuiTableCellDirective` se importa aparte (`<ng-template suiTableCell="key" let-row>`).
+El orden cicla `asc → desc → sin orden` y emite `sortChanged` en cada paso; ordenar las filas es
+trabajo de la página.
+
+## Trampas
+
+- **Por encima de 767 px la tabla recorta, no scrollea.** Sin una columna `sticky`, el contenedor
+  es `overflow: hidden` en desktop: lo que no entra **desaparece** a la derecha (monto, estado,
+  acciones). Las columnas tienen que entrar en el ancho real, que con el sidebar abierto es
+  ~483 px en iPad y ~1015 px en una pantalla de 1351. Lo comentan tres pantallas:
+  `pages/drivers/drivers.html:210`, `pages/super-admin/master-gastos/master-gastos.html:38`,
+  `pages/central/central-gastos/central-gastos.ts:76`. El wrapper `drivers__table-wrap` es un
+  respaldo de eso; no se copia.
+- `sticky` en **cualquier** columna activa el scroll lateral en todos los anchos (no solo en mobile)
+  y quita el recorte redondeado de las filas.
+- `descriptionKey` y `truncate` **se ignoran** si la columna tiene plantilla `suiTableCell`.
+- Sin `rowKey`, la fila se identifica por su índice: la selección se mezcla al reordenar o al cargar
+  más. Si usas `selectable` o la lista cambia en vivo, pasa `rowKey="id"`.
+- `rowClicked` dispara en **toda** la fila. Un botón dentro de una plantilla necesita
+  `$event.stopPropagation()` o abre el detalle además de hacer lo suyo.
+- `toggleAll` selecciona **lo cargado**, no la colección: con cursor, «todas» son las de la página.
+- El hover de fila solo existe con mouse (`@media (hover: hover)`); en táctil no hay feedback de
+  toque: si la fila abre algo, que se note por el contenido (una pista «Toca un gasto para…», como
+  `central-gastos.html:46`).
+- La fila esqueleto son siempre 5, sin importar el tamaño de página.
+- No le pongas `touch-action` ni `overflow-x` desde la página: el componente ya maneja el gesto en
+  Android y lo romperías.
+
+## Ejemplo
+
+```html
+<sui-card>
+  <sui-table
+    [columns]="columnas"
+    [rows]="filas()"
+    rowKey="id"
+    [loading]="cargando()"
+    emptyMessage="Sin pedidos en este estado."
+    (rowClicked)="abrirDetalle($event)">
+    <ng-template suiTableCell="estado" let-row>
+      <sui-badge [color]="row.color" variant="lighter" size="small">{{ row.estadoLabel }}</sui-badge>
+    </ng-template>
+  </sui-table>
+
+  @if (hayMas()) {
+    <sui-button variant="stroke" color="neutral" [size]="bp.isMobile() ? 'large' : 'small'"
+                [disabled]="cargandoMas()" (click)="cargarMas()">Cargar más</sui-button>
+  }
+</sui-card>
+```
+
+```ts
+readonly columnas: SuiTableColumn[] = [
+  { key: 'numero', label: 'Pedido', priority: 'leading', descriptionKey: 'desdeHace', minWidth: '130px' },
+  { key: 'cliente', label: 'Cliente', minWidth: '160px', maxWidth: '220px', truncate: true },
+  { key: 'total', label: 'Total', align: 'right', width: '100px' },
+  { key: 'estado', label: 'Estado', width: '130px' },
+];
+```

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

@@ -52,6 +52,9 @@ Publicado (0.19.0): `xsmall` (32), `small` (36), `medium` (40). **En el repo del
 0.19.0 queda en 14). Los chips de abajo son `sui-tag` de tamaño fijo: **la ✕ para quitar un chip
 no crece** con el campo.
 
+En large y xlarge el texto sube a 16 px (regla del 03-10-2026): lo que se escribe va en 16/24 también
+en web; el alto sigue en 48/52. Los chips de abajo no cambian.
+
 | uso | mobile | web | fuente |
 |---|---|---|---|
 | campo de formulario | `large` (48) **cuando se publique**; hasta entonces `medium` (40) | `medium` (40) | propuesta, falta aprobación |

package/docs/sui-textarea/README.md

@@ -87,6 +87,9 @@ evita el zoom de iOS al enfocar y el textarea deja de verse más chico que los c
 eso cada fila mide 24 px en el teléfono y 20 en web (3 filas ≈ 72 + padding en mobile, 60 + padding
 en web): el área que se toca siempre pasa los 44 px.
 
+En large y xlarge el texto sube a 16 px (regla del 03-10-2026): en esos dos tamaños va en 16/24
+también en web, así que cada fila mide 24 en las dos plataformas.
+
 | uso | mobile | web | fuente |
 |---|---|---|---|
 | motivo, nota | el `size` del formulario (`large` si los inputs van en `large`), `rows=3`, `[resizable]="false"` | `medium`, `rows=3`, manija | propuesta, falta aprobación |

package/docs/sui-time-picker/README.md

@@ -106,6 +106,9 @@ el panel también crece: **filas de 44** y **Cancelar / Aplicar en `large` (48)*
 | fila de la columna | 36 | 44 | 44 | 36: Figma · 44: canon (aprobado por el dueño, 03-10-2026), extensión SUI |
 | Cancelar / Aplicar | 36 | 48 | el del `size` | canon (aprobado por el dueño, 03-10-2026), extensión SUI |
 
+En large y xlarge el texto sube a 16 px (regla del 03-10-2026): con `large`, la hora del campo y la
+de las filas van en 16/24; la fila sigue en 44 (el padding bajó de 12 a 10).
+
 | uso | mobile | web | fuente |
 |---|---|---|---|
 | horario en un formulario | `large` | `medium`, o `small` en filas densas | propuesta, falta aprobación |

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