@ajuarezso/sui-stencil 0.0.0-stage → 0.1.0

package/docs/sui-avatar/README.md

@@ -0,0 +1,338 @@
+---
+name: sui-avatar
+selector: sui-avatar
+resumen: La cara de alguien (o el logo de un local) en un círculo, con iniciales cuando no hay foto
+alternativas: [sui-avatar-group (varias personas apiladas), sui-compact-avatar-group (varias personas en una celda de tabla), sui-key-icon (un ícono en círculo que no es nadie), sui-image-upload-profile (subir o cambiar la foto)]
+---
+
+# sui-avatar
+
+<!-- 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-avatar`); 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: [Atoms/Avatar/Avatar](https://sui-design-system.web.app/?path=/docs/atoms-avatar-avatar--docs)
+
+## Cuándo usarlo / cuándo no
+
+**Úsalo** para mostrar **quién es**: un cliente, un repartidor, un local, un miembro del equipo.
+Lleva la foto si la hay y, si no, las iniciales del nombre.
+
+**No lo uses** para:
+
+- Un ícono en un círculo que no representa a nadie (un candado, un check, un reloj): eso es
+  `sui-key-icon`.
+- Subir o cambiar la foto: `sui-image-upload-profile`.
+- Varias personas juntas: `sui-avatar-group` o `sui-compact-avatar-group`.
+- Decir el estado de una cuenta (activa, pendiente, bloqueada): eso es un `sui-badge` o
+  `sui-status-badge` al lado del nombre, no el punto de `status`.
+
+Regla corta: **es alguien → avatar · es una cosa → key-icon · son varios → avatar-group.**
+
+## Qué variante usar
+
+> **La guía del DS dice qué es y qué opciones tiene, no cuándo usar cada una.** Lo marcado
+> «según la guía del DS» sale de su texto o de su código publicado; lo marcado «canon» ya es
+> regla escrita del proyecto (`CLAUDE.md`) o lo aprobó el dueño; el resto es **propuesta, falta aprobación**.
+>
+> Uso medido el 04-10-2026 en `master-pedidos/src/app`: 55 avatares en los templates, sin contar
+> prototipos ni vitrinas (`master-preview`, `master-prototipos`, `mockup-sheets-*`, `dx/*`,
+> `master-rutina`, `master-medico`, `dev-index`). Tamaños: 23 `lg`, 19 `md`, 5 `sm`, 3 `xs`,
+> 3 `xl`, 1 `2xl`, 1 `3xl`. Colores, ya con el canon por rol: 21 `green`, 14 `orange`, 12 `blue`,
+> 1 `gray` y 7 dinámicos (`color` que sale del rol). Ninguno con `bgColor` ni `slate`.
+
+### Lo que sí dice la guía del DS
+
+- **Para qué es**: una imagen que representa a una persona o a una organización.
+- **Tamaños**: 80, 72, 64, 56, 48, 40, 32, 24 y 20 px; el default de la guía es 80 (en SUI,
+  `md` = 32).
+- **Colores**: solo seis, `gray` (default), `yellow`, `blue`, `sky`, `purple` y `red`. Son el
+  fondo de las iniciales. `orange`, `green`, `pink`, `teal` y `slate` son **extensiones de SUI**.
+- **Texto**: las iniciales van en MAYÚSCULAS.
+- **Placeholder**: sin contenido sale una silueta (de persona o de empresa).
+- **Indicadores**: el estado (`online`, `offline`, `busy`, `away`) y el logo de la empresa van
+  **abajo** a la derecha; la notificación (punto rojo) y el sello de verificado van **arriba**.
+
+### Contenido: qué se muestra
+
+La cascada es fija: `src` → `memojiSrc` → `illustrationSrc` → `initials` → `icon` → silueta. Si
+la foto falla al cargar, cae sola a las iniciales.
+
+| contenido | cuándo | fuente |
+|---|---|---|
+| foto (`src`) | Siempre que exista. Si es la foto **de otra persona**, es su `avatarUrl` de nuestro Storage, denormalizada en el documento por la Cloud Function y filtrada por `fotoDeStorage()`. **Nunca `photoURL` de Google**: solo carga en el navegador del dueño de esa cuenta. | canon (`CLAUDE.md`, «Fotos de otra persona») |
+| `initials` | Sin foto. Pasa el **nombre completo**: el componente saca las iniciales. | según la guía del DS |
+| `icon` | Solo para «todavía no hay nadie»: pedido sin repartidor (`e-bike-2-line`), envío sin destinatario (`user-3-line`). Va con `color="gray"`. Extensión de SUI. | canon (aprobado por el dueño, 05-10-2026, bloque B3) |
+| silueta | Cae sola cuando no hay ni nombre. No se pide a propósito. | según la guía del DS |
+
+### `size`
+
+| size | px | cuándo | ejemplo real de la app | fuente |
+|---|---|---|---|---|
+| `xs` | 20 | Pegado a un texto en la misma línea. | `components/sidebar/sidebar.html:77` (selector de local) · `pages/envios/envios.html:250` | canon (aprobado por el dueño, 05-10-2026, bloque B1) |
+| `sm` | 24 | Chips y filas compactas. | `pages/driver/driver-dashboard/driver-dashboard.html:1047` (quién tomó el pedido) | canon (aprobado por el dueño, 05-10-2026, bloque B1) |
+| `md` (default SUI) | 32 | Filas de listas y tablas. | `pages/super-admin/master-orders/master-orders.html:197` | canon (aprobado por el dueño, 05-10-2026, bloque B1) |
+| `lg` | 40 | La tarjeta de una persona o de un local. | `pages/customer/order-tracking/order-tracking.html:348` (tu repartidor) | canon (aprobado por el dueño, 05-10-2026, bloque B1) |
+| `xl` | 48 | Cabecera de un panel. | `pages/driver/driver-dashboard/driver-dashboard.html:19` (tu foto) | canon (aprobado por el dueño, 05-10-2026, bloque B1) |
+| `2xl` | 56 | Cabecera de una ficha. | `pages/super-admin/master-users/master-user-sheet.html:21` | canon (aprobado por el dueño, 05-10-2026, bloque B1) |
+| `3xl` | 64 | Tu propia foto al registrarte. | `pages/driver-onboarding/step-info/step-info.html:31` | canon (aprobado por el dueño, 05-10-2026, bloque B1) |
+| `4xl` / `5xl` | 72 / 80 | No usar hoy (ver «No usar»). | — | canon (aprobado por el dueño, 05-10-2026, bloque B1) |
+
+Hasta `md` (32 px) se ve **una** inicial; desde `lg` (40 px), dos. Es del Figma: en chico dos
+letras no entran.
+
+### `color` — solo se ve cuando no hay foto
+
+La guía no le da significado al color. En Master Pedidos dice **qué rol** tiene la persona, para
+que en una pantalla con cliente, local y repartidor juntos (el detalle de un pedido) se distingan
+sin leer el nombre.
+
+| color | cuándo | fuente |
+|---|---|---|
+| `orange` | Locales (y la gente del local: su equipo y sus empleados). Extensión de SUI. | canon (aprobado por el dueño, 03-10-2026) |
+| `green` | Repartidores, también el propio repartidor en su app. Extensión de SUI. | canon (aprobado por el dueño, 03-10-2026) |
+| `blue` | Clientes y destinatarios, también quien firma una reseña de cliente. | canon (aprobado por el dueño, 03-10-2026) |
+| `gray` (default de la guía) | «Todavía nadie», con `icon` (pedido sin repartidor, envío sin destinatario). | canon (aprobado por el dueño, 03-10-2026) |
+| `slate` (default SUI) | No hace falta en la app: todo avatar tiene un rol o es «todavía nadie». | derivado del canon por rol, falta confirmación |
+| `purple`, `sky`, `yellow`, `pink`, `teal`, `red` | No se usan para personas: un quinto color no diría ningún rol. | derivado del canon por rol, falta confirmación |
+
+Reglas que van con la tabla:
+
+- **Un mismo rol en una lista no cambia de color por persona.** Las reseñas de `ratings-detail`
+  ya no llevan un color por id: van azules (cliente) o verdes (repartidor) según quién opina.
+- **El color sale del rol de quien se muestra, no de la pantalla.** El logo del local en la app
+  del repartidor sigue siendo `orange`; el repartidor en el seguimiento del cliente, `green`.
+- **Un componente que muestra a «alguien» que cambia según quién lo usa** recibe el color del que
+  lo llama, no lo fija adentro (`ratings-detail` con `entityColor` / `autoresColor`,
+  `rate-entity-card` con `color`).
+- **`bgColor` con un hex no se usa para personas**: era un color por nombre que no decía nada.
+- **Las configs (`SuiAvatarConfig`) llevan el `color` explícito**: `sui-content-card` cae a
+  `orange` y `sui-content-label` a `slate`, así que confiar en el default pinta mal a la mitad.
+
+Aplicado en toda la app (fuera de `master-preview`, prototipos, mockups y `/dx`) el 03-10-2026.
+Pendiente: el perfil de los sidebars (`SuiSidebarProfile`) no acepta `color`, así que la persona
+logueada sigue en el default.
+
+### `status` — el punto de abajo
+
+| status | cuándo | fuente |
+|---|---|---|
+| `online` | Conectado **ahora** (repartidor en línea). No significa «cuenta activa». | canon (aprobado por el dueño, 05-10-2026, bloque B2) (el valor es de la guía) |
+| `away` | En pausa: conectado pero sin recibir pedidos. | canon (aprobado por el dueño, 05-10-2026, bloque B2) (el valor es de la guía) |
+| `busy` | Ocupado: ya lleva un pedido. | canon (aprobado por el dueño, 05-10-2026, bloque B2) (el valor es de la guía) |
+| `offline` | Desconectado. Si en esa lista todos estarían `offline` casi siempre, mejor sin punto. | canon (aprobado por el dueño, 05-10-2026, bloque B2) (el valor es de la guía) |
+| `company` | Repartidor propio de un local: el logo del local abajo (con `companyLogoSrc`). | canon (aprobado por el dueño, 05-10-2026, bloque B2) (la guía lo muestra como «con logo de marca») |
+
+**Usos de hoy que rompen la regla: 2.** Los dos usan el punto para el **estado de la cuenta**,
+no para la presencia: `pages/settings/team/team.html:99` (activo/pendiente/inactivo →
+online/away/offline, mapeo en `pages/settings/team/team.ts:99`) y `pages/employees/employees.html:70`
+(«Activo» por pedidos recientes → `online`). Eso va en un `sui-badge` al lado del nombre.
+
+### `topBadge` — la insignia de arriba
+
+| topBadge | cuándo | fuente |
+|---|---|---|
+| `verified` | Identidad revisada (repartidor aprobado). | canon (aprobado por el dueño, 05-10-2026, bloque B2) (la guía muestra un sello de verificado arriba) |
+| `notification` | Tiene algo sin leer. | canon (aprobado por el dueño, 05-10-2026, bloque B2) (el punto rojo arriba es de la guía) |
+| `favorite`, `pin`, `add`, `remove` | No usar hoy (ver «No usar»). | canon (aprobado por el dueño, 05-10-2026, bloque B2) |
+
+Hoy no hay ningún `topBadge` en la app.
+
+### El resto de las propiedades
+
+| input | cuándo | fuente |
+|---|---|---|
+| `alt` | **Siempre** el nombre de quien es. Con foto va en el `<img>`; con iniciales, ícono o silueta el host pasa a `role="img"` con `aria-label` = `alt` (desde el 04-10-2026; antes el lector leía la letra suelta). Sin `alt`, el lector no dice nada. | canon (aprobado por el dueño, 05-10-2026, bloque B5) |
+| `companyLogoSrc` | Solo con `status="company"`. | canon (aprobado por el dueño, 05-10-2026, bloque B6) |
+| `memojiSrc`, `illustrationSrc` | No usar hoy. | canon (aprobado por el dueño, 05-10-2026, bloque B6) |
+| `bgColor` | No usar (ver abajo). | canon (aprobado por el dueño, 05-10-2026, bloque B6) |
+
+**Usos de hoy sin `alt`: 9** (más uno decorativo que está bien sin él,
+`pages/super-admin/master-orders/master-orders.html:586`). Ejemplos:
+`pages/super-admin/master-drivers/master-drivers.html:252`, `:779`, `pages/employees/employees.html:70`.
+
+**`bgColor` en la app: 0** (eran 7 hasta el 03-10-2026). Los cinco con paleta saturada escrita a
+mano (clientes, empleados, reporte de repartidores y equipo) rompían la rampa `*-200` del DS y
+dejaban las iniciales sin contraste; los dos con `var(--sui-bg-weak-50)` eran un `slate`
+disfrazado. Todos pasaron a `color` por rol.
+
+### La foto de otra persona (regla del proyecto)
+
+- **Resuelta** (commit `74fa3b26` de master-pedidos): `core/services/orders.service.ts:407` ya
+  congela en el pedido (`driverPhotoUrl`) solo una foto que pasa `esFotoDeStorage`, así que el
+  cliente ya no puede recibir la de Google en `pages/customer/order-tracking/order-tracking.html:348`.
+- **A revisar** (pintan un `avatarUrl` de otra persona sin el filtro de `fotoMostrable` a la
+  vista): `pages/super-admin/master-drivers/master-drivers.html:712` (`r.foto`), `:779`
+  (`s.avatarUrl`) y `pages/drivers/add-driver/add-driver.html:73`.
+- **Latente**: `pages/customers/customers.ts:277` arma `avatarUrl || photoURL`, pero la tabla
+  hoy no lo pinta.
+
+## Tamaño en mobile y en web
+
+En mobile se lee y se toca con el dedo, así que va más grande; en web, más chico. En las
+pantallas que se usan en los dos (panel del local, super admin) se elige con el servicio de
+breakpoints de la app (`bp`, en `services/breakpoints.service.ts`); en las que solo existen en
+el celular (cliente, repartidor) va directo el valor de mobile. No se toca, así que la tablet va
+con el valor de web, y el celular chico (< 380 px) también (D16).
+Es **canon (dueño, 05-10-2026, P1 b)**: un paso más grande en el celular que en computadora, y
+se migra todo ahora, no solo al tocar cada pantalla.
+
+| uso | mobile | web |
+|---|---|---|
+| pegado a un texto | `sm` (24) | `xs` (20) |
+| fila de lista o tabla | `lg` (40) | `md` (32) |
+| tarjeta de una persona o un local | `xl` (48) | `lg` (40) |
+| cabecera de una ficha | `3xl` (64) | `2xl` (56) |
+
+```html
+<sui-avatar size={bp.sizeAvatar('md')} color="blue" initials={c.nombre} alt={c.nombre} />
+```
+
+El avatar no se toca solo: si la fila o la card es tocable, el área táctil (44 px o más) la da
+la fila, no el avatar. Medido el 06-10-2026: 56 de los 57 avatares de la app ya van con
+`bp.sizeAvatar(…)`; el único fijo es `pages/driver-onboarding/step-info/step-info.html:31`
+(`3xl`, tu foto al registrarte).
+
+### Por dispositivo (D16)
+
+El avatar no se toca: sube un paso **solo en el celular de 380 px o más**. Fuente: D16, dueño
+05-10-2026 (P1 b).
+
+| dispositivo | size | nota |
+|---|---|---|
+| celular chico (< 380) | valor «web» (`md` en una fila) | no se toca: no sube aunque sea un celular |
+| celular (380–767) | valor «mobile» (`lg` en una fila) | un paso más que en la computadora |
+| tablet táctil (`pointer: coarse`) | valor «web» (`md` en una fila) | no se toca: el puntero no cambia nada |
+| computadora (`pointer: fine`) | valor «web» (`md` en una fila) | |
+
+En el ultrawide, igual que en la computadora: el espacio extra va a más columnas, no a avatares
+más grandes.
+
+En master-pedidos: `size={bp.sizeAvatar('md')}` — recibe el valor de la computadora y en el
+celular devuelve el siguiente de la escala, con tope en `3xl` (no sube a `4xl`/`5xl`). No uses
+`bp.isMobile() ? 'lg' : 'md'`: `isMobile` incluye el celular chico, que va con el valor de web.
+
+## «No usar»: por qué no hoy y cuándo sí
+
+Nada se borra del DS. Lo marcado «no usar» no tiene caso en la app de hoy; si un flujo nuevo
+cae en la columna de la derecha, se usa.
+
+| qué | por qué no hoy | cuándo sí, en un flujo nuevo |
+|---|---|---|
+| `size` `4xl`, `5xl` | ninguna pantalla muestra una foto tan grande | un perfil público del repartidor o del local con la foto como protagonista |
+| `color` `red` | un círculo rojo se lee como error | ninguno previsto; se deja porque la guía lo tiene |
+| `topBadge` `favorite`, `pin`, `add`, `remove` | no hay favoritos, fijados ni selección de personas con avatar | elegir varios repartidores para una zona (`add`/`remove`) o fijar un chat (`pin`) |
+| `memojiSrc`, `illustrationSrc` | no hay memojis ni ilustraciones de personas | avatares ilustrados por defecto para quien no sube foto |
+| `bgColor` | pinta colores fuera de la paleta y deja el texto sin contraste | una entidad con su color de marca guardado que tiene que verse igual en todas partes |
+
+## API
+
+<!-- api:inicio -->
+<!-- generada: no editar a mano — `npm run docs` -->
+
+| prop | atributo | tipo | default |
+|---|---|---|---|
+| `alt` | `alt` | `string` | `''` |
+| `bgColor` | `bg-color` | `null \| string` | `null` |
+| `color` | `color` | `"blue" \| "gray" \| "green" \| "orange" \| "pink" \| "purple" \| "red" \| "sky" \| "slate" \| "teal" \| "yellow"` | `'slate'` |
+| `companyLogoSrc` | `company-logo-src` | `null \| string` | `null` |
+| `icon` | `icon` | `null \| string` | `null` |
+| `illustrationSrc` | `illustration-src` | `null \| string` | `null` |
+| `initials` | `initials` | `string` | `''` |
+| `memojiSrc` | `memoji-src` | `null \| string` | `null` |
+| `size` | `size` | `"2xl" \| "3xl" \| "4xl" \| "5xl" \| "lg" \| "md" \| "sm" \| "xl" \| "xs"` | `'md'` |
+| `src` | `src` | `null \| string` | `null` |
+| `status` | `status` | `"away" \| "busy" \| "company" \| "offline" \| "online" \| null` | `null` |
+| `topBadge` | `top-badge` | `"add" \| "favorite" \| "notification" \| "pin" \| "remove" \| "verified" \| null` | `null` |
+
+Eventos: ninguno.
+
+### Diferencias con el SUI Angular
+
+Ninguna en nombres de props, eventos y valores.
+<!-- api:fin -->
+
+```ts
+// Lo reciben los componentes con avatar adentro (command-menu-item, content-label,
+// dropdown-item, tag…). Un string suelto = src.
+interface SuiAvatarConfig {
+  src?: string | null;
+  initials?: string;
+  color?: SuiAvatarColor;
+}
+```
+
+## Trampas
+
+- **`initials` recibe el nombre, no las iniciales.** «Rosa Quispe» → `RQ`; una sola palabra
+  («Rosa») → `RO`. Si le pasas `"R"` ya cortado, en `lg` sale `R` sola.
+- **Una letra hasta `md`, dos desde `lg`.** No es un bug: es el Figma.
+- **El color no se ve si hay foto.** Solo pinta el fondo de las iniciales, del ícono y de la silueta.
+- **`slate` (default de SUI) y `gray` (default de la guía) no son lo mismo**: `slate` es casi
+  blanco con texto gris; `gray` es gris claro con texto negro.
+- **El avatar no cambia con el tema oscuro**: fondos y texto de las iniciales son fijos a propósito.
+- **`bgColor` gana sobre `color`** pero no cambia el color del texto: con un fondo oscuro, las
+  iniciales quedan ilegibles.
+- **El punto de `status` mide el 25 % del avatar; `topBadge` y el logo de `company`, el 40 %**:
+  en `xs` casi no se ven.
+- **`companyLogoSrc` solo se ve con `status="company"`.**
+- **Si la foto falla, cae sola a las iniciales**, y si cambia el `src` lo vuelve a intentar.
+- **No tiene `title`, ni output, ni es clickeable.** Para tocarlo, envuélvelo en un botón o en
+  la card que ya lo es.
+
+## Bien y mal
+
+Estado de la cuenta de un empleado
+
+```html
+<!-- ❌ mal: el punto es presencia (conectado ahora), no «cuenta activa»; y sin alt (pages/employees/employees.html:70) -->
+<sui-avatar size={bp.sizeAvatar('lg')} color="orange" initials={employee.initials}
+  status={employee.status === 'Activo' ? 'online' : 'offline'} />
+```
+
+```html
+<!-- ✅ bien -->
+<sui-avatar size={bp.sizeAvatar('lg')} color="orange" initials={employee.initials} alt={employee.name} />
+<sui-badge size={bp.sizeBadge()} color="green">Activo</sui-badge>
+```
+
+Repartidor en una fila
+
+```html
+<!-- ❌ mal: sin alt, el lector de pantalla no dice quién es; y en una fila (aquí, el ranking de rendimiento) la tabla de tamaños pide md en web, no lg (pages/super-admin/master-drivers/master-drivers.html:256) -->
+<sui-avatar size={bp.sizeAvatar('lg')} color="green" initials={iniciales(d.nombre)} />
+```
+
+```html
+<!-- ✅ bien -->
+<sui-avatar size={bp.sizeAvatar('md')} color="green" initials={iniciales(d.nombre)} alt={d.nombre} />
+```
+
+Color de una persona
+
+```html
+<!-- ❌ mal: el color sale del vehículo, no del rol. El conductor queda blue, que es el color de cliente, y el motorizado purple, que no dice ningún rol. Los dos son postulantes a repartidor: green. Y falta el alt (pages/super-admin/master-solicitudes/master-solicitudes.html:24) -->
+<sui-avatar size={bp.sizeAvatar('md')} color={f.tipo === 'conductor' ? 'blue' : 'purple'} initials={iniciales(f.nombre)} />
+```
+
+```html
+<!-- ✅ bien -->
+<sui-avatar size={bp.sizeAvatar('md')} color="green" initials={iniciales(f.nombre)} alt={f.nombre} />
+```
+
+## Ejemplo
+
+```html
+<!-- Tu repartidor, en la tarjeta del seguimiento -->
+<sui-avatar size={bp.sizeAvatar('lg')} color="green" src={driverPhotoUrl()} initials={driverName} alt={driverName} />
+
+<!-- El local, en una fila -->
+<sui-avatar size={bp.sizeAvatar('md')} color="orange" src={tenantLogo} initials={tenantName} alt={tenantName} />
+
+<!-- Todavía sin repartidor -->
+<sui-avatar size={bp.sizeAvatar('md')} color="gray" icon="e-bike-2-line" alt="Sin repartidor" />
+```

package/docs/sui-avatar-group/README.md

@@ -0,0 +1,203 @@
+---
+name: sui-avatar-group
+selector: sui-avatar-group
+resumen: Varias personas apiladas en una fila, con «+N» cuando no entran todas
+alternativas: [sui-compact-avatar-group (la versión en píldora, para celdas de tabla), sui-avatar (una sola persona)]
+---
+
+# sui-avatar-group
+
+<!-- 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-avatar-group`); 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: [Atoms/Avatar/Avatar Group](https://sui-design-system.web.app/?path=/docs/atoms-avatar-avatar-group--docs)
+
+## Cuándo usarlo / cuándo no
+
+**Úsalo** cuando importa **cuántos y quiénes** a la vez: el equipo de un local, los repartidores
+conectados en una zona. Cada persona se ve chica; el grupo es lo que cuenta.
+
+**No lo uses** para:
+
+- Una sola persona: `sui-avatar`.
+- Una celda de tabla o una fila muy baja: `sui-compact-avatar-group`, que ocupa menos alto.
+- Una lista donde hay que leer el nombre de cada uno: ahí van filas con `sui-avatar` y el nombre.
+
+## Qué variante usar
+
+> **La guía del DS dice qué es y sus tamaños, no cuándo usarlo.** Lo marcado «según la guía
+> del DS» sale de su texto o de su código; lo marcado «canon» ya lo aprobó el dueño; el resto es
+> **propuesta, falta aprobación**.
+>
+> Uso medido el 03-10-2026 en `master-pedidos/src/app`: **0 usos directos**. En el DS no lo
+> monta ningún componente: `sui-table` solo lo nombra como contenido que se proyecta en una celda.
+
+### Lo que sí dice la guía del DS
+
+- **Para qué es**: dos o más avatares en una pila en línea.
+- **Tamaños**: los mismos nueve del avatar (80 a 20 px); el default de la guía es 80.
+- **El «+N»**: un círculo gris (`bg-weak-50`, texto `text-sub-600`) del mismo tamaño que los
+  avatares. Su ejemplo muestra **tres** avatares y el «+9».
+
+### `size` y `max`
+
+| input | valor | cuándo | fuente |
+|---|---|---|---|
+| `size` | `sm` (24) | Dentro de una fila: «los que tomaron pedidos hoy». | canon (aprobado por el dueño, 05-10-2026, bloque B1) |
+| `size` | `md` (32, default SUI) | La card del equipo de un local. | canon (aprobado por el dueño, 05-10-2026, bloque B1) |
+| `size` | `lg` (40) | La cabecera de un panel (repartidores en la zona). | canon (aprobado por el dueño, 05-10-2026, bloque B1) |
+| `size` | `xs`, `xl` a `5xl` | No usar hoy: en `xs` el «+N» no se lee; desde `xl` ya no es un resumen. | canon (aprobado por el dueño, 05-10-2026, bloque B1) |
+| `max` | `3` | Tres visibles y el «+N», como el ejemplo de la guía. El default de SUI es `4`. | canon (aprobado por el dueño, 05-10-2026, bloque B1) |
+| `items` | — | Cada item es `{ src, initials, color, alt }`. Las reglas de foto y color son las de `sui-avatar`: la foto de otra persona es su `avatarUrl` de Storage, y el `color` va **siempre** explícito por rol (sin `color` el item cae a `slate`). | canon (`CLAUDE.md`, «Fotos de otra persona») · canon (aprobado por el dueño, 03-10-2026: naranja local, verde repartidor, azul cliente) |
+
+Usos de hoy que rompen la regla: **0** (no hay usos).
+
+## Tamaño en mobile y en web
+
+En mobile se lee y se toca con el dedo, así que va más grande; en web, más chico. En las
+pantallas que se usan en los dos (panel del local, super admin) se elige con el servicio de
+breakpoints de la app (`bp`, en `services/breakpoints.service.ts`); en las que solo existen en
+el celular (cliente, repartidor) va directo el valor de mobile. No se toca, así que la tablet va
+con el valor de web, y el celular chico (< 380 px) también (D16).
+Es **canon (dueño, 05-10-2026, P1 b)**: un paso más grande en el celular que en computadora, y
+se migra todo ahora, no solo al tocar cada pantalla.
+
+| uso | mobile | web |
+|---|---|---|
+| dentro de una fila | `md` (32) | `sm` (24) |
+| dentro de una card | `lg` (40) | `md` (32) |
+
+```html
+<sui-avatar-group size={bp.sizeAvatar('sm')} max="3" items={equipo} />
+```
+
+### Por dispositivo (D16)
+
+El grupo no se toca: sigue la misma regla que `sui-avatar` y sube un paso **solo en el celular
+de 380 px o más**. Fuente: D16, dueño 05-10-2026 (P1 b).
+
+| dispositivo | size | nota |
+|---|---|---|
+| celular chico (< 380) | valor «web» (`sm` en una fila, `md` en una card) | no se toca: no sube aunque sea un celular |
+| celular (380–767) | valor «mobile» (`md` en una fila, `lg` en una card) | un paso más que en la computadora |
+| tablet táctil (`pointer: coarse`) | valor «web» | no se toca: el puntero no cambia nada |
+| computadora (`pointer: fine`) | valor «web» | |
+
+En el ultrawide, igual que en la computadora.
+
+En master-pedidos: `size={bp.sizeAvatar('sm')}` (fila) · `size={bp.sizeAvatar('md')}` (card).
+No hay un helper propio del grupo: `sizeAvatar` sirve porque usa la misma escala (`SuiAvatarSize`).
+No uses `bp.isMobile() ? 'md' : 'sm'`: `isMobile` incluye el celular chico, que va con el valor
+de web. Ojo: con `bp.sizeAvatar('lg')` (cabecera de un panel) el celular sale en `xl`, que arriba
+está en «no usar» — pendiente de decidir si la cabecera se queda en `lg` también en el celular.
+
+## «No usar»: por qué no hoy y cuándo sí
+
+| qué | por qué no hoy | cuándo sí, en un flujo nuevo |
+|---|---|---|
+| todo el componente (0 usos) | ninguna pantalla muestra varias personas juntas | el equipo de un local en su card, o los repartidores conectados en una zona del super admin |
+| `size` `xs` y de `xl` para arriba | en 20 px el «+N» no se lee; desde 48 px el grupo deja de ser un resumen | ninguno previsto |
+
+## API
+
+<!-- api:inicio -->
+<!-- generada: no editar a mano — `npm run docs` -->
+
+| prop | atributo | tipo | default |
+|---|---|---|---|
+| `items` | — (solo por propiedad JS) | `readonly SuiAvatarGroupItem[]` | `[]` |
+| `max` | `max` | `number` | `4` |
+| `size` | `size` | `"2xl" \| "3xl" \| "4xl" \| "5xl" \| "lg" \| "md" \| "sm" \| "xl" \| "xs"` | `'md'` |
+
+Eventos: ninguno.
+
+### 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 |
+|---|---|---|
+| `comun.masN` | {n} más | — |
+<!-- textos:fin -->
+
+```ts
+interface SuiAvatarGroupItem {
+  src?: string;
+  initials?: string;
+  color?: SuiAvatarColor;
+  alt?: string;
+}
+```
+
+## Trampas
+
+- **No recibe avatares proyectados**: los arma él desde `items`. Para un indicador
+  (`status`, `topBadge`) en una persona del grupo, no hay forma.
+- **`max` cuenta avatares, no el total**: con 6 items y `max` 3 sale «+3».
+- **El «+N» no es un botón**: no tiene output. Si tiene que abrir la lista completa, envuélvelo.
+- El solape cambia con el tamaño (−4 px en `xs`/`sm`, −16 px desde `2xl`): en `lg` las iniciales
+  de dos letras quedan tapadas a medias.
+
+## Bien y mal
+
+Hoy no hay usos en la app (0 el 06-10-2026): los pares salen de las reglas de arriba.
+
+Color de cada persona
+
+```html
+<!-- ❌ mal: items sin color caen a slate y no dicen el rol (ver «size y max») -->
+<sui-avatar-group size={bp.sizeAvatar('md')} max="3"
+  items={[{ initials: 'Carlos Mamani', alt: 'Carlos Mamani' }, { initials: 'Ana Torres', alt: 'Ana Torres' }]} />
+```
+
+```html
+<!-- ✅ bien -->
+<sui-avatar-group size={bp.sizeAvatar('md')} max="3"
+  items={[{ initials: 'Carlos Mamani', color: 'green', alt: 'Carlos Mamani' }, { initials: 'Ana Torres', color: 'green', alt: 'Ana Torres' }]} />
+```
+
+Grupo dentro de una fila
+
+```html
+<!-- ❌ mal: en xs (20 px) el «+N» no se lee, y sin [max] salen 4 en vez de 3 -->
+<sui-avatar-group size="xs" items={equipo} />
+```
+
+```html
+<!-- ✅ bien -->
+<sui-avatar-group size={bp.sizeAvatar('sm')} max="3" items={equipo} />
+```
+
+Tamaño fijo en una pantalla que se ve en los dos
+
+```html
+<!-- ❌ mal: md fijo en el panel; en el celular queda un paso por debajo (D16) -->
+<sui-avatar-group size="md" max="3" items={equipo} />
+```
+
+```html
+<!-- ✅ bien -->
+<sui-avatar-group size={bp.sizeAvatar('md')} max="3" items={equipo} />
+```
+
+## Ejemplo
+
+```html
+<sui-avatar-group size={bp.sizeAvatar('md')} max="3" items={[
+  { initials: 'Carlos Mamani', color: 'green', alt: 'Carlos Mamani' },
+  { src: repartidor2.avatarUrl, initials: repartidor2.nombre, color: 'green', alt: repartidor2.nombre },
+  { initials: 'Luis Huamán', color: 'green', alt: 'Luis Huamán' },
+  { initials: 'Ana Torres', color: 'green', alt: 'Ana Torres' }
+]} />
+```