@ajuarezso/sui-design-system 0.20.0 → 0.22.0

package/docs/sui-rich-editor/README.md

@@ -0,0 +1,114 @@
+---
+name: sui-rich-editor
+selector: sui-rich-editor
+resumen: Barra de formato (negrita, cursiva, alineación, enlace) con un área de texto editable opcional
+alternativas: [sui-textarea (todo texto libre de la app hoy, sin formato)]
+---
+
+# sui-rich-editor
+
+Story: [Molecules/Rich Editor](https://sui-design-system.web.app/?path=/docs/molecules-rich-editor--docs)
+
+## Cuándo usarlo / cuándo no
+
+**Úsalo** solo si un texto **necesita formato** y se va a mostrar con ese formato: negritas,
+listas o enlaces en un texto largo que se publica en la web.
+
+**No lo uses** para:
+
+- Notas, motivos, descripciones de productos, mensajes y avisos: `sui-textarea`. Todo eso se
+  guarda y se muestra como texto plano.
+- Un push o un aviso del celular: no muestran formato.
+
+Regla corta: **hoy, siempre `sui-textarea`.**
+
+## Qué variante usar
+
+> **La guía del DS no tiene página para este componente.** Viene del Figma («Rich Editor»), donde
+> solo está la barra de formato. Todo lo de abajo es **propuesta, falta aprobación**.
+>
+> Uso medido el 03-10-2026 en `master-pedidos/src/app`: **0 usos**.
+
+| prop / evento | cuándo | fuente |
+|---|---|---|
+| `layout="full"` (default) | Título, tamaño, B I U S, alineación, comentario, enlace, mención. | API |
+| `layout="formatting"` | Solo B I U S y alineación: lo único que el editor aplica solo. | propuesta, falta aprobación |
+| `layout="compact"` | Solo título y tamaño (los dos son avisos a la pantalla, no formato real). | — |
+| `layout="social"` | Comentario, enlace, mención (también avisos). | — |
+| `showMore` | El botón ⋮ al final. Apagarlo si no hay más acciones. | API |
+| `editable` | `true` para tener el área donde se escribe; `false` deja solo la barra. | API |
+| `placeholder` | «Escribe algo…» (default) o algo del contexto. | API |
+| `value` | El contenido, **en HTML**. | API |
+| `headingLabel` · `fontSizeLabel` | Lo que dicen los botones de título y tamaño («Header», «14px» por default). | API |
+| `(action)` | Cada botón de la barra: la pantalla tiene que resolver título, tamaño, enlace, comentario y mención. | API |
+
+## Tamaño en mobile y en web
+
+**No tiene `size`.** Los botones de la barra son de 28 px: **no tiene tamaño suficiente para
+mobile**. Si alguna vez se usa, que sea en el panel web.
+
+## «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) | ningún texto de la app lleva formato | una página de ayuda o de términos que se escribe desde el super admin y se muestra en la web |
+| `layout` `full`, `compact`, `social` | título, tamaño, enlace, comentario y mención no los hace el editor: solo avisa | si se monta un editor completo (Tiptap) detrás |
+
+## API
+
+<!-- api:inicio -->
+<!-- generada: no editar a mano — `npm run docs` -->
+
+### `sui-rich-editor`
+
+| input | tipo | default |
+|---|---|---|
+| `layout` | `'full' \| 'compact' \| 'formatting' \| 'social'` | `'full'` |
+| `showMore` | `boolean` | `true` |
+| `editable` | `boolean` | `false` |
+| `placeholder` | `string` | `'Escribe algo…'` |
+| `value` · model, `[(value)]` | `string` | `''` |
+| `headingLabel` | `string` | `'Header'` |
+| `fontSizeLabel` | `string` | `'14px'` |
+
+| output | payload |
+|---|---|
+| `action` | `SuiRichEditorAction` |
+| `valueChange` | `string` |
+
+### `sui-rich-editor-item`
+
+| input | tipo | default |
+|---|---|---|
+| `type` | `'text' \| 'dropdown' \| 'icon' \| 'color'` | `'icon'` |
+| `state` | `'default' \| 'hover' \| 'active'` | `'default'` |
+| `label` | `string` | `''` |
+| `icon` | `string` | `''` |
+| `color` | `'gray' \| 'blue' \| 'orange' \| 'red' \| 'green' \| 'yellow' \| 'purple' \| 'sky' \| 'pink' \| 'teal'` | `'gray'` |
+| `colorHex` | `string \| null` | `null` |
+| `ariaLabel` | `string` | `''` |
+| `disabled` | `boolean` | `false` |
+
+| output | payload |
+|---|---|
+| `clicked` | `void` |
+<!-- api:fin -->
+
+Sub-componente: `sui-rich-editor-item` (cada botón de la barra).
+
+## Trampas
+
+- **`value` es HTML.** Mostrarlo con `[innerHTML]` sin limpiarlo abre la puerta a código ajeno.
+  Limpiarlo en el servidor antes de guardar.
+- **Solo B I U S y alineación funcionan solos** (usa `document.execCommand`, que está en desuso).
+  Título, tamaño, enlace, comentario y mención solo emiten `(action)`: la pantalla tiene que hacer
+  el resto.
+- Por default muestra solo la barra: sin `[editable]="true"` no hay dónde escribir.
+- Labels por default en inglés o técnicos («Header», «14px»).
+
+## Ejemplo
+
+```html
+<sui-rich-editor layout="formatting" [showMore]="false" [editable]="true"
+                 placeholder="Escribe la respuesta…" [(value)]="html" />
+```

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

@@ -0,0 +1,183 @@
+---
+name: sui-select
+selector: sui-select
+resumen: Campo que despliega una lista para elegir UNA opción (distrito, repartidor, categoría, motivo)
+alternativas: [sui-radio-label / sui-radio-card (2 a 6 opciones fijas a la vista), sui-segmented-control (2 a 4 modos que se aplican al instante), sui-compact-select (filtro chico que se ajusta al texto), sui-compact-select-for-input (elegir moneda o país dentro de un campo), sui-tag-input (varios valores)]
+---
+
+# sui-select
+
+Story: [Molecules/Select/Select](https://sui-design-system.web.app/?path=/docs/molecules-select-select--docs)
+
+## Cuándo usarlo / cuándo no
+
+**Úsalo** para elegir **una** opción de una lista que **sale de datos** (departamento, provincia,
+distrito, repartidor, categoría, plan) o que tiene **más de 6 opciones fijas**.
+
+**No lo uses** para:
+
+- 2 a 6 opciones fijas dentro de un formulario: se ven todas de una con `sui-radio-label` (web) o
+  `sui-radio-card` (mobile). Abrir un menú para elegir entre «Casa» y «Trabajo» es un toque de más.
+- 2 a 4 modos de la vista que se aplican al tocar (Hoy · Semana · Mes): `sui-segmented-control`.
+- **Buscar** dentro de la lista: `sui-select` **no tiene buscador**. Con 40 distritos se scrollea.
+- Elegir **varias**: no es múltiple. Varias opciones fijas → casillas; valores libres → `sui-tag-input`.
+- Una lista con foto o bandera por opción: las opciones solo muestran texto (ver «Trampas»).
+
+Regla corta: **sale de datos o son más de 6 → select · 2–6 fijas → radio · modos de la vista → segmented.**
+
+## Qué variante usar
+
+> **La guía del DS lo define como el control para elegir una sola opción de un menú** y muestra
+> label y hint, íconos, tamaños, país, método de pago, usuario y deshabilitado. Trae además tres
+> variantes que en SUI son componentes aparte: `compact` (`sui-compact-select`), `inline`
+> (`sui-inline-select`) y `compactForInput` (`sui-compact-select-for-input`). No dice cuándo va cada una.
+>
+> Uso medido el 03-10-2026 en `master-pedidos/src/app` (misma exclusión que `sui-badge`, más
+> `master-ejercicios`): **57 usos en 26 archivos**. Todos `type="basic"` y sin ícono. Tamaños:
+> 39 sin `size` (`medium`), 11 `large`, 3 `bp.isMobile() ? 'large' : 'small'`, 2 `medium`,
+> 1 `small`, 1 `bp.controlSize()`. 29 pasan `placeholder`.
+
+### Qué elegir según las opciones
+
+| caso | componente | fuente |
+|---|---|---|
+| La lista sale de datos (ubigeo, repartidores, categorías, planes) | `sui-select` | según la guía del DS (elegir una opción de un menú) |
+| Más de ~6 opciones fijas | `sui-select` | canon (README de `sui-radio`, aprobado 03-10-2026) |
+| 2 a 6 opciones fijas en un formulario | `sui-radio-label` / `sui-radio-card` | propuesta, falta aprobación (sale del umbral de `sui-radio`) |
+| 2 a 4 modos que se aplican al instante | `sui-segmented-control` | canon (README de `sui-segmented-control`, aprobado 03-10-2026) |
+| Filtro de una barra con 5 o más opciones | `sui-select` sin label (o `sui-compact-select` en web) | propuesta, falta aprobación |
+
+**Candidatos de hoy** (no rompen nada; se verían mejor con radios o segmented):
+
+- **6 selects con 2 opciones fijas**: `components/add-product-modal/add-product-modal.html:246`,
+  `pages/drivers/drivers.html:373` y `pages/drivers/add-driver/add-driver.html:111` («Tipo de pago»),
+  `pages/super-admin/master-gastos/master-gastos.html:185` y `:200`,
+  `pages/super-admin/master-sonidos-push/master-sonidos-push.html:85`.
+- **15 con 3 a 6 opciones fijas en un formulario**: `components/address-form-modal/address-form-modal.html:11`
+  («Etiqueta»), `pages/customer/profile/profile.html:249` («Género»), `pages/drivers/drivers.html:359`
+  («Tipo de vehículo»), `pages/discounts/discounts.html:139`.
+- **2 filtros de período de 3 opciones** → segmented: `pages/overview/overview.html:46`,
+  `pages/discounts/discounts.html:48`.
+
+### `type`, `leadingIcon`, `imageUrl`, `flag`, `badge`
+
+| prop | cuándo | fuente |
+|---|---|---|
+| `type="basic"` (default) sin ícono | Todo select de la app hoy. | según la guía del DS |
+| `type="avatar"` + `imageUrl` | Elegir un **repartidor**: la foto de quien quedó elegido en el campo. Hoy `pages/orders/orders.html:256` muestra solo el nombre. | según la guía del DS (ejemplo «User»); el caso es propuesta |
+| `type="provider"` + `imageUrl` | Método de pago con logo (Yape, Plin). | según la guía del DS (ejemplo «Payment Method»); el caso es propuesta |
+| `leadingIcon` (`true` o nombre RemixIcon) | Un ícono que ayuda a reconocer el campo en un formulario largo. Hoy sin caso. | según la guía del DS (ejemplo «Icons») |
+| `type="country"` + `flag` | No usar hoy: todo es Perú. | según la guía del DS (ejemplo «Country») |
+| `type="brand"` / `"company"` | No usar hoy. | — |
+| `badge` | No usar hoy. | — |
+
+### Las piezas
+
+| prop | cuándo | fuente |
+|---|---|---|
+| `label` | Siempre en formularios. Sin label solo en un filtro de barra donde el valor se explica solo («Todos los roles»). | según la guía del DS (ejemplo con label y hint) |
+| `placeholder` | **Siempre**, en imperativo con tuteo: «Elige el motivo», «Elige tu distrito». El default es «Seleccionar...». | canon (CANON-SUI §5.3) |
+| `required` · `sublabel` · `tooltip` · `hint` | Igual que `sui-input`: asterisco, «(Opcional)» con paréntesis, aclaración, ayuda de una línea. Hoy 1 sin paréntesis: `pages/customer/profile/profile.html:249`. | según la guía del DS |
+| `error` + `errorMessage` | No eligió en un campo obligatorio: «Elige tu distrito». | según la guía del DS |
+| `disabled` | Selects en cascada: provincia hasta elegir departamento, distrito hasta elegir provincia. | según la guía del DS (ejemplo deshabilitado); el caso ya es práctica (`components/address-form-modal/address-form-modal.html:87`) |
+| `options` | `SuiSelectOption<T>[]`: `{ value, label, disabled? }`. `disabled` en la opción para lo que existe pero hoy no se puede elegir. | API |
+
+**Usos de hoy que rompen la regla:**
+
+- **28 sin `placeholder`** muestran «Seleccionar...» si arrancan vacíos.
+- **16 placeholders «Seleccionar…» o «Selecciona…»** (y 4 que ya dicen «Elige…») → «Elige…»: «Seleccionar departamento»
+  (`components/address-form-modal/address-form-modal.html:77`), «Seleccionar tipo»,
+  «Selecciona una categoría».
+
+## Tamaño en mobile y en web
+
+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 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 |
+|---|---|---|---|
+| `xsmall` · `small` · `medium` | 36 | 44 | 36: según la guía del DS · 44 en mobile: canon (aprobado por el dueño, 03-10-2026), extensión SUI |
+| `large` | 44 | 44 | canon (aprobado por el dueño, 03-10-2026), extensión SUI |
+| `xlarge` | 48 | 48 | canon (aprobado por el dueño, 03-10-2026), extensión SUI |
+
+| uso | mobile | web | fuente |
+|---|---|---|---|
+| campo de formulario | `large` (48) | `medium` (40) | propuesta, falta aprobación (igual que `sui-input`) |
+| filtro de una barra | `large` (48) | `small` (36) | propuesta (ya es práctica en `pages/orders/orders.html:256`) |
+| dentro de una tabla densa | no aplica | `xsmall` (32) | según la guía del DS |
+| `xlarge` (52) | no usar | no usar | propuesta: queda más alto que el botón `large` del footer |
+
+```html
+<sui-select [size]="bp.isMobile() ? 'large' : 'medium'" label="Distrito" … />   <!-- bp = BreakpointsService -->
+```
+
+## «No usar»: por qué no hoy y cuándo sí
+
+| qué | por qué no hoy | cuándo sí, en un flujo nuevo |
+|---|---|---|
+| `type="country"` + `flag` | todo es Perú | si se abren repartidores o locales en otro país |
+| `type="brand"` / `"company"` | no hay listas de marcas o empresas | elegir la marca de un producto envasado o la empresa de una flota |
+| `leadingIcon` | ningún formulario lo necesita para reconocerse | un formulario largo del panel con varios selects seguidos |
+| `badge` | no hay valores que marcar | marcar el plan elegido como «Recomendado» |
+| `size="xsmall"` | no hay selects dentro de tablas | cambiar el estado de una fila sin abrir el detalle |
+| `size="xlarge"` | queda más alto que el botón del footer | un select solo, como acción principal de la pantalla |
+
+## API
+
+<!-- api:inicio -->
+<!-- generada: no editar a mano — `npm run docs` -->
+
+| input | tipo | default |
+|---|---|---|
+| `size` | `'xsmall' \| 'small' \| 'medium' \| 'large' \| 'xlarge'` | `'medium'` |
+| `placeholder` | `string` | `'Seleccionar...'` |
+| `options` | `SuiSelectOption<T>[]` | `[]` |
+| `disabled` | `boolean` | `false` |
+| `error` | `boolean` | `false` |
+| `errorMessage` | `string \| null` | `null` |
+| `label` | `string \| null` | `null` |
+| `hint` | `string \| null` | `null` |
+| `type` | `'basic' \| 'country' \| 'avatar' \| 'provider' \| 'brand' \| 'company'` | `'basic'` |
+| `leadingIcon` | `string \| boolean` | `false` |
+| `flag` | `SuiFlagName \| null` | `null` |
+| `imageUrl` | `string \| null` | `null` |
+| `badge` | `SuiBadgeConfig \| string \| null` | `null` |
+| `sublabel` | `string \| null` | `null` |
+| `required` | `boolean` | `false` |
+| `tooltip` | `string \| null` | `null` |
+| `value` · model, `[(value)]` | `T \| null` | `null` |
+
+Outputs: ninguno.
+<!-- api:fin -->
+
+`value` es `model<T | null>`. Implementa `ControlValueAccessor`. Slot `[slot=leading]` para una
+decoración propia del campo (gana sobre ícono, imagen y bandera).
+
+## Trampas
+
+- **No busca y no es múltiple.** Con 40 opciones la lista se scrollea; con varias a elegir no sirve.
+- **Las opciones solo llevan texto**: `SuiSelectOption` no tiene ícono, foto ni bandera. El
+  `type="avatar"` o `"country"` decora **el campo**, no la lista.
+- **El default del placeholder es «Seleccionar...»**: genérico y con `...`. Pásalo siempre.
+- El `valueChange` puede traer `null`: los usos de hoy hacen `$event ?? ''`.
+- `T` arranca en `any`: tipa las opciones (`SuiSelectOption<string>[]`) para no arrastrar `any`
+  a la pantalla.
+- Con 44 px por opción en mobile el panel muestra unas 4 opciones antes de scrollear (el alto
+  máximo del panel no cambió).
+- El label también abre la lista al tocarlo.
+
+## Ejemplo
+
+```html
+<sui-select label="Distrito" [required]="true" placeholder="Elige tu distrito"
+            [options]="distritos()" [disabled]="!provinciaId()"
+            [error]="intentado() && !distritoId()" errorMessage="Elige tu distrito"
+            [size]="bp.isMobile() ? 'large' : 'medium'"
+            [value]="distritoId()" (valueChange)="distritoId.set($event ?? '')" />
+```

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
+}
+```