@ajuarezso/sui-stencil 0.0.0-stage → 0.1.0

package/docs/sui-otp-input/README.md

@@ -0,0 +1,204 @@
+---
+name: sui-otp-input
+selector: sui-otp-input
+resumen: Código de verificación dígito por dígito, una celda por número (SMS, código de entrega)
+alternativas: [sui-input (un código largo o que se pega entero), sui-input type="password-toggle" (una clave que no se ve)]
+---
+
+# sui-otp-input
+
+<!-- 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-otp-input`); 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: [Molecules/Input/Otp Input](https://sui-design-system.web.app/?path=/docs/molecules-input-otp-input--docs)
+
+## Cuándo usarlo / cuándo no
+
+**Úsalo** para un código corto que llega por otro canal y se copia dígito por dígito: un código
+por SMS o WhatsApp, o un código de entrega que el cliente le dicta al repartidor. Salta solo a la
+celda siguiente, retrocede con borrar, reparte lo que se pega y avisa con `completed` cuando
+está lleno. La primera celda pide `autocomplete="one-time-code"` (el teléfono sugiere el código
+del SMS).
+
+**No lo uses** para:
+
+- Una contraseña o PIN que se elige: `sui-input type="password-toggle"`.
+- Un código de más de 6 caracteres o con letras y guiones (un cupón): `sui-input`.
+
+Regla corta: **código corto que llega por otro canal → otp · cupón o clave → input.**
+
+## Qué variante usar
+
+> **La guía del DS lo define como el campo para escribir códigos de un solo uso dígito por dígito,
+> pensado para flujos de verificación** con códigos numéricos cortos. Muestra error, deshabilitado
+> y celdas cuadradas. No dice cuántas celdas.
+>
+> Uso medido el 03-10-2026 en `master-pedidos/src/app`: **0 usos**. Hoy no hay login por SMS ni
+> código de entrega.
+
+| prop / evento | cuándo | fuente |
+|---|---|---|
+| `type="number"` (default) | Códigos numéricos: teclado de números. | según la guía del DS (códigos numéricos) |
+| `type="text"` | No usar hoy: un código con letras se tipea mejor en un `sui-input`. | canon (aprobado por el dueño, 05-10-2026, bloque B6) |
+| `length` | `6` para un SMS (lo que manda Firebase); `4` para un código de entrega dictado en voz alta. | propuesta, falta aprobación |
+| `error` | El código no coincide. Pinta todas las celdas; el mensaje va aparte, debajo. | según la guía del DS (ejemplo con error) |
+| `disabled` | Mientras se verifica el código. | según la guía del DS (ejemplo deshabilitado) |
+| `ariaLabel` | Qué código es: «Código que te llegó por SMS». El default es «Código de verificación». | canon (aprobado por el dueño, 05-10-2026, bloque B5) |
+| `completed` | Verificar apenas se llena, sin botón «Continuar». | canon (aprobado por el dueño, 05-10-2026, bloque B8) |
+
+## Tamaño en mobile y en web
+
+Tiene `size` (extensión SUI) para la celda. `large` es el de la guía y el default: **80 × 64** con 8
+px entre celdas (6 celdas = 520 px). Para el teléfono, **`medium` (52 × 56)**: 6 celdas miden 352
+px y entran en los 358 útiles de una pantalla de 390. `small` (44 × 48, dígito de 20) **no se usa**:
+en 360 px el `medium` se achica solo a unos 48 × 56 y sigue por encima de 44 (D16, dueño
+05-10-2026: nada en `small`; reemplaza el «`small` para 360 px» del 03-10-2026).
+
+Además, **el componente nunca es más ancho que su contenedor**: si las celdas no entran, se achican
+parejo en vez de salirse de la pantalla (un `large` de 6 en 390 queda en celdas de 53 × 64). Es la red
+de seguridad, no el tamaño a elegir: se ve angosto y alto.
+
+| size | celda | 6 celdas | fuente |
+|---|---|---|---|
+| `large` (default) | 80 × 64 · dígito 24 | 520 px | según la guía del DS |
+| `medium` | 52 × 56 · dígito 24 | 352 px | canon (aprobado por el dueño, 03-10-2026), extensión SUI |
+| `small` | 44 × 48 · dígito 20 | 304 px | canon (aprobado por el dueño, 03-10-2026), extensión SUI · no se usa: D16, dueño 05-10-2026 |
+
+| uso | mobile (390) | web | fuente |
+|---|---|---|---|
+| código de 6 dígitos | `medium` | `large` | canon (aprobado por el dueño, 05-10-2026, bloque B1) · la mitad web queda pendiente frente a D16 (ver «Por dispositivo») |
+| código de 4 dígitos | `large` (344 px, entra) | `large` | canon (aprobado por el dueño, 05-10-2026, bloque B1) · la mitad web queda pendiente frente a D16 (ver «Por dispositivo») |
+
+```html
+<sui-otp-input length="6" size={bp.isMobile() ? 'medium' : 'large'} value={codigo} onValueChange={(e) => (codigo = e.detail)} />
+<!-- bp = BreakpointsService -->
+```
+
+### Por dispositivo (D16)
+
+Las celdas se tocan, pero aquí el `size` lo elige **el ancho** (que las celdas entren), no el
+puntero: las tres miden 48 o más de alto, así que cualquiera se toca bien. Fuente: D16, dueño
+05-10-2026, y el bloque B1 (05-10-2026).
+
+| dispositivo | size | nota |
+|---|---|---|
+| celular chico (< 380) | `medium` (6 dígitos) · `large` (4) | 6 `medium` no entran en los 328 útiles de 360: se achican solos a unos 48 × 56 y siguen tocables. Nada en `small` |
+| celular (380–767) | `medium` (6 dígitos) · `large` (4) | 6 `medium` miden 352 y entran en los 358 útiles de 390; 4 `large` miden 344 |
+| tablet táctil (`pointer: coarse`) | `large` desde 768 px · por debajo (iPad mini vertical, 744), como el celular: `medium` con 6 dígitos | aquí manda el ancho, no el puntero: es lo que da `bp.isMobile()` (hasta 767). Las dos celdas pasan los 44 |
+| computadora (`pointer: fine`) | **pendiente** (`large` por ahora) | el bloque B1 (aprobado el 05-10-2026) dio `large` en web; la regla general de D16 (la misma tarde) da `medium` en lo que se toca. Pero el `medium` del otp es la celda angosta para que 6 entren en el teléfono (52 × 56), no un tamaño de escritorio. Falta que el dueño diga si D16 pisa a B1 aquí; mientras tanto se queda el `large` de B1, que es el default (interino) |
+
+En el ultrawide, igual que en la computadora: el espacio extra no agranda las celdas.
+
+En master-pedidos: `size={bp.isMobile() ? 'medium' : 'large'}` con 6 dígitos; con 4, sin `size`
+(`large` es el default). El `'large'` de la computadora es el interino de B1 mientras la fila sigue
+pendiente. No hay helper: `bp.sizeControl()` da `large` en el celular, y 6 celdas
+`large` no entran.
+
+## «No usar»: por qué no hoy y cuándo sí
+
+| qué | por qué no hoy | cuándo sí, en un flujo nuevo |
+|---|---|---|
+| el componente entero (0 usos) | no hay verificación por código | verificar el teléfono del cliente por SMS, o un código de entrega de 4 dígitos que el cliente le dicta al repartidor |
+| `type="text"` | los códigos que llegan son numéricos | un código alfanumérico corto de una campaña |
+| `size="small"` | `medium` ya entra en 390 | ninguno: en 360 px el `medium` se achica solo a 48 × 56 (D16, dueño 05-10-2026: nada en `small`) |
+
+## API
+
+<!-- api:inicio -->
+<!-- generada: no editar a mano — `npm run docs` -->
+
+| prop | atributo | tipo | default |
+|---|---|---|---|
+| `ariaLabel` | `aria-label` | `string` | `'Código de verificación'` |
+| `disabled` | `disabled` | `boolean` | `false` |
+| `error` | `error` | `boolean` | `false` |
+| `length` | `length` | `number` | `6` |
+| `size` | `size` | `"large" \| "medium" \| "small"` | `'large'` |
+| `type` | `type` | `"number" \| "text"` | `'number'` |
+| `value` | `value` | `string` | `''` |
+
+| evento | `event.detail` |
+|---|---|
+| `completed` | `string` |
+| `valueChange` | `string` |
+
+### Diferencias con el SUI Angular
+
+- **Eventos de Angular que aquí no existen:** `disabledChange`
+<!-- api:fin -->
+
+<!-- textos:inicio -->
+### Textos
+
+Lo que el componente escribe solo sale de `provideSuiTextos` (español por defecto, se cambia en vivo; ver `docs/TEXTOS.md`). El input de la última columna le gana al texto global.
+
+| clave | por defecto | se pisa con |
+|---|---|---|
+| `otp.digito` | Dígito {n} | — |
+| `otp.nombre` | Código de verificación | `ariaLabel` |
+<!-- textos:fin -->
+
+`value` y `disabled` son `model`. Implementa `ControlValueAccessor`.
+
+## Trampas
+
+- **6 celdas `large` no entran en un teléfono** (520 px): se achican solas, pero en mobile va
+  `size="medium"`. Ver «Tamaño en mobile y en web».
+- `error` no trae mensaje: el texto va debajo, con `sui-form-hint` en variante error.
+- `disabled` es un `model`: si el formulario lo deshabilita, el componente lo escribe de vuelta.
+- No hay grupos (3-3): si se necesitan, son dos componentes.
+
+## Bien y mal
+
+Código de 6 dígitos en el teléfono
+
+```html
+<!-- ❌ mal: sin size va large; 6 celdas de 80 no entran en 390 y se aplastan a 53 × 64. No hay usos en la app: la vitrina aún lo muestra así, marcado como propuesta y con la nota «falta una celda angosta en el DS», que ya existe (medium) (pages/super-admin/master-preview/_guia-moleculas/campos.ts:322) -->
+<sui-otp-input length="6" aria-label="Código que te llegó por SMS" value={codigo} onValueChange={(e) => (codigo = e.detail)} />
+```
+
+```html
+<!-- ✅ bien -->
+<sui-otp-input length="6" aria-label="Código que te llegó por SMS"
+               size={bp.isMobile() ? 'medium' : 'large'} value={codigo} onValueChange={(e) => (codigo = e.detail)} />
+```
+
+Código que no coincide
+
+```html
+<!-- ❌ mal: error solo pinta las celdas; nadie dice qué pasó -->
+<sui-otp-input length="4" aria-label="Código de entrega" error={codigoMalo()} value={codigo} onValueChange={(e) => (codigo = e.detail)} />
+```
+
+```html
+<!-- ✅ bien -->
+<sui-otp-input length="4" aria-label="Código de entrega" error={codigoMalo()} value={codigo} onValueChange={(e) => (codigo = e.detail)} />
+@if (codigoMalo()) { <sui-form-hint variant="error" message="El código no coincide" /> }
+```
+
+Un cupón con letras
+
+```html
+<!-- ❌ mal: más de 6 caracteres y con letras no es un otp -->
+<sui-otp-input length="8" type="text" aria-label="Cupón" value={cupon} onValueChange={(e) => (cupon = e.detail)} />
+```
+
+```html
+<!-- ✅ bien -->
+<sui-input label="Cupón" size={bp.sizeControl()} value={cupon} onValueChange={(e) => (cupon = e.detail)} />
+```
+
+## Ejemplo
+
+```html
+<sui-otp-input length="4" aria-label="Código de entrega" error={codigoMalo()}
+               value={codigo} onValueChange={(e) => (codigo = e.detail)} onCompleted={(e) => verificar(e.detail)} />
+```

package/docs/sui-page-header/README.md

@@ -0,0 +1,211 @@
+---
+name: sui-page-header
+selector: sui-page-header
+resumen: Título y subtítulo de una pantalla, con las acciones de la pantalla a la derecha en desktop y debajo en mobile
+alternativas: [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-page-header
+
+<!-- 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-page-header`); 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/Page Header](https://sui-design-system.web.app/?path=/docs/organisms-page-header--docs)
+
+## Cuándo usarlo / cuándo no
+
+**Úsalo** una vez por pantalla, **arriba del todo**, antes de cualquier contenido: dice dónde
+está la persona («Pedidos», «Descuentos») y, si hace falta, junta las acciones que valen para
+toda la pantalla («Agregar», «Exportar»).
+
+**No lo uses** para:
+
+- Títulos de sección dentro de la pantalla: un `<h2>` con el token de tipografía, o el título de
+  la `sui-card`.
+- Modales y paneles: `sui-modal-header` / `sui-drawer-header`.
+- Meter contenido debajo del título: **solo** acepta `slot="actions"`; todo lo demás se descarta
+  sin avisar.
+- Re-implementarlo con un `<h1>` y CSS propio (canon, CANON-SUI §0: «no re-implementar»).
+
+## Qué variante usar
+
+> **No está en la guía del DS: es extensión de SUI.** Nació como el título de las pantallas del
+> panel de empresa y no tiene Figma. Lo marcado **canon** sale de `master-pedidos/docs/CANON-SUI.md` o de la aprobación del dueño (05-10-2026);
+> lo marcado «componente» describe lo que el código ya hace. No queda nada en propuesta.
+>
+> Uso medido el 06-10-2026 en `master-pedidos/src/app`: 70 page headers en total y **66** sin contar
+> prototipos ni vitrinas (1 en cada uno: `master-preview`, `master-prototipos`, `master-rutina` y
+> `master-medico`; `mockup-sheets-*`, `dx/*`, `dev-index` y las copias de `components/sui/` no
+> tienen). Un `grep` da 72 porque cuenta 2 comentarios (`master-preview.scss:1`, `envios.ts:923`).
+> De los 66: 51 llevan `subtitle` fijo y 15 calculado; 17 tienen algo en
+> `slot="actions"` (15 botones y 2 solo badges: `master-drivers`, `master-approvals`); 0 usan `sticky`.
+
+### Lo que sí dice la guía del DS
+
+Nada: el page header no está en la guía. Su tipografía (24/600, 28 en desktop) **no existe en la
+escala del DS** (CANON-SUI §7): si se homologa, sería `title-h5`.
+
+### Contenido
+
+| pieza | regla | ejemplo real de la app | fuente |
+|---|---|---|---|
+| `title` | El nombre de la pantalla, el mismo que en el menú. Sentence case, sin punto. Nunca un ID. | `pages/discounts/discounts.html:2` | canon (CANON-SUI, copy) |
+| `subtitle` | Una línea que dice **qué se hace aquí**, no que repite el título. | `pages/super-admin/master-orders/master-orders.html:1` | canon (aprobado por el dueño, 05-10-2026, bloque B4) |
+| acciones | Las que valen para toda la pantalla: una `filled` como máximo (la principal) y el resto `stroke`. Hoy, de los 16 botones que se dibujan: 10 `filled` (uno por default, sin `variant`: `master-gastos.html:8`) y 6 `stroke`. | `pages/drivers/drivers.html:2` | canon (CANON-SUI §6.2: una sola primaria por pantalla; CLAUDE.md «Botones — composición y orden», 27-07-2026: uno solo `filled`, el secundario `stroke` `neutral`) |
+
+**Usos de hoy que rompen** (medido el 06-10-2026):
+
+- `pages/orders/orders.html:14`: el botón «Actualizar» va sin `slot="actions"`, así que no se
+  proyecta y no se dibuja en ningún ancho (ver «Bien y mal»).
+
+Los cuatro botones en Title Case que había (`drivers.html:8`, `discounts.html:7`,
+`employees.html:7`, `locations.html:7`) ya van en sentence case desde el commit `8b34d8ed`
+(06-10-2026) de master-pedidos.
+
+### `sticky`
+
+| valor | cuándo | fuente |
+|---|---|---|
+| `false` (default) | el caso normal: el título se va con el scroll | canon (aprobado por el dueño, 05-10-2026, bloque B9) |
+| `true` | listas largas donde las acciones del header se usan mientras se recorre (filtros, «Agregar»). Le pone fondo blanco. 0 usos hoy | canon (aprobado por el dueño, 05-10-2026, bloque B9) |
+
+## Tamaño en mobile y en web
+
+El page header **no tiene `size`**. Cambia solo en 767 px:
+
+| | mobile (< 767 px) | web (≥ 767 px) | fuente |
+|---|---|---|---|
+| título | 24 px | 28 px | componente |
+| disposición | título y subtítulo arriba, acciones **debajo** | título a la izquierda, acciones a la derecha, alineadas abajo | componente |
+| padding vertical | 24 arriba y abajo | 32 arriba, 16 abajo | componente |
+| padding lateral | ninguno: lo pone el contenedor del layout | igual | componente |
+| botones de las acciones | `large` (48) | `medium` (40) | mobile `large`: canon (decisión del dueño 04-10-2026, piso táctil 44) · web `medium`: canon (dueño, 05-10-2026, D16), reemplaza el `small` del bloque B1 |
+
+En mobile, `large` es canon (piso táctil 44, 04-10-2026: `small` y `medium` no llegan); en la
+computadora va `medium` y la tablet va como el celular (canon, dueño, 05-10-2026, D16; reemplaza el
+`small` del bloque B1): en mobile las acciones bajan a su fila y tienen sitio para 48 px; en desktop
+van al lado del título de 28. Medido el 06-10-2026: 66 page headers (sin vitrinas ni prototipos),
+16 botones en las acciones, los 16 con `bp.sizeControl()` (ya no queda ningún `small`). Hay un
+botón 17 dentro de un page header, también con `bp.sizeControl()`, pero va sin `slot="actions"` y no
+se dibuja (`pages/orders/orders.html:14`).
+
+```html
+<sui-button size={bp.sizeControl()} slot="actions">Agregar</sui-button>
+```
+
+### Por dispositivo (D16)
+
+El header no tiene `size`: lo que cambia por dispositivo son **los botones de las acciones**, que
+se tocan. Fuente: D16, dueño 05-10-2026 (fila `page-header (acciones)`).
+
+| dispositivo | size | nota |
+|---|---|---|
+| celular chico (< 380) | `large` por ahora | D16 pide `medium` con área tocable de 44; el DS todavía no la estira, así que se queda el grande (interino) |
+| celular (380–767) | `large` | las acciones bajan a su propia fila |
+| tablet táctil (`pointer: coarse`) | `large` | Apple pide 44 también en el iPad; a 767 px o más las acciones ya van al lado del título |
+| computadora (`pointer: fine`) | `medium` | al lado del título de 28 |
+
+En el ultrawide, igual que en la computadora: el espacio extra no agranda los botones.
+
+En master-pedidos: `size={bp.sizeControl()}` en cada `sui-button` de las acciones. No uses
+`bp.isMobile() ? 'large' : 'medium'`: en el iPad `isMobile` es falso y el botón queda en 40.
+
+## API
+
+<!-- api:inicio -->
+<!-- generada: no editar a mano — `npm run docs` -->
+
+| prop | atributo | tipo | default |
+|---|---|---|---|
+| `heading` | `heading` | `string` | — (requerido) |
+| `sticky` | `sticky` | `boolean` | `false` |
+| `subtitle` | `subtitle` | `null \| string` | `null` |
+
+Eventos: ninguno.
+
+Slots: `actions`, `(por defecto)`.
+
+### Diferencias con el SUI Angular
+
+- **Props de Angular que aquí no existen:** `title`
+- **Props solo de aquí:** `heading`
+<!-- api:fin -->
+
+Slot: `slot="actions"`, a la derecha (desktop) o debajo (mobile), gap 8. No hay slot default.
+
+## Trampas
+
+- **Lo que proyectas sin `slot="actions"` desaparece.** El JSDoc viejo hablaba de un slot
+  default; no existe.
+- **No respeta el safe-area de arriba**: el padding es fijo. El layout de la pantalla se encarga
+  del notch; si lo pones en una pantalla sin layout, el título queda bajo la barra de estado.
+- **Sin padding lateral**: depende de que el contenedor de la página lo tenga
+  (`.layout__body`, `.ml__content`). Fuera de esos layouts queda pegado al borde.
+- `sticky` se pega a `top: 0` del **contenedor que scrollea**, no de la ventana. En los layouts de
+  la app el scroll vive en `.layout__body` / `.ml__content`, así que funciona; en un contenedor
+  sin overflow no hace nada.
+- El breakpoint es `min-width: 767px`: a 767 px exactos ya está en modo desktop, un píxel antes
+  que el `max-width: 767px` de los mixins de la app.
+- `title` es requerido: sin él, Angular falla al compilar la plantilla.
+- El host borra el atributo `title` nativo (sin tooltip gris del navegador).
+
+## Bien y mal
+
+Botón de la pantalla
+
+```html
+<!-- ❌ mal: sin slot="actions" el botón no se dibuja en ningún ancho (pages/orders/orders.html:14) -->
+<sui-page-header title="Pedidos" subtitle="Lo que está en curso y todo lo que pasó por tu local.">
+  <sui-button variant="stroke" color="neutral" size={bp.sizeControl()} onClick={() => refresh()}>Actualizar</sui-button>
+</sui-page-header>
+```
+
+```html
+<!-- ✅ bien -->
+<sui-page-header title="Pedidos" subtitle="Lo que está en curso y todo lo que pasó por tu local.">
+  <sui-button slot="actions" variant="stroke" color="neutral" size={bp.sizeControl()} onClick={() => refresh()}>Actualizar</sui-button>
+</sui-page-header>
+```
+
+Texto de la acción
+
+```html
+<!-- ❌ mal: Title Case; los botones van en sentence case (así estaba pages/locations/locations.html:7 hasta el 06-10-2026) -->
+<sui-button slot="actions" variant="filled" color="primary" size={bp.sizeControl()}>Agregar Sucursal</sui-button>
+```
+
+```html
+<!-- ✅ bien -->
+<sui-button slot="actions" variant="filled" color="primary" size={bp.sizeControl()}>Agregar sucursal</sui-button>
+```
+
+Tamaño de la acción
+
+```html
+<!-- ❌ mal: isMobile no mira el puntero; en el iPad el botón queda en medium (40) -->
+<sui-button slot="actions" variant="filled" size={bp.isMobile() ? 'large' : 'medium'}>Crear descuento</sui-button>
+```
+
+```html
+<!-- ✅ bien -->
+<sui-button slot="actions" variant="filled" size={bp.sizeControl()}>Crear descuento</sui-button>
+```
+
+## Ejemplo
+
+```html
+<sui-page-header title="Descuentos" subtitle="Promociones y campañas activas de tu negocio.">
+  <sui-button slot="actions" variant="filled"
+    size={bp.sizeControl()} onClick={() => crear()}>
+    Crear descuento
+  </sui-button>
+</sui-page-header>
+```

package/docs/sui-pagination/README.md

@@ -0,0 +1,240 @@
+---
+name: sui-pagination
+selector: sui-pagination
+resumen: Números de página para recorrer una tabla larga en web cuando todos los datos ya están cargados
+alternativas: [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-pagination
+
+<!-- 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-pagination`); 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: [Molecules/Pagination](https://sui-design-system.web.app/?path=/docs/molecules-pagination--docs)
+
+## Cuándo usarlo / cuándo no
+
+**Úsalo** en **web**, debajo de una **tabla larga cuyos datos ya están en memoria** (un reporte, un
+export, una tabla filtrada en el navegador), cuando ayuda saber «voy por la 3 de 12» o saltar a una
+página.
+
+**No lo uses** para:
+
+- **Mobile**: las listas se recorren con el dedo. Va scroll infinito (la directiva
+  `appInfiniteScroll` que ya usan productos, clientes, el historial del repartidor y del cliente,
+  usuarios del super admin y las listas de la central).
+- **Listas que se leen de Firestore por cursor** (`getCollectionPage`): con cursores solo se puede
+  pedir la página siguiente. Saltar a la página 7 obliga a leer las 6 anteriores, y Firestore las
+  cobra igual. El canon de la app para esas listas es scroll infinito (CLAUDE.md, «Performance —
+  Firestore reads»).
+- Pasos de un flujo: `sui-stepper`.
+- Pocas filas (una sola página): no se muestra.
+
+Regla corta: **tabla con todo cargado en web → pagination · lista de Firestore o mobile → scroll infinito.**
+
+## Qué variante usar
+
+> **Lo que dice la guía del DS**: es un conjunto horizontal de enlaces para **navegar contenido
+> paginado**. Trae tres formas: `basic`, `rounded` (en SUI, `full-radius`) y `group`, más botones
+> de primera/última y anterior/siguiente, y la página actual marcada. No trae do/don't ni dice
+> cuándo cada forma.
+>
+> Uso medido el 03-10-2026 en `master-pedidos/src/app` (misma exclusión que `sui-badge`): **0 usos**.
+> Las listas largas de la app usan scroll infinito con `appInfiniteScroll` (por ejemplo
+> `pages/products/products.html:242` y `pages/customers/customers.html:161`). Equipo
+> (`pages/settings/team/team.ts:339`) pagina por cursor con `loadMore()`, pero hoy nada lo llama
+> (medido el 04-10-2026).
+
+### `type`
+
+| type | cuándo | fuente |
+|---|---|---|
+| `basic` (default) | El normal, debajo de una tabla con bordes. | según la guía del DS (es su default); el cuándo: canon (aprobado por el dueño, 05-10-2026, bloque B2) |
+| `group` | Cuando la tabla va dentro de una card y la paginación se apoya en su borde: un solo bloque se lee como parte de la tabla. | según la guía del DS (la forma existe); el cuándo: canon (aprobado por el dueño, 05-10-2026, bloque B2) |
+| `full-radius` | No: el resto de los controles de la app (botones, inputs) tienen esquinas de 8-10, no círculos. | según la guía del DS (la forma existe); el no es propuesta |
+
+### `size`
+
+| size | qué mide | cuándo | fuente |
+|---|---|---|---|
+| `medium` (default) | celdas de 32 px | Web, siempre: debajo de una tabla y en un modal o panel angosto. | extensión de SUI (la guía tiene un tamaño); el cuándo: canon (aprobado por el dueño, 05-10-2026, bloque B1) · también en paneles angostos: canon (dueño, 05-10-2026, D16) |
+| `small` | celdas de 28 px | No usar: es chico. En un modal o panel angosto va `medium`. | canon (dueño, 05-10-2026, D16), reemplaza el «cuándo» del bloque B1 |
+
+### Botones y texto
+
+| input | valor | cuándo | fuente |
+|---|---|---|---|
+| `nextPrevious` | `true` (default) | Siempre. | según la guía del DS |
+| `firstLast` | `false` (default) | Lo normal: con las elipsis ya se ve la primera y la última. | canon (aprobado por el dueño, 05-10-2026, bloque B9) |
+| `firstLast` | `true` | Más de 20 páginas, donde ir al final es un caso de uso (la última semana de un export). | según la guía del DS (los botones existen); el cuándo: canon (aprobado por el dueño, 05-10-2026, bloque B9) |
+| `siblingCount` | `1` (default) | Siempre. Más números a cada lado ensanchan sin ayudar. | canon (aprobado por el dueño, 05-10-2026, bloque B9) |
+| `showInfo` | `true` (default) | Con `infoFormat="items"`: «Mostrando 11-20 de 134». | canon (aprobado por el dueño, 05-10-2026, bloque B4) |
+| `infoFormat` | `'items'` (default) | «Mostrando 11-20 de 134». | según el código |
+| `infoFormat` | `'pages'` | Imprime «Página 2 de 14» (en español desde 03-10-2026). Cuando no se sabe el total de ítems o no importa. | canon (aprobado por el dueño, 05-10-2026, bloque B4) |
+| `pageSizeOptions` | `[]` (default) | Lo normal: sin selector de filas por página. | canon (aprobado por el dueño, 05-10-2026, bloque B9) |
+| `pageSizeOptions` | `[10, 25, 50]` | Las opciones dicen «10 / página» (en español desde 03-10-2026). | canon (aprobado por el dueño, 05-10-2026, bloque B9) |
+
+Usos de hoy que rompen las reglas: **0** (no se usa).
+
+## Tamaño en mobile y en web
+
+**No tiene tamaño para mobile**: la celda más grande mide 32 px, por debajo de los 44 tocables. En
+mobile no se usa.
+
+| uso | mobile | web | fuente |
+|---|---|---|---|
+| debajo de una tabla | no se usa: scroll infinito | `medium` (32) | canon (aprobado por el dueño, 05-10-2026, bloque B7) |
+| tabla en un panel angosto | no se usa | `medium` (32) | no se usa en mobile: canon (aprobado por el dueño, 05-10-2026, bloque B7) · web: canon (dueño, 05-10-2026, D16), antes `small` |
+
+```html
+@if (!bp.isMobile()) {
+  <sui-pagination total={filas().length} currentPage={pagina} onCurrentPageChange={(e) => (pagina = e.detail)} page-size="25" />
+}
+```
+
+### Por dispositivo (D16)
+
+Las celdas se tocan, pero ningún `size` llega a 44 (el más grande mide 32). Fuente: D16, dueño
+05-10-2026 (fila `pagination`).
+
+| dispositivo | size | nota |
+|---|---|---|
+| celular chico (< 380) | no se usa | scroll infinito |
+| celular (380–767) | no se usa | scroll infinito |
+| tablet táctil (`pointer: coarse`) | **pendiente** | con 32 px tiene el mismo problema que en el celular: celdas por debajo de 44 para el dedo. Falta que el dueño decida qué va en la tablet |
+| computadora (`pointer: fine`) | `medium` | también en un modal o panel angosto. `small` no se usa |
+
+En el ultrawide, igual que en la computadora: el espacio extra va a más columnas de la tabla, no a
+celdas más grandes.
+
+En master-pedidos no hay helper: `size` no se pasa (`medium` es el default) y el componente va
+dentro de `@if (!bp.isMobile())`. Ojo: con esa condición el iPad (768 px o más) **sí** lo muestra,
+en 32 px; es justo el caso pendiente, y no se resuelve cambiando a `bp.tactil()` hasta que el dueño
+decida.
+
+## «No usar»: por qué no hoy y cuándo sí
+
+| qué | por qué no hoy | cuándo sí, en un flujo nuevo |
+|---|---|---|
+| el componente entero | las listas de la app leen de Firestore por cursor y usan scroll infinito | una tabla de web con todos los datos ya cargados (un reporte de 300 filas filtrado en el navegador) |
+| `full-radius` | no combina con las esquinas del resto de la app | nunca, salvo que la app pase a botones redondos |
+| `infoFormat="pages"` | la razón original (salía en inglés) ya no aplica: desde el 03-10-2026 dice «Página 2 de 14» | cuando no se sabe el total de ítems o no importa |
+| `firstLast` | ninguna tabla tiene 20+ páginas | un export largo donde ir al final es habitual |
+
+## API
+
+<!-- api:inicio -->
+<!-- generada: no editar a mano — `npm run docs` -->
+
+| prop | atributo | tipo | default |
+|---|---|---|---|
+| `currentPage` | `current-page` | `number` | `1` |
+| `firstLast` | `first-last` | `boolean` | `false` |
+| `infoFormat` | `info-format` | `"items" \| "pages"` | `'items'` |
+| `nextPrevious` | `next-previous` | `boolean` | `true` |
+| `pageSize` | `page-size` | `number` | `10` |
+| `pageSizeOptions` | — (solo por propiedad JS) | `number[]` | `[]` |
+| `showInfo` | `show-info` | `boolean` | `true` |
+| `siblingCount` | `sibling-count` | `number` | `1` |
+| `size` | `size` | `"medium" \| "small"` | `'medium'` |
+| `total` | `total` | `number` | `0` |
+| `type` | `type` | `"basic" \| "full-radius" \| "group"` | `'basic'` |
+
+| evento | `event.detail` |
+|---|---|
+| `pageChange` | `number` |
+| `pageSizeChange` | `number` |
+
+### Diferencias con el SUI Angular
+
+- **Eventos de Angular que aquí no existen:** `currentPageChange`
+<!-- api:fin -->
+
+<!-- textos:inicio -->
+### Textos
+
+Lo que el componente escribe solo sale de `provideSuiTextos` (español por defecto, se cambia en vivo; ver `docs/TEXTOS.md`). El input de la última columna le gana al texto global.
+
+| clave | por defecto | se pisa con |
+|---|---|---|
+| `paginacion.nombre` | Paginación | — |
+| `paginacion.primera` | Primera página | — |
+| `paginacion.anterior` | Página anterior | — |
+| `paginacion.pagina` | Página {n} | — |
+| `paginacion.siguiente` | Página siguiente | — |
+| `paginacion.ultima` | Última página | — |
+| `paginacion.porPagina` | {n} / página | — |
+<!-- textos:fin -->
+
+```ts
+type SuiPaginationType = 'basic' | 'full-radius' | 'group';
+type SuiPaginationSize = 'small' | 'medium';
+type SuiPaginationInfoFormat = 'items' | 'pages';
+```
+
+## Trampas
+
+- **`total` es la cantidad de ítems, no de páginas.** Las páginas salen de `total / pageSize`.
+- **`currentPage` arranca en 1** (el stepper arranca en 0).
+- **`currentPage` y `pageSize` son `model`**: con `currentPage` + `currentPageChange` no hace falta `pageChange`.
+- **No carga datos**: solo dice qué página se pidió. Cortar las filas lo hace la pantalla.
+- **Textos en español** desde 03-10-2026: «Página X de Y» (`infoFormat="pages"`), «N / página»
+  (`pageSizeOptions`) y el default «Mostrando X-Y de Z».
+- **La página actual se pinta con `bg-weak-50`**, el mismo gris de las superficies de fondo: sobre
+  una card gris o un fondo `weak-50` no se distingue cuál es. Ponla sobre blanco.
+- **Con `total` en 0 no dibuja el texto**, pero sí los botones (una sola página «1»). Ocúltalo tú.
+- Las flechas son `<i class="ri-…">`: necesitan la fuente de Remix Icon cargada.
+
+## Bien y mal
+
+Lista en el celular
+
+```html
+<!-- ❌ mal: en el celular no se usa; las celdas de 32 no llegan a 44 -->
+<sui-pagination total={filas().length} currentPage={pagina} onCurrentPageChange={(e) => (pagina = e.detail)} page-size="25" />
+```
+
+```html
+<!-- ✅ bien -->
+@if (!bp.isMobile()) {
+  <sui-pagination total={filas().length} currentPage={pagina} onCurrentPageChange={(e) => (pagina = e.detail)} page-size="25" />
+}
+```
+
+Tabla en un panel angosto
+
+```html
+<!-- ❌ mal: small (28) no se usa; la vitrina aún lo marca como propuesta (pages/super-admin/master-preview/_guia-moleculas/navegacion.ts:169) -->
+<sui-pagination total="134" currentPage={pagina} onCurrentPageChange={(e) => (pagina = e.detail)} size="small" show-info="false" />
+```
+
+```html
+<!-- ✅ bien -->
+<sui-pagination total="134" currentPage={pagina} onCurrentPageChange={(e) => (pagina = e.detail)} show-info="false" />
+```
+
+Qué va en `total`
+
+```html
+<!-- ❌ mal: total es la cantidad de ítems, no de páginas: con 6 páginas de 25 dibuja una sola -->
+<sui-pagination total={paginas()} currentPage={pagina} onCurrentPageChange={(e) => (pagina = e.detail)} page-size="25" />
+```
+
+```html
+<!-- ✅ bien -->
+<sui-pagination total={filas().length} currentPage={pagina} onCurrentPageChange={(e) => (pagina = e.detail)} page-size="25" />
+```
+
+## Ejemplo
+
+```html
+<sui-pagination total="134" page-size="10" currentPage={pagina} onCurrentPageChange={(e) => (pagina = e.detail)} type="group" />
+```