@ajuarezso/sui-stencil 0.0.0-stage → 0.1.0

package/dist/types/utils/enfocables.d.ts

@@ -0,0 +1,2 @@
+/** Selector de lo que recibe foco con Tab. Uso interno del DS (tooltip, trap del modal). */
+export declare const ENFOCABLES = "button:not([disabled]), a[href], input:not([disabled]), select:not([disabled]), textarea:not([disabled]), [tabindex]:not([tabindex=\"-1\"])";

package/dist/types/utils/pista-de-scroll-marco.d.ts

@@ -0,0 +1,15 @@
+import { FunctionalComponent } from '../stencil-public-runtime';
+import type { SuiPistaDeScroll, SuiPistaEstado } from './pista-de-scroll';
+interface PistaMarcoProps {
+    estado: SuiPistaEstado;
+    pista?: SuiPistaDeScroll;
+    /** Oculta el lado izquierdo (p. ej. la tabla con columna fija). */
+    ocultarInicio?: boolean;
+}
+/**
+ * Bordes degradados + flechas de la pista de scroll (equivalente al template de
+ * `<sui-pista-de-scroll>` del SUI Angular). Va como hermano del scroller dentro
+ * de un contenedor `.sui-pista`. Las flechas no entran al Tab (tabindex -1).
+ */
+export declare const PistaMarco: FunctionalComponent<PistaMarcoProps>;
+export {};

package/dist/types/utils/pista-de-scroll.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Pista de scroll horizontal — canon del SUI Angular (dueño, 05-10-2026).
+ *
+ * Un contenedor con `overflow-x: auto` y la barra oculta no avisa que hay más.
+ * La pista dibuja un degradado en el borde con contenido oculto y, solo con
+ * puntero fino, flechas que desplazan ~80 % del ancho visible.
+ *
+ * Port del par `[suiPistaDeScroll]` + `<sui-pista-de-scroll>` del Angular a una
+ * clase sin framework: mide el scroller con su propio `scroll` (nativo y
+ * pasivo) + `ResizeObserver` y avisa por `onChange`. Cada componente (sui-table,
+ * sui-tab-chips) dibuja los bordes/flechas con el partial `_pista-de-scroll.scss`.
+ */
+export interface SuiPistaEstado {
+    antes: boolean;
+    despues: boolean;
+}
+export declare class SuiPistaDeScroll {
+    private readonly el;
+    private readonly onChange;
+    private activa;
+    private ro?;
+    private desliza;
+    private estado;
+    private readonly onScroll;
+    constructor(el: HTMLElement, onChange: (e: SuiPistaEstado) => void, activa?: boolean);
+    setActiva(activa: boolean): void;
+    /** Re-mide (layout o contenido cambiado): si el scroller se desliza y los dos lados. */
+    medir(): void;
+    private actualizar;
+    /** Desplaza ~80 % del ancho visible hacia un lado (−1 izquierda, 1 derecha). */
+    desplazar(sentido: -1 | 1): void;
+    destroy(): void;
+}

package/dist/types/utils/pruebas.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Ayudas para los `.spec.tsx` (newSpecPage). El tsconfig es estricto y también
+ * tipa los specs: sin esto cada `page.root` / `querySelector` pide un `!`.
+ * (No se llama `spec.ts`: jest lo tomaría por un archivo de pruebas.)
+ */
+/** `newSpecPage(...)` con `root` no opcional. */
+export declare const conRoot: <T extends {
+    root?: HTMLElement;
+}>(p: Promise<T>) => Promise<T & {
+    root: HTMLElement;
+}>;
+/** `querySelector` tipado como presente; si falta, el test falla al usarlo. */
+export declare const q: <E extends HTMLElement = HTMLElement>(el: ParentNode, selector: string) => E;
+/** Escucha un CustomEvent y devuelve un `jest.fn` que recibe su `detail`. */
+export declare const espiar: (el: EventTarget, evento: string) => jest.Mock<any, any, any>;

package/dist/types/utils/roving-focus.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Navegación con flechas para grupos de un solo tab stop («roving tabindex»):
+ * segmented-control y tab menus. Uso interno del DS. Copia 1:1 de
+ * `core/roving-focus.ts` del SUI Angular.
+ *
+ * Devuelve el índice al que tiene que ir el foco según la tecla, o `null` si la
+ * tecla no es de navegación (el caller no hace preventDefault en ese caso).
+ * - Horizontal: ← / →. Vertical: ↑ / ↓. `both`: las cuatro (radiogroup).
+ * - Home / End van al primero / último.
+ * - Con `wrap` (default) el último → primero y al revés.
+ */
+export type SuiRovingOrientation = 'horizontal' | 'vertical' | 'both';
+export declare function suiRovingIndex(key: string, current: number, total: number, orientation?: SuiRovingOrientation, wrap?: boolean): number | null;
+/**
+ * Como `suiRovingIndex`, pero salta los ítems deshabilitados en la dirección de
+ * la tecla (Home busca hacia adelante, End hacia atrás). Devuelve `null` si la
+ * tecla no es de navegación o si no hay ningún ítem habilitado.
+ */
+export declare function suiRovingIndexEnabled(key: string, current: number, items: readonly {
+    disabled?: boolean;
+}[], orientation?: SuiRovingOrientation): number | null;
+/** Índice del único ítem con tabindex 0: el activo, o el primero habilitado. */
+export declare function suiTabStopIndex(items: readonly {
+    value: string;
+    disabled?: boolean;
+}[], active: string | undefined): number;

package/dist/types/utils/scroll-lock.d.ts

@@ -0,0 +1,2 @@
+export declare function lockBodyScroll(el: HTMLElement): void;
+export declare function unlockBodyScroll(el: HTMLElement): void;

package/dist/types/utils/sui-configs.d.ts

@@ -0,0 +1,18 @@
+import type { SuiBadgeConfig } from '../components/sui-badge/sui-badge';
+import type { SuiAvatarConfig } from '../components/sui-avatar/sui-avatar';
+import type { SuiFooterButtonConfig } from '../components/sui-button/sui-button';
+import type { SuiLinkConfig } from '../components/sui-link-button/sui-link-button';
+export type { SuiBadgeConfig, SuiAvatarConfig, SuiFooterButtonConfig, SuiLinkConfig };
+/**
+ * Configs objeto que el SUI Angular usa en vez de N props sueltos (badge, link,
+ * avatar embebidos). Cada tipo vive en su componente (badge, avatar, button, link-button).
+ * String shorthand = el caso común (`badge="NEW"`, `link="Ver más"`, `avatar="url"`).
+ */
+/** `badge` → config (string = label; vacío = sin badge). Desde HTML un objeto llega como JSON. */
+export declare function resolverBadge(badge: SuiBadgeConfig | string | null | undefined): SuiBadgeConfig | null;
+/** `link` → config con `rel` automático para `_blank` (igual que Angular). */
+export declare function resolverLink(link: SuiLinkConfig | string | null | undefined): SuiLinkConfig | null;
+/** Botón de pie → config (string = solo label; `null`/label vacío = oculto). */
+export declare function resolverBotonPie(b: SuiFooterButtonConfig | string | null | undefined): SuiFooterButtonConfig | null;
+/** `avatar` → config (string = src directo). */
+export declare function resolverAvatar(avatar: SuiAvatarConfig | string | null | undefined): SuiAvatarConfig | null;

package/dist/types/utils/sui-toque.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Homólogo del `SuiToque` del SUI Angular (16-10-2026): el arreglo de iOS para
+ * el `:active` de lo que se toca, con listeners PASIVOS.
+ *
+ * iOS WKWebView necesita un listener de `touchstart` para pintar y soltar
+ * `:active` a tiempo (sin él se queda pegado 300-500 ms), y un `blur()` en
+ * `touchend` suelta el foco. Un `onTouchStart` de JSX se registra NO pasivo:
+ * con el dedo encima, el navegador espera al JavaScript antes de scrollear.
+ *
+ * Uso en el componente (los dos en el host, pasivos):
+ *   @Listen('touchstart', { passive: true }) alTocar(): void {}
+ *   @Listen('touchend', { passive: true }) alSoltar(e: Event): void { soltarToque(e, '.sui-x__btn'); }
+ *
+ * `selector` acota a los controles que se tocan: nunca un campo de texto
+ * (un blur ahí cierra el teclado).
+ */
+export declare function soltarToque(event: Event, selector: string): void;

package/docs/INDEX.md

@@ -0,0 +1,149 @@
+<!-- generado por scripts/gen-docs.mjs — no editar a mano; `npm run docs` -->
+
+# SUI Design System (Stencil) — componentes
+
+Una fila por componente: qué es y qué usar en su lugar cuando no calza. Para elegir,
+se lee esta lista; para usar uno, se abre su doc:
+
+- en el paquete npm: `node_modules/@ajuarezso/sui-stencil/docs/<name>/README.md`
+- en el repo: `docs/<name>/README.md`
+
+Entradas: 126. Con criterio de uso heredado del SUI Angular: 118.
+Con diferencias de API frente a Angular: 47 — cada README las lista en «Diferencias con el SUI Angular».
+
+Marcas en el resumen:
+
+- **Obsoleto.** — no usar en código nuevo; el resumen dice qué va en su lugar.
+- *(pieza)* — parte de otro componente; el criterio está en el README de ese componente.
+- *(familia `sui-x`)* — en el SUI Angular varias piezas comparten una página `sui-x`, que aquí no existe como componente.
+- *(solo Stencil)* — no existe en el SUI Angular; el README trae solo la descripción del código y la API.
+- *(utilidad)* — no es un elemento: una función que usan otros componentes.
+
+| 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-tab-menu-horizontal (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-40 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-segmented-control (2 a 4 días o períodos fijos) · sui-tab-chips (5 o más) |
+| `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-segmented-control (2 a 4 períodos fijos: hoy, 7 días, 30 días) · sui-tab-chips (5 o más períodos fijos) |
+| `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 dentro de un botón) 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-bar` | *(familia `sui-filter`)* La barra horizontal arriba de una tabla. Es solo layout: un lado izquierdo (`slot="start"`) y uno derecho (`slot="end"`); los controles se proyectan | 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-filter-item` | *(familia `sui-filter`)* Una fila del panel vertical (una categoría de filtro: «Estado», «Local») | 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-filter-panel-footer` | *(familia `sui-filter`)* El pie del panel, con «Limpiar» y «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-filter-panel-header` | *(familia `sui-filter`)* La cabecera del panel, con un link «Limpiar» opcional | 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` | *(utilidad: función, no elemento)* Port de la directiva Angular `a[suiHref]`. En Stencil no hay directivas ni Router, así que es una función que los componentes del DS llaman desde el `onClick` de su `<a>`. No dibuja nada | — |
+| `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 (solo en el celular: 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 (pie del panel de notificaciones: ayuda de teclado y link a ajustes) |
+| `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 del celular que sube desde abajo, se arrastra entre alturas fijas y puede dejar usable lo de atrás (un mapa); en tablet y computadora se usa sui-modal | 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-segmented-control (2 a 4 períodos fijos a la vista) · sui-tab-chips (5 o más períodos fijos o que deslizan) |
+| `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-group` | *(pieza)* Pieza de sui-radio; cuándo usarla y sus trampas están en el README de sui-radio | sui-radio |
+| `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-rich-editor-item` | *(pieza)* Pieza de sui-rich-editor; cuándo usarla y sus trampas están en el README de sui-rich-editor | sui-rich-editor |
+| `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-swatch` | *(solo Stencil, sin criterio de uso)* Celda de color para documentar la paleta de tokens del DS | — |
+| `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-tabs` | **Obsoleto.** Para código nuevo usar sui-tab-chips, sui-segmented-control, sui-tab-menu-horizontal, sui-tab-menu-vertical | sui-tab-chips · sui-segmented-control · sui-tab-menu-horizontal · sui-tab-menu-vertical |
+| `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 (chips para elegir) · sui-tag-input (campo que junta tags) |
+| `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-time-picker-duration` | *(pieza)* Pieza de sui-time-picker; cuándo usarla y sus trampas están en el README de sui-time-picker | sui-time-picker |
+| `sui-time-picker-item` | *(pieza)* Pieza de sui-time-picker; cuándo usarla y sus trampas están en el README de sui-time-picker | sui-time-picker |
+| `sui-time-picker-status` | *(pieza)* Pieza de sui-time-picker; cuándo usarla y sus trampas están en el README de sui-time-picker | sui-time-picker |
+| `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 sin texto de 20 a 40 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,263 @@
+---
+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-tab-menu-horizontal (vistas hermanas que se alternan), sui-modal (detalle que pide atención completa), sui-card (contenido que siempre se ve)]
+---
+
+# sui-accordion
+
+<!-- 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-accordion`); 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.
+>
+> **La API de aquí no es igual a la de Angular.** Lo que el texto nombre y figure en «Diferencias con
+> el SUI Angular» (dentro de API) aquí no existe.
+
+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-tab-menu-horizontal` (o `sui-segmented-control` si son 2-4 modos de la misma vista). `sui-tabs` ya no existe: se partió en esos dos y `sui-tab-menu-vertical` en la 0.3.0.
+- 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 |
+|---|---|---|---|
+| `left-icon="false"` | el caso normal: el título se explica solo | `pages/envios/envios.html:413` («Más detalles (opcional)») | canon (aprobado por el dueño, 05-10-2026, bloque B9) |
+| `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`) | canon (aprobado por el dueño, 05-10-2026, bloque B9) |
+
+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 | canon (aprobado por el dueño, 05-10-2026, bloque B9) |
+
+**A revisar:** 2 accordions pasan un **resumen** en `description` (`resumenDetallesEnvio()`,
+`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/envios/envios.html:413` y `pages/customer/mandadito/mandadito.html:189`. Los dos del
+dashboard del repartidor («Votaciones» y «Reto semanal») ya pasaron su resumen al `badge`
+(05-10-2026), que sí se ve cerrado.
+
+### `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` + contenido plano | no se pinta hasta abrir, pero **los componentes de adentro igual se crean** al cargar | no ahorra mucho; evitarlo | componente |
+| `lazy` + `<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`, y sin `lazy` el template se crea al cargar igual que el contenido plano:
+`pages/envios/envios.html:413` y `:756`, `pages/customer/order-tracking/order-tracking.html:611`,
+`pages/customer/mandadito/mandadito.html:189`. Les falta `lazy`.
+
+### `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»), o dejar a la vista con la fila cerrada un estado de una o dos palabras («Sin reto», «3 de 10»). Extensión de SUI; 2 usos hoy, los dos del segundo tipo: `pages/driver/driver-dashboard/driver-dashboard.html:332` y `:516` | «Nuevo»: canon (aprobado por el dueño, 05-10-2026, bloque B9) · estado con la fila cerrada: pedido del dueño, 05-10-2026 (`core/resumen-acordeones-repartidor.ts`) |
+
+## 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 |
+
+### Por dispositivo (D16)
+
+La fila no tiene `size`: mide 48 en todos los dispositivos, que ya pasa los 44 del dedo en el
+celular y la tablet, y en la computadora no estorba. Lo único con tamaño es el **`badge`**, que
+no se toca y sigue la fila de `badge` de D16. El accordion lo pinta en `small` si no le pasas
+`size` (también con el atajo `badge="Nuevo"`), y D16 no deja nada en `small`:
+
+| dispositivo | size del `badge` | nota |
+|---|---|---|
+| celular chico (< 380) | `medium` | lo que no se toca no sube en el celular chico |
+| celular (380–767) | `large` | un paso más que en la computadora (P1 b). No `xlarge`: ver abajo |
+| tablet táctil | `medium` | |
+| computadora | `medium` | `medium` va sin MAYÚSCULAS |
+
+Ultrawide: igual que la computadora. Fuente: D16, dueño 05-10-2026.
+
+**Por qué `large` y no `xlarge` en el celular**, aunque el badge va en la fila del título
+(`.sui-accordion__title-row`): la excepción «`xlarge` junto a un título» de D16 es para un título
+de encabezado o un monto: según el README de `sui-badge`, en el celular el badge va al lado de
+textos de 16. El título del accordion es
+Label/Small 14/20, el mismo nivel que una fila de lista: un `xlarge` (28, texto 16) tendría letra
+más grande que el título que acompaña, y `large` (24, texto 14) lo iguala. Es una lectura de D16,
+no una decisión aparte del dueño; si se quiere `xlarge` aquí, lo decide él. `bp.sizeBadge()` ya da
+`large`/`medium`, así que no hace falta otra expresión.
+
+En master-pedidos: `badge={{ label: 'Nuevo', size: bp.sizeBadge() }}`. Hoy los dos badges del
+dashboard del repartidor salen en `medium` fijo (`core/resumen-acordeones-repartidor.ts:19`):
+en el celular les falta subir a `large`.
+
+## API
+
+<!-- api:inicio -->
+<!-- generada: no editar a mano — `npm run docs` -->
+
+| prop | atributo | tipo | default |
+|---|---|---|---|
+| `badge` | `badge` | `SuiBadgeConfig \| null \| string` | `null` |
+| `description` | `description` | `string` | `''` |
+| `flipIcon` | `flip-icon` | `"off" \| "on"` | `'off'` |
+| `heading` | `heading` | `string` | `''` |
+| `lazy` | `lazy` | `boolean` | `false` |
+| `leftIcon` | `left-icon` | `boolean \| string` | `true` |
+| `open` | `open` | `boolean` | `false` |
+
+| evento | `event.detail` |
+|---|---|
+| `openChange` | `boolean` |
+
+| método | firma |
+|---|---|
+| `toggle` | `toggle() => Promise<void>` |
+
+Slots: `(por defecto)`.
+
+### Diferencias con el SUI Angular
+
+- **Props de Angular que aquí no existen:** `title`
+- **Props solo de aquí:** `heading`
+<!-- api:fin -->
+
+`open` es un `model`: el cambio se escucha con `openChange` o `open` + `openChange`. 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
+
+- **SSR / prerender** (desde la rama `ssr-fixes`, 19-10-2026): en el servidor no mide ni crea el `ResizeObserver`; un acordeón abierto sale con su contenido y la altura se mide al hidratar.
+
+- **`leftIcon` arranca en `true`**: sin `left-icon="false"` sale un signo de pregunta junto a
+  cualquier título.
+- **`suiAccordionContent` sin `lazy` no difiere nada.** Las dos piezas van juntas.
+- **`lazy` 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).
+
+## Bien y mal
+
+Contenido diferido
+
+```html
+<!-- ❌ mal: el template sin [lazy] se crea al cargar igual (pages/envios/envios.html:756) -->
+<sui-accordion title={tituloDetalle(e)} left-icon="false" open={detalleAbierto} onOpenChange={(e) => (detalleAbierto = e.detail)}>
+  <ng-template suiAccordionContent>…</ng-template>
+</sui-accordion>
+```
+
+```html
+<!-- ✅ bien -->
+<sui-accordion title={tituloDetalle(e)} left-icon="false" lazy open={detalleAbierto} onOpenChange={(e) => (detalleAbierto = e.detail)}>
+  <ng-template suiAccordionContent>…</ng-template>
+</sui-accordion>
+```
+
+Resumen de la fila cerrada
+
+```html
+<!-- ❌ mal: description solo se ve abierto; cerrado, el resumen no aparece (pages/envios/envios.html:413) -->
+<sui-accordion title="Más detalles (opcional)" description={resumenDetallesEnvio()}
+  left-icon="false" />
+```
+
+```html
+<!-- ✅ bien: lo que tiene que verse cerrado va en el título, como en master-orders.html:673 -->
+<sui-accordion title={'Más detalles · ' + resumenDetallesEnvio()} left-icon="false" />
+```
+
+Badge en la fila
+
+```html
+<!-- ❌ mal: el atajo de string sale en small, y D16 no deja nada en small -->
+<sui-accordion title="Reto semanal" badge="Nuevo" left-icon="false" />
+```
+
+```html
+<!-- ✅ bien -->
+<sui-accordion title="Reto semanal" badge={{ label: 'Nuevo', size: bp.sizeBadge() }}
+  left-icon="false" />
+```
+
+## Ejemplo
+
+```html
+<!-- Sección opcional de un formulario, con el contenido diferido de verdad -->
+<sui-accordion
+  title="Más detalles (opcional)"
+  left-icon="false"
+  lazy
+  open={detallesAbiertos} onOpenChange={(e) => (detallesAbiertos = e.detail)}>
+  <ng-template suiAccordionContent>
+    <sui-textarea label="Indicaciones para el repartidor" value={indicaciones} onValueChange={(e) => (indicaciones = e.detail)} />
+  </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." />
+```