@ajuarezso/sui-design-system 0.21.0 → 0.22.0

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())" />
+```