@ajuarezso/sui-stencil 0.0.0-stage → 0.1.0

package/docs/sui-topbar/README.md

@@ -0,0 +1,235 @@
+---
+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
+
+<!-- generado por scripts/gen-docs.mjs — no editar a mano; `npm run docs` -->
+
+> **De dónde sale este doc.** El criterio es el del SUI Angular (`sui-topbar`); la API es la de este
+> paquete, leída del código. Los ejemplos se pasaron de Angular de forma mecánica: lo literal va como
+> atributo (`only-icon`, `size="large"`), lo dinámico entre llaves (`size={expr}` → `el.size = expr`)
+> y los eventos como `onValueChange={…}` → `el.addEventListener('valueChange', …)`. `@if`, `@for` y
+> `<ng-template>` quedan como en Angular: se leen como pseudocódigo.
+
+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 celular o una tablet táctil: 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. Las reglas marcadas canon están aprobadas (05-10-2026) y no queda
+> ninguna en propuesta; lo marcado «Figma» lo fija el componente.
+>
+> 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. | canon (aprobado por el dueño, 05-10-2026, bloque B9) |
+| items | con `icon` | Si **todos** llevan ícono. Mezclar con y sin se lee desordenado. | canon (aprobado por el dueño, 05-10-2026, bloque B9) |
+| 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`. | canon (aprobado por el dueño, 05-10-2026, bloque B9) |
+| `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. | canon (aprobado por el dueño, 05-10-2026, bloque B9) |
+| `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` | canon (aprobado por el dueño, 05-10-2026, bloque B7) |
+
+**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 celular o tablet táctil, primero
+hay que agregarle al componente un modo mobile (menú hamburguesa, buscador en botón, safe area).
+
+### Por dispositivo (D16)
+
+No aplica una tabla: no tiene input `size` y sus piezas tienen tamaño fijo (items de 36, íconos y
+chip de 40, buscador de 40). Como se toca y no tiene un size que llegue a 44, B7 lo saca de todo lo
+táctil: en el celular chico, el celular y la tablet táctil **no se usa**; solo en la computadora
+(`pointer: fine`) y en el ultrawide, igual que en la computadora, con el ancho extra para el
+contenido y no para la barra. La columna «mobile» de D16 incluye la tablet en lo que se toca, así
+que el «no usar en mobile» de B7 la cubre.
+
+En master-pedidos: sin `size` ni helper; si algún día se monta, va detrás de `@if (!bp.tactil())`
+(`isMobile() || toque()`: todo celular por ancho y toda pantalla táctil). No `!bp.isMobile()`: ese
+es solo por ancho (≤ 768) y deja pasar un iPad de 769 a 1024 con `pointer: coarse`.
+
+## «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` -->
+
+| prop | atributo | tipo | default |
+|---|---|---|---|
+| `accent` | `accent` | `"brand" \| "information"` | `'brand'` |
+| `actions` | — (solo por propiedad JS) | `SuiTopbarAction[]` | `[]` |
+| `activeValue` | `active-value` | `null \| string` | `null` |
+| `items` | — (solo por propiedad JS) | `SuiTopbarEntry[]` | `[]` |
+| `search` | `search` | `SuiTopbarSearchConfig \| boolean \| null` | `false` |
+| `searchValue` | `search-value` | `string` | `''` |
+| `user` | `user` | `SuiTopbarUserConfig \| null \| string` | `null` |
+| `userOpen` | `user-open` | `boolean` | `false` |
+
+| evento | `event.detail` |
+|---|---|
+| `actionClicked` | `SuiTopbarAction` |
+| `itemClicked` | `SuiTopbarEntry` |
+| `searchClicked` | `void` |
+| `searchSubmitted` | `string` |
+| `searchValueChange` | `string` |
+| `userClicked` | `void` |
+
+Slots: `topbar-logo`.
+
+### Diferencias con el SUI Angular
+
+Ninguna en nombres de props, eventos y valores.
+<!-- api:fin -->
+
+<!-- textos:inicio -->
+### Textos
+
+Lo que el componente escribe solo sale de `provideSuiTextos` (español por defecto, se cambia en vivo; ver `docs/TEXTOS.md`). El input de la última columna le gana al texto global.
+
+| clave | por defecto | se pisa con |
+|---|---|---|
+| `navegacion.principal` | Principal | — |
+| `comun.buscar` | Buscar… | `search.placeholder` |
+<!-- textos: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; ariaLabel?: string; shortcut?: string; compact?: boolean; }
+interface SuiTopbarUserConfig { name?: string; avatar?: SuiAvatarConfig | string; verified?: boolean; }
+```
+
+Slot: `<slot 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` + `searchValueChange` y `searchSubmitted` con Enter. El placeholder
+  por defecto es «Buscar…», igual que en `sui-sidebar` (con elipsis desde 0.26.0). El campo lleva
+  `enterkeyhint="search"` sin `inputmode` (D14), sube a 16 px en ≤ 767 px y su nombre accesible es
+  `ariaLabel` o el placeholder.
+- 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.
+- `count` en `0` **se muestra** («0» rojo), igual que en `sui-topbar-item`: pasa
+  `pendientes() || undefined`.
+
+## Bien y mal
+
+El contador de un item
+
+```html
+<!-- ❌ mal: sin pendientes sale un «0» rojo -->
+<sui-topbar items={[{ value: 'pedidos', label: 'Pedidos', count: pendientes() }]} />
+```
+
+```html
+<!-- ✅ bien -->
+<sui-topbar items={[{ value: 'pedidos', label: 'Pedidos', count: pendientes() || undefined }]} />
+```
+
+Las acciones de ícono
+
+```html
+<!-- ❌ mal: sin ariaLabel, el lector de pantalla lee el value («notifications») -->
+<sui-topbar actions={[{ value: 'notifications', icon: 'notification-3-line', dot: hayAvisos() }]} />
+```
+
+```html
+<!-- ✅ bien -->
+<sui-topbar actions={[{ value: 'avisos', icon: 'notification-3-line',
+  ariaLabel: 'Avisos', dot: hayAvisos() }]} />
+```
+
+El item activo en una ruta con id
+
+```html
+<!-- ❌ mal: en /pedidos/123 la url nunca es igual a 'pedidos'; no se marca ninguno -->
+<sui-topbar items={items} activeValue={router.url} onItemClicked={(e) => ir(e.detail.value)} />
+```
+
+```html
+<!-- ✅ bien: seccion() saca 'pedidos' del primer tramo de la ruta -->
+<sui-topbar items={items} activeValue={seccion()} onItemClicked={(e) => ir(e.detail.value)} />
+```
+
+## Ejemplo
+
+```html
+<sui-topbar
+  items={[
+    { value: 'tablero', label: 'Tablero' },
+    { value: 'pedidos', label: 'Pedidos', count: pendientes() || undefined },
+    { value: 'mas', label: 'Más', rightIcon: 'arrow-down-s-line' }
+  ]}
+  activeValue={seccion()}
+  search={{ placeholder: 'Buscar pedidos', shortcut: '⌘K' }}
+  searchValue={busqueda} onSearchValueChange={(e) => (busqueda = e.detail)}
+  actions={[{ value: 'avisos', icon: 'notification-3-line', ariaLabel: 'Avisos', dot: hayAvisos() }]}
+  user={{ name: usuario().nombre, avatar: usuario().avatarUrl }}
+  userOpen={menuCuenta()}
+  onItemClicked={(e) => ir(e.detail.value)}
+  onActionClicked={() => abrirAvisos()}
+  onUserClicked={() => 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,161 @@
+---
+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
+
+<!-- generado por scripts/gen-docs.mjs — no editar a mano; `npm run docs` -->
+
+> **De dónde sale este doc.** El criterio es el del SUI Angular (`sui-topbar-button`); la API es la de este
+> paquete, leída del código. Los ejemplos se pasaron de Angular de forma mecánica: lo literal va como
+> atributo (`only-icon`, `size="large"`), lo dinámico entre llaves (`size={expr}` → `el.size = expr`)
+> y los eventos como `onValueChange={…}` → `el.addEventListener('valueChange', …)`. `@if`, `@for` y
+> `<ng-template>` quedan como en Angular: se leen como pseudocódigo.
+
+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`). Las reglas marcadas
+> canon están aprobadas (05-10-2026) y no queda ninguna en propuesta.
+
+| 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. | canon (aprobado por el dueño, 05-10-2026, bloque B9) |
+| `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. 40 queda debajo de
+los 44 que D1 y D16 piden para lo que se toca, y por eso no va en mobile (B7): vive en la topbar,
+que es solo de computadora (ver `sui-topbar`).
+
+| uso | mobile | web | fuente |
+|---|---|---|---|
+| ícono de la barra superior | no usar (no hay topbar en mobile) | 40×40 | canon (aprobado por el dueño, 05-10-2026, bloque B7) |
+
+### Por dispositivo (D16)
+
+No aplica una tabla: no tiene input `size` y mide 40×40 en todos los dispositivos. Como se toca y no
+tiene un size que llegue a 44, B7 lo saca de todo lo táctil: en el celular chico, el celular y la
+tablet táctil **no se usa**; solo en la computadora (`pointer: fine`) y en el ultrawide, igual que
+en la computadora. La columna «mobile» de D16 incluye la tablet en lo que se toca, así que el «no
+usar en mobile» de B7 la cubre.
+
+En master-pedidos: sin `size` ni helper; si algún día se monta, va detrás de `@if (!bp.tactil())`
+(`isMobile() || toque()`: todo celular por ancho y toda pantalla táctil). No `!bp.isMobile()`: ese
+es solo por ancho (≤ 768) y deja pasar un iPad de 769 a 1024 con `pointer: coarse`.
+
+## «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` -->
+
+| prop | atributo | tipo | default |
+|---|---|---|---|
+| `accent` | `accent` | `"brand" \| "information"` | `'brand'` |
+| `active` | `active` | `boolean` | `false` |
+| `ariaLabel` | `aria-label` | `string` | — (requerido) |
+| `dot` | `dot` | `boolean` | `false` |
+| `icon` | `icon` | `string` | — (requerido) |
+
+| evento | `event.detail` |
+|---|---|
+| `clicked` | `void` |
+
+### Diferencias con el SUI Angular
+
+Ninguna en nombres de props, eventos y valores.
+<!-- 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.
+
+## Bien y mal
+
+El ícono de avisos
+
+```html
+<!-- ❌ mal: el lector de pantalla dice «notifications» y no se entera del punto rojo -->
+<sui-topbar-button icon="notification-3-line" aria-label="notifications" dot={hayAvisos()} />
+```
+
+```html
+<!-- ✅ bien -->
+<sui-topbar-button icon="notification-3-line" dot={hayAvisos()}
+  ariaLabel={hayAvisos() ? 'Avisos, hay nuevos' : 'Avisos'} />
+```
+
+El panel abierto
+
+```html
+<!-- ❌ mal: azul del Figma original y (click) en vez de la API -->
+<sui-topbar-button icon="question-line" aria-label="Ayuda" accent="information"
+  active={panelAyuda()} onClick={() => panelAyuda.set(!panelAyuda())} />
+```
+
+```html
+<!-- ✅ bien -->
+<sui-topbar-button icon="question-line" aria-label="Ayuda"
+  active={panelAyuda()} onClicked={() => panelAyuda.set(!panelAyuda())} />
+```
+
+Un ícono en una card
+
+```html
+<!-- ❌ mal: es el botón de la barra superior; en una card desentona (radio 10, 40 fijo) -->
+<sui-topbar-button icon="more-2-line" aria-label="Opciones" onClicked={() => abrirMenu()} />
+```
+
+```html
+<!-- ✅ bien -->
+<sui-button variant="ghost" color="neutral" size={bp.sizeControl()} only-icon
+  left-icon="more-2-line" aria-label="Opciones" onClick={() => abrirMenu()} />
+```
+
+## Ejemplo
+
+```html
+<sui-topbar-button
+  icon="notification-3-line"
+  aria-label="Avisos"
+  dot={hayAvisos()}
+  active={panelAvisos()}
+  onClicked={() => panelAvisos.set(!panelAvisos())} />
+```

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

@@ -0,0 +1,170 @@
+---
+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
+
+<!-- generado por scripts/gen-docs.mjs — no editar a mano; `npm run docs` -->
+
+> **De dónde sale este doc.** El criterio es el del SUI Angular (`sui-topbar-item`); la API es la de este
+> paquete, leída del código. Los ejemplos se pasaron de Angular de forma mecánica: lo literal va como
+> atributo (`only-icon`, `size="large"`), lo dinámico entre llaves (`size={expr}` → `el.size = expr`)
+> y los eventos como `onValueChange={…}` → `el.addEventListener('valueChange', …)`. `@if`, `@for` y
+> `<ng-template>` quedan como en Angular: se leen como pseudocódigo.
+
+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. Las reglas
+> marcadas canon están aprobadas (05-10-2026) y no queda ninguna en propuesta.
+
+| prop | cuándo | fuente |
+|---|---|---|
+| solo `label` | El caso normal. Una o dos palabras, sentence case. | canon (aprobado por el dueño, 05-10-2026, bloque B4) |
+| `icon` | Si **todos** los items de la barra lo llevan. | canon (aprobado por el dueño, 05-10-2026, bloque B9) |
+| `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. | según el código |
+| sin `href` | Es un `<button>`: navegas tú en `clicked`. | según el código |
+| `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 | canon (aprobado por el dueño, 05-10-2026, bloque B7) |
+
+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.
+
+### Por dispositivo (D16)
+
+No aplica una tabla: no tiene input `size` y mide 36 de alto en todos los dispositivos. Como se toca
+y no tiene un size que llegue a 44, B7 lo saca de todo lo táctil: en el celular chico, el celular y
+la tablet táctil **no se usa**; solo en la computadora (`pointer: fine`) y en el ultrawide, igual
+que en la computadora. La columna «mobile» de D16 incluye la tablet en lo que se toca, así que el
+«no usar en mobile» de B7 la cubre.
+
+Badges internos: el `count` va en `small` fijo (hardcodeado en el template, no se puede cambiar). El
+`badge` cae en `small` cuando no se le pasa `size` (el shorthand string siempre); con
+`SuiBadgeConfig` sí acepta `size`, y en la computadora va `medium`, que es lo que D16 da a lo que no
+se toca (lo mismo que devuelve `bp.sizeBadge()` fuera del celular):
+`badge={{ label: 'Nuevo', size: 'medium' }}`. Los dos `small` chocan con «nada en `small`» de D16:
+cambiar el default del badge y el `count` fijo es código del DS, **pendiente** («internos del DS en
+chico» en el doc de decisiones).
+
+En master-pedidos: sin `size` ni helper; si algún día se monta, va detrás de `@if (!bp.tactil())`
+(`isMobile() || toque()`: todo celular por ancho y toda pantalla táctil). No `!bp.isMobile()`: ese
+es solo por ancho (≤ 768) y deja pasar un iPad de 769 a 1024 con `pointer: coarse`.
+
+## API
+
+<!-- api:inicio -->
+<!-- generada: no editar a mano — `npm run docs` -->
+
+| prop | atributo | tipo | default |
+|---|---|---|---|
+| `accent` | `accent` | `"brand" \| "information"` | `'brand'` |
+| `active` | `active` | `boolean` | `false` |
+| `badge` | `badge` | `SuiBadgeConfig \| null \| string` | `null` |
+| `count` | `count` | `null \| number` | `null` |
+| `href` | `href` | `null \| string` | `null` |
+| `icon` | `icon` | `null \| string` | `null` |
+| `label` | `label` | `string` | — (requerido) |
+| `rightIcon` | `right-icon` | `null \| string` | `null` |
+| `target` | `target` | `null \| string` | `null` |
+
+| evento | `event.detail` |
+|---|---|
+| `clicked` | `void` |
+
+### Diferencias con el SUI Angular
+
+Ninguna en nombres de props, eventos y valores.
+<!-- 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.
+
+## Bien y mal
+
+Pedidos por aceptar
+
+```html
+<!-- ❌ mal: sin pendientes sale un «0» rojo; solo null lo oculta -->
+<sui-topbar-item label="Pedidos" count={pendientes()} onClicked={() => ir('pedidos')} />
+```
+
+```html
+<!-- ✅ bien -->
+<sui-topbar-item label="Pedidos" count={pendientes() || null} onClicked={() => ir('pedidos')} />
+```
+
+Un item que es link
+
+```html
+<!-- ❌ mal: con href el item ya navega y (clicked) navega otra vez -->
+<sui-topbar-item label="Reportes" href="/reportes" active={seccion() === 'reportes'}
+  onClicked={() => router.navigateByUrl('/reportes')} />
+```
+
+```html
+<!-- ✅ bien -->
+<sui-topbar-item label="Reportes" href="/reportes" active={seccion() === 'reportes'} />
+```
+
+Íconos en la barra
+
+```html
+<!-- ❌ mal: unos con ícono y otros sin; se lee desordenado -->
+<sui-topbar-item label="Tablero" icon="layout-grid-line" active />
+<sui-topbar-item label="Pedidos" />
+```
+
+```html
+<!-- ✅ bien: todos sin ícono (el caso normal), o todos con -->
+<sui-topbar-item label="Tablero" active />
+<sui-topbar-item label="Pedidos" />
+```
+
+## Ejemplo
+
+```html
+<nav class="mi-barra">
+  <sui-topbar-item label="Tablero" active={seccion() === 'tablero'} onClicked={() => ir('tablero')} />
+  <sui-topbar-item label="Pedidos" count={pendientes() || null}
+                   active={seccion() === 'pedidos'} onClicked={() => ir('pedidos')} />
+  <sui-topbar-item label="Más" right-icon="arrow-down-s-line" onClicked={() => abrirMenu()} />
+</nav>
+```