@ajuarezso/sui-design-system 0.18.10 → 0.20.0

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

@@ -0,0 +1,137 @@
+---
+name: sui-radio-label
+selector: sui-radio-label
+resumen: Círculo con su texto (y opcionalmente descripción, badge y link) para elegir una opción de una lista corta
+alternativas: [sui-radio (el círculo solo), sui-radio-card (cada opción es una tarjeta), sui-select (más de 6 opciones), sui-checkbox-label (varias a la vez)]
+---
+
+# sui-radio-label
+
+Story: [Atoms/Checkbox, Radio & Switch/Radio Label](https://sui-design-system.web.app/?path=/docs/atoms-checkbox-radio-switch-radio-label--docs)
+
+## Cuándo usarlo / cuándo no
+
+**Úsalo** para una lista corta de opciones de texto donde se elige una y la lista es densa: las
+franjas horarias del checkout, tipo de documento. Toda la fila se toca. Va dentro de un
+`sui-radio-group`.
+
+**No lo uses** para:
+
+- Opciones con identidad propia (ícono o logo, descripción, borde): `sui-radio-card`. Es lo que
+  usa la app para método de pago, tipo de entrega y modo de asignación.
+- **Una lista de motivos que se toca en el teléfono**: la app ya resolvió ese caso con
+  `sui-radio-card type="basic"` y `bp.controlSize()` (motivos de cancelación del local,
+  `pages/orders/orders.html:566`). El radio-label no tiene `size` y en mobile queda chico.
+- Más de ~6 opciones: `sui-select`.
+- Varias a la vez: `sui-checkbox-label`.
+- Prender algo al instante: `sui-switch-label`.
+
+Regla corta: **lista densa de texto → radio-label · motivos u opciones que se tocan en el teléfono
+o con peso → radio-card · muchas → select.**
+
+## Qué variante usar
+
+> **La guía del DS muestra las piezas, no cuándo usarlas.** Su ejemplo con label es una lista de
+> motivos («Spam», «Acoso», «Infringe las reglas»); el «avanzado» suma (Sublabel), badge «NEW»,
+> descripción, Link Button y la versión con el círculo a la derecha.
+>
+> Uso medido el 03-10-2026 en `master-pedidos/src/app` (misma exclusión que `sui-badge`):
+> **1 uso**, las franjas horarias del checkout, con `flip`. Más **1 radio nativo** de motivos
+> (ver abajo a qué componente va).
+
+### Las piezas
+
+| prop | cuándo | fuente |
+|---|---|---|
+| `value` | Siempre (es obligatorio). Lo que lee el `sui-radio-group`. | API |
+| `label` | Siempre. La opción en pocas palabras («Dirección no encontrada», «12:00 — 12:30 p. m.»). | según la guía del DS (pieza) |
+| `sublabel` | Precisión corta entre paréntesis: «(recomendado)». | según la guía del DS |
+| `description` | Una frase de qué pasa si se elige. Sube el label a peso medio. Si casi todas las opciones la necesitan, probablemente es `sui-radio-card`. | según la guía del DS (pieza); el «cuándo» es propuesta |
+| `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` | «Ver detalle» que no elige la opción. Solo se ve con `description`. | según la guía del DS |
+| `flip` | Círculo a la derecha en listas de opciones tipo hoja (sheet) y de ajustes, donde el texto es lo que se lee y el círculo es el indicador, como las franjas del checkout. En formularios, a la izquierda. | canon (aprobado por el dueño, 03-10-2026) |
+| `disabled` | La opción existe pero no aplica (franja ya llena). | según la guía del DS |
+| `size` | `medium` (default, Figma): círculo 20, label 14/20. `large`: círculo 24, label 16/24. `xlarge`: círculo 28, label 16/24. En large y xlarge el sublabel y la descripción pasan a 14/20, el badge sin `size` propio sube a `medium` / `large` y el link a `medium`. Se usa con `[size]="bp.controlSize()"`. | `medium`: según la guía del DS · `large` / `xlarge`: canon (aprobado por el dueño, 03-10-2026), extensión SUI |
+
+**Usos de hoy:**
+
+- **1 radio nativo de motivos:** `pages/driver/driver-order-detail/driver-order-detail.html:812`
+  (motivos de cancelación del repartidor). Por la pantalla hermana va a `sui-radio-card
+  type="basic"` como `pages/orders/orders.html:566`, no a este componente.
+- El único uso actual, `pages/customer/checkout/checkout.html:480`, controla la selección con
+  `[checked]` + `(selected)` por fila, sin `sui-radio-group`. Funciona porque el padre fija el
+  estado, pero no se enchufa a un formulario.
+
+## Tamaño en mobile y en web
+
+En mobile se toca con el dedo: el área táctil tiene que medir **44 px o más**. En web, con mouse,
+va un tamaño más chico. La app ya lo resuelve con `BreakpointsService`
+(`src/app/services/breakpoints.service.ts`, mobile = hasta 767 px); para controles,
+`bp.controlSize()` devuelve `xlarge` en mobile y `large` en web (regla de controles grandes del
+dueño, 28-09-2026).
+
+| uso | mobile | web | fuente |
+|---|---|---|---|
+| opciones de un formulario o una hoja (franjas horarias, método de entrega) | `xlarge` (círculo 28, label 16/24) | `large` (círculo 24, label 16/24) | canon (aprobado por el dueño, 03-10-2026) |
+| lista densa de desktop | — | `medium` (círculo 20, label 14/20) | propuesta, falta aprobación |
+| opciones con mucho contexto cada una | `sui-radio-card` con `bp.controlSize()` | `sui-radio-card` con `bp.controlSize()` | propuesta |
+
+```html
+<sui-radio-label value="recojo" [size]="bp.controlSize()" label="Recojo en tienda" />
+```
+
+Toda la fila se toca (el host recibe el click). Con `xlarge` el contenido baja 2 px para que la
+línea del label (24) quede centrada con el círculo (28).
+
+## «No usar»: por qué no hoy y cuándo sí
+
+| qué | por qué no hoy | cuándo sí, en un flujo nuevo |
+|---|---|---|
+| `badge` | ninguna opción es nueva | una opción recién agregada a una lista que el usuario ya conoce |
+| `link` | ninguna opción necesita detalle | «Plan Pro» con «Ver precios» (con `description`) |
+
+## API
+
+<!-- api:inicio -->
+<!-- generada: no editar a mano — `npm run docs` -->
+
+| input | tipo | default |
+|---|---|---|
+| `value` | `string` | — (requerido) |
+| `label` | `string` | `''` |
+| `sublabel` | `string \| null` | `null` |
+| `description` | `string \| null` | `null` |
+| `badge` | `SuiBadgeConfig \| string \| null` | `null` |
+| `link` | `SuiLinkConfig \| string \| null` | `null` |
+| `size` | `'medium' \| 'large' \| 'xlarge'` | `'medium'` |
+| `flip` | `boolean` | `false` |
+| `disabled` | `boolean` | `false` |
+| `checked` · model, `[(checked)]` | `boolean` | `false` |
+
+| output | payload |
+|---|---|
+| `selected` | `string` |
+| `linkClick` | `MouseEvent` |
+<!-- api:fin -->
+
+## Trampas
+
+- **No implementa `ControlValueAccessor`.** El formulario se engancha al `sui-radio-group`, no a
+  cada opción. Sin grupo, se maneja con `[(checked)]`.
+- **No tiene `size`**: el círculo mide 20 px siempre. Choca con la regla de controles grandes
+  (dueño, 28-09-2026) en mobile; si hace falta grande, `sui-radio-card`.
+- **Tocar una opción ya elegida no la desmarca** (bien, es un radio). Tocar el link tampoco la elige.
+- **`link` solo se dibuja con `description`.**
+- El `sui-radio` de adentro no recibe clics (`pointer-events: none`): no le pongas handlers.
+- El badge con string sale naranja; en `sui-radio-card` el default es azul.
+- `flip` usa CSS `order`: el orden para lector de pantalla no cambia.
+
+## Ejemplo
+
+```html
+<sui-radio-group [(ngModel)]="motivo" class="lista-vertical">
+  @for (m of motivos; track m) {
+    <sui-radio-label [value]="m" [label]="m" />
+  }
+</sui-radio-group>
+```

package/docs/sui-rating/README.md

@@ -0,0 +1,198 @@
+---
+name: sui-rating
+selector: sui-rating
+resumen: Muestra una nota con estrellas o la pide (estrellas, emojis, corazones o números)
+alternativas: [sui-icon (una estrella o un corazón sueltos, sin nota), sui-badge (la nota escrita como dato corto)]
+---
+
+# sui-rating
+
+Story: [Atoms/Rating](https://sui-design-system.web.app/?path=/docs/atoms-rating--docs)
+
+## Cuándo usarlo / cuándo no
+
+**Úsalo** para dos cosas distintas:
+
+1. **Mostrar una nota** (de un local, un repartidor, un cliente, una reseña): `readonly`, y con
+   `halfStep` si es un promedio.
+2. **Pedir una nota** (calificar el pedido, al local, al repartidor): interactivo, con
+   `(valueChange)` o un `FormControl`.
+
+**No lo uses** para:
+
+- Un ícono suelto de estrella o corazón (favoritos, «lo guardaron 12»): `sui-icon`.
+- Escribir el número de la nota: eso lo escribe la pantalla con coma («4,7»), no el rating.
+- Recalcular la nota a partir de una lista de reseñas (ver la regla de abajo).
+
+**La nota que se muestra sale del agregado de la entidad** (`rating` y `ratingCount` del
+documento, que calcula la Cloud Function sobre todas las calificaciones), nunca de promediar la
+lista cargada, que viene con tope. La fórmula depende de `n`: otro denominador da otro número.
+**Canon** (CLAUDE.md, «Una nota, una sola cuenta», 26-08-2026).
+
+## Qué variante usar
+
+> **La guía del DS no trae un componente de rating: trae ejemplos** para que cada producto arme
+> el suyo («cada sistema de calificación se comporta distinto»). Los ejemplos son: nota con
+> reseñas («4.5 ∙ 5.2K Ratings · 18 reviews»), celdas, barra de estrellas, barra de corazones,
+> barra de emojis, barra de números del 1 al 5 y barra con área de texto. No trae tamaños, ni
+> do/don't. Lo marcado «según la guía del DS» es que el ejemplo existe; el cuándo es
+> **propuesta, falta aprobación**, salvo lo que diga «canon».
+>
+> Uso medido el 03-10-2026 en `master-pedidos/src/app`: **23 ratings en 13 pantallas**, sin
+> contar prototipos ni vitrinas (`master-preview`, `master-prototipos`, `mockup-sheets-*`,
+> `dx/*`, `_guia-*`, `master-rutina`, `master-medico`, `master-ejercicios`, `dev-index`).
+> `appearance`: 21 `inline` (13 por default, 8 explícitos), 2 `bar`. `type`: 20 `star`,
+> 1 `emoji`, 1 `heart`, 1 dinámico. `size`: 10 `small`, 6 `medium`, 1 `large`, 4 `xlarge`, 2 en
+> `bar` (sin size). 20 son `readonly`.
+
+### `appearance` — para qué
+
+| appearance | cuándo | ejemplo real | fuente |
+|---|---|---|---|
+| `inline` (default), `readonly` | **Mostrar** una nota: la fila de estrellas pelada. | `components/ratings-detail/ratings-detail.html:31` (la nota del local) | según la guía del DS (ejemplo «Rating Review») |
+| `inline`, interactivo | **A discutir.** Pedir la nota en grande (`xlarge`). Cada estrella mide 28 px, por debajo de los 44 que pide un dedo. | `pages/customer/rate-order/rate-order.html:93` y `:166` | propuesta, falta aprobación |
+| `bar` | **Pedir** una nota en el celular: celdas de 64 × 36 fáciles de tocar. | `components/rate-entity-card/rate-entity-card.html:40` | según la guía del DS (ejemplo «Rating Bar») |
+| `cell` | **No usar** hoy (ver abajo). | — | según la guía del DS (ejemplo «Rating Cell») |
+| `bar-area` | **No usar** hoy (ver abajo). | — | según la guía del DS (ejemplo «Rating Bar With Textarea») |
+
+### `type`
+
+| type | cuándo | fuente |
+|---|---|---|
+| `star` (default) | La nota de un pedido, un local, un repartidor o un cliente: la que entra al promedio. | según la guía del DS (ejemplo) · propuesta (cuándo) |
+| `emoji` | Cómo le fue a la persona con la app o con un proceso (no entra a la nota de nadie). Solo en `bar`. Hoy: `components/rate-entity-card/rate-entity-card.html:38`. | según la guía del DS (ejemplo «Single Selectable») · propuesta (cuándo) |
+| `heart` | **No usar** como nota (ver abajo). | según la guía del DS (ejemplo «Rating Bar Heart») |
+| `number` | **No usar** hoy (ver abajo). Solo en `bar`. | según la guía del DS (ejemplo de 1 a 5) |
+
+### `size` (solo cuenta en `inline`)
+
+| size | px | cuándo | fuente |
+|---|---|---|---|
+| `small` | 16 | Web: filas y listas (cada reseña, tablas, historial). | propuesta, falta aprobación |
+| `medium` (default) | 20 | Web: perfil, ficha, detalle. Mobile: filas y listas. | propuesta, falta aprobación |
+| `large` | 24 | Web: la nota grande de un resumen, la card de una calificación enviada. Mobile: perfil y ficha. | propuesta, falta aprobación |
+| `xlarge` | 28 | Extensión SUI. Mobile: la nota grande de un resumen. | propuesta, falta aprobación |
+
+### El resto de las propiedades
+
+| propiedad | valor | cuándo | fuente |
+|---|---|---|---|
+| `readonly` | `true` | **Todo rating que muestra una nota.** Sin él se puede tocar y cambiar. | propuesta, falta aprobación |
+| `halfStep` | `true` | Obligatorio si el valor es un **promedio** (sin él, 4,5 se pinta como 4). Una nota individual es entera y no lo necesita. Solo funciona en `inline` + `readonly`. | según la guía del DS (muestra 4.5) |
+| `value` | `0` | Solo dentro del botón que invita a calificar, junto al texto «Calificar» (`pages/customer/order-history/order-history.html:352`). Suelto, cinco estrellas vacías se leen como «0 estrellas». | propuesta, falta aprobación |
+| `max` | `5` (default) | Siempre 5 en notas: la fórmula de la nota asume 5. | propuesta, falta aprobación |
+| `max` | otro | Solo con `type="number"` (encuesta de 1 a 10). | propuesta, falta aprobación |
+| `alignment` | `inline` (default) | Solo los íconos; el número y el conteo los escribe la pantalla. | propuesta, falta aprobación |
+| `alignment` | `horizontal` | Junto con `reviewLink`. | propuesta, falta aprobación |
+| `alignment` | `vertical` | **No usar** (ver abajo). | propuesta, falta aprobación |
+| `reviewLink` | `{ label, href? }` | Link «Ver 128 reseñas» que abre la hoja de reseñas. Hoy sin usos. | según la guía del DS («18 reviews») |
+| `showValue` | `true` | **No usar** (ver abajo). | propuesta, falta aprobación |
+| `reviewCount` | número | **No usar** (ver abajo). | propuesta, falta aprobación |
+| `emojis` | lista | Dejar el default (cinco caras, de triste a feliz). Cambiarlo rompe la lectura de la escala. | propuesta, falta aprobación |
+| `ariaLabel` | texto | Decir qué se califica: «Califica al repartidor», «Nota del local». El default es «Calificación». | propuesta, falta aprobación |
+| `reason` / `reasonPlaceholder` / `reasonRows` | — | Solo en `bar-area`. **El placeholder va siempre en español**: el default está en inglés. | propuesta, falta aprobación |
+
+**Usos de hoy que rompen la regla:**
+
+- **1 `reviewCount`** (pinta «Ratings» en inglés):
+  `pages/super-admin/master-users/master-user-sheet.html:142`.
+- **1 rating usado como ícono** (`type="heart"` con `max=1` para los favoritos):
+  `components/ratings-detail/ratings-detail.html:45`. Va `sui-icon name="heart-3-fill"`.
+- **A discutir, 2 `inline` interactivos de 28 px** como input:
+  `pages/customer/rate-order/rate-order.html:93` y `:166`. Alternativa: `appearance="bar"`.
+
+## No usar: por qué no hoy y cuándo sí
+
+| qué | por qué no hoy | cuándo sí, en un flujo nuevo |
+|---|---|---|
+| `appearance="cell"` | En el celular `bar` es más clara y más fácil de tocar. | Calificar una sola cosa a pantalla completa en tablet o web. |
+| `appearance="bar-area"` | La calificación de hoy separa la nota, los chips y el comentario. | Una encuesta corta de una sola card: nota + «Cuéntanos qué pasó». |
+| `type="heart"` | La app califica con estrellas; el corazón es favoritos. | «¿Cuánto te gustó?» de una campaña, donde una estrella se leería como la nota del local. |
+| `type="number"` | No hay encuestas de 1 a 10. | «¿Qué tan probable es que nos recomiendes?» con `max=10` (ocupa 640 px de ancho). |
+| `showValue` | Escribe «4.7» con punto; la app escribe «4,7». | Si el DS formatea en `es-PE`. |
+| `reviewCount` | Agrega la palabra «Ratings» en inglés y abrevia «1.2K». | Si el DS traduce la etiqueta. |
+| `alignment="vertical"` | Solo ordena `showValue` y `reviewCount`, que no se usan. | Junto con esos dos, si se arreglan. |
+
+## Tamaño en mobile y en web
+
+Criterio de la app: **en mobile se lee y se toca con el dedo, así que va más grande; en web
+(desktop), más chico.** Mobile es `≤ 767 px`, el mismo corte de `BreakpointsService.isMobile()`
+en master-pedidos. Fuente: canon del dueño (03-10-2026), el mismo patrón que ya usan 27 controles
+de la app.
+
+| uso | mobile | web | fuente |
+|---|---|---|---|
+| Mostrar en una fila o lista | `medium` (20) | `small` (16) | propuesta, falta aprobación |
+| Mostrar en perfil o ficha | `large` (24) | `medium` (20) | propuesta, falta aprobación |
+| La nota grande de un resumen | `xlarge` (28) | `large` (24) | propuesta, falta aprobación |
+| Pedir una nota | `appearance="bar"` (celdas de 64 × 36) | `bar`, o `inline` `large` con mouse | propuesta, falta aprobación |
+
+```ts
+readonly bp = inject(BreakpointsService); // master-pedidos: src/app/services/breakpoints.service.ts
+```
+
+```html
+<sui-rating [value]="local.rating" [readonly]="true" [halfStep]="true"
+  [size]="bp.isMobile() ? 'medium' : 'small'" ariaLabel="Nota del local" />
+```
+
+En `bar` el `size` no cuenta (íconos fijos de 20) y en `cell` tampoco (32): el tamaño por
+plataforma solo se elige en `inline`.
+
+## API
+
+<!-- api:inicio -->
+<!-- generada: no editar a mano — `npm run docs` -->
+
+| input | tipo | default |
+|---|---|---|
+| `appearance` | `'inline' \| 'cell' \| 'bar' \| 'bar-area'` | `'inline'` |
+| `type` | `'star' \| 'heart' \| 'emoji' \| 'number'` | `'star'` |
+| `value` · model, `[(value)]` | `number` | `0` |
+| `max` | `number` | `5` |
+| `size` | `'small' \| 'medium' \| 'large' \| 'xlarge'` | `'medium'` |
+| `readonly` | `boolean` | `false` |
+| `halfStep` | `boolean` | `false` |
+| `showValue` | `boolean` | `false` |
+| `reviewCount` | `number \| null` | `null` |
+| `reviewLink` | `SuiRatingReviewLink \| null` | `null` |
+| `alignment` | `'inline' \| 'vertical' \| 'horizontal'` | `'inline'` |
+| `emojis` | `string[]` | `[ 'pensive-face', 'confused-face', 'neutral-face', 'slightly-smiling-face', 'grinning-face-smiling-eyes', ]` |
+| `ariaLabel` | `string` | `'Calificación'` |
+| `reason` · model, `[(reason)]` | `string` | `''` |
+| `reasonPlaceholder` | `string` | `'Tell us why!'` |
+| `reasonRows` | `number` | `3` |
+
+| output | payload |
+|---|---|
+| `valueChange` | `number` |
+<!-- api:fin -->
+
+Implementa `ControlValueAccessor` sobre `value` (sirve con `formControlName`). `reason` es un
+`model` aparte: no entra al `FormControl`.
+
+## Trampas
+
+- **`showValue`, `reviewCount` y `reviewLink` solo se ven con `alignment="horizontal"` o
+  `"vertical"`.** Con el default `inline` no aparecen.
+- **`reviewCount` agrega «Ratings» en inglés** y `showValue` formatea con punto.
+- **`reasonPlaceholder` viene en inglés** («Tell us why!»).
+- **`halfStep` solo funciona en `inline` + `readonly`.** En un input no hay medias.
+- **En `bar` el `size` no hace nada** (íconos de 20, celdas de 64); en `cell` los íconos miden 32.
+- **En `bar` y `bar-area` se pinta solo la celda elegida**, no las anteriores: no es una fila de
+  estrellas que se llena.
+- `emoji` y `number` **solo se dibujan en `bar`**.
+- `(valueChange)` emite de 1 a `max`, nunca 0; volver a tocar la misma no la quita.
+- El host lleva `role="radiogroup"` y `aria-label`: si la pantalla ya escribe la nota al lado,
+  ponle `aria-hidden="true"` para que no se lea dos veces.
+
+## Ejemplo
+
+```html
+<!-- Mostrar la nota del local (promedio, desde el agregado) -->
+<span class="nota">{{ notaTexto }}</span>
+<sui-rating [value]="local.rating" [readonly]="true" [halfStep]="true" size="small" aria-hidden="true" />
+
+<!-- Pedir la nota al repartidor -->
+<sui-rating appearance="bar" type="star" [(value)]="nota" ariaLabel="Califica al repartidor" />
+```

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

@@ -0,0 +1,144 @@
+---
+name: sui-segmented-control
+selector: sui-segmented-control
+resumen: Píldora de 2 a 4 opciones hermanas donde se elige una y se aplica en el momento
+alternativas: [sui-tab-menu-horizontal (navegar entre secciones de contenido), sui-tab-chips (fila de filtros con muchas opciones), sui-radio-card (elegir una opción de un formulario que se guarda después), sui-button-group (varias opciones a la vez)]
+---
+
+# sui-segmented-control
+
+Story: [Atoms/Segmented Control](https://sui-design-system.web.app/?path=/docs/atoms-segmented-control--docs)
+
+## Cuándo usarlo / cuándo no
+
+**Úsalo** para cambiar entre 2 a 4 modos de **la misma vista**, que se aplican apenas se tocan:
+cuadrícula o lista en el catálogo, el local cuyo horario estás viendo, el rol que vas a invitar.
+
+**No lo uses** para:
+
+- Navegar entre secciones de contenido distinto: `sui-tab-menu-horizontal`.
+- Una fila de filtros con muchas opciones o que scrollea: `sui-tab-chips`.
+- Elegir un valor que se guarda después con un botón: `sui-radio-card` (no se enchufa a un formulario).
+- Varias opciones a la vez: `sui-button-group`.
+- 5 o más opciones: los segmentos se reparten el ancho y los textos se cortan.
+
+Regla corta: **2-4 modos de la misma vista, efecto inmediato → segmented · secciones → tab menu · filtros → tab-chips.**
+
+## Qué variante usar
+
+> **La guía del DS lo define como control para elegir una opción de un conjunto lineal de
+> opciones muy relacionadas «y aplicarla de inmediato»**. Muestra la versión base y la redondeada
+> (`Rounded`). No trae tamaños ni do/don't.
+>
+> Uso medido el 03-10-2026 en `master-pedidos/src/app` (misma exclusión que `sui-badge`):
+> **5 usos en 4 archivos**. Tamaños: 3 `small`, 1 `medium`, 1 sin `size` (`medium`). 1 con solo
+> íconos (vista cuadrícula / lista del catálogo).
+
+### `size`
+
+| size | cuándo | fuente |
+|---|---|---|
+| `xlarge` | Mobile: es el único que se acerca a los 44 px de área táctil (segmento de 40 px). | canon (dueño: «componentes grandes», 28-09-2026, y tamaño por plataforma, 03-10-2026) |
+| `large` | No aporta: 32 px, chico para el dedo y grande para web. | propuesta, falta aprobación |
+| `medium` (default) | Web, junto a títulos o filtros. | canon (dueño: tamaño por plataforma, 03-10-2026); el valor exacto es propuesta |
+| `small` | Web, solo íconos en una barra de herramientas (cuadrícula / lista). | propuesta, falta aprobación |
+
+### Ítems (`tabs`)
+
+| qué | cuándo | fuente |
+|---|---|---|
+| texto | Lo normal. Una o dos palabras por segmento («Por distancia», «Precio único»). | según la guía del DS (ejemplos con texto) |
+| `icon` + texto | Cuando el ícono ayuda a reconocer el modo rápido. | propuesta, falta aprobación |
+| `iconOnly` | Solo para modos universales (cuadrícula / lista). El `label` pasa a ser el nombre accesible: escríbelo igual. | propuesta, falta aprobación |
+| `disabled` (por ítem) | Un modo que existe pero no aplica todavía. | propuesta, falta aprobación |
+
+**Usos de hoy que rompen las reglas:**
+
+- **2 dentro de un borrador que se guarda después (a discutir):**
+  `pages/super-admin/master-settings/master-settings.html:296` (modo de envío: «Por distancia» /
+  «Precio único») y `:329` («Por calle» / «En línea recta»). La guía dice que se aplica de
+  inmediato; aquí la elección espera al «Guardar». Es trabajo de `sui-radio-card`.
+- **1 con textos largos, a verificar en mobile:** `pages/super-admin/master-roles/master-roles.html:47`
+  («Administrador de ciudad» / «Jefe de operaciones»). Por ancho de texto quedan apretados cerca
+  del borde a 390 px; no se midió en la pantalla real.
+- **2 en `small` con texto** (la propuesta deja `small` solo para íconos): `master-settings.html:296`
+  y `:329`. El tercero en `small`, `pages/products/products.html:80`, está bien: solo íconos.
+- **5 sin tamaño por plataforma** (todos fijos): ninguno cambia a `xlarge` en mobile. Ejemplo:
+  `pages/driver/driver-schedule/driver-schedule.html:32` (`size="medium"` en una pantalla del
+  repartidor, que se usa en el teléfono).
+
+## Tamaño en mobile y en web
+
+Alto de cada segmento: `small` 28 px, `medium` 28 px, `large` 32 px, `xlarge` 40 px (el control
+suma 8 px de borde interno).
+
+| uso | mobile | web |
+|---|---|---|
+| modos con texto (local del horario, rol) | `xlarge` (segmento de 40 px) | `medium` |
+| solo íconos en una barra (cuadrícula / lista) | `xlarge` | `small` |
+
+```html
+<sui-segmented-control [size]="bp.isMobile() ? 'xlarge' : 'medium'" … />
+```
+
+El más grande llega a 40 px por segmento: queda 4 px corto de los 44 px de área táctil. Es el
+mejor disponible para mobile.
+
+## «No usar»: por qué no hoy y cuándo sí
+
+| qué | por qué no hoy | cuándo sí, en un flujo nuevo |
+|---|---|---|
+| `large` | 32 px: no llega al dedo en mobile y sobra en web | un control dentro de un sheet de mobile muy apretado donde `xlarge` no entra |
+| `disabled` por ítem | ningún modo está bloqueado | un modo que depende del plan («Reportes completos» en plan básico) |
+| 5+ ítems | se cortan los textos | nunca: pasa a `sui-tab-chips` |
+
+## API
+
+<!-- api:inicio -->
+<!-- generada: no editar a mano — `npm run docs` -->
+
+| input | tipo | default |
+|---|---|---|
+| `tabs` | `SuiSegmentedControlItem<T>[]` | — (requerido) |
+| `active` · model, `[(active)]` | `T` | `undefined` |
+| `size` | `'small' \| 'medium' \| 'large' \| 'xlarge'` | `'medium'` |
+
+| output | payload |
+|---|---|
+| `tabChange` | `T` |
+<!-- api:fin -->
+
+```ts
+interface SuiSegmentedControlItem<T = string> {
+  value: T;
+  label: string;
+  icon?: string;       // RemixIcon, 20 px fijo
+  iconOnly?: boolean;  // requiere icon; label pasa a aria-label
+  disabled?: boolean;
+}
+```
+
+## Trampas
+
+- **Sin `active` igual dibuja el fondo blanco bajo el primer ítem**, aunque ninguno esté elegido.
+  Pásale siempre un valor inicial.
+- **Emite dos veces**: `tabChange` y `activeChange`. Con `[(active)]` no hace falta `(tabChange)`.
+- **No implementa `ControlValueAccessor`**: no va con `formControlName`.
+- **Ocupa todo el ancho del padre.** Para que no se estire, envuélvelo con un `max-width`.
+- El indicador se mide con el DOM: si arranca oculto queda en ancho 0 hasta que algo cambie de tamaño.
+- `iconOnly` sin `icon` no dibuja nada. El ícono mide 20 px en todos los tamaños.
+- `disabled` es por ítem; no hay `disabled` del control entero.
+- Los tamaños son extensión de SUI: la guía tiene uno solo. Su versión redondeada (`Rounded`)
+  no existe en SUI.
+
+## Ejemplo
+
+```html
+<div style="max-width: 320px">
+  <sui-segmented-control
+    [size]="bp.isMobile() ? 'xlarge' : 'small'"
+    [tabs]="[{ value: 'grid', label: 'Vista cuadrícula', icon: 'layout-grid-line', iconOnly: true },
+             { value: 'list', label: 'Vista lista', icon: 'list-unordered', iconOnly: true }]"
+    [(active)]="vista" />
+</div>
+```

package/docs/sui-slider/README.md

@@ -0,0 +1,143 @@
+---
+name: sui-slider
+selector: sui-slider
+resumen: Barra para elegir un valor, o un rango, dentro de una escala donde importa ver la posición
+alternativas: [sui-counter-input (cantidad chica y exacta con − y +), sui-input type="number" (valor exacto o rango abierto), sui-progress-bar (avance de solo lectura)]
+---
+
+# sui-slider
+
+Story: [Atoms/Slider](https://sui-design-system.web.app/?path=/docs/atoms-slider--docs)
+
+## Cuándo usarlo / cuándo no
+
+**Úsalo** cuando el valor vive en una escala con mínimo y máximo y **ver dónde cae** ayuda a
+decidir: el radio de cobertura del repartidor en km, un rango de precios en un filtro, un
+porcentaje.
+
+**No lo uses** para:
+
+- Una cantidad chica y exacta (unidades, comensales): `sui-counter-input`.
+- Un valor exacto o sin tope (un monto, un DNI): `sui-input`.
+- Mostrar avance sin que se pueda mover: `sui-progress-bar`.
+- Dinero que se cobra: el arrastre no da precisión; va un `sui-input type="amount"`.
+
+Regla corta: **escala con tope y la posición importa → slider · número exacto → input · cantidad chica → counter.**
+
+## Qué variante usar
+
+> **La guía del DS lo define como selección «precisa de un valor dentro de un rango»** y muestra
+> tres ejemplos: valor único, rango (dos manijas) y con tooltip. No dice cuándo va cada uno.
+>
+> Uso medido el 03-10-2026 en `master-pedidos/src/app` (misma exclusión que `sui-badge`):
+> **1 uso**, `components/driver-coverage-modal/driver-coverage-modal.html:83` (radio de
+> cobertura, 1–15 km, con `label`, `amount` y `tooltip`). Más **1 `<input type="range">` nativo**.
+
+### `type`
+
+| type | cuándo | fuente |
+|---|---|---|
+| `single` (default) | Un valor: radio de cobertura, porcentaje. | según la guía del DS |
+| `range` | Un mínimo y un máximo en la misma escala: rango de precios de un filtro. Una sola barra con dos manijas, nunca dos sliders. | según la guía del DS (existe); el «cuándo» es propuesta |
+
+### Las piezas
+
+| prop | cuándo | fuente |
+|---|---|---|
+| `label` | Siempre que el slider no esté dentro de un campo que ya lo titula. Sin `label` desaparece toda la fila de arriba, `amount` incluido. | propuesta, falta aprobación |
+| `amount` | El valor con su unidad, a la derecha del label: «12 km», «S/ 10 – S/ 40». Sin `amount` escribe el número pelado. | propuesta, falta aprobación |
+| `sublabel` | Una precisión corta junto al label: «(máximo 15)». | propuesta, falta aprobación |
+| `tooltip` | Solo **sin** `amount`: el número flota sobre la manija mientras se arrastra. Con `amount` repite el valor y sin unidad. | según la guía del DS (existe); el «cuándo» es propuesta |
+| `tooltipAlways` | No usar (ver abajo). | propuesta, falta aprobación |
+| `min` / `max` / `step` | La escala real del negocio (1–15 km, paso 1). | API |
+| `disabled` | La escala existe pero hoy no se puede mover (falta un dato antes). | propuesta, falta aprobación |
+| `size` | `medium` (default, Figma): manija 16, riel 6, label 12/16. `large`: manija 24, riel 8, punto interno 8, label 14/20 — para mobile. | `medium`: según la guía del DS · `large`: canon (aprobado por el dueño, 03-10-2026), extensión SUI |
+
+**Usos de hoy que rompen la propuesta:**
+
+- **1 con `amount` y `tooltip` a la vez:** `components/driver-coverage-modal/driver-coverage-modal.html:83`
+  muestra «12 km» arriba y «12» flotando al arrastrar.
+- **1 nativo → `sui-slider`:** `components/image-cropper/image-cropper.html:57` (zoom del recorte).
+  A discutir: es un control de herramienta sin label, con botones − y + al lado.
+
+## Tamaño en mobile y en web
+
+En mobile se toca con el dedo: el área táctil tiene que medir **44 px o más**. En web, con mouse,
+va un tamaño más chico. La app ya lo resuelve con `BreakpointsService`
+(`src/app/services/breakpoints.service.ts`, mobile = hasta 767 px). Regla del dueño, 03-10-2026.
+
+| uso | mobile | web | fuente |
+|---|---|---|---|
+| slider con label (radio de cobertura, filtro de precio) | `large` (manija 24, riel 8) | `medium` (manija 16, riel 6) | canon (aprobado por el dueño, 03-10-2026) |
+
+```html
+<sui-slider [size]="bp.isMobile() ? 'large' : 'medium'" label="Radio de cobertura" amount="12 km"
+            [min]="1" [max]="15" [(value)]="radioKm" />
+```
+
+Toda la barra responde al toque (24 de alto en `large`), así que no hace falta acertarle a la
+manija. Igual la barra mide menos de 44: el slider necesita aire arriba y abajo en la fila. La
+manija en 0 o en 100 sobresale media manija (12 px en `large`) del borde de la barra: el
+contenedor tiene que tener margen lateral.
+
+## «No usar»: por qué no hoy y cuándo sí
+
+| qué | por qué no hoy | cuándo sí, en un flujo nuevo |
+|---|---|---|
+| `type="range"` (0 usos) | ningún filtro de la app pide mínimo y máximo | un filtro de rango de precios o de distancia en la búsqueda del cliente |
+| `tooltipAlways` | un número fijo encima de la manija tapa el contenido de arriba y repite el `amount` | un slider sin `label` dentro de una herramienta (zoom del recorte), donde el número es lo único que orienta |
+
+## API
+
+<!-- api:inicio -->
+<!-- generada: no editar a mano — `npm run docs` -->
+
+| input | tipo | default |
+|---|---|---|
+| `type` | `'single' \| 'range'` | `'single'` |
+| `size` | `'medium' \| 'large'` | `'medium'` |
+| `min` | `number` | `0` |
+| `max` | `number` | `100` |
+| `step` | `number` | `1` |
+| `label` | `string` | `''` |
+| `sublabel` | `string` | `''` |
+| `amount` | `string \| null` | `null` |
+| `tooltip` | `boolean` | `false` |
+| `tooltipAlways` | `boolean` | `false` |
+| `disabled` | `boolean` | `false` |
+| `value` | `number` | `0` |
+| `minValue` | `number` | `0` |
+| `maxValue` | `number` | `0` |
+
+| output | payload |
+|---|---|
+| `valueChange` | `number` |
+| `minValueChange` | `number` |
+| `maxValueChange` | `number` |
+<!-- api:fin -->
+
+Implementa `ControlValueAccessor` **solo para `single`**.
+
+## Trampas
+
+- **`label=""` borra toda la fila**, `amount` incluido. No hay forma de tener solo el valor.
+- **El tooltip va 28 px arriba de la manija**: deja aire arriba o queda cortado.
+- En `range`, `amount` vacío escribe «min–max» con guion largo; el formulario no lo cubre: usa
+  `[(minValue)]` y `[(maxValue)]`.
+- Con `formControlName` ignora `[value]`. No mezcles las dos formas.
+- `value` es input + output (`[(value)]` funciona), no un model.
+- El punto de la manija queda **gris** cuando el valor está en el mínimo: es a propósito.
+- Mide el ancho con el DOM: si arranca oculto (`display: none`, una pestaña cerrada) el arrastre
+  calcula mal hasta que se muestra.
+- Las flechas, Inicio y Fin lo mueven con teclado.
+
+## Ejemplo
+
+```html
+<sui-slider
+  label="Radio de cobertura"
+  [amount]="radioKm() + ' km'"
+  [min]="1" [max]="15" [step]="1"
+  [value]="radioKm()"
+  (valueChange)="radioKm.set($event)" />
+```