@ajuarezso/sui-design-system 0.20.0 → 0.21.0

package/docs/sui-notification/README.md

@@ -0,0 +1,179 @@
+---
+name: sui-notification
+selector: sui-notification
+resumen: Fila de la bandeja de notificaciones, con quién, qué pasó, hace cuánto y si ya se leyó
+alternativas: [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
+
+Story: [Molecules/Feedback/Notification](https://sui-design-system.web.app/?path=/docs/molecules-feedback-notification--docs)
+
+## Primero: dos cosas distintas con el mismo nombre
+
+- **En la guía del DS**, una «notification» es un aviso **temporal en una esquina** con título,
+  descripción y una acción (un pago, una actualización). En SUI ese caso **es un `sui-toast`** con
+  `description` y `action`.
+- **En SUI**, `sui-notification` es la **fila de la bandeja**: el panel de la campana del Figma del
+  DS (foto, título, descripción, hora, punto de no leída). Este README es sobre eso.
+
+El componente además arrastra un tercer uso: un aviso con tipo y relleno (`variant`, `variantStyle`)
+igual al de `sui-alert`. Ese uso no va: para eso está el alert.
+
+## Cuándo usarlo / cuándo no
+
+**Úsalo** para cada aviso de una **bandeja** que la persona revisa cuando quiere: «Tu pedido llegó»,
+«Nuevo pedido de Pollería El Dorado», «Recarga aprobada». Lleva **la hora**, se marca como leído y
+se puede volver a abrir.
+
+**No lo uses** para:
+
+- Avisar algo en el momento: `sui-toast` (aunque tenga título, descripción y acción).
+- Un aviso dentro de una pantalla: `sui-alert`.
+- Una lista de actividad sin leído/no leído (el historial de un pedido): `sui-activity-feed`.
+
+Regla corta (canon, la misma del alert): **contexto → alert · toda la app → banner · efímero →
+toast · bandeja → notification.**
+
+## Qué variante usar
+
+> La guía del DS no tiene esta fila (su «notification» es otra cosa, ver arriba). Lo de abajo sale
+> del Figma del DS y del componente («según el componente»), de lo ya aprobado («canon») o es
+> **propuesta**.
+>
+> Uso medido el 03-10-2026 en `master-pedidos/src/app`: **0 usos**. La bandeja de la app
+> (`pages/notifications/notifications.html:98`, la misma pantalla en las rutas de los 4 roles) dibuja
+> sus filas a mano.
+
+### Qué lleva cada fila
+
+| prop | valor | cuándo | fuente |
+|---|---|---|---|
+| `avatar` | `src` con la foto | **Siempre**: la cara o el logo de quien generó el aviso (el local del pedido, el repartidor que lo lleva). Una foto se reconoce antes que un texto. | propuesta |
+| `avatar` | `{ initials }` | Solo si no hay foto. Ojo: sale en un círculo negro, **no** con el color por rol (ver Trampas). | según el componente |
+| `avatar` | el isotipo de la app | Avisos **del sistema** sin una persona detrás («Tu plan vence en 3 días»): así toda la bandeja queda en filas iguales. | propuesta |
+| `title` | frase corta | Qué pasó: «Tu pedido llegó». Sentence case, sin punto final. | canon (copy de la app) |
+| `description` | una o dos frases | El detalle que decide si abrirla: «Pollería El Dorado · S/ 42.50». | propuesta |
+| `timestamp` | texto ya formateado | **Siempre**: la hora es lo que hace bandeja a la bandeja. «Hace 5 min», «Ayer 18:40». | canon (bandeja con hora) · formato: propuesta |
+| `unread` | `true` | Hasta que la persona la abre. El punto es naranja (el primario de la app). | según el componente |
+| `showMore` | `true` | No usar hoy: el botón ⋮ solo aparece con el mouse encima. **Cuándo sí:** en web, acciones por fila (marcar como leída, archivar). | propuesta |
+| `active` | `true` | No usar hoy: pinta la fila como si tuviera el mouse encima. **Cuándo sí:** navegar la bandeja con las flechas del teclado (ver `sui-notification-footer`). | propuesta |
+| `dismissible` | `true` | No usar hoy: los avisos de la bandeja se leen, no se cierran. **Cuándo sí:** una bandeja donde se borran avisos uno por uno. | propuesta |
+
+### `type` — el cuerpo de la fila
+
+| type | cuándo | fuente |
+|---|---|---|
+| `basic` (default) | Todas las de hoy: título, descripción y hora. | según el componente |
+| `button` | No usar hoy. **Cuándo sí:** una solicitud que se resuelve desde la misma bandeja, con «Rechazar» / «Aprobar» en `slot="actions"` (por ejemplo, una invitación a un equipo). Secundario a la izquierda, primario a la derecha. | propuesta · orden: canon |
+| `message` | No usar hoy. **Cuándo sí:** el aviso trae lo que escribió otra persona (la nota del cliente, un mensaje del repartidor), en la burbuja. | propuesta |
+| `file` | No usar hoy: la app no manda adjuntos. **Cuándo sí:** un comprobante o una boleta adjunta. | propuesta |
+
+### `variant` y `variantStyle` — el modelo de alert
+
+| prop | valor | cuándo | fuente |
+|---|---|---|---|
+| `variant` | `default` (default) | **Siempre** en la bandeja: el tipo lo dice la foto y el texto, no un color. | propuesta |
+| `variant` | `info` · `success` · `warning` · `error` · `feature` | No usar: con tipo y sin foto, la fila se vuelve un alert con borde y sombra. **Cuándo sí:** ninguno; ese aviso es un `sui-alert`. | propuesta (sigue la regla canon) |
+| `variantStyle` | `stroke` (default) | Siempre. Con foto, la fila es plana: sin borde ni sombra. | según el componente |
+| `variantStyle` | `filled` · `light` · `lighter` | No usar: pintan la fila de color, que es lo que hace el alert. **Cuándo sí:** ninguno. | propuesta |
+| `showIcon` | `true` (default) | No cambia nada con foto; el ícono de tipo solo sale en el modelo de alert. | según el componente |
+
+### Slots
+
+| slot | cuándo | fuente |
+|---|---|---|
+| `slot="company-logo"` | Logo de 16 px antes de la descripción: el local, cuando la foto es la del repartidor. | propuesta |
+| `slot="actions"` | Los dos botones de `type="button"`. | según el componente |
+| `slot="message"` · `slot="file"` | El cuerpo de `type="message"` y `type="file"`. | según el componente |
+
+### Usos de hoy que romperían la regla
+
+- **La bandeja dibuja sus filas a mano — 1 pantalla, 4 rutas:** `pages/notifications/notifications.html:98`
+  (ícono de color por tipo, fila teñida si no se leyó, punto a la derecha). **A discutir**: no es un
+  cambio 1:1. Con el componente, el tipo se ve en la foto y no en un ícono de color, y la no leída
+  lleva solo el punto, sin teñir la fila.
+
+## Tamaño en mobile y en web
+
+La fila **no tiene `size`**: foto de 40 px, 12 px de relleno, texto de 14.
+
+| uso | mobile | web | fuente |
+|---|---|---|---|
+| la fila | toda la fila se toca para abrirla: mide 64 px o más | igual | según el componente |
+| ⋮ (`showMore`) | no aplica: aparece con el mouse | 24 px | según el componente |
+| la X (`dismissible`) | se ve de 20 px; **se toca en 40 × 40** | igual | canon (aprobado por el dueño, 03-10-2026): área táctil invisible, extensión SUI |
+| botones de `type="button"` | los pone quien la usa: `[size]="bp.isMobile() ? 'large' : 'xsmall'"` | `xsmall` | propuesta |
+
+## «No usar»: por qué no hoy y cuándo sí
+
+| qué | por qué no hoy | cuándo sí, en un flujo nuevo |
+|---|---|---|
+| el modelo de alert (`variant` ≠ `default`, rellenos de color) | duplica a `sui-alert` | ninguno: es un alert |
+| `type="button"` | nada se resuelve desde la bandeja | aceptar o rechazar una solicitud (una invitación a un equipo) desde la bandeja |
+| `type="message"` | los avisos no traen texto de otra persona | la nota del cliente o un mensaje del repartidor |
+| `type="file"` | no hay adjuntos | un comprobante o una boleta |
+| `showMore` | solo se ve con mouse | acciones por fila en web |
+| `active` | no se navega con teclado | bandeja con flechas del teclado |
+| `dismissible` | se leen, no se cierran | una bandeja donde se borra aviso por aviso |
+
+## API
+
+<!-- api:inicio -->
+<!-- generada: no editar a mano — `npm run docs` -->
+
+| input | tipo | default |
+|---|---|---|
+| `variant` | `'info' \| 'success' \| 'warning' \| 'error' \| 'feature' \| 'default'` | `'default'` |
+| `variantStyle` | `'filled' \| 'light' \| 'lighter' \| 'stroke'` | `'stroke'` |
+| `title` | `string \| null` | `null` |
+| `description` | `string \| null` | `null` |
+| `timestamp` | `string \| null` | `null` |
+| `avatar` | `SuiAvatarConfig \| string \| null` | `null` |
+| `showIcon` | `boolean` | `true` |
+| `dismissible` | `boolean` | `false` |
+| `unread` | `boolean` | `false` |
+| `type` | `'basic' \| 'file' \| 'button' \| 'message'` | `'basic'` |
+| `showMore` | `boolean` | `false` |
+| `active` | `boolean` | `false` |
+
+| output | payload |
+|---|---|
+| `dismissed` | `void` |
+| `moreClicked` | `MouseEvent` |
+<!-- api:fin -->
+
+Slots: `[slot=company-logo]`, `[slot=file]`, `[slot=message]`, el contenido libre, `[slot=actions]`.
+
+## Trampas
+
+- **La X se toca en 40 × 40** aunque se vea de 20 (un `::before` invisible sobre su `<button>`,
+  desde 03-10-2026): en una fila que se toca entera, el toque a 10 px de la X la cierra en vez de
+  abrirla.
+- **Es el avatar el que decide el modelo**: con `avatar` es una fila plana (`role="article"`); sin
+  `avatar` es un alert con borde y sombra (`role="status"`, que el lector de pantalla anuncia).
+- **El avatar no es `sui-avatar`**: lo dibuja la fila, en un círculo **negro** con iniciales.
+  Ignora `color`, así que no respeta el color por rol de la app (local naranja, repartidor verde,
+  cliente azul). Con foto no se nota; sin foto, sí.
+- **La hora cambia de lugar**: sin avatar va a la derecha del título; con avatar, delante de la
+  descripción («Hace 5 min ∙ …»).
+- `timestamp` es texto: el formato («Hace 5 min») lo arma quien la usa.
+- `feature` usa `sparkling-fill` aquí y en el alert, y `magic-fill` en el banner.
+- `dismissible` solo emite `(dismissed)`: la fila **no se esconde sola** (a diferencia de alert y
+  banner). La saca quien la usa.
+- El ⋮ de `showMore` se ve solo con el mouse encima o con `active`: en mobile no aparece.
+- **`showMore` y `dismissible` juntos se pisan**: el ⋮ y la X van los dos arriba a la derecha.
+- Con avatar (o con `type` distinto de `basic`) y **sin `description`**, queda un «∙» colgando
+  después de la hora («Hace 8 min ∙»).
+- Borra el `title` nativo del host.
+
+## Ejemplo
+
+```html
+<div role="list">
+  <sui-notification role="listitem"
+    [avatar]="pedido.localLogo" title="Tu pedido llegó"
+    description="Pollería El Dorado · S/ 42.50" timestamp="Hace 5 min" [unread]="!n.read"
+    (click)="abrir(n)" />
+</div>
+```

package/docs/sui-notification-footer/README.md

@@ -0,0 +1,98 @@
+---
+name: sui-notification-footer
+selector: sui-notification-footer
+resumen: Pie del panel desplegable de notificaciones (web): ayuda de teclado a la izquierda y un link a los ajustes a la derecha
+alternativas: [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-footer
+
+Story: [Molecules/Feedback/Notification Footer](https://sui-design-system.web.app/?path=/docs/molecules-feedback-notification-footer--docs)
+
+## Cuándo usarlo / cuándo no
+
+**Úsalo** solo como **pie del panel de la campana** en web: el desplegable que abre la bandeja desde
+la barra superior, con filas `sui-notification` y la cabecera `sui-notification-tab-menu`. Dice
+«Usa ↑ ↓ para moverte» y lleva el link a los ajustes de notificaciones.
+
+**No lo uses** para:
+
+- La pantalla de notificaciones (la bandeja a pantalla completa): ahí los ajustes ya están en la
+  misma pantalla y nadie navega con flechas.
+- Mobile: la mitad del componente es una ayuda de **teclado**.
+- El pie de cualquier otro panel: `sui-drawer-footer` o `sui-modal-footer`.
+
+## Qué variante usar
+
+> La guía del DS no tiene página para este componente: sale del Figma del DS (pie del panel de
+> notificaciones). Todo lo de abajo es **propuesta**, salvo lo marcado «según el componente».
+>
+> Uso medido el 03-10-2026 en `master-pedidos/src/app`: **0 usos**. La app no tiene panel
+> desplegable de campana: su bandeja es una pantalla (`pages/notifications/`).
+
+| prop | valor | cuándo | fuente |
+|---|---|---|---|
+| `usePrefix` · `useSuffix` | `'Usa'` · `'para moverte'` | Ya son los defaults (03-10-2026); no hace falta pasarlos. | canon (copy de la app: tuteo, español) |
+| `manage` | `'Ajustes de notificaciones'` | El link a los ajustes. Emite `(manageClick)`. | propuesta |
+| `manage` | `{ label, href }` | Cuando los ajustes son otra ruta: se dibuja un `<a>` de verdad. | según el componente |
+| `manage` | `true` (default) | Dice «Administrar notificaciones» (en español desde 03-10-2026). | propuesta |
+| `manage` | `false` · `null` | Cuando los ajustes ya están a la vista en el mismo panel. | propuesta |
+
+## Tamaño en mobile y en web
+
+**No tiene `size`**: texto de 12 y link `small` (16 px de alto).
+
+| uso | mobile | web | fuente |
+|---|---|---|---|
+| el pie entero | no aplica: es ayuda de teclado; en mobile no se muestra | unos 48 px de alto | propuesta |
+| el link de ajustes | si hiciera falta, un `sui-link-button` `large` suelto | `small` (16 px) | propuesta |
+
+```html
+@if (!bp.isMobile()) {
+  <sui-notification-footer usePrefix="Usa" useSuffix="para moverte"
+    manage="Ajustes de notificaciones" (manageClick)="abrirAjustes()" />
+}
+```
+
+## «No usar»: por qué no hoy y cuándo sí
+
+| qué | por qué no hoy | cuándo sí, en un flujo nuevo |
+|---|---|---|
+| el componente | no hay panel de campana | si el panel del local o el super admin suman una campana con la bandeja desplegable en la barra superior (web) |
+| `manage` con el texto por defecto | está en inglés | nunca: siempre un texto propio |
+
+## API
+
+<!-- api:inicio -->
+<!-- generada: no editar a mano — `npm run docs` -->
+
+| input | tipo | default |
+|---|---|---|
+| `usePrefix` | `string` | `'Usa'` |
+| `useSuffix` | `string` | `'para moverte'` |
+| `manage` | `SuiLinkConfig \| string \| boolean \| null` | `true` |
+
+| output | payload |
+|---|---|
+| `manageClick` | `MouseEvent` |
+<!-- api:fin -->
+
+```ts
+interface SuiLinkConfig { label: string; href?: string; target?: string; rel?: string; }
+```
+
+## Trampas
+
+- **Textos por defecto en español** desde 03-10-2026: «Usa ↑ ↓ para moverte» y «Administrar
+  notificaciones» (antes «Use», «to navigate» y «Manage Notification»).
+- Las teclas ↑ ↓ están fijas: no se pueden cambiar por otras.
+- Con `href` y `target="_blank"` agrega `rel="noopener noreferrer"` solo.
+- Ocupa el 100 % del ancho de su contenedor (el Figma lo dibuja de 540 px).
+- Borra el `title` nativo del host.
+
+## Ejemplo
+
+```html
+<sui-notification-footer usePrefix="Usa" useSuffix="para moverte"
+  [manage]="{ label: 'Ajustes de notificaciones', href: '/empresa/notificaciones' }" />
+```

package/docs/sui-notification-tab-menu/README.md

@@ -0,0 +1,112 @@
+---
+name: sui-notification-tab-menu
+selector: sui-notification-tab-menu
+resumen: Cabecera con pestañas del panel desplegable de notificaciones (web), con conteo de no leídas y botón de filtro
+alternativas: [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-notification-tab-menu
+
+Story: [Molecules/Feedback/Notification Tab Menu](https://sui-design-system.web.app/?path=/docs/molecules-feedback-notification-tab-menu--docs)
+
+## Cuándo usarlo / cuándo no
+
+**Úsalo** solo como **cabecera del panel de la campana** en web: «Todas · No leídas (3) · Pedidos |
+Archivadas» con el filtro a la derecha, encima de las filas `sui-notification`.
+
+**No lo uses** para:
+
+- La bandeja a pantalla completa y en mobile: la app usa `sui-tab-chips` («Todas», «No leídas (3)»)
+  en `pages/notifications/notifications.html:47`, que se toca mejor con el dedo. Es lo correcto.
+- Las pestañas de cualquier otra pantalla: `sui-tab-menu-horizontal`.
+
+## Qué variante usar
+
+> La guía del DS no tiene página para este componente: sale del Figma del DS (cabecera del panel
+> de notificaciones). Todo lo de abajo es **propuesta**, salvo lo marcado «según el componente».
+>
+> Uso medido el 03-10-2026 en `master-pedidos/src/app`: **0 usos** (no hay panel de campana).
+
+| prop | valor | cuándo | fuente |
+|---|---|---|---|
+| `tabs` | 2 a 4 pestañas | «Todas» primero, luego «No leídas» y los grupos del rol (Pedidos, Promos, Encargos…). Más de 4 no caben en el panel. | propuesta |
+| `tabs[].badge` | número > 0 | El conteo de **no leídas**, solo en la pestaña donde importa. Es un `sui-badge` rojo lleno: un conteo que pide acción. | según el componente · regla de badge: canon |
+| `tabs[].dividerBefore` | `true` | Separa lo que no es bandeja activa: «Archivadas» al final. | según el componente (Figma) |
+| `[(active)]` | el `value` de la pestaña | Siempre enlazado: es un model de dos vías. | según el componente |
+| `showFilter` | `true` (default) | Solo si el panel tiene filtros de verdad (por local, por fecha). | propuesta |
+| `showFilter` | `false` | Lo normal: sin filtros, un botón que no hace nada estorba. | propuesta |
+| `filterLabel` | texto | El nombre del botón de filtro para el lector de pantalla. Default «Filtrar». | según el componente |
+
+## Tamaño en mobile y en web
+
+**No tiene `size`**: la fila mide 48 px, pero cada pestaña es un botón de **20 px de alto** (solo el
+texto) y el filtro es un compact-button de 24 px.
+
+| uso | mobile | web | fuente |
+|---|---|---|---|
+| las pestañas | **no alcanza**: 20 px de alto para el dedo. Usar `sui-tab-chips` | 20 px de alto, en una fila de 48 | sin tamaño suficiente (no se cambia aquí) |
+| el filtro | 24 px, **bajo el mínimo de 32 px** en mobile | 24 px | sin tamaño suficiente |
+
+```html
+@if (bp.isMobile()) {
+  <sui-tab-chips [chips]="pestanas" [value]="activa()" (valueChange)="activa.set($event)" />
+} @else {
+  <sui-notification-tab-menu [tabs]="pestanas" [(active)]="activa" [showFilter]="false" />
+}
+```
+
+## «No usar»: por qué no hoy y cuándo sí
+
+| qué | por qué no hoy | cuándo sí, en un flujo nuevo |
+|---|---|---|
+| el componente | no hay panel de campana; la bandeja es una pantalla con `sui-tab-chips` | si el panel del local o el super admin suman la campana con bandeja desplegable en web |
+| `showFilter` | no hay filtros en la bandeja | filtrar avisos por local (central con varios locales) o por fecha |
+| `dividerBefore` | no hay «Archivadas» | si se agrega archivar avisos |
+
+## API
+
+<!-- api:inicio -->
+<!-- generada: no editar a mano — `npm run docs` -->
+
+| input | tipo | default |
+|---|---|---|
+| `tabs` | `SuiNotificationTab<T>[]` | — (requerido) |
+| `active` · model, `[(active)]` | `T` | `undefined` |
+| `showFilter` | `boolean` | `true` |
+| `filterLabel` | `string` | `'Filtrar'` |
+
+| output | payload |
+|---|---|
+| `tabChange` | `T` |
+| `filterClick` | `MouseEvent` |
+<!-- api:fin -->
+
+```ts
+interface SuiNotificationTab<T = string> {
+  value: T;
+  label: string;
+  badge?: number;          // > 0 lo muestra
+  dividerBefore?: boolean; // línea vertical antes de esta pestaña
+}
+```
+
+## Trampas
+
+- **`showFilter` arranca en `true`**: si no pasas `false`, aparece un botón de filtro.
+- `tabs` es **obligatorio** y `active` es un model: `[(active)]`, no `[value]` como en `sui-tab-chips`.
+- La raya de la pestaña activa usa el primario de la app (naranja), no el azul del Figma.
+- El badge no tiene tope: 120 sale «120». Si hace falta, el texto lo recorta quien lo usa («99+» va
+  en `label`, no en `badge`, porque `badge` es un número).
+- El host lleva `role="tablist"` y cada pestaña `role="tab"` con `aria-selected`; no hay panel `tabpanel` asociado: lo arma quien lo usa.
+
+## Ejemplo
+
+```html
+<sui-notification-tab-menu [showFilter]="false" [(active)]="pestana"
+  [tabs]="[
+    { value: 'todas', label: 'Todas' },
+    { value: 'no-leidas', label: 'No leídas', badge: 3 },
+    { value: 'pedidos', label: 'Pedidos' },
+    { value: 'archivadas', label: 'Archivadas', dividerBefore: true },
+  ]" />
+```

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

@@ -0,0 +1,116 @@
+---
+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
+
+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`. | propuesta, falta aprobación |
+| `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». | propuesta, falta aprobación |
+| `(completed)` | Verificar apenas se llena, sin botón «Continuar». | propuesta, falta aprobación |
+
+## 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) queda para
+360 px o un código dentro de una tarjeta.
+
+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 |
+
+| uso | mobile (390) | web | fuente |
+|---|---|---|---|
+| código de 6 dígitos | `medium` | `large` | propuesta, falta aprobación |
+| código de 4 dígitos | `large` (344 px, entra) | `large` | propuesta, falta aprobación |
+
+```html
+<sui-otp-input [length]="6" [size]="bp.isMobile() ? 'medium' : 'large'" [(value)]="codigo" />
+<!-- bp = BreakpointsService -->
+```
+
+## «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 | pantallas de 360 px o un código dentro de una tarjeta |
+
+## API
+
+<!-- api:inicio -->
+<!-- generada: no editar a mano — `npm run docs` -->
+
+| input | tipo | default |
+|---|---|---|
+| `length` | `number` | `6` |
+| `size` | `'large' \| 'medium' \| 'small'` | `'large'` |
+| `type` | `'number' \| 'text'` | `'number'` |
+| `disabled` · model, `[(disabled)]` | `boolean` | `false` |
+| `error` | `boolean` | `false` |
+| `ariaLabel` | `string` | `'Código de verificación'` |
+| `value` · model, `[(value)]` | `string` | `''` |
+
+| output | payload |
+|---|---|
+| `completed` | `string` |
+<!-- api: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.
+
+## Ejemplo
+
+```html
+<sui-otp-input [length]="4" ariaLabel="Código de entrega" [error]="codigoMalo()"
+               [(value)]="codigo" (completed)="verificar($event)" />
+```

package/docs/sui-pagination/README.md

@@ -0,0 +1,146 @@
+---
+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
+
+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 y equipo).
+- **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 3 listas largas de la app (`pages/products/products.html:242`, `pages/customers/customers.html:161`,
+> `pages/settings/team/team.ts:347`) usan scroll infinito.
+
+### `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 es propuesta |
+| `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 es propuesta |
+| `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, debajo de una tabla. | extensión de SUI (la guía tiene un tamaño); el cuándo es propuesta |
+| `small` | celdas de 28 px | Web, en una tabla dentro de un modal o panel angosto. | propuesta, falta aprobación |
+
+### 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. | propuesta, falta aprobación |
+| `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 es propuesta |
+| `siblingCount` | `1` (default) | Siempre. Más números a cada lado ensanchan sin ayudar. | propuesta, falta aprobación |
+| `showInfo` | `true` (default) | Con `infoFormat="items"`: «Mostrando 11-20 de 134». | propuesta, falta aprobación |
+| `infoFormat` | `'items'` (default) | El único en español. | 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. | propuesta, falta aprobación |
+| `pageSizeOptions` | `[]` (default) | Lo normal: sin selector de filas por página. | propuesta, falta aprobación |
+| `pageSizeOptions` | `[10, 25, 50]` | Las opciones dicen «10 / página» (en español desde 03-10-2026). | propuesta, falta aprobación |
+
+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) | propuesta, falta aprobación |
+| tabla en un panel angosto | no se usa | `small` (28) | propuesta, falta aprobación |
+
+```html
+@if (!bp.isMobile()) {
+  <sui-pagination [total]="filas().length" [(currentPage)]="pagina" [pageSize]="25" />
+}
+```
+
+## «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"` | sale en inglés | cuando el DS lo traduzca («Página 2 de 14») |
+| `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` -->
+
+| input | tipo | default |
+|---|---|---|
+| `total` | `number` | — (requerido) |
+| `pageSize` · model, `[(pageSize)]` | `number` | `10` |
+| `siblingCount` | `number` | `1` |
+| `showInfo` | `boolean` | `true` |
+| `size` | `'small' \| 'medium'` | `'medium'` |
+| `type` | `'basic' \| 'full-radius' \| 'group'` | `'basic'` |
+| `firstLast` | `boolean` | `false` |
+| `nextPrevious` | `boolean` | `true` |
+| `infoFormat` | `'items' \| 'pages'` | `'items'` |
+| `pageSizeOptions` | `readonly number[]` | `[]` |
+| `currentPage` · model, `[(currentPage)]` | `number` | `1` |
+
+| output | payload |
+|---|---|
+| `pageChange` | `number` |
+| `pageSizeChange` | `number` |
+<!-- api: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)]` 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.
+
+## Ejemplo
+
+```html
+<sui-pagination [total]="134" [pageSize]="10" [(currentPage)]="pagina" type="group" />
+```