@ajuarezso/sui-design-system 0.19.0 → 0.21.0

package/docs/sui-switch-label/README.md

@@ -0,0 +1,139 @@
+---
+name: sui-switch-label
+selector: sui-switch-label
+resumen: Interruptor con su texto (y opcionalmente descripción, badge y link) para un ajuste que se aplica al instante
+alternativas: [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-switch-label
+
+Story: [Atoms/Checkbox, Radio & Switch/Switch Label](https://sui-design-system.web.app/?path=/docs/atoms-checkbox-radio-switch-switch-label--docs)
+
+## Cuándo usarlo / cuándo no
+
+**Úsalo** para cada fila de ajustes que se prende o se apaga: «Disponible para pedir», «Recibir
+pedidos», «Un uso por cliente», «Permitir analítica de uso». Es el default de una lista de
+ajustes: toda la fila se toca y el texto queda alineado con el interruptor.
+
+**No lo uses** para:
+
+- Un ajuste que merece tarjeta (borde, ícono, más contexto): `sui-switch-card`.
+- Una integración con logo y botón de administrar: `sui-integration-switch`.
+- Algo que se confirma después con «Guardar» y no tiene efecto propio: `sui-checkbox-label`.
+- Algo destructivo o que no se deshace.
+
+Regla corta: **ajuste con texto → este · ajuste con peso → switch-card · sin texto → sui-switch.**
+
+## Qué variante usar
+
+> **La guía del DS dice para qué es el switch** («prender o apagar un ajuste de forma inmediata»)
+> y su ejemplo avanzado arma Label + (Sublabel) + badge «NEW» + descripción + Link Button, con el
+> interruptor a la izquierda o a la derecha. No dice cuándo va cada lado.
+>
+> Uso medido el 03-10-2026 en `master-pedidos/src/app` (misma exclusión que `sui-badge`):
+> **5 usos en 4 archivos**, todos con `description`. Desde el 03-10-2026, 3 con `flip` (los
+> ajustes del producto en `add-product-modal` y la analítica de `privacidad`) y 2 sin él porque
+> viven dentro de un formulario (el horario de una categoría en `products`, «Cerrar por hoy» en
+> `central-inicio`). Tamaños: 2 `ctrlSize()`
+> (`large`/`xlarge`), 1 `xlarge` fijo, 2 sin `size` (`medium`). Hay **19 `sui-switch` con el texto
+> armado a mano** y 1 nativo que deberían ser este componente.
+
+### Las piezas
+
+| prop | cuándo | fuente |
+|---|---|---|
+| `label` | Siempre. Qué hace prenderlo, sin cambiar con el estado: «Recibir pedidos», no «Abierto/Cerrado». | según la guía del DS (pieza); la regla de qué dice es propuesta (precedente en `pages/schedule/schedule.html:31`) |
+| `description` | Cuando conviene decir la consecuencia: «Los clientes pueden agregarlo al carrito. Apágalo si se te acabó.» Es lo que ya hacen los 5 usos. | según la guía del DS (pieza); el «cuándo» ya es práctica de la app |
+| `sublabel` | Precisión corta entre paréntesis: «(beta)». | según la guía del DS |
+| `badge` | Solo novedad. Con string sale naranja `light`: pasa el objeto. | según la guía del DS (pieza «NEW»); el color es propuesta |
+| `link` | «Saber más» que no toca el interruptor. Solo se ve con `description`. | según la guía del DS |
+| `flip` | Interruptor a la **derecha** en listas de ajustes: el texto se lee primero y el control queda bajo el pulgar, como en iOS y Android (es lo que hacen a mano `drivers.html:58`, `discounts.html:198`, `schedule.html:46`). Sin `flip` (izquierda) dentro de un formulario, alineado con las casillas o los switches del resto del form. | canon (aprobado por el dueño, 03-10-2026) |
+| `disabled` | Mientras se guarda el cambio o cuando no aplica. | según la guía del DS |
+
+### `size`
+
+| size | cuándo | fuente |
+|---|---|---|
+| `xlarge` | Mobile, vía `bp.controlSize()`; y cuando el ajuste es la acción principal de la pantalla («Cerrar por hoy» en Central). | canon (aprobado por el dueño, 28-09-2026: «componentes grandes») |
+| `large` | Desktop, vía `bp.controlSize()`. | canon (aprobado por el dueño, 28-09-2026) |
+| `medium` (default) | No usar en pantallas nuevas. | canon (aprobado por el dueño, 28-09-2026) |
+
+**Usos de hoy que rompen las reglas:**
+
+- **2 en `medium`:** `pages/products/products.html:300` («Horario propio
+  para esta categoría») y `pages/public/privacidad/privacidad.html:132` («Permitir analítica de uso»).
+- **19 `sui-switch` con texto a mano + 1 nativo** que deberían ser este componente: el detalle
+  está en el README de `sui-switch`. Ejemplos: `pages/discounts/discounts.html:198`,
+  `pages/drivers/drivers.html:58`, `components/settings-panel/settings-panel.html:97`.
+
+## Tamaño en mobile y en web
+
+| uso | mobile | web |
+|---|---|---|
+| fila de ajustes | `xlarge` (48 × 28) | `large` (40 × 24) |
+| ajuste que es la acción principal de la pantalla («Cerrar por hoy») | `xlarge` | `xlarge` |
+
+```html
+<sui-switch-label [size]="bp.controlSize()" … />   <!-- isMobile() ? 'xlarge' : 'large' -->
+```
+
+El bloque entero se toca, así que con descripción la fila pasa los 44 px sola. Sin descripción,
+dale a la fila un alto mínimo de 44 px.
+
+## «No usar»: por qué no hoy y cuándo sí
+
+| qué | por qué no hoy | cuándo sí, en un flujo nuevo |
+|---|---|---|
+| `badge` (0 usos) | ningún ajuste es nuevo | un ajuste recién agregado en una pantalla que el usuario ya conoce |
+| `link` (0 usos) | ningún ajuste necesita más detalle | «Permitir analítica de uso» con «Qué se mide» (con `description`) |
+| `size="medium"` | se pierde en el teléfono | una tabla densa solo de desktop |
+
+## API
+
+<!-- api:inicio -->
+<!-- generada: no editar a mano — `npm run docs` -->
+
+| input | tipo | default |
+|---|---|---|
+| `label` | `string` | `''` |
+| `sublabel` | `string \| null` | `null` |
+| `description` | `string \| null` | `null` |
+| `size` | `'medium' \| 'large' \| 'xlarge'` | `'medium'` |
+| `badge` | `SuiBadgeConfig \| string \| null` | `null` |
+| `link` | `SuiLinkConfig \| string \| null` | `null` |
+| `flip` | `boolean` | `false` |
+| `disabled` | `boolean` | `false` |
+| `active` | `boolean` | `false` |
+
+| output | payload |
+|---|---|
+| `activeChange` | `boolean` |
+| `linkClick` | `MouseEvent` |
+<!-- api:fin -->
+
+Implementa `ControlValueAccessor` (`[(ngModel)]`, `formControlName`).
+
+## Trampas
+
+- **El estado se llama `active` / `activeChange`**, no `checked` como en `sui-switch`.
+- **Es controlado**, como `sui-switch`: sin `[(active)]` o `(activeChange)` el toque no se ve.
+- **El host es `inline-flex`.** Con `flip`, para que el interruptor quede pegado al borde derecho
+  de la fila, dale `display: flex` (o `width: 100%`) desde afuera.
+- **`link` solo se dibuja con `description`.**
+- `description` sube el label a peso medio y abre el bloque en columna.
+- Deshabilitado baja todo el bloque a 0.5 de opacidad **además** del gris propio del switch.
+- El badge con string sale naranja; en `sui-switch-card` el default es azul.
+- `flip` usa CSS `order`: el orden de lectura no cambia.
+
+## Ejemplo
+
+```html
+<sui-switch-label
+  [size]="bp.controlSize()"
+  [flip]="true"
+  label="Recibir pedidos"
+  description="Desactívalo para cerrar un rato sin tocar el horario."
+  [active]="abierto()"
+  [disabled]="guardando()"
+  (activeChange)="cambiarAbierto($event)" />
+```

package/docs/sui-tab-chips/README.md

@@ -0,0 +1,185 @@
+---
+name: sui-tab-chips
+selector: sui-tab-chips
+resumen: Fila de chips que se desliza en horizontal para filtrar una lista o saltar entre categorías; siempre hay uno elegido
+alternativas: [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-chips
+
+Story: [Molecules/Tabs/Tab Chips](https://sui-design-system.web.app/?path=/docs/molecules-tabs-tab-chips--docs)
+
+## Cuándo usarlo / cuándo no
+
+**Úsalo** para:
+
+- **Filtrar una lista** por estado, período, rol o zona: «Todos · Activos · Entregados · Cancelados»,
+  «Hoy · 7 días · 30 días», los meses de la central.
+- **Saltar entre categorías** de un catálogo que viene de la base («Hamburguesas · Pizzas ·
+  Bebidas»), con `sticky` en la carta del local.
+
+Sirve cuando las opciones son muchas, cambian según los datos o no caben y tienen que deslizarse.
+
+**No lo uses** para:
+
+- **2 a 4 modos de la misma vista** (por semana / día vs día): `sui-segmented-control`.
+- **Secciones de contenido distinto** (Ventas · Productos · Repartidores): `sui-tab-menu-horizontal`.
+- **Elegir un valor que se guarda** con un botón (radio de visibilidad, motivo de rechazo,
+  sumar o descontar): `sui-radio-card` o `sui-segmented-control`. El tab-chips **siempre tiene uno
+  elegido** y no puede quedar vacío (ver Trampas).
+- Un chip que la persona quita: `sui-tag`.
+
+Regla corta (la misma del README de `sui-segmented-control`, 03-10-2026): **2-4 modos de la misma
+vista → segmented · secciones → tab menu · filtros o categorías → tab-chips.**
+
+## Qué variante usar
+
+> **La guía del DS no tiene este componente**: es una extensión de SUI (la «cat nav» de las apps de
+> delivery). Todo lo que sigue es propuesta salvo lo marcado como canon.
+>
+> Uso medido el 03-10-2026 en `master-pedidos/src/app` (sin `master-preview`, `master-prototipos`,
+> `mockup-*`, `dx/*`, `_guia-*`, `master-rutina`, `master-medico`, `master-ejercicios`):
+> **41 usos en 28 archivos `.html`**. `[sticky]="true"`: 1 (carta del local). `count`: 5 listas.
+> `[(value)]`: 2; el resto `[value]` + `(valueChange)`. `autoScroll`: 0. `size`: 0 (no existe en
+> la versión publicada).
+
+### Para qué se usa (el contenido de los chips)
+
+| caso | cuándo | ejemplo real de la app | fuente |
+|---|---|---|---|
+| filtro de estado | La lista es la misma; los chips la recortan. «Todos» va primero y es el elegido por defecto. | `pages/envios/envios.html:98` («Todos · Activos · Entregados · Cancelados») · `pages/orders/orders.html:64` | propuesta, falta aprobación |
+| filtro de período | Rango de fechas de un reporte o gráfico. | `pages/super-admin/master-earnings/master-earnings.html:11` · `pages/central/central-gastos/central-gastos.html:10` (meses) | propuesta, falta aprobación |
+| categorías del catálogo | Saltar a una categoría de la carta; con `sticky` y `autoScroll`. | `pages/customer/restaurant-menu/restaurant-menu.html:226` | propuesta, falta aprobación |
+| sugerencias rápidas | **No.** Un motivo frecuente que completa un texto no es una selección: el chip elige el primero solo. Si se usa, el primer chip es el neutro («Otro motivo») y el texto lleva su propio signal. | `pages/super-admin/master-orders/master-orders.html:898` (bien resuelto) | propuesta, falta aprobación |
+
+### `sticky`
+
+| valor | cuándo | fuente |
+|---|---|---|
+| `false` (default) | Filtros arriba de una lista corta o dentro de un modal o sheet. | propuesta, falta aprobación |
+| `true` | Solo la navegación de categorías de una lista larga que scrollea (la carta). Se pega arriba del contenedor de scroll y, pegado, pinta fondo `bg-weak-50`. | propuesta, falta aprobación |
+
+### `autoScroll`
+
+| valor | cuándo | fuente |
+|---|---|---|
+| `true` (default) | Siempre: centra el chip elegido cuando cambia `value` (también si lo cambia el scroll de la carta). | propuesta, falta aprobación |
+| `false` | Solo si el `value` cambia muy seguido por código y el movimiento distrae. Hoy ningún caso. | propuesta, falta aprobación |
+
+### Ítems (`chips`)
+
+| qué | cuándo | fuente |
+|---|---|---|
+| `string[]` | Cuando el texto es el valor (meses, provincias). | propuesta, falta aprobación |
+| `{ value, label }` | Cuando el valor es un id o una clave en inglés (`'active'` → «Activos»). | propuesta, falta aprobación |
+| `count` | El número de ítems detrás del filtro, cuando ayuda a decidir («Recargas 3»). `0` o `undefined` no se dibuja. **El número va en `count`, no dentro del `label`.** | propuesta, falta aprobación |
+| texto | Una o dos palabras, sentence case, sin punto. Plural si filtra («Activos»). | canon (copy de `docs/CANON-SUI.md`) |
+
+**Usos de hoy que rompen las reglas:**
+
+- **3 con un bug real: el motivo escrito a mano rebota al primer chip.** En los modales de rechazo
+  del super admin, los chips y el textarea comparten el mismo signal. Cada tecla deja un texto que
+  no es ningún chip; el componente vuelve al primero y lo emite, así que el textarea se reescribe con
+  «El comprobante no se lee». No se puede escribir un motivo propio, y al abrir el modal ya hay un
+  motivo elegido sin que nadie lo toque. `pages/super-admin/master-drivers/master-drivers.html:652`,
+  `:924` y `:1002`. Es el mismo bug que se arregló en `master-orders` el 01-09-2026 (signal propio
+  para los chips y «Otro motivo» primero).
+- **4 son secciones de contenido distinto** (→ `sui-tab-menu-horizontal` en web; en mobile, a
+  discutir porque el tab menu no se desliza, ver su README): `pages/products/products.html:6`
+  («Categorías · Productos · Secciones reutilizables»), `pages/promociones/promociones.html:7`
+  («Carrusel pagado · Push notifications»), `pages/super-admin/master-drivers/master-drivers.html:16`,
+  `pages/reports/reports.html:98` («Ventas · Productos · Repartidores · Clientes»).
+- **2 son modos de la misma vista** (→ `sui-segmented-control`):
+  `pages/super-admin/master-semanas/master-semanas.html:67` (3 métricas del mismo gráfico) y `:72`
+  («Por semana · Día vs día»).
+- **4 eligen un valor de un formulario** (→ `sui-radio-card` o `sui-segmented-control`):
+  `components/option-sections-manager/option-sections-manager.html:175` (a qué se aplica),
+  `pages/super-admin/master-drivers/master-drivers.html:98` («Sumar · Descontar»),
+  `pages/mi-negocio/mi-negocio.html:938` (radio de visibilidad) y `:973` (tiempo para confirmar).
+  A discutir: `pages/customer/checkout/checkout.html:468` (día del pedido programado), que filtra
+  las franjas de abajo y se parece más a un filtro.
+- **1 con el número dentro del texto:** `pages/notifications/notifications.ts:191`
+  (`No leídas (3)` → `count: 3`).
+- **41 sin tamaño por plataforma** (el input todavía no está publicado): cuando se publique, los de
+  pantallas del cliente y del repartidor pasan a `large`.
+
+## Tamaño en mobile y en web
+
+> `size` está **en el repo del DS (03-10-2026) y no en la versión publicada 0.19.0**. Hasta que se
+> publique, todos miden lo de `medium`.
+
+Alto del chip: `small` 32 px · `medium` 36 px (el de siempre, default) · `large` 40 px. Los tres
+con texto de 14 px; cambia el alto y el aire lateral. El scroller suma 12 px arriba y abajo.
+
+| uso | mobile | web | fuente |
+|---|---|---|---|
+| filtros y categorías | `large` (40; con el aire del scroller llega a 44+ de área táctil) | `medium` | canon (dueño: tamaño por plataforma, 03-10-2026) |
+| filtros densos en la cabecera de una tabla | — | `small` | propuesta, falta aprobación |
+
+```html
+<sui-tab-chips [chips]="filtros" [(value)]="filtro" [size]="bp.isMobile() ? 'large' : 'medium'" />
+```
+
+## «No usar»: por qué no hoy y cuándo sí
+
+| qué | por qué no hoy | cuándo sí, en un flujo nuevo |
+|---|---|---|
+| `autoScroll` en `false` | ningún caso cambia el valor tan seguido como para que moleste | una vista que sincroniza el chip con un scroll muy rápido y el movimiento distrae |
+| `sticky` fuera de la carta | en una lista corta tapa contenido sin ayudar | otra lista larga por categorías (un catálogo de bodega con muchas secciones) |
+| `small` en mobile | 32 px no llega al dedo | nunca en mobile |
+
+## API
+
+<!-- api:inicio -->
+<!-- generada: no editar a mano — `npm run docs` -->
+
+| input | tipo | default |
+|---|---|---|
+| `chips` | `readonly (string \| SuiTabChipItem)[]` | — (requerido) |
+| `value` · model, `[(value)]` | `string` | `''` |
+| `sticky` | `boolean` | `false` |
+| `size` | `'small' \| 'medium' \| 'large'` | `'medium'` |
+| `autoScroll` | `boolean` | `true` |
+
+Outputs: ninguno.
+<!-- api:fin -->
+
+```ts
+interface SuiTabChipItem {
+  value: string;
+  label: string;
+  count?: number;   // 0 o undefined no se dibuja
+}
+type SuiTabChipsSize = 'small' | 'medium' | 'large';   // repo del DS, no en 0.19.0
+```
+
+## Trampas
+
+- **Siempre hay uno elegido.** Si `value` está vacío o no coincide con ningún chip, el componente
+  elige el **primero y lo emite** por `valueChange`. No existe «ninguno». Si el valor también lo
+  escribe otro control (un textarea), cada tecla rebota al primer chip: usa un signal propio para
+  los chips.
+- **`value` es `string`.** Para números (km, minutos) hay que convertir en los dos sentidos
+  (`radioEfectivo() + ''` y `+$event`).
+- **Lleva `role="tablist"`** aunque se use como filtro: el lector de pantalla lo anuncia como pestañas.
+- **No tiene padding lateral propio**: lo pone la pantalla. Sí trae 12 px arriba y abajo.
+- **`sticky` cambia el host a `display: contents`**: las clases que le pongas al host dejan de
+  pintar caja (márgenes, anchos). Pon el estilo en un contenedor.
+- **Pegado, el fondo es `bg-weak-50`**: sobre una página blanca se nota la franja gris.
+  Con `sticky` el sentinel agrega 16 px arriba.
+- **`count` en 0 no se dibuja**: no sirve para decir «0 pendientes».
+- **El chip activo es oscuro** (`bg-strong-950`), no naranja: es el estilo del componente, no se
+  cambia por pantalla.
+
+## Ejemplo
+
+```html
+<!-- Filtro de estado: «Todos» primero -->
+<sui-tab-chips
+  [chips]="[{ value: 'todos', label: 'Todos' }, { value: 'activos', label: 'Activos' },
+            { value: 'entregados', label: 'Entregados' }, { value: 'cancelados', label: 'Cancelados' }]"
+  [(value)]="filtro" />
+
+<!-- Categorías de la carta -->
+<sui-tab-chips [chips]="categorias()" [value]="categoria()" (valueChange)="irA($event)" [sticky]="true" />
+```

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

@@ -0,0 +1,142 @@
+---
+name: sui-tab-menu-horizontal
+selector: sui-tab-menu-horizontal
+resumen: Pestañas subrayadas para cambiar entre secciones de contenido distinto dentro de una pantalla
+alternativas: [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-horizontal
+
+Story: [Molecules/Tabs/Tab Menu Horizontal](https://sui-design-system.web.app/?path=/docs/molecules-tabs-tab-menu-horizontal--docs)
+
+## Cuándo usarlo / cuándo no
+
+**Úsalo** para cambiar entre **secciones de contenido distinto** de la misma pantalla o detalle:
+«Opiniones · Información» en el modal del local, «Ventas · Productos · Repartidores · Clientes» en
+reportes. Cada pestaña muestra otra cosa, no la misma lista recortada.
+
+**No lo uses** para:
+
+- **Filtrar una lista** o saltar entre categorías: `sui-tab-chips`.
+- **2 a 4 modos de la misma vista** (cuadrícula o lista): `sui-segmented-control`.
+- **Secciones que no entran a lo ancho en mobile** (4 con nombres largos o con `number`, o 5+): el
+  componente no se desliza y las pestañas se salen de la pantalla (ver Trampas). Ahí, por ahora,
+  `sui-tab-chips`.
+- Un menú lateral de ajustes en web: `sui-tab-menu-vertical`.
+
+Regla corta (README de `sui-segmented-control`, 03-10-2026): **2-4 modos de la misma vista →
+segmented · secciones → tab menu · filtros → tab-chips.**
+
+## Qué variante usar
+
+> **Lo que dice la guía del DS**: es un layout lineal para **cambiar entre secciones o categorías**.
+> Muestra un ejemplo con pestañas que **desbordan y se deslizan**, y su pestaña mide 48 px de alto
+> (toda la franja es tocable). No trae do/don't ni tamaños.
+>
+> Uso medido el 03-10-2026 en `master-pedidos/src/app` (misma exclusión que `sui-badge`):
+> **1 uso**: `components/store-ratings-modal/store-ratings-modal.html:43` («Opiniones ·
+> Información»), sin `size`, sin ícono, sin `number`.
+
+### Ítems (`tabs`)
+
+| qué | cuándo | fuente |
+|---|---|---|
+| texto | Lo normal: el nombre de la sección, una o dos palabras. | según la guía del DS (ejemplos con texto) |
+| `icon` | Solo si **todas** las pestañas llevan ícono y ayuda a reconocerlas. Nunca en una sola. | propuesta, falta aprobación |
+| `number` | Pendientes **que piden acción** dentro de esa sección («Solicitudes 3»). Es un círculo rojo: no lo uses para totales neutros. | propuesta, falta aprobación |
+| `rightIcon` | No: la flecha dice «te lleva a otra pantalla» y una pestaña no navega. | propuesta, falta aprobación |
+| `disabled` | Una sección que existe pero no aplica todavía (depende del plan). | propuesta, falta aprobación |
+
+### `size`
+
+| size | cuándo | fuente |
+|---|---|---|
+| `medium` (default) | El único que cambia algo: **ninguno**. El input existe pero no tiene estilos; los cuatro valores se ven igual. No lo pases. | según el código (`sui-tab-menu-horizontal.scss`: no hay reglas por tamaño) |
+| `small` · `large` · `xlarge` | No usar: no hacen nada. | según el código |
+
+**Usos de hoy que rompen las reglas:**
+
+- **0** en este componente. Los casos que deberían ser tab menu y hoy son `sui-tab-chips` están en el
+  README de `sui-tab-chips` (4: `pages/products/products.html:6`, `pages/promociones/promociones.html:7`,
+  `pages/super-admin/master-drivers/master-drivers.html:16`, `pages/reports/reports.html:98`).
+- **A verificar en mobile:** el uso actual es del modal del local, que el cliente abre en el
+  teléfono. La pestaña mide 20 px de alto tocable (ver Tamaño).
+
+## Tamaño en mobile y en web
+
+Cada pestaña ocupa **todo el alto de la franja**, así que lo tocable es la franja entera (desde
+03-10-2026; antes eran solo los 20 px del texto). El `size` cambia ese alto y el texto:
+
+| size | franja tocable (+ 2 de bordes) | texto | ícono | gap | fuente |
+|---|---|---|---|---|---|
+| `small` | 40 | `label-sm` 14/20 | 20 | 20 | canon (aprobado por el dueño, 03-10-2026): extensión SUI |
+| `medium` (default) | 48 | `label-sm` 14/20 | 20 | 24 | Figma |
+| `large` | 52 | `label-md` 16/24 | 20 | 24 | canon (aprobado por el dueño, 03-10-2026): extensión SUI |
+| `xlarge` | 56 | `label-md` 16/24 | 24 | 28 | canon (aprobado por el dueño, 03-10-2026): extensión SUI |
+
+| uso | mobile | web | fuente |
+|---|---|---|---|
+| 2-3 secciones | `large` (52, texto 16) | `medium` (48) | propuesta: el tamaño es extensión SUI aprobada (03-10-2026); el «cuándo» falta aprobarlo |
+| 4+ secciones | si no entran a 390 px, se salen sin poder deslizarse (las 4 del panel de repartidores, con sus números, ya no entran a 360): va `sui-tab-chips` | el mismo | según el código |
+
+```html
+<sui-tab-menu-horizontal [tabs]="secciones" [(active)]="seccion" [size]="bp.isMobile() ? 'large' : 'medium'" />
+```
+
+## «No usar»: por qué no hoy y cuándo sí
+
+| qué | por qué no hoy | cuándo sí, en un flujo nuevo |
+|---|---|---|
+| `rightIcon` | una pestaña no lleva a otra pantalla | nunca en pestañas; es del tab menu vertical cuando cada ítem abre una página |
+| `icon` | ningún caso de hoy lo necesita | secciones con ícono reconocible en las tres (Mapa · Lista · Fotos) en web |
+| `number` | ninguna sección del único uso tiene pendientes | «Solicitudes» o «Recargas» del panel de repartidores, si se pasa a tab menu |
+| `disabled` | ninguna sección bloqueada | una sección que depende del plan («Reportes» en plan básico) |
+
+## API
+
+<!-- api:inicio -->
+<!-- generada: no editar a mano — `npm run docs` -->
+
+| input | tipo | default |
+|---|---|---|
+| `tabs` | `SuiTabMenuHorizontalItem<T>[]` | — (requerido) |
+| `active` · model, `[(active)]` | `T` | `undefined` |
+| `size` | `'small' \| 'medium' \| 'large' \| 'xlarge'` | `'medium'` |
+
+| output | payload |
+|---|---|
+| `tabChange` | `T` |
+<!-- api:fin -->
+
+```ts
+interface SuiTabMenuHorizontalItem<T = string> {
+  value: T;
+  label: string;
+  icon?: string;        // RemixIcon, 20 px
+  rightIcon?: boolean;  // flecha en píldora
+  number?: number;      // círculo rojo; 0/undefined no se dibuja
+  disabled?: boolean;
+}
+```
+
+## Trampas
+
+- **Sin `active` no se marca ninguna pestaña.** Pásale siempre un valor inicial.
+- **No se desliza.** El track no tiene `overflow-x`: con muchas pestañas en un ancho chico se salen
+  del contenedor. La guía del DS sí lo resuelve; SUI todavía no.
+- **El área tocable es toda la franja** (40–56 según `size`), desde 03-10-2026: el aire de 14 px
+  que Figma pone en el contenedor ahora va dentro de cada pestaña. Si algo de afuera le pone
+  padding al `.sui-tab-menu-horizontal__track`, la franja crece al doble.
+- **Emite dos veces**: `tabChange` y `activeChange`. Con `[(active)]` no hace falta `(tabChange)`.
+- **Trae bordes arriba y abajo** (`stroke-soft-200`) y fondo blanco: no lo metas en una card que ya
+  tiene borde, o quedan dos líneas.
+- El ícono de la pestaña activa es `strong-950`, no naranja; en el tab menu vertical es naranja.
+  Es a propósito.
+
+## Ejemplo
+
+```html
+<sui-tab-menu-horizontal
+  [tabs]="[{ value: 'opiniones', label: 'Opiniones' }, { value: 'info', label: 'Información' }]"
+  [(active)]="tab" />
+```

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

@@ -0,0 +1,136 @@
+---
+name: sui-tab-menu-vertical
+selector: sui-tab-menu-vertical
+resumen: Menú apilado para cambiar entre secciones de una página de ajustes en web
+alternativas: [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-tab-menu-vertical
+
+Story: [Molecules/Tabs/Tab Menu Vertical](https://sui-design-system.web.app/?path=/docs/molecules-tabs-tab-menu-vertical--docs)
+
+## Cuándo usarlo / cuándo no
+
+**Úsalo** en **web** para una página con varias secciones que se leen de a una, con el menú a la
+izquierda y el contenido a la derecha: los ajustes del local («Datos del local · Horario · Métodos
+de pago · Repartidores»), el perfil del super admin.
+
+**No lo uses** para:
+
+- **Mobile**: el ítem mide 36 px y ocupa el ancho de la pantalla dejando el contenido debajo. En
+  mobile cada sección es una fila de una lista que abre su propia pantalla.
+- La navegación de toda la app: `sui-sidebar`.
+- 2 a 4 secciones arriba del contenido: `sui-tab-menu-horizontal`.
+- Filtros de una lista: `sui-tab-chips`.
+
+Regla corta: **secciones de una página de ajustes en web → tab menu vertical · en mobile → lista de
+filas que abren pantalla.**
+
+## Qué variante usar
+
+> **Lo que dice la guía del DS**: es un layout apilado para **cambiar entre secciones o categorías**.
+> Sus ejemplos son ajustes («Profile Settings · Contact Information · Social Links · Export Data»),
+> uno con **título arriba** (en SUI, `dividerLabel`) y otro con **contenedor con estilo** (en SUI,
+> `menuStyle="card"`). No trae do/don't.
+>
+> Uso medido el 03-10-2026 en `master-pedidos/src/app` (misma exclusión que `sui-badge`): **0 usos**.
+
+### `menuStyle`
+
+| valor | cuándo | fuente |
+|---|---|---|
+| `card` | El menú flota junto al contenido sobre un fondo gris (`bg-weak-50`): el borde y la sombra lo separan. | según la guía del DS (ejemplo «contenedor con estilo»); el cuándo es propuesta |
+| `list` | El menú vive dentro de una columna que ya tiene fondo o borde propio (una card, un panel). | según la guía del DS (ejemplo base); el cuándo es propuesta |
+
+### `dividerLabel`
+
+| valor | cuándo | fuente |
+|---|---|---|
+| vacío (default) | Un solo grupo de secciones. | propuesta, falta aprobación |
+| texto | Nombra el grupo cuando hay más de un menú apilado («Tu local» · «Tu cuenta»). Sale en MAYÚSCULAS y gris. | según la guía del DS (ejemplo con título) |
+
+### Ítems (`tabs`)
+
+| qué | cuándo | fuente |
+|---|---|---|
+| texto | El nombre de la sección. Una o dos palabras; si es más largo, se corta con «…». | según la guía del DS (ejemplos con texto) |
+| `icon` | Sí, en todos los ítems: en un menú lateral el ícono ayuda a encontrar rápido. El activo se pinta naranja. | propuesta, falta aprobación |
+| `number` | Pendientes que piden acción en esa sección (círculo rojo). | propuesta, falta aprobación |
+| `rightIcon` | Cuando el ítem lleva a otra página en vez de cambiar el panel de al lado. | propuesta, falta aprobación |
+| `disabled` | Una sección que depende del plan. | propuesta, falta aprobación |
+
+Usos de hoy que rompen las reglas: **0** (no se usa).
+
+## Tamaño en mobile y en web
+
+Ítem de **36 px** (8 + 20 + 8), ícono de 20. **No tiene `size`** y no tiene tamaño para mobile.
+
+| uso | mobile | web | fuente |
+|---|---|---|---|
+| secciones de ajustes | no se usa: lista de filas que abren pantalla | `tab-menu-vertical` | propuesta, falta aprobación |
+
+```html
+@if (!bp.isMobile()) {
+  <sui-tab-menu-vertical [tabs]="secciones" [(active)]="seccion" menuStyle="card" />
+}
+```
+
+## «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 | ninguna pantalla de la app tiene hoy un menú lateral de secciones | una página de ajustes en web con 5+ secciones (ajustes del local en desktop) |
+| en mobile | 36 px y sin lugar para el contenido al lado | nunca |
+| `rightIcon` | ningún menú mezcla paneles y páginas | un ítem «Facturación» que sale a otra página mientras el resto cambia el panel |
+
+## API
+
+<!-- api:inicio -->
+<!-- generada: no editar a mano — `npm run docs` -->
+
+| input | tipo | default |
+|---|---|---|
+| `tabs` | `SuiTabMenuVerticalItem<T>[]` | — (requerido) |
+| `active` · model, `[(active)]` | `T` | `undefined` |
+| `menuStyle` | `'card' \| 'list'` | `'card'` |
+| `dividerLabel` | `string` | `''` |
+
+| output | payload |
+|---|---|
+| `tabChange` | `T` |
+<!-- api:fin -->
+
+```ts
+interface SuiTabMenuVerticalItem<T = string> {
+  value: T;
+  label: string;
+  icon?: string;        // RemixIcon, 20 px
+  rightIcon?: boolean;  // flecha en píldora con sombra
+  number?: number;      // círculo rojo; 0/undefined no se dibuja
+  disabled?: boolean;
+}
+type SuiTabMenuVerticalStyle = 'card' | 'list';
+```
+
+## Trampas
+
+- **El estilo se llama `menuStyle`**, no `style` ni `variant` (ni `verticalStyle`, que era el nombre
+  viejo de `sui-tabs`).
+- **Sin `active` no se marca ningún ítem.** Pásale un valor inicial.
+- **Ocupa el ancho del padre**: dale un ancho fijo a la columna (240-280 px).
+- **El ícono activo es naranja** (`primary-base`); en el tab menu horizontal es negro. Es a propósito.
+- **Emite dos veces**: `tabChange` y `activeChange`.
+- `role="tablist"`: si cada ítem navega a una ruta, el lector de pantalla lo anuncia mal; para
+  navegación entre rutas, `sui-sidebar`.
+
+## Ejemplo
+
+```html
+<sui-tab-menu-vertical
+  menuStyle="card"
+  dividerLabel="Tu local"
+  [tabs]="[{ value: 'datos', label: 'Datos del local', icon: 'store-2-line' },
+           { value: 'horario', label: 'Horario', icon: 'time-line' },
+           { value: 'pagos', label: 'Métodos de pago', icon: 'bank-card-line' }]"
+  [(active)]="seccion" />
+```