@ajuarezso/sui-design-system 0.20.0 → 0.22.0

package/docs/INDEX.md

@@ -9,128 +9,123 @@ se lee esta lista; para usar uno, se abre su doc:
 - en Storybook: `<storybook>/<name sin sui->.md` (ej. `/alert.md`) y la lista en `/index.md`
 - en el repo: `projects/sui-design-system/src/lib/<name>/README.md`
 
-Documentados: 42 de 116.
+Documentados: 116 de 116.
 
 | name | resumen | alternativas |
 |---|---|---|
+| `sui-accordion` | Fila con título que se abre para mostrar un texto o contenido secundario que no hace falta ver siempre | sui-tabs (vistas hermanas que se alternan) · sui-modal (detalle que pide atención completa) · sui-card (contenido que siempre se ve) |
+| `sui-activity-feed` | Historial de actividad — quién hizo qué y hace cuánto — con archivos, comentarios, personas o tareas debajo de cada fila | sui-notification (bandeja de avisos para quien mira, con leído/no leído) · sui-stepper (los pasos fijos de un flujo, no un historial) · sui-table (registros para comparar por columnas) · sui-activity-filter (los filtros que van arriba del feed) |
+| `sui-activity-filter` | Chip con ícono para filtrar un historial de actividad por tipo — Archivos, Comentarios, Tareas — prendido o apagado | sui-tab-chips (los filtros de lista de la app, siempre uno elegido) · sui-segmented-control (2-4 vistas hermanas) · sui-tag (una etiqueta que se puede quitar) · sui-badge (un estado que no se toca) |
 | `sui-alert` | Aviso que se queda en la pantalla, en el lugar donde pasa lo que avisa | sui-toast (efímero, resultado de una acción) · sui-banner (afecta a toda la app o la pantalla) · sui-notification (fila de la bandeja) · sui-form-hint (ayuda de un solo campo) |
 | `sui-app-store-badge` | El sello oficial de App Store o Google Play que lleva a descargar la app | sui-link-button (link directo de descarga, «Descargar la app») · sui-social-button (entrar con una cuenta de Google o Apple) |
 | `sui-avatar` | La cara de alguien (o el logo de un local) en un círculo, con iniciales cuando no hay foto | 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-group` | Varias personas apiladas en una fila, con «+N» cuando no entran todas | sui-compact-avatar-group (la versión en píldora, para celdas de tabla) · sui-avatar (una sola persona) |
 | `sui-badge` | Etiqueta corta o número que clasifica algo sin competir con el contenido | sui-status-badge (estado de ciclo: completado, pendiente, fallido, deshabilitado) · sui-tag (chip que se puede quitar) · sui-alert (mensaje que tiene que envolver) |
+| `sui-banner` | Barra de aviso a todo el ancho, arriba de la pantalla, para algo que afecta a toda la app | sui-alert (aviso ligado a una sección o una card) · sui-toast (resultado efímero de una acción) · sui-notification (fila de la bandeja) · sui-modal (algo que bloquea todo, como quedarse sin conexión) |
 | `sui-brand-logo` | El logo oficial de otra marca (WhatsApp, Google, Apple, Instagram…) en su color, sin tocarlo | sui-icon (el mismo logo como ícono monocromo de una línea) · sui-logo (el logo de Master Pedidos) · sui-social-button (botón de entrar con Google o Apple) |
+| `sui-breadcrumb-item` | Una miga suelta de la ruta; casi siempre la dibuja sui-breadcrumbs por ti | sui-breadcrumbs (la ruta completa con separadores) · sui-link-button (un enlace de texto suelto) |
+| `sui-breadcrumbs` | Ruta de migas en web que dice dónde estás dentro de una jerarquía de 3 o más niveles y deja volver a cualquiera | sui-page-header (título de la pantalla) · botón de volver del layout (mobile) · sui-tab-menu-horizontal (secciones del mismo nivel) |
 | `sui-button` | Botón base para que la persona dispare una acción | sui-link-button (acción que se lee como texto) · sui-compact-button (ícono de 20-28 px en filas y barras) · sui-fancy-button (el CTA héroe) · sui-social-button (entrar con Google/Apple) · sui-button-group (opciones que se ven como un solo control) |
 | `sui-button-group` | Opciones pegadas en una fila que se prenden y se apagan, varias a la vez | sui-segmented-control (cambiar de vista o elegir una sola opción) · sui-checkbox (opciones que se suman dentro de un formulario largo) · sui-tab-chips (filtros en chips que se pueden desplazar) |
 | `sui-button-group-item` | Cada opción de un sui-button-group; no se usa suelto | sui-button-group (el grupo, que ya pinta sus ítems desde items[]) · sui-segmented-control (elegir una sola opción) · sui-switch (prender o apagar algo suelto) |
+| `sui-card` | Superficie con borde, radio y sombra que agrupa contenido, con slots de header, cuerpo, media y footer | sui-content-card (una fila «cara + nombre + detalle» dentro de su cajita) · sui-radio-card / sui-checkbox-card / sui-switch-card (la card ES la opción que se elige) · sui-product-card (un producto de la carta) · sui-store-card (un local en un listado del cliente) · sui-modal-sheet (contenido encima de la pantalla) |
+| `sui-chart-legend` | Leyenda de un gráfico — punto de color, nombre de la serie y su valor — dibujada fuera del gráfico | sui-chart-legend-dot (el punto suelto, en una fila o tabla) · la leyenda propia de ECharts (cuando hay que poder apagar series tocándolas) · sui-badge (una etiqueta, no una serie) |
+| `sui-chart-legend-dot` | Punto de color de una serie de gráfico, para atar un número de una fila o una tabla con su color en el gráfico | sui-chart-legend (la leyenda completa, que ya trae sus puntos) · sui-color-dot (elegir un color, no nombrar una serie) · sui-badge with-dot (un estado vivo) |
 | `sui-checkbox` | La casilla sola para marcar una o varias opciones, sin texto propio | sui-checkbox-label (casilla con su texto, el caso normal) · sui-checkbox-card (cada opción es una tarjeta) · sui-switch (prende algo que se aplica al instante) · sui-radio (opciones excluyentes) |
+| `sui-checkbox-card` | Opción con tarjeta (ícono o foto, título, descripción y la casilla) para elegir VARIAS que se guardan después | sui-checkbox-label (la misma casilla sin tarjeta, en un formulario denso) · sui-switch-card (un ajuste que se aplica al toque, sin «Guardar») · sui-radio-card (se elige solo una) · sui-tag-input (valores que la persona escribe) |
 | `sui-checkbox-label` | Casilla con su texto (y opcionalmente descripción, badge y link) para opciones que se suman | sui-checkbox (la casilla sola, el texto vive en otra parte) · sui-checkbox-card (cada opción es una tarjeta) · sui-switch-label (se aplica al instante) · sui-radio-label (una sola opción) |
 | `sui-circular-progress-bar` | El avance de algo en un anillo, para cuando cabe en un cuadrado al lado de un título | sui-progress-bar-label (barra con título y número, cuando hay ancho) · sui-progress-bar (barra pelada) |
 | `sui-color-dot` | Una opción de color para elegir (o mostrar el color elegido); no es un punto de estado | sui-color-picker (el selector completo, con hex propio) · sui-badge type="with-dot" (punto de estado vivo) · sui-status-badge withDot (punto de estado de un ciclo) |
 | `sui-color-picker` | Botón que abre un panel para elegir un color libre (espectro, matiz, hex) o uno de los recomendados | sui-color-dot (un punto de color, para armar una grilla propia) · sui-select o sui-radio-card (el color es una categoría con nombre, no un color libre) |
+| `sui-command-menu-footer` | Pie del buscador ⌘K (command menu) con las teclas para moverse y elegir, y un link de ayuda | sui-modal-footer (botones de un modal) · sui-kbd (una tecla suelta) · sui-dropdown-caption (texto de pie de un menú flotante) |
+| `sui-command-menu-item` | Fila de resultado del buscador ⌘K (command menu) que lleva a una pantalla, un pedido o una persona | sui-dropdown-item (fila de un menú de acciones anclado a un botón) · sui-filter-item (fila de un panel de filtros) · sui-content-card (resultado que se ve en una lista de la pantalla) |
+| `sui-command-menu-search` | Campo de arriba del buscador ⌘K (command menu), sin caja y con borde inferior | sui-input type="search" (buscador de una pantalla) · sui-dropdown-search (filtrar los items de un menú flotante) |
 | `sui-compact-avatar-group` | Varias personas en una píldora baja con el «+N» en texto, para tablas y filas apretadas | sui-avatar-group (la pila grande, para cards y cabeceras) · sui-avatar (una sola persona) |
 | `sui-compact-button` | Botón de solo ícono, chico, para cuando falta espacio | sui-button (acción con texto, o de ícono con onlyIcon en tamaños de 28 a 52) · sui-link-button (acción que se lee como texto) · sui-topbar-button (ícono de la barra superior) |
+| `sui-compact-select` | Select chico que se ajusta al ancho de su texto, para filtros sueltos y paginación | sui-select (campo de formulario a todo el ancho, con label) · sui-inline-select (dentro de una frase, sin caja) · sui-compact-select-for-input (dentro de un sui-input) · sui-segmented-control (2 a 4 modos a la vista) |
+| `sui-compact-select-for-input` | Selector chico que vive DENTRO de un sui-input, para elegir moneda o código de país sin salir del campo | sui-select (el valor se elige aparte, con su propio label) · sui-compact-select (filtro suelto con caja propia) · sui-inline-select (dentro de una frase) |
+| `sui-content-card` | Fila «cara + nombre + detalle» dentro de su propia cajita, con badge y una X opcional para quitarla | sui-content-label (la misma fila sin caja, dentro de una card que ya existe) · sui-card (contenido libre) · sui-radio-card / sui-checkbox-card (la fila se elige) |
 | `sui-content-divider` | Línea con algo encima: el «o» entre dos opciones, la cabecera de un grupo o un botón entre bloques | sui-divider (la línea sola, horizontal o vertical) |
+| `sui-content-label` | Fila sin caja con ícono, foto o logo a la izquierda, título, descripción y un badge opcional | sui-content-card (la misma fila dentro de su propia cajita, con X) · sui-switch-label (un ajuste que se prende o apaga) · sui-alert (un aviso con color) · sui-card (para agrupar las filas) |
+| `sui-counter-input` | Cantidad con − y + a los lados, con mínimo y máximo (unidades en el carrito, pasajeros) | sui-input type="number" (un número que se tipea, sin pasos de a uno) · sui-slider (un valor de un rango continuo) · sui-select (elegir una cantidad de una lista corta) |
+| `sui-date-selector` | La cabecera de un calendario con el mes y las flechas de anterior y siguiente | sui-datepicker (el calendario completo, que ya la trae) · sui-tab-chips (elegir entre pocos días: hoy, mañana, sábado) |
+| `sui-datepicker` | Calendario para elegir una fecha o un rango de fechas, en popover o en línea | sui-input type="date" (una fecha suelta en un formulario: abre el selector del sistema) · sui-tab-chips + sui-radio-label (día y franja de un pedido programado) · sui-tab-chips o sui-select (períodos fijos: hoy, 7 días, 30 días) |
+| `sui-day-cell` | Un día del calendario, con sus estados de elegido, rango, hoy, marcado y bloqueado | sui-datepicker (el calendario completo, que ya la trae) · sui-tab-chips (pocos días para elegir, con nombre: hoy, mañana) |
+| `sui-day-label` | La inicial del día de la semana arriba de cada columna del calendario | sui-datepicker (el calendario completo, que ya la trae) · sui-button-group (elegir días de la semana: L M M J V S D) |
 | `sui-divider` | Línea de 1 px que separa bloques (horizontal) o datos en una fila (vertical) | sui-content-divider (línea con texto o botones encima, o el «o» entre dos opciones) |
+| `sui-drawer-footer` | Pie de un panel lateral con dos botones y un extra a la izquierda; hoy sin uso, los botones van en sui-modal-footer | sui-modal-footer (el canon de botones de toda la app) · sui-filter-panel-footer (pie de un panel de filtros) |
+| `sui-drawer-header` | Cabecera de un panel lateral (título, descripción, cerrar); hoy sin contenedor en SUI y sin uso en la app | sui-modal (con title y description: la cabecera de todos los modales de la app) · sui-modal-header (la cabecera suelta del modal) · sui-page-header (título de una página) |
+| `sui-dropdown-caption` | Texto gris de pie dentro de un menú flotante (una pista, la versión, cuándo se actualizó) | sui-content-divider (cabecera de un grupo de items) · sui-form-hint (ayuda debajo de un campo) · sui-empty-state (el menú no tiene resultados) |
+| `sui-dropdown-item` | Fila de un menú flotante o de una lista de opciones, con ícono, bandera, avatar o logo a la izquierda y badge o atajo a la derecha | sui-command-menu-item (fila del buscador ⌘K) · sui-filter-item (fila de un panel de filtros) · sui-sidebar (navegación lateral, con sus items) · sui-radio-label (opciones fijas a la vista en un formulario) |
+| `sui-dropdown-menu` | Menú flotante anclado a un botón (el kebab ⋮ de una card, un avatar) con acciones sobre eso; también es el overlay que usan por dentro los selects | sui-select (elegir un valor de un formulario) · sui-modal-sheet (más de 5 acciones o una lista larga en mobile) · sui-popover (explicar algo con una flecha, sin anclaje propio) · sui-tooltip (ayuda corta al pasar el mouse) · sui-command-menu-item (buscar y saltar con ⌘K en desktop) |
+| `sui-dropdown-search` | Buscador sin caja que va arriba del panel de un menú flotante para filtrar sus items | sui-input type="search" (buscador de una pantalla o una lista a la vista) · sui-command-menu-search (buscador del ⌘K) · sui-select (elegir de una lista corta, sin buscar) |
 | `sui-emoji` | Un emoji 3D animado (Fluent) para los momentos con emoción: estados vacíos, celebraciones, onboarding | sui-icon (ícono funcional, monocromo) · sui-empty-state (el estado vacío completo, que ya trae su emoji) |
+| `sui-empty-state` | Pantalla o lista sin nada que mostrar (o que no pudo cargar) con emoji animado, título, explicación y una acción opcional | sui-alert (un aviso dentro de una pantalla que sí tiene contenido) · sui-banner (aviso de toda la app) · skeleton (mientras carga, nunca un empty) |
 | `sui-fancy-button` | Botón con brillo y degradé para el CTA de una landing o campaña | sui-button (toda acción dentro de la app) · sui-app-store-badge (descargar la app desde una landing) |
 | `sui-file-icon` | El ícono de un archivo con su extensión (PDF, XLSX, JPG…) en el color de su tipo | sui-file-upload-card (el archivo que se está subiendo, con progreso) · sui-icon (un ícono genérico de documento) |
+| `sui-file-upload` | Área para arrastrar o elegir archivos que no son una foto (PDF, Excel, CSV) | sui-image-upload (una sola imagen con vista previa: logo, portada, comprobante) · sui-image-upload-profile (foto de perfil con botones Subir/Cambiar/Eliminar) · sui-file-upload-card (el archivo ya elegido, con su progreso) |
+| `sui-file-upload-card` | La fila de un archivo que se está subiendo, con su progreso, listo o error para reintentar | sui-file-upload (el área para elegir el archivo) · sui-image-upload (una imagen: muestra la vista previa en vez de la fila) · sui-file-icon (un archivo en una lista, sin subida) |
+| `sui-filter` | Piezas de filtros de una lista o tabla del panel; la barra horizontal (buscador, vista, orden) y el panel vertical (fila, cabecera con «Limpiar», pie con «Limpiar» / «Aplicar») | sui-segmented-control (2 a 4 vistas que se aplican al instante) · sui-compact-select (un filtro suelto) · sui-tab-chips (filtros rápidos con chips) · sui-activity-filter (filtro del feed de actividad) · sui-modal-sheet (el panel de filtros en mobile) |
 | `sui-flag` | La bandera circular de un país | sui-emoji (un emoji con emoción) · sui-icon (un ícono funcional) |
 | `sui-form-hint` | Una línea de ayuda o de error debajo de un campo o de un grupo de controles | el hint propio de sui-input / sui-select / sui-textarea (campo de texto) · sui-alert (un aviso de la pantalla o algo que salió bien) · sui-tooltip (ayuda escondida tras un toque) · sui-form-label (el rótulo de arriba) |
 | `sui-form-label` | Rótulo de un campo o de un grupo de controles que no traen el suyo (asterisco, opcional, ayuda y link) | el label propio de sui-input / sui-select / sui-textarea (campo de texto) · sui-checkbox-label / sui-radio-label / sui-switch-label (un control con su texto) · sui-page-header o sui-content-label (título de sección) · sui-form-hint (la ayuda debajo) |
+| `sui-href` | Directiva para los <a> del DS que reciben un href configurable; los links internos navegan con el Router sin recargar la app | routerLink (link interno escrito en la plantilla de la app) · sui-link-button (acción con forma de link, ya usa suiHref por dentro) |
 | `sui-icon` | Un ícono monocromo de RemixIcon (o uno propio del DS) que toma el color del texto | sui-key-icon (el ícono dentro de un círculo de color) · sui-emoji (emoji con emoción) · sui-brand-logo (el logo de otra marca en su color) · sui-compact-button (un ícono que se toca) |
+| `sui-image-upload` | Subir una imagen y ver su vista previa en el mismo lugar (logo, portada, foto de producto, comprobante) | sui-image-upload-profile (foto de perfil con botones Subir/Cambiar/Eliminar al lado) · sui-file-upload (documentos que no son foto: PDF, Excel) · app-image-cropper (el recortador de la app, que se abre desde el lápiz) |
+| `sui-image-upload-profile` | Foto de perfil o logo en círculo con los botones Subir, o Eliminar y Cambiar, al lado | sui-image-upload (la imagen grande con su vista previa y el lápiz que abre el recortador; es lo que usa hoy la app) · sui-avatar (solo mostrar la foto) |
+| `sui-img-retry` | Directiva que reintenta cargar un <img> cuando falla la red y marca cuándo cargó o se dio por perdido | sui-avatar (foto de persona o logo con iniciales de respaldo) · sui-image-upload (subir una imagen) |
+| `sui-inline-input` | Texto que se edita en su lugar: en reposo muestra el dato y un lápiz; al tocarlo, campo con ✓ y ✕ | sui-input (campo de formulario, siempre editable) · sui-modal con sui-input (editar con más contexto o varios datos a la vez) |
+| `sui-inline-select` | Selector sin caja que vive dentro de una frase o al final de un campo («Mostrar en USD ▾») | sui-compact-select (filtro suelto con caja propia) · sui-compact-select-for-input (al inicio de un sui-input, con divisor) · sui-select (campo de formulario) |
+| `sui-input` | Campo de una sola línea para escribir un dato (nombre, teléfono, monto, búsqueda) | sui-textarea (texto de varias líneas) · sui-select (elegir de una lista) · sui-counter-input (una cantidad con − y +) · sui-tag-input (varios valores cortos) · sui-otp-input (código de verificación) · sui-inline-input (editar un dato en su lugar, con lápiz) |
+| `sui-integration-switch` | Integración con otro servicio — logo, nombre, qué hace, botón «Administrar» y el interruptor para prenderla | sui-switch-card (un ajuste propio de la app, sin logo ni «Administrar») · sui-switch-label (un ajuste en una lista) · sui-content-card type="brand" (mostrar que un servicio está conectado, sin prender ni apagar) |
 | `sui-kbd` | Una tecla dibujada para mostrar un atajo de teclado (⌘K, Esc, ↑ ↓) | sui-badge (una etiqueta corta que no es una tecla) · sui-tag (un chip) |
 | `sui-key-icon` | Un ícono dentro de un círculo, con fondo de color si el ícono dice un estado | sui-icon (el ícono suelto) · sui-avatar (cuando es una persona o un local) · sui-payment-icon (el círculo ya armado para un pago de servicio) |
 | `sui-link-button` | Acción que se lee como texto, sin caja | sui-button (acción con caja: la principal o la secundaria de un grupo) · sui-compact-button (solo ícono, sin texto) · sui-alert (sus acciones se pasan en actions[] y ya salen como link) |
 | `sui-logo` | El logo de Master Pedidos (la M y la palabra), dibujado en SVG y coloreable | sui-brand-logo (logos de OTRAS marcas: WhatsApp, Google, Apple…) · sui-avatar (el logo de un local, que es una foto) |
+| `sui-modal` | Diálogo que se abre encima de la pantalla y pide terminar o cerrar algo antes de seguir | sui-modal-sheet (hoja que sube desde abajo y deja ver lo de atrás, p. ej. un mapa) · sui-alert (aviso en la misma pantalla, sin interrumpir) · sui-toast (confirmación breve de una acción) · sui-popover (contenido chico anclado a un botón) · sui-drawer-header (panel lateral) |
+| `sui-modal-footer` | Pie de modal con la acción principal a la derecha, la secundaria a su izquierda y un slot izquierdo para un checkbox, un link o un texto | sui-button (botones sueltos fuera de un modal o una hoja) · sui-drawer-footer (pie de un panel lateral) · sui-notification-footer (acciones de una notificación) |
+| `sui-modal-header` | Cabecera de modal con título, descripción, ícono opcional y la X de cerrar; sui-modal ya la dibuja sola | sui-modal (ya trae este header por title/description/iconVariant) · sui-drawer-header (cabecera de un panel lateral) · sui-page-header (título de una pantalla) |
+| `sui-modal-sheet` | Hoja que sube desde abajo, se arrastra entre alturas fijas y puede dejar usable lo de atrás (un mapa) | sui-modal (pide terminar algo antes de seguir, sin fondo usable) · sui-popover (contenido chico anclado a un botón) · sui-dropdown-menu (lista de acciones) |
+| `sui-notification` | Fila de la bandeja de notificaciones, con quién, qué pasó, hace cuánto y si ya se leyó | sui-toast (aviso efímero, incluido el «notification» de esquina de la guía) · sui-alert (aviso que se queda en su contexto) · sui-banner (toda la app) |
+| `sui-notification-footer` | Pie del panel desplegable de notificaciones (web): ayuda de teclado a la izquierda y un link a los ajustes a la derecha | sui-link-button (un link suelto a los ajustes) · sui-drawer-footer (pie de un panel lateral) · sui-modal-footer (pie con botones) |
+| `sui-notification-tab-menu` | Cabecera con pestañas del panel desplegable de notificaciones (web), con conteo de no leídas y botón de filtro | sui-tab-chips (pestañas de la bandeja a pantalla completa, en mobile) · sui-tab-menu-horizontal (pestañas de una pantalla) · sui-segmented-control (cambiar de vista con 2–4 opciones) |
+| `sui-otp-input` | Código de verificación dígito por dígito, una celda por número (SMS, código de entrega) | sui-input (un código largo o que se pega entero) · sui-input type="password-toggle" (una clave que no se ve) |
+| `sui-page-header` | Título y subtítulo de una pantalla, con las acciones de la pantalla a la derecha en desktop y debajo en mobile | sui-modal-header (cabecera de un modal) · sui-drawer-header (cabecera de un panel lateral) · sui-topbar (barra superior de la app, no de la pantalla) |
+| `sui-pagination` | Números de página para recorrer una tabla larga en web cuando todos los datos ya están cargados | scroll infinito (directiva appInfiniteScroll de la app, para listas de Firestore) · sui-stepper (pasos de un flujo) · sui-tab-chips (filtrar en vez de paginar) |
+| `sui-password-strength` | Barra de 3 niveles y lista de condiciones que acompaña al campo de una contraseña nueva | sui-input con hint (una sola regla, como «Mínimo 6 caracteres») |
 | `sui-payment-icon` | El círculo de color de un pago de servicio (agua, gas, luz, internet, alquiler…) | sui-key-icon (cualquier otro ícono en círculo) · sui-brand-logo (el logo de un medio de pago con marca) |
+| `sui-period-range` | Un período predefinido (Hoy, Últimos 7 días) en la columna de presets del calendario de rango | sui-datepicker mode="range" (ya los trae) · sui-tab-chips (períodos fijos a la vista: super admin, ganancias del repartidor) · sui-select (períodos fijos en poco espacio: resumen del local) |
+| `sui-popover` | Panel con flecha que señala un elemento de la pantalla y explica algo nuevo, con una o dos acciones; sirve para recorridos de bienvenida | sui-tooltip (ayuda corta al pasar el mouse, sin acciones) · sui-alert (aviso dentro del contenido) · sui-modal (algo que pide decidir antes de seguir) |
+| `sui-product-card` | Tarjeta de un producto de la carta con foto, nombre, descripción, precio y el botón para agregar (o editar) | sui-store-card (un local, no un producto) · sui-card (cualquier otro contenido) · sui-content-card (un producto en una fila, sin foto grande) |
 | `sui-progress-bar` | Barra que muestra cuánto falta para completar algo, pintada con el estado de lo que mide | sui-progress-bar-label (la misma barra con título, número y descripción) · sui-circular-progress-bar (el avance en un círculo, junto a un título) · un gráfico (repartir un total entre partes) |
 | `sui-progress-bar-label` | La barra de progreso con lo que mide, cuánto va y, si hace falta, qué hacer | sui-progress-bar (la barra pelada, cuando otra cosa ya la rotula) · sui-circular-progress-bar (el avance en un círculo, junto a un título) |
 | `sui-radio` | El círculo solo para elegir una opción de una lista corta, sin texto propio | sui-radio-label (círculo con su texto, lista densa) · sui-radio-card (opción con peso o que se toca en el teléfono) · sui-select (más de 6 opciones) · sui-segmented-control (2-4 modos que se aplican al instante) · sui-checkbox (varias a la vez) |
+| `sui-radio-card` | Opción con tarjeta (ícono o foto, título, descripción y el radio) para elegir UNA de una lista corta | sui-radio-label (la misma elección sin tarjeta, en un formulario denso) · sui-select (lista larga o que no entra en pantalla) · sui-segmented-control (2–4 vistas de la misma pantalla) · sui-checkbox-card (se pueden elegir varias) · sui-switch-card (se prende o se apaga un ajuste) |
 | `sui-radio-label` | Círculo con su texto (y opcionalmente descripción, badge y link) para elegir una opción de una lista corta | sui-radio (el círculo solo) · sui-radio-card (cada opción es una tarjeta) · sui-select (más de 6 opciones) · sui-checkbox-label (varias a la vez) |
 | `sui-rating` | Muestra una nota con estrellas o la pide (estrellas, emojis, corazones o números) | sui-icon (una estrella o un corazón sueltos, sin nota) · sui-badge (la nota escrita como dato corto) |
+| `sui-rich-editor` | Barra de formato (negrita, cursiva, alineación, enlace) con un área de texto editable opcional | sui-textarea (todo texto libre de la app hoy, sin formato) |
 | `sui-segmented-control` | Píldora de 2 a 4 opciones hermanas donde se elige una y se aplica en el momento | sui-tab-menu-horizontal (navegar entre secciones de contenido) · sui-tab-chips (fila de filtros con muchas opciones) · sui-radio-card (elegir una opción de un formulario que se guarda después) · sui-button-group (varias opciones a la vez) |
+| `sui-select` | Campo que despliega una lista para elegir UNA opción (distrito, repartidor, categoría, motivo) | sui-radio-label / sui-radio-card (2 a 6 opciones fijas a la vista) · sui-segmented-control (2 a 4 modos que se aplican al instante) · sui-compact-select (filtro chico que se ajusta al texto) · sui-compact-select-for-input (elegir moneda o país dentro de un campo) · sui-tag-input (varios valores) |
+| `sui-sidebar` | Navegación principal de un rol — columna fija a la izquierda en web y cajón que entra desde la izquierda en mobile | la barra inferior nativa del layout (las 4-5 secciones más usadas en el teléfono) · sui-topbar (navegación arriba, sin columna lateral) · sui-tab-menu-vertical (secciones dentro de UNA pantalla, como ajustes) · sui-dropdown-menu (acciones de una cuenta o un botón) |
 | `sui-slider` | Barra para elegir un valor, o un rango, dentro de una escala donde importa ver la posición | sui-counter-input (cantidad chica y exacta con − y +) · sui-input type="number" (valor exacto o rango abierto) · sui-progress-bar (avance de solo lectura) |
 | `sui-social-button` | Botón para iniciar sesión o registrarse con una cuenta de Google o Apple | sui-button (cualquier otra acción, aunque mencione una marca) · sui-app-store-badge (descargar la app de una tienda) |
 | `sui-status-badge` | El resultado de un ciclo (completado, pendiente, fallido, deshabilitado) con su color y su ícono ya resueltos | sui-badge (estado con muchos valores, categoría o distinción) · sui-tag (chip neutro que se puede quitar) · sui-alert (mensaje que hay que leer) |
+| `sui-stepper` | Indica en qué paso de un flujo con orden está la persona, cuánto hizo y cuánto le falta | sui-progress-bar (importa el porcentaje, no los pasos) · sui-pagination (páginas de una lista) · sui-tab-menu-horizontal (secciones sin orden) |
+| `sui-store-card` | Tarjeta de un local para los listados del cliente con portada, logo, abierto/cerrado, favorito, nota, ubicación, envío y distancia | sui-product-card (un producto, no un local) · sui-content-card (un local en una fila de un panel, sin portada) · sui-card (cualquier otro contenido) |
 | `sui-switch` | Interruptor solo para prender o apagar algo que se aplica al instante, sin texto propio | sui-switch-label (interruptor con su texto, el caso normal) · sui-switch-card (cada ajuste es una tarjeta) · sui-integration-switch (fila de integración con logo) · sui-checkbox (valor que se confirma después con un botón) |
+| `sui-switch-card` | Ajuste con tarjeta (ícono, título, descripción y el interruptor) que se aplica al instante | sui-switch-label (el mismo ajuste sin tarjeta, en una lista de ajustes) · sui-integration-switch (una integración con logo y «Administrar») · sui-checkbox-card (varias opciones que se guardan con «Guardar») |
 | `sui-switch-label` | Interruptor con su texto (y opcionalmente descripción, badge y link) para un ajuste que se aplica al instante | sui-switch (el interruptor solo, el texto vive en otra parte) · sui-switch-card (cada ajuste es una tarjeta) · sui-integration-switch (fila de integración con logo) · sui-checkbox-label (se confirma después) |
+| `sui-tab-chips` | Fila de chips que se desliza en horizontal para filtrar una lista o saltar entre categorías; siempre hay uno elegido | sui-segmented-control (2 a 4 modos de la misma vista) · sui-tab-menu-horizontal (secciones de contenido distinto) · sui-radio-card (elegir un valor de un formulario) · sui-tag (chip que se quita) |
+| `sui-tab-menu-horizontal` | Pestañas subrayadas para cambiar entre secciones de contenido distinto dentro de una pantalla | sui-tab-chips (filtros o categorías que se deslizan) · sui-segmented-control (2 a 4 modos de la misma vista) · sui-tab-menu-vertical (menú lateral de ajustes en web) |
+| `sui-tab-menu-vertical` | Menú apilado para cambiar entre secciones de una página de ajustes en web | sui-tab-menu-horizontal (pocas secciones arriba del contenido) · sui-sidebar (navegación de toda la app) · sui-tab-chips (filtros o categorías) |
+| `sui-table` | Tabla de datos — una fila por registro, una columna por dato — para comparar y recorrer listas en web | 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-tag` | Chip neutro que nombra algo elegido o aplicado y que la persona puede quitar | sui-badge (etiqueta de solo lectura, con color y significado) · sui-status-badge (resultado de un ciclo) · sui-tab-chips / sui-filter (chips para elegir) · sui-tag-input (campo que junta tags) |
-
-## Sin documentar
-
-Existen en el paquete pero todavía no tienen doc; antes de usarlos, leer su `.d.ts`.
-
-- `sui-accordion`
-- `sui-activity-feed`
-- `sui-activity-filter`
-- `sui-banner`
-- `sui-breadcrumb-item`
-- `sui-breadcrumbs`
-- `sui-card`
-- `sui-chart-legend`
-- `sui-chart-legend-dot`
-- `sui-checkbox-card`
-- `sui-command-menu-footer`
-- `sui-command-menu-item`
-- `sui-command-menu-search`
-- `sui-compact-select`
-- `sui-compact-select-for-input`
-- `sui-content-card`
-- `sui-content-label`
-- `sui-counter-input`
-- `sui-date-selector`
-- `sui-datepicker`
-- `sui-day-cell`
-- `sui-day-label`
-- `sui-drawer-footer`
-- `sui-drawer-header`
-- `sui-dropdown-caption`
-- `sui-dropdown-item`
-- `sui-dropdown-menu`
-- `sui-dropdown-search`
-- `sui-empty-state`
-- `sui-file-upload`
-- `sui-file-upload-card`
-- `sui-filter`
-- `sui-href`
-- `sui-image-upload`
-- `sui-image-upload-profile`
-- `sui-img-retry`
-- `sui-inline-input`
-- `sui-inline-select`
-- `sui-input`
-- `sui-integration-switch`
-- `sui-modal`
-- `sui-modal-footer`
-- `sui-modal-header`
-- `sui-modal-sheet`
-- `sui-notification`
-- `sui-notification-footer`
-- `sui-notification-tab-menu`
-- `sui-otp-input`
-- `sui-page-header`
-- `sui-pagination`
-- `sui-password-strength`
-- `sui-period-range`
-- `sui-popover`
-- `sui-product-card`
-- `sui-radio-card`
-- `sui-rich-editor`
-- `sui-select`
-- `sui-sidebar`
-- `sui-stepper`
-- `sui-store-card`
-- `sui-switch-card`
-- `sui-tab-chips`
-- `sui-tab-menu-horizontal`
-- `sui-tab-menu-vertical`
-- `sui-table`
-- `sui-tag-input`
-- `sui-textarea`
-- `sui-time-picker`
-- `sui-toast`
-- `sui-tooltip`
-- `sui-topbar`
-- `sui-topbar-button`
-- `sui-topbar-item`
-- `sui-topbar-user`
+| `sui-tag-input` | Campo donde se escriben varios valores cortos que se van sumando como chips (palabras clave) | sui-input (un solo valor) · sui-select (una opción de una lista) · sui-checkbox-label (varias opciones fijas) |
+| `sui-textarea` | Campo de varias líneas para un texto libre (motivo, nota al repartidor, descripción) | sui-input (un dato de una línea) · sui-rich-editor (texto con formato, hoy sin uso) · sui-select (motivos que se pueden elegir de una lista) |
+| `sui-time-picker` | Campo para elegir una hora del día, con columnas de hora, minuto y AM/PM | sui-tab-chips + sui-radio-label (día y franja de entrega de un pedido programado) · sui-select (pocas horas fijas) · sui-input type="time" (hora libre con el selector del sistema) |
+| `sui-toast` | Aviso efímero que confirma el resultado de una acción y se va solo; se dispara con SuiToastService | sui-alert (aviso que se queda, en su contexto) · sui-banner (toda la app) · sui-notification (fila de la bandeja, con hora) · sui-form-hint (error de un campo) |
+| `sui-tooltip` | Directiva que muestra una ayuda corta al pasar el mouse o al enfocar un elemento; solo web, no sirve con el dedo | sui-form-hint (ayuda visible bajo un campo) · sui-modal-sheet (explicación que se abre al tocar, en mobile) · sui-popover (panel que señala algo y pide una acción) |
+| `sui-topbar` | Barra de navegación horizontal de escritorio — logo, secciones, buscador, íconos de acción y el chip de la cuenta | 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-button` | Botón de solo ícono de 40×40 para la barra superior, con punto rojo de «hay algo nuevo» | 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-item` | Una sección de la navegación horizontal — texto, ícono opcional, badge o contador — con estado activo | 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-user` | Chip de la cuenta en la barra superior — avatar, nombre y flecha — que abre el menú de la cuenta | 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ú) |

package/docs/sui-accordion/README.md

@@ -0,0 +1,171 @@
+---
+name: sui-accordion
+selector: sui-accordion
+resumen: Fila con título que se abre para mostrar un texto o contenido secundario que no hace falta ver siempre
+alternativas: [sui-tabs (vistas hermanas que se alternan), sui-modal (detalle que pide atención completa), sui-card (contenido que siempre se ve)]
+---
+
+# sui-accordion
+
+Story: [Organisms/Accordion](https://sui-design-system.web.app/?path=/docs/organisms-accordion--docs)
+
+## Cuándo usarlo / cuándo no
+
+**Úsalo** para esconder lo **secundario** y dejar a la vista lo que decide: preguntas frecuentes,
+«Más detalles (opcional)» en un formulario, el historial técnico de un pedido, la lista completa
+de cambios de una versión.
+
+**No lo uses** para:
+
+- Lo que la persona necesita para decidir en esa pantalla: si hay que abrirlo siempre, va abierto
+  (sin accordion).
+- Navegar entre vistas del mismo nivel: `sui-tabs`.
+- Un solo campo que aparece o desaparece: un `@if` con un `sui-switch` que lo controle.
+- Anidar accordions: dos niveles de «+» dentro de una card se leen como un árbol.
+
+## Qué variante usar
+
+> **La guía del DS dibuja los estados pero no dice cuándo usar cada cosa.** El Figma del DS
+> (nodo 210:4022) trae el accordion en tres estados (normal, hover y abierto) y con el «+» a la
+> derecha o a la izquierda. No trae do/don't. Lo marcado **propuesta** falta aprobar.
+>
+> Uso medido el 03-10-2026 en `master-pedidos/src/app`: 19 accordions, sin contar prototipos ni
+> vitrinas (`master-preview`, `master-prototipos`, `mockup-sheets-*`, `dx/*`, `master-rutina`,
+> `master-medico`, `dev-index`) ni las copias de `components/sui/`.
+
+### Lo que sí dice la guía del DS
+
+- **Cerrado**: fondo blanco, borde gris y sombra mínima; el toggle es un «+».
+- **Hover y abierto**: fondo gris claro, sin borde ni sombra; abierto, el toggle es un «−».
+- **La descripción solo se ve abierto**, 6 px bajo el título.
+- **Con el «+» a la izquierda (`flipIcon="on"`) no hay ícono lateral**: el toggle ocupa su lugar.
+- Padding 14, gap 10, radio 10, íconos de 20.
+
+### Ícono izquierdo — `leftIcon`
+
+| valor | cuándo | ejemplo real de la app | fuente |
+|---|---|---|---|
+| `[leftIcon]="false"` | el caso normal: el título se explica solo | `pages/envios/envios.html:412` («Más detalles (opcional)») | propuesta |
+| `true` (default, `question-line`) | **solo** si el título es una pregunta de ayuda | `pages/driver/driver-profile/driver-profile.html:156` («¿Por qué no me llegan pedidos?») | propuesta |
+| un nombre de ícono | el ícono dice de qué es la sección y hay varias juntas | `pages/notifications/notifications.html:72` (`settings-3-line`) | propuesta |
+
+Hoy: 16 en `false`, 2 con el default (las dos son preguntas de ayuda) y 1 con ícono propio. El
+default del componente es el caso raro: **casi siempre hay que apagarlo**.
+
+**A revisar:** las preguntas frecuentes de las landings (`pages/public/landing-business/landing-business.html:170`,
+`pages/public/landing-driver/landing-driver.html:167`, `pages/public/pricing/pricing.html:131`)
+son preguntas y van sin ícono; las dos de ayuda dentro de la app, con. Elegir uno.
+
+### `description` vs contenido proyectado
+
+| qué | cuándo | fuente |
+|---|---|---|
+| `description` | **una respuesta corta en texto** (FAQ): aparece al abrir, alineada con el título | según el Figma del DS |
+| contenido proyectado | cualquier otra cosa: campos, listas, cards, tablas | propuesta |
+
+**A revisar:** 4 accordions pasan un **resumen** en `description` (`resumenReto()`,
+`resumenVotaciones()`, `resumenDetalles()`…) que, por cómo funciona el componente, **solo se ve
+con el accordion abierto**. Si la idea era ver el resumen cerrado, hoy no se ve:
+`pages/driver/driver-dashboard/driver-dashboard.html:287` y `:486`,
+`pages/envios/envios.html:412`, `pages/customer/mandadito/mandadito.html:188`.
+
+### `lazy` — cuándo diferir el contenido
+
+| forma | qué pasa | cuándo | fuente |
+|---|---|---|---|
+| contenido plano, sin `lazy` | se crea y se pinta al cargar la pantalla | contenido liviano (texto, 2-3 campos) | componente |
+| `[lazy]="true"` + contenido plano | no se pinta hasta abrir, pero **los componentes de adentro igual se crean** al cargar | no ahorra mucho; evitarlo | componente |
+| `[lazy]="true"` + `<ng-template suiAccordionContent>` | no se crea nada hasta el primer open; después queda montado | contenido pesado (listas, mapas, formularios grandes) o muchos accordions en la misma pantalla | componente |
+
+**Usos de hoy que no hacen lo que parecen:** 4 accordions usan `<ng-template suiAccordionContent>`
+**sin** `[lazy]="true"`, y sin `lazy` el template se crea al cargar igual que el contenido plano:
+`pages/envios/envios.html:418` y `:743`, `pages/customer/order-tracking/order-tracking.html:590`,
+`pages/customer/mandadito/mandadito.html:194`. Les falta `[lazy]="true"`.
+
+### `flipIcon` y `badge`
+
+| input | cuándo | fuente |
+|---|---|---|
+| `flipIcon="on"` | listas largas donde el «+» a la izquierda se escanea mejor que a la derecha. 0 usos hoy | según el Figma del DS (la variante existe) |
+| `badge` | marcar una sección como nueva o actualizada («Nuevo»). Extensión de SUI; 0 usos hoy | propuesta |
+
+## Tamaño en mobile y en web
+
+El accordion **no tiene `size`** ni cambia por breakpoint: ocupa todo el ancho de su contenedor y
+mide 48 px de alto cerrado con una línea de título (14 + 20 + 14), que ya es un área táctil
+cómoda en mobile.
+
+| uso | mobile | web | fuente |
+|---|---|---|---|
+| fila | ancho completo, 48 px | igual | componente |
+| texto | Label/Small 14 y Paragraph/Small 14 | igual | según el Figma del DS |
+
+## API
+
+<!-- api:inicio -->
+<!-- generada: no editar a mano — `npm run docs` -->
+
+### `sui-accordion`
+
+| input | tipo | default |
+|---|---|---|
+| `title` | `string` | `''` |
+| `description` | `string` | `''` |
+| `open` · model, `[(open)]` | `boolean` | `false` |
+| `lazy` | `boolean` | `false` |
+| `flipIcon` | `'off' \| 'on'` | `'off'` |
+| `leftIcon` | `string \| boolean` | `true` |
+| `badge` | `SuiBadgeConfig \| string \| null` | `null` |
+
+Outputs: ninguno.
+
+### `ng-template[suiAccordionContent]`
+
+Inputs: ninguno.
+
+Outputs: ninguno.
+<!-- api:fin -->
+
+`open` es un `model`: el cambio se escucha con `(openChange)` o `[(open)]`. Método público:
+`toggle()`.
+
+`badge` acepta un `string` (atajo de `{ label }`, en verde, `lighter`, `small`) o un
+`SuiBadgeConfig` con `color`, `variant` y `size`.
+
+Slots: contenido plano (o con el atributo `sui-accordion-body`) y el template
+`<ng-template suiAccordionContent>`. Van debajo de la descripción, con padding `0 14px 14px`.
+
+## Trampas
+
+- **`leftIcon` arranca en `true`**: sin `[leftIcon]="false"` sale un signo de pregunta junto a
+  cualquier título.
+- **`suiAccordionContent` sin `[lazy]="true"` no difiere nada.** Las dos piezas van juntas.
+- **`[lazy]="true"` con contenido plano engaña**: los componentes de adentro se construyen igual
+  al cargar (corren su `ngOnInit`, piden datos). Para no construirlos, el template.
+- **Una vez abierto, queda montado**: cerrar no destruye el contenido (conserva lo escrito).
+  Si necesitas reiniciarlo al cerrar, hazlo tú en `(openChange)`.
+- **`description` solo se ve abierto.** No sirve como resumen de la fila cerrada.
+- **No hay `disabled`** (el Figma tampoco lo trae).
+- El toggle cambia de «+» a «−»; no rota. El cuerpo anima su alto con un `ResizeObserver`: si el
+  contenido cambia de alto estando abierto, acompaña.
+- El host borra el atributo `title` nativo (sin tooltip gris del navegador).
+
+## Ejemplo
+
+```html
+<!-- Sección opcional de un formulario, con el contenido diferido de verdad -->
+<sui-accordion
+  title="Más detalles (opcional)"
+  [leftIcon]="false"
+  [lazy]="true"
+  [(open)]="detallesAbiertos">
+  <ng-template suiAccordionContent>
+    <sui-textarea label="Indicaciones para el repartidor" [(value)]="indicaciones" />
+  </ng-template>
+</sui-accordion>
+
+<!-- Pregunta de ayuda: el ícono por defecto sí calza -->
+<sui-accordion
+  title="¿Cómo apareces más arriba en el inicio?"
+  description="El inicio de cada cliente se ordena solo. Esto es lo que puedes mover desde tu panel." />
+```

package/docs/sui-activity-feed/README.md

@@ -0,0 +1,155 @@
+---
+name: sui-activity-feed
+selector: sui-activity-feed
+resumen: Historial de actividad — quién hizo qué y hace cuánto — con archivos, comentarios, personas o tareas debajo de cada fila
+alternativas: [sui-notification (bandeja de avisos para quien mira, con leído/no leído), sui-stepper (los pasos fijos de un flujo, no un historial), sui-table (registros para comparar por columnas), sui-activity-filter (los filtros que van arriba del feed)]
+---
+
+# sui-activity-feed
+
+Story: [Organisms/Activity/Activity Feed](https://sui-design-system.web.app/?path=/docs/organisms-activity-activity-feed--docs)
+
+## Cuándo usarlo / cuándo no
+
+**Úsalo** para un **historial de acciones hechas por personas**, de la más nueva a la más vieja:
+«Ana aprobó la recarga de S/ 50 · hace 4 min», «Carlos editó la carta de Pollería Don Tito ·
+ayer». Cada fila tiene autor, verbo, objeto y hora, y puede llevar debajo los archivos, el
+comentario, las personas o las tareas de esa acción.
+
+**No lo uses** para:
+
+- Avisos para quien mira, que se marcan como leídos: `sui-notification`.
+- El avance de un pedido por estados fijos (recibido → en camino → entregado): es una línea de
+  pasos (`sui-stepper` o la línea de tiempo del detalle del pedido), no un historial libre.
+- Registros que se comparan por columnas (montos, fechas): `sui-table`.
+
+Regla corta: **quién hizo qué → activity feed · avisos para mí → notification · pasos de un flujo → stepper.**
+
+## Qué variante usar
+
+> **La guía del DS no tiene página del activity feed.** El componente sale del Figma de SUI
+> (Activity Feed [1.1], frame 166035:46833). Uso medido el 03-10-2026 en `master-pedidos/src/app`:
+> **0 usos**. Todo lo de abajo es **propuesta, falta aprobación**.
+
+El tipo de fila lo decide `type` de cada item (una unión discriminada): lo que cuelga debajo de
+la línea de texto.
+
+| `type` | cuándo | ejemplo posible en la app | fuente |
+|---|---|---|---|
+| `default` | La acción se entiende sola con la línea. Es el caso normal. | «Ana aprobó la recarga de Luis» | propuesta, falta aprobación |
+| `file` | La acción dejó archivos que se pueden bajar. | «Luis subió su comprobante de Yape» | propuesta, falta aprobación |
+| `comment` | La acción fue escribir algo y el texto importa. | «El local dejó una nota en el pedido» | propuesta, falta aprobación |
+| `avatar-group` | La acción involucró a varias personas. | «Se asignaron 3 repartidores a la zona» | propuesta, falta aprobación |
+| `tasks` | La acción tuvo un resultado por partes (hechas, pendientes, con error). | «Se importó la carta: 40 productos, 2 con error» | propuesta, falta aprobación |
+
+| pieza del item | regla | fuente |
+|---|---|---|
+| leading | `avatar` cuando lo hizo una persona; `icon` cuando lo hizo el sistema (una Cloud Function, un cobro automático). | propuesta, falta aprobación |
+| `avatar.src` | La foto de **otra** persona va denormalizada y pasada por `fotoDeStorage()`, nunca la URL de Google. | canon (CLAUDE.md, «Fotos de otra persona») |
+| `avatar.color` | Para iniciales sin foto, `color` del set de SUI. `bgColor` solo como escape: no ajusta el color del texto. | canon del componente |
+| `userName` / `target` | Nombres, nunca IDs. | canon (CLAUDE.md, «Pasada de UX/UI»: un identificador nunca es el título de nada) |
+| `verb` | En pasado y en minúscula: «aprobó», «subió». | propuesta, falta aprobación |
+| `timestamp` | Relativo y corto: «hace 4 min», «ayer». Lo formateas tú. | propuesta, falta aprobación |
+| `showAction` | `false` salvo que haya un menú real detrás de los tres puntos. | propuesta, falta aprobación |
+
+**Carga:** un historial crece sin techo. Se pide por páginas con cursor (`getCollectionPage`
+ordenado por fecha) y un «Cargar más» al final, nunca la colección entera. Canon
+(`master-pedidos/CLAUDE.md`, «Performance — Firestore reads»).
+
+## Tamaño en mobile y en web
+
+**No tiene `size`** ni breakpoints. Avatar o ícono de 32, texto 14/20, chips de 28-30. La línea
+de texto **envuelve** (`flex-wrap`), así que en mobile un «Ana aprobó la recarga de S/ 50 de Luis
+· hace 4 min» baja a dos o tres renglones sin romperse.
+
+| uso | mobile | web | fuente |
+|---|---|---|---|
+| historial | ancho completo de la columna | dentro de una `sui-card` o un panel lateral | propuesta, falta aprobación |
+
+En táctil, el botón de tres puntos y la descarga miden 20 y 28: por debajo del área cómoda. Si
+el feed va en mobile con acciones, esa es la primera mejora que pide el componente.
+
+## «No usar»: por qué no hoy y cuándo sí
+
+| qué | por qué no hoy | cuándo sí, en un flujo nuevo |
+|---|---|---|
+| `sui-activity-feed` entero (0 usos) | no hay pantallas de auditoría | historial de cambios de un local en super admin, o quién aprobó cada recarga |
+| `type: 'comment'` con `replyLabel` | no hay hilos de respuesta | notas entre el local y la central sobre un pedido |
+| `avatar.bgColor` | el set de `color` ya cubre los casos y ajusta el texto | una entidad con color propio guardado en la base |
+
+## API
+
+<!-- api:inicio -->
+<!-- generada: no editar a mano — `npm run docs` -->
+
+| input | tipo | default |
+|---|---|---|
+| `items` | `readonly SuiActivityFeedItem[]` | — (requerido) |
+
+| output | payload |
+|---|---|
+| `action` | `{ item: SuiActivityFeedItem; event: MouseEvent }` |
+| `fileDownload` | `{ item: SuiActivityFeedItem; file: SuiActivityFile; event: MouseEvent }` |
+| `reply` | `{ item: SuiActivityFeedItem; event: MouseEvent }` |
+<!-- api:fin -->
+
+```ts
+type SuiActivityFeedItem =
+  | (Base & { type: 'default' })
+  | (Base & { type: 'file'; files: SuiActivityFile[] })
+  | (Base & { type: 'comment'; comment: string; replyLabel?: string })
+  | (Base & { type: 'avatar-group'; avatars: SuiActivityAvatarRef[]; extraCount?: number })
+  | (Base & { type: 'tasks'; tasks: SuiActivityTask[] });
+
+interface Base {
+  id: string;                     // track del @for: único
+  avatar?: SuiActivityAvatarRef;  // { src?, initials?, color?, bgColor? }
+  icon?: string;                  // en vez del avatar (lo hizo el sistema)
+  userName: string;
+  verb: string;
+  target?: string;
+  timestamp: string;              // ya formateado
+  showAction?: boolean;           // default true
+}
+interface SuiActivityFile { name: string; size?: string; href?: string; }
+interface SuiActivityTask { state: 'success' | 'warning' | 'pending' | 'error'; label: string; }
+```
+
+## Trampas
+
+- **Los tres puntos salen por defecto** (`showAction` es `true` si no lo pasas). Si no hay menú
+  detrás, pon `showAction: false` en cada item o la persona toca algo que no hace nada.
+- **`replyLabel` por defecto dice «Reply», en inglés.** En una fila `comment`, pasa siempre
+  `replyLabel: 'Responder'`.
+- **`file.href` no hace nada.** El tipo dice que dispara la descarga, pero la plantilla no lo lee:
+  la descarga la haces tú en `(fileDownload)`.
+- `timestamp` es un string: el feed no formatea ni actualiza «hace 4 min». Si la pantalla queda
+  abierta, recalcúlalo tú.
+- Sin `avatar.src`, `initials` ni `icon`, el leading es la silueta gris genérica.
+- Los tres outputs hacen `stopPropagation`: un `(click)` en un contenedor padre no se entera.
+- El host lleva `role="feed"`; cada fila es un `<article>`. No lo metas dentro de otra lista.
+- No hay estado vacío ni de carga: cuando `items` está vacío no se ve nada. Usa `sui-empty-state`
+  afuera, y un skeleton mientras llega la primera página.
+
+## Ejemplo
+
+```html
+<sui-card>
+  <sui-activity-feed [items]="historial()" (fileDownload)="descargar($event.file)" />
+  @if (hayMas()) {
+    <sui-button variant="stroke" color="neutral" [size]="bp.isMobile() ? 'large' : 'small'"
+                (click)="cargarMas()">Cargar más</sui-button>
+  }
+</sui-card>
+```
+
+```ts
+readonly historial = signal<SuiActivityFeedItem[]>([
+  { id: 'r1', type: 'default', avatar: { src: ana.avatarUrl, initials: 'AR', color: 'orange' },
+    userName: 'Ana', verb: 'aprobó la recarga de', target: 'Luis Quispe', timestamp: 'hace 4 min',
+    showAction: false },
+  { id: 'r2', type: 'file', icon: 'bank-card-line', userName: 'Luis Quispe', verb: 'subió su',
+    target: 'comprobante de Yape', timestamp: 'hace 6 min', showAction: false,
+    files: [{ name: 'yape-50.jpg', size: '(320 kb)' }] },
+]);
+```