@ajuarezso/sui-design-system 0.21.0 → 0.22.0

package/docs/sui-modal-sheet/README.md

@@ -0,0 +1,170 @@
+---
+name: sui-modal-sheet
+selector: sui-modal-sheet
+resumen: Hoja que sube desde abajo, se arrastra entre alturas fijas y puede dejar usable lo de atrás (un mapa)
+alternativas: [sui-modal (pide terminar algo antes de seguir, sin fondo usable), sui-popover (contenido chico anclado a un botón), sui-dropdown-menu (lista de acciones)]
+---
+
+# sui-modal-sheet
+
+Story: [Organisms/Modal/Modal Sheet](https://sui-design-system.web.app/?path=/docs/organisms-modal-modal-sheet--docs)
+
+## Cuándo usarlo / cuándo no
+
+**Úsalo** cuando el contenido **convive con lo de atrás** o se mira a distintas alturas:
+
+- El panel del seguimiento sobre un mapa (pedido, envío, viaje): a 25 % se ve el mapa, a 100 %
+  el detalle. El mapa sigue respondiendo.
+- Una lista o un detalle que se abre desde abajo y se cierra deslizando (reseñas, movimientos
+  de la billetera, elegir la hora de entrega).
+
+**No lo uses** para:
+
+- Un formulario o una confirmación que hay que terminar: `sui-modal`. El sheet se cierra con un
+  deslizón y se pierde lo escrito.
+- Desktop como superficie principal: en una pantalla de 1440 px un sheet a todo el ancho se lee
+  como un error (ver tamaño). Si en desktop hay sitio, un panel lateral sirve mejor.
+
+## Qué variante usar
+
+> **No está en la guía del DS: es extensión de SUI**, inspirada en el `ion-modal` en modo sheet
+> de Ionic y en las hojas de Apple Maps. No hay Figma que la legisle. Lo marcado **canon** sale
+> de `master-pedidos/CLAUDE.md`; lo demás es **propuesta** sacada del uso real.
+>
+> Uso medido el 03-10-2026 en `master-pedidos/src/app`: 13 sheets, sin contar prototipos ni
+> vitrinas (`master-preview`, `master-prototipos`, `mockup-sheets-*`, `dx/*`, `master-rutina`,
+> `master-medico`, `dev-index`) ni las copias de `components/sui/`.
+
+### Lo que sí dice la guía del DS
+
+Nada: el sheet no está en la guía. Lo único que hereda del DS es el criterio del body (20 px) y
+el radio Android (`--sui-radius-20`).
+
+### Los dos patrones de la app
+
+El sheet no tiene variantes: se configura con tres números. En la app salen **dos recetas**, y
+conviene copiar una de las dos en vez de inventar otra.
+
+| patrón | `breakpoints` | `initialBreakpoint` | `backdropBreakpoint` | cuándo | ejemplo real de la app | fuente |
+|---|---|---|---|---|---|---|
+| **Sobre un mapa** | `[0.25, 0.5, 0.7, 1]` (sin `0`) | `0.5` | `1` | el seguimiento: el mapa se usa a cualquier altura y la hoja no se puede cerrar | `pages/customer/order-tracking/order-tracking.html:130` · `pages/driver/driver-order-detail/driver-order-detail.html:60` | propuesta |
+| **Hoja de lectura** | `[0, 0.92]` | `0.92` | `0` | una lista o detalle que se abre y se cierra deslizando, con el fondo apagado | `pages/customer/order-tracking/order-tracking.html:809` (reseñas) · `pages/customer/checkout/checkout.html:448` (hora) | propuesta |
+
+Hoy: 4 «sobre un mapa» (más 2 variantes con alturas propias: `pages/envios/envios.html:578` y
+`pages/customer/viaje/viaje.html:24`), 5 hojas de lectura en `0.92`–`0.96`, 2 en `[0, 1]` y 1 en
+`[0, 0.6, 0.95]`.
+
+| input | regla | fuente |
+|---|---|---|
+| `breakpoints` | Con `0` en la lista, la hoja **se cierra deslizando**. Sin `0`, no se cierra con el dedo (solo por código o backdrop). | componente |
+| `initialBreakpoint` | Tiene que estar en `breakpoints`. | componente |
+| `backdropBreakpoint` | `0` = fondo apagado desde que abre. `1` = **nunca hay backdrop**: el mapa de atrás se toca siempre. | componente |
+| tope en las hojas de lectura | `0.92`, no `1`: deja ver arriba un borde de la pantalla de atrás, que es lo que dice «esto es una hoja». | propuesta |
+| `showHandle` | Déjalo en `true` siempre que la hoja se arrastre. Hoy nadie lo apaga. | propuesta |
+| `fullBody` | Solo para contenido a sangre (una foto, un mapa dentro de la hoja). | canon (CLAUDE.md, 2026-07-21) |
+
+**Usos de hoy a revisar:**
+
+- `pages/customer/viaje/viaje.html:24` reabre la hoja en `(closed)` (`hojaAbierta.set(true)`)
+  para que no se pueda cerrar. Sin `0` en `breakpoints` y con `[closeOnBackdrop]="false"` ya no se
+  cierra; el reabrir sobra o tapa otro caso.
+- 2 footers de modal metidos en hojas: van sin `slot` (no hay slot de footer). Está bien, pero el
+  botón scrollea con el contenido: `pages/customer/checkout/checkout.html:490`,
+  `pages/super-admin/master-sonidos-push/master-sonidos-push.html:146`.
+
+## Tamaño en mobile y en web
+
+El sheet **no tiene `size`**. Mide lo que mide su contenido, con tope en el breakpoint más alto
+(y nunca más que la pantalla menos el safe-area de arriba y 16 px).
+
+| | mobile | web desktop | fuente |
+|---|---|---|---|
+| ancho | toda la pantalla menos 8 px a cada lado | **igual: todo el ancho menos 8 px** | componente |
+| esquinas | iOS 36 arriba / 54 abajo · Android 20 | igual | canon (CLAUDE.md, 2026-07-22) |
+| padding del body | `0 20px 20px` | igual | canon (CLAUDE.md, 2026-07-21) |
+| ancho en desktop | — | acotarlo a una columna centrada de 560 px | propuesta (hoy lo hace cada pantalla a mano) |
+
+**El sheet no se acota en desktop.** La app lo arregla con CSS propio, cinco reglas en cuatro archivos:
+`components/store-ratings-modal/store-ratings-modal.scss:81`,
+`pages/driver/movimientos/movimientos-sheet.scss:24`,
+`pages/driver/driver-order-detail/driver-order-detail.scss:1028` y
+`pages/customer/order-tracking/order-tracking.scss:1175` y `:1238`, todos a 560 px. Propuesta:
+que el DS traiga ese tope (`max-width` desde 768 px, centrado) y se borren esos parches.
+
+## API
+
+<!-- api:inicio -->
+<!-- generada: no editar a mano — `npm run docs` -->
+
+| input | tipo | default |
+|---|---|---|
+| `open` · model, `[(open)]` | `boolean` | `false` |
+| `breakpoints` | `number[]` | `[0, 1]` |
+| `initialBreakpoint` | `number` | `1` |
+| `backdropBreakpoint` | `number` | `0` |
+| `showHandle` | `boolean` | `true` |
+| `closeOnBackdrop` | `boolean` | `true` |
+| `closeOnEscape` | `boolean` | `true` |
+| `fullBody` | `boolean` | `false` |
+
+| output | payload |
+|---|---|
+| `closed` | `void` |
+| `breakpointChange` | `number` |
+<!-- api:fin -->
+
+Métodos públicos: `setCurrentBreakpoint(bp, animated = true)` (avisa por consola y no hace nada
+si `bp` no está en `breakpoints`) y `close()`.
+
+Signals públicas: `currentBreakpoint` y `progress` (cambian al soltar, no durante el arrastre) y
+`dragging`.
+
+Slot: un solo `<ng-content>`, el body. No hay header ni footer.
+
+## Trampas
+
+- **El padding del body es fuente única** (`0 20px 20px`). No le pongas padding lateral ni abajo
+  a tus secciones ni lo pises con `::ng-deep .sui-sheet__body`: el margen queda doble (pasó en el
+  tracking del repartidor: ~36 px a los lados y ~68 px bajo el último botón).
+- **Anidar radios**: el body ya cumple `exterior = interior + padding` (36 − 20 = 16, el radio de
+  `sui-card`). Una card adentro no necesita otro radio.
+- **`breakpointChange` y `progress` no cambian durante el arrastre**, solo al soltar. Si algo
+  tiene que seguir al dedo (el padding del mapa), usa `breakpointChange` y acepta el salto, o lee
+  la posición del panel.
+- **Arrastre y scroll**: en la altura máxima el body scrollea; desde arriba del todo, jalar hacia
+  abajo mueve la hoja. En alturas intermedias el body entero arrastra (`touch-action: none`): un
+  carrusel o un slider dentro puede pelear con el gesto. Los campos (`input`, `textarea`,
+  `select`) no arrancan arrastre; para otro control que necesita el dedo, ponle el atributo
+  `data-sui-no-sheet-drag` (o a un ancestro).
+- **Sin `0` en `breakpoints` no se cierra deslizando.** Si quieres que se cierre y no lo hace, es
+  eso.
+- **`closeOnBackdrop` solo actúa cuando hay backdrop** (altura actual por encima de
+  `backdropBreakpoint`). Con `backdropBreakpoint` en `1` nunca hay.
+- **El transform es tuyo, el movimiento no**: el sheet se mueve con la propiedad `translate` del
+  panel interno, así que puedes escribir `left` / `right` / `transform` sobre `.sui-sheet` (por
+  ejemplo para centrarlo en desktop) sin romper el arrastre.
+- Pide ocultar la barra inferior de la app por `SUI_NAVBAR_VISIBILITY`, igual que `sui-modal`.
+
+## Ejemplo
+
+```html
+<!-- Sobre un mapa: no se cierra, el mapa se usa siempre -->
+<sui-modal-sheet
+  [(open)]="hojaAbierta"
+  [breakpoints]="[0.25, 0.5, 0.7, 1]"
+  [initialBreakpoint]="0.5"
+  [backdropBreakpoint]="1"
+  (breakpointChange)="mapa.setSheetRatio($event)">
+  <h2>Tu pedido va en camino</h2>
+  …
+</sui-modal-sheet>
+
+<!-- Hoja de lectura: se cierra deslizando -->
+<sui-modal-sheet
+  [(open)]="resenasAbiertas"
+  [breakpoints]="[0, 0.92]"
+  [initialBreakpoint]="0.92"
+  [backdropBreakpoint]="0">
+  <app-ratings-detail … />
+</sui-modal-sheet>
+```

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

@@ -0,0 +1,123 @@
+---
+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
+
+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`;
+> lo demás es **propuesta**.
+>
+> Uso medido el 03-10-2026 en `master-pedidos/src/app`: 64 page headers, sin contar prototipos ni
+> vitrinas (`master-preview`, `master-prototipos`, `mockup-sheets-*`, `dx/*`, `master-rutina`,
+> `master-medico`, `dev-index`) ni las copias de `components/sui/`. 50 llevan `subtitle` fijo, 14
+> calculado; 17 tienen acciones; 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` | propuesta |
+| acciones | Las que valen para toda la pantalla: una `filled` como máximo (la principal) y el resto `stroke`. Hoy: 9 `filled`, 7 `stroke`. | `pages/drivers/drivers.html:2` | canon para «una principal» (CANON-SUI §6.2), propuesta el resto |
+
+**Usos de hoy que rompen el copy canon** (sentence case en botones): `pages/drivers/drivers.html:8`
+(«Nuevo Repartidor»).
+
+### `sticky`
+
+| valor | cuándo | fuente |
+|---|---|---|
+| `false` (default) | el caso normal: el título se va con el scroll | propuesta |
+| `true` | listas largas donde las acciones del header se usan mientras se recorre (filtros, «Agregar»). Le pone fondo blanco. 0 usos hoy | propuesta |
+
+## 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) | `small` (36) | propuesta |
+
+Los botones de las acciones hoy: 10 `small` fijos, 2 `bp.isMobile() ? 'large' : 'small'`, 2
+`bp.controlSize()` (`large`/`xlarge`), 2 `large`, 1 `medium`. La propuesta es la pareja que ya
+usan dos pantallas: en mobile las acciones bajan a su fila y tienen sitio para 48 px; en desktop
+van al lado del título de 28 y `small` no le compite.
+
+```html
+<sui-button [size]="bp.isMobile() ? 'large' : 'small'" slot="actions">Agregar</sui-button>
+```
+
+## API
+
+<!-- api:inicio -->
+<!-- generada: no editar a mano — `npm run docs` -->
+
+| input | tipo | default |
+|---|---|---|
+| `title` | `string` | — (requerido) |
+| `subtitle` | `string \| null` | `null` |
+| `sticky` | `boolean` | `false` |
+
+Outputs: ninguno.
+<!-- 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).
+
+## Ejemplo
+
+```html
+<sui-page-header title="Descuentos" subtitle="Promociones y campañas activas de tu negocio.">
+  <sui-button slot="actions" variant="filled"
+    [size]="bp.isMobile() ? 'large' : 'small'" (click)="crear()">
+    Crear descuento
+  </sui-button>
+</sui-page-header>
+```

package/docs/sui-segmented-control/README.md

@@ -72,6 +72,9 @@ Regla corta: **2-4 modos de la misma vista, efecto inmediato → segmented · se
 Alto de cada segmento: `small` 28 px, `medium` 28 px, `large` 32 px, `xlarge` 40 px (el control
 suma 8 px de borde interno).
 
+En large y xlarge el texto sube a 16 px (regla del 03-10-2026): Label/Medium 16/24. En `large` el
+padding del segmento con texto bajó de 6 a 4 para que siga midiendo 32.
+
 | uso | mobile | web |
 |---|---|---|
 | modos con texto (local del horario, rol) | `xlarge` (segmento de 40 px) | `medium` |

package/docs/sui-select/README.md

@@ -94,8 +94,11 @@ Regla corta: **sale de datos o son más de 6 → select · 2–6 fijas → radio
 El campo sigue la escala del input y del botón (`large` 48 y `xlarge` 52 son extensión de SUI;
 la guía tiene `medium` 40, `small` 36 y `xsmall` 32). **La lista acompaña al campo**: las opciones
 miden 36 hasta `medium` (las de la guía), 44 en `large` y 48 en `xlarge`, y **en mobile (≤ 767 px)
-nunca bajan de 44**, sea cual sea el `size`. El texto de la opción queda en 14/20, el mismo del
-valor del campo.
+nunca bajan de 44**, sea cual sea el `size`. El texto de la opción es el mismo del valor del
+campo: 14/20 hasta `medium` y 16/24 en `large` y `xlarge`.
+
+En large y xlarge el texto sube a 16 px (regla del 03-10-2026). Vale para el valor, el placeholder
+y las opciones de la lista; el alto no cambia (las opciones bajan 2 de padding para seguir en 44/48).
 
 | size del campo | opción en web | opción en mobile | fuente |
 |---|---|---|---|

package/docs/sui-sidebar/README.md

@@ -0,0 +1,217 @@
+---
+name: sui-sidebar
+selector: sui-sidebar
+resumen: Navegación principal de un rol — columna fija a la izquierda en web y cajón que entra desde la izquierda en mobile
+alternativas: [la barra inferior nativa del layout (las 4-5 secciones más usadas en el teléfono), sui-topbar (navegación arriba, sin columna lateral), sui-tab-menu-vertical (secciones dentro de UNA pantalla, como ajustes), sui-dropdown-menu (acciones de una cuenta o un botón)]
+---
+
+# sui-sidebar
+
+Story: [Organisms/Sidebar](https://sui-design-system.web.app/?path=/docs/organisms-sidebar--docs)
+
+## Cuándo usarlo / cuándo no
+
+**Úsalo** como **la** navegación de un layout de rol: una por layout, montada en el layout y no
+en las páginas. En la app hay 4 y cubren los roles: empresa (`components/sidebar/sidebar.html:43`,
+dentro del shell), repartidor (`layouts/driver/driver-layout.html:4`), super admin y central
+(`layouts/master/master-layout.html:5`) y cliente (`layouts/customer/customer-layout.html:5`).
+
+**No lo uses** para:
+
+- Navegar entre secciones **de una sola pantalla** (las pestañas de Ajustes, los pasos de un
+  formulario): `sui-tab-menu-vertical` o `sui-tab-chips`.
+- Un menú de acciones (editar, eliminar, cerrar sesión de un item): `sui-dropdown-menu`.
+- Reemplazar la barra inferior en el teléfono. En mobile, las secciones de todos los días van en la
+  barra inferior (nativa en iOS) y el sidebar es el cajón de «Más».
+
+Regla corta: **navegación del rol → sidebar · secciones de una pantalla → tab menu · acciones → dropdown.**
+
+## Qué variante usar
+
+> **La guía del DS no tiene página del sidebar.** El componente sale del Figma de SUI (Sidebar
+> [Navigation], node 3802:11759) y el cajón de mobile no existe en ese Figma: se portó del layout
+> del super admin. Lo de abajo es **práctica de la app** (los 4 usos están homologados desde el
+> 25-07-2026) o **propuesta, falta aprobación**; lo marcado «canon» sale de `docs/CANON-SUI.md`
+> o de `master-pedidos/CLAUDE.md`.
+>
+> Uso medido el 03-10-2026 en `master-pedidos/src/app`: **4 sidebars**, sin contar vitrinas
+> (`master-preview` tiene el quinto).
+
+### La composición (igual en los 4 layouts)
+
+| pieza | cómo | fuente |
+|---|---|---|
+| `brand` | `{ name: 'Master Pedidos', subtitle: '<Rol>', logo: 'assets/app-icon.png', fallback: 'M' }`. En empresa, el nombre del local. | práctica de la app (4 de 4) |
+| `showHeaderButton` + `headerButtonActive` + panel `[header-panel]` | El botón del header abre el **cambio de rol** (o de negocio/sucursal en empresa). El panel se proyecta con `<div header-panel>` y adentro van `sui-dropdown-item mode="option" size="large"`. El cliente lo muestra solo en mobile. | práctica de la app (4 de 4) |
+| tres secciones con rótulo | `items` + `itemsLabel` (lo de todos los días), `secondaryItems` + `secondaryItemsLabel` (dinero o crecimiento), `supportingItems` + `supportingItemsLabel` (cuenta, administración: va anclado abajo). Rótulos en sentence case: «Operación», «Dinero», «Cuenta». | práctica de la app (4 de 4) |
+| `activeRoute` | Siempre `[activeRoute]="currentUrl()"`, aunque los items tengan `route`: así el activo se resuelve por prefijo (`/cliente/pedidos/123` deja marcado «Pedidos»). | práctica de la app (4 de 4) |
+| `profile` | Nombre + `avatarUrl` (nunca `photoURL`) + correo. | canon (CLAUDE.md, «Fotos de otra persona»: el campo correcto es `avatarUrl`) |
+| cerrar sesión | Hoy **ningún** item usa `action: 'logout'`: el cierre real vive en el selector de rol y el «salir» del panel solo cambia de rol (`components/sidebar/sidebar.ts:367`). Los 4 layouts dejan `(logoutClicked)` conectado por si se agrega. | práctica de la app |
+| `[(mobileOpen)]` + `closeOnItemClick` | Siempre los dos. Más `cerrarAlNavegar(...)` en el constructor del layout (ver Trampas). | canon (CANON-SUI §1.1) |
+| `search` | `{ placeholder: 'Buscar...', shortcut: '⌘K' }` y el layout **filtra** los items con `searchValue` (el componente no filtra). | práctica de la app (4 de 4) |
+| `indicatorColor` | Default `brand` (naranja). No se cambia. | canon del DS (accent = marca) |
+| `collapsed` | Solo el cliente lo usa, con un item «colapsar», y **solo en web**: `[collapsed]="colapsado() && !bp.isMobile()"`. | práctica de la app (1 uso) |
+
+### El item (`SuiSidebarItem`)
+
+| prop | cuándo | fuente |
+|---|---|---|
+| `icon` | Siempre, RemixIcon `-line`. Sin ícono, el modo colapsado queda vacío. | propuesta, falta aprobación |
+| `route` | Navegación normal (usa `routerLink`). | práctica de la app |
+| sin `route` | Acción, no navegación (abrir Configuración, colapsar): `action` o solo `value`, y se escucha `(itemClicked)`. | práctica de la app |
+| `badge` | Un contador que pide acción: notificaciones sin leer, con tope «99+» (`components/sidebar/sidebar.ts:129`). Nunca un «NEW» decorativo. | práctica de la app (el «nunca NEW» es propuesta) |
+| `variant: 'danger'` | Solo «Cerrar sesión» o salidas destructivas. | propuesta, falta aprobación |
+| `shortcut`, `colorDot` | No usar (ver «No usar»). | propuesta, falta aprobación |
+
+## Tamaño en mobile y en web
+
+El sidebar **no tiene `size`**. El ancho lo decide el viewport:
+
+| estado | ancho | fuente |
+|---|---|---|
+| web (> 767 px) | 272 fijo, alto `100dvh` | Figma |
+| web colapsado (`collapsed`) | 80, solo íconos; los rótulos siguen visibles y cada item tiene tooltip nativo con su label | Figma |
+| mobile `drawer` (default) | `min(86vw, 360px)`, entra desde la izquierda con fondo oscuro | extensión SUI (no está en el Figma) |
+| mobile `sheet` | `100vw - 40px`, se siente casi a pantalla completa | extensión SUI |
+
+| uso | mobile | web | fuente |
+|---|---|---|---|
+| navegación del rol | cajón `drawer`, cerrado por defecto | columna fija de 272 | práctica de la app (4 de 4) |
+| colapsar | nunca (`!bp.isMobile()`) | opcional, a pedido de la persona | práctica de la app |
+| `sheet` | no usar (0 usos) | — | propuesta, falta aprobación |
+
+**Qué pasa en mobile (≤ 767 px):** el sidebar sale del flujo y queda `position: fixed` fuera de la
+pantalla. Lo abre la acción `toggle-sidebar` de la **barra inferior** («Más»), que el layout
+traduce a `mobileOpen = true` (`layouts/shell/shell.ts:326`, `customer-layout.ts:322`). Se cierra
+con el fondo, con Escape, al tocar un item (`closeOnItemClick`) y —por el helper del proyecto—
+al terminar cualquier navegación. Cerrado queda `inert` y `aria-hidden`: el foco no se mete.
+Respeta las safe areas de arriba, izquierda y abajo.
+
+## «No usar»: por qué no hoy y cuándo sí
+
+| qué | por qué no hoy | cuándo sí, en un flujo nuevo |
+|---|---|---|
+| `indicatorColor="information"` | el activo es naranja de marca en toda la app | nunca en esta app (es el azul del Figma original) |
+| `mobileMode="sheet"` | el `drawer` deja ver la página detrás y se entiende que es un cajón | un rol con muchísimos items donde 360 px quedan cortos |
+| `shortcut` en items | no hay atajos de teclado por sección | si se agregan atajos tipo `⌘1` en el panel web |
+| `colorDot` | no hay «favoritos» ni etiquetas de color | proyectos o locales favoritos fijados por la persona |
+| `profileDropdown` | el perfil se abre desde «Cuenta» | si el perfil pasa a tener menú propio (cambiar cuenta, idioma) |
+| feature card (`[feature-card]`) | no hay promo dentro de la navegación | invitar a mejorar el plan en el panel de empresa |
+| `showBackdrop` en `false` | sin fondo, el cajón parece pegado a la página | nunca en mobile |
+
+## API
+
+<!-- api:inicio -->
+<!-- generada: no editar a mano — `npm run docs` -->
+
+| input | tipo | default |
+|---|---|---|
+| `collapsed` | `boolean` | `false` |
+| `indicatorColor` | `'information' \| 'brand'` | `'brand'` |
+| `brand` | `SuiSidebarBrandConfig \| null` | `null` |
+| `showHeaderButton` | `boolean` | `false` |
+| `headerButtonActive` | `boolean` | `false` |
+| `search` | `SuiSidebarSearchConfig \| boolean \| null` | `false` |
+| `searchValue` · model, `[(searchValue)]` | `string` | `''` |
+| `items` | `SuiSidebarItem[]` | `[]` |
+| `secondaryItems` | `SuiSidebarItem[]` | `[]` |
+| `supportingItems` | `SuiSidebarItem[]` | `[]` |
+| `supportingAnchorBottom` | `boolean` | `true` |
+| `itemsLabel` | `string \| null` | `null` |
+| `secondaryItemsLabel` | `string \| null` | `null` |
+| `supportingItemsLabel` | `string \| null` | `null` |
+| `activeRoute` | `string \| null` | `null` |
+| `profile` | `SuiSidebarProfile \| null` | `null` |
+| `profileDropdown` | `boolean` | `false` |
+| `mobileOpen` · model, `[(mobileOpen)]` | `boolean` | `false` |
+| `closeOnItemClick` | `boolean` | `true` |
+| `showBackdrop` | `boolean` | `true` |
+| `mobileMode` | `'drawer' \| 'sheet'` | `'drawer'` |
+
+| output | payload |
+|---|---|
+| `itemClicked` | `SuiSidebarItem` |
+| `logoutClicked` | `void` |
+| `backdropClicked` | `void` |
+| `headerButtonClicked` | `void` |
+| `profileClicked` | `void` |
+| `searchSubmitted` | `string` |
+<!-- api:fin -->
+
+```ts
+interface SuiSidebarItem {
+  value: string;              // lo emite (itemClicked)
+  label: string;
+  icon?: string;              // RemixIcon sin 'ri-'
+  route?: string;             // routerLink; sin route solo emite
+  external?: boolean;
+  variant?: 'default' | 'danger';
+  action?: 'logout' | string; // cualquier action anula el route
+  badge?: string | number;
+  shortcut?: string;
+  colorDot?: string;          // reemplaza el ícono por un punto de color
+  tooltip?: string;           // tooltip en colapsado; default = label
+}
+interface SuiSidebarBrandConfig { name: string; subtitle?: string; subtitleAsBadge?: boolean; logo?: string; fallback?: string; }
+interface SuiSidebarSearchConfig { placeholder?: string; shortcut?: string; }
+interface SuiSidebarProfile { name: string; avatarUrl?: string; initials?: string; status?: SuiAvatarStatus; email?: string; verified?: boolean; }
+```
+
+Slots: `[header-panel]` (debajo del header: el switcher), `[feature-card]` (al fondo del contenido).
+
+## Trampas
+
+- **El cajón no se cierra solo al navegar desde afuera.** Se cierra con el fondo, Escape y el toque
+  en un item; cualquier otra navegación (atrás, un push, `router.navigate`, una ruta cacheada que
+  vuelve) lo deja abierto tapando la página siguiente. Mientras el DS no traiga `closeOnNavigate`,
+  cada layout llama `cerrarAlNavegar(menuAbierto, switcherAbierto)`
+  (`core/services/cerrar-al-navegar.ts`). Canon: CANON-SUI §1.1.
+- **El buscador no filtra nada.** Solo expone `[(searchValue)]` y `(searchSubmitted)`; el layout
+  filtra los items (`master-layout.ts:125`). Y su placeholder por defecto es **`'Search...'`, en
+  inglés**: pásale siempre `{ placeholder: 'Buscar...' }`. (En `sui-topbar` el default sí es «Buscar...».)
+- **`collapsed` no mira el viewport.** Con `collapsed` en `true`, el cajón de mobile también sale
+  de 80 px. Condiciónalo: `[collapsed]="colapsado() && !bp.isMobile()"`.
+- Un item con `route` queda activo por `routerLinkActive` **y** por `activeRoute`; un item sin
+  `route` solo por `activeRoute` (por `value` exacto). Si no pasas `activeRoute`, los items-acción
+  nunca se marcan.
+- Cualquier `action` (no solo `'logout'`) anula el `route`: el item no navega.
+- El `title` nativo del host se borra (sin tooltip gris); en colapsado el tooltip va en cada item.
+- El cajón tiene `z-index: 300` sobre la barra inferior (200). Mientras está abierto el layout
+  esconde la barra (`customer-layout.ts:66`); si armas un layout nuevo, haz lo mismo.
+- El comentario de cabecera del `.ts` todavía dice 240 px; el ancho real es 272 (`sui-sidebar.scss:50`).
+- Los items ya traen el arreglo de iOS del `:active` pegado: no lo agregues.
+
+## Ejemplo
+
+```html
+<sui-sidebar
+  [brand]="{ name: 'Master Pedidos', subtitle: 'Repartidor', logo: 'assets/app-icon.png', fallback: 'M' }"
+  [showHeaderButton]="true"
+  [headerButtonActive]="switcherOpen()"
+  (headerButtonClicked)="switcherOpen.set(!switcherOpen())"
+  [search]="{ placeholder: 'Buscar...', shortcut: '⌘K' }"
+  [(searchValue)]="busqueda"
+  itemsLabel="Operación" [items]="items()"
+  secondaryItemsLabel="Dinero" [secondaryItems]="itemsDinero()"
+  supportingItemsLabel="Cuenta" [supportingItems]="itemsCuenta()"
+  [activeRoute]="currentUrl()"
+  [profile]="perfil()"
+  [(mobileOpen)]="menuAbierto"
+  [closeOnItemClick]="true"
+  (logoutClicked)="logout()">
+  @if (switcherOpen()) {
+    <div header-panel role="listbox" aria-label="Cambiar de rol">
+      @for (rol of roles; track rol.value) {
+        <sui-dropdown-item [label]="rol.label" [sublabel]="rol.sublabel" mode="option" size="large"
+                           (clicked)="irARol(rol)" />
+      }
+    </div>
+  }
+</sui-sidebar>
+```
+
+```ts
+constructor() {
+  cerrarAlNavegar(this.menuAbierto, this.switcherOpen); // mientras el DS no cierre solo
+}
+```

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

@@ -80,6 +80,9 @@ Regla corta: **ajuste con texto → este · ajuste con peso → switch-card · s
 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.
 
+En large y xlarge el texto sube a 16 px (regla del 03-10-2026): el label va en 16/24; sublabel y
+descripción se quedan en 12.
+
 ## «No usar»: por qué no hoy y cuándo sí
 
 | qué | por qué no hoy | cuándo sí, en un flujo nuevo |

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

@@ -108,8 +108,11 @@ vista → segmented · secciones → tab menu · filtros o categorías → tab-c
 > `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.
+Alto del chip: `small` 32 px · `medium` 36 px (el de siempre, default) · `large` 40 px. `small` y
+`medium` con texto de 14 px; cambia el alto y el aire lateral. El scroller suma 12 px arriba y abajo.
+
+En large y xlarge el texto sube a 16 px (regla del 03-10-2026): el chip `large` va en 16/24 y sigue
+midiendo 40. El número del contador se queda en 12.
 
 | uso | mobile | web | fuente |
 |---|---|---|---|