@ajuarezso/sui-stencil 0.0.0-stage → 0.1.0

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

@@ -0,0 +1,254 @@
+---
+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
+
+<!-- generado por scripts/gen-docs.mjs — no editar a mano; `npm run docs` -->
+
+> **De dónde sale este doc.** El criterio es el del SUI Angular (`sui-radio-label`); la API es la de este
+> paquete, leída del código. Los ejemplos se pasaron de Angular de forma mecánica: lo literal va como
+> atributo (`only-icon`, `size="large"`), lo dinámico entre llaves (`size={expr}` → `el.size = expr`)
+> y los eventos como `onValueChange={…}` → `el.addEventListener('valueChange', …)`. `@if`, `@for` y
+> `<ng-template>` quedan como en Angular: se leen como pseudocódigo.
+>
+> **La API de aquí no es igual a la de Angular.** Lo que el texto nombre y figure en «Diferencias con
+> el SUI Angular» (dentro de API) aquí no existe.
+
+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:567`). La tarjeta da el área táctil; un radio-label sin descripción
+  mide 28 px de alto aun en `xlarge`.
+- 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`), revisado
+> el 06-10-2026: **2 usos**, las franjas horarias del checkout (con `flip`) y los distritos de
+> «Trabaja con nosotros». 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 canon (aprobado por el dueño, 05-10-2026, bloque B4) |
+| `badge` | Solo novedad. Con string sale naranja `light`: pasa el objeto. | según la guía del DS (pieza «NEW»); el color es canon (aprobado por el dueño, 05-10-2026, bloque B3) |
+| `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 se quedan en 12/16 (canon, dueño 04-10-2026); el badge sin `size` propio sube a `medium` / `large` y el link a `medium`. `2xlarge`: círculo 28 con la fila a 44 (su uso por dispositivo está pendiente, ver D16). 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:874`
+  (motivos de cancelación del repartidor). Por la pantalla hermana va a `sui-radio-card
+  type="basic"` como `pages/orders/orders.html:567`, no a este componente.
+- `pages/customer/checkout/checkout.html:474` 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. Va con `bp.isMobile() ? '2xlarge' : 'medium'`: en la computadora baja a
+  `medium`, que D16 ya no usa (va `large`, dueño 06-10-2026). El `2xlarge` del teléfono está
+  pendiente (ver D16).
+- `pages/customer/trabaja/trabaja.html:150` va con `bp.isMobile() ? 'xlarge' : 'large'`, que es lo
+  mismo que `bp.controlSize()`: cumple la fila de D16. Sin descripción la fila mide 28 en el
+  teléfono, no 44; si pasa a `2xlarge` está pendiente (ver D16).
+
+## 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; sin descripción la fila mide 28, no 44: `2xlarge` pendiente, ver D16) | `large` (círculo 24, label 16/24) | D16 (fila de checkbox, radio y switch; dueño 06-10-2026) |
+| lista densa de desktop | — | `large` (círculo 24): no baja a `medium` | D16, dueño 06-10-2026 |
+| opciones con mucho contexto cada una | `sui-radio-card` con `bp.controlSize()` | `sui-radio-card` con `bp.controlSize()` | canon (aprobado por el dueño, 05-10-2026, bloque B2) |
+
+```html
+<sui-radio-label value="recojo" size={bp.controlSize()} label="Recojo en tienda" />
+```
+
+| size | círculo | label | sublabel / descripción | alto de la fila sin descripción |
+|---|---|---|---|---|
+| `medium` (default, Figma) | 20 | 14/20 | 12/16 | 20 |
+| `large` | 24 | 16/24 | 12/16 | 24 |
+| `xlarge` | 28 | 16/24 | 12/16 | 28 |
+| `2xlarge` | 28 | 16/24 | 12/16 | **44** (`min-height`) |
+
+`2xlarge` (canon, dueño 04-10-2026: piso táctil 44 en el teléfono) tiene el mismo círculo de 28 y
+el mismo label que `xlarge`, pero la fila mide 44 como mínimo con todo centrado en vertical, y el
+texto secundario se queda en 12 (regla del 03-10). Con descripción la fila ya pasa de 44 y vuelve a
+alinearse arriba. Si reemplaza a `xlarge` en el celular y la tablet está **pendiente** (ver D16).
+
+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).
+
+Sin descripción, la fila en `xlarge` mide 28 px (lo que mide el círculo):
+`2xlarge` la lleva a 44 (pendiente, ver D16). Con descripción llega sola: 2 + 24 (label) + 4 + 16 (descripción) = 46 px
+en `xlarge` y en `2xlarge`.
+
+**Regla de tamaños aplicada (canon, dueño 04-10-2026):** en `large` y `xlarge` el label sube a
+16/24 y el sublabel y la descripción se quedan en 12/16, igual que `sui-switch-label`. Antes subían
+a 14/20. El badge y el link siguen creciendo con el size.
+
+### Por dispositivo (D16)
+
+| dispositivo | size | nota |
+|---|---|---|
+| celular chico (< 380) | `xlarge` | círculo de 28 |
+| celular (380–767) | `xlarge` | |
+| tablet táctil (`pointer: coarse`) | `xlarge` | `bp.controlSize()` mira solo el ancho: un iPad de 768 o más recibe `large` hasta que el helper mire el puntero |
+| computadora (`pointer: fine`) | `large` | un paso menos que el celular; no baja a `medium` (D16, dueño 06-10-2026) |
+
+Ultrawide: igual que la computadora (`large`).
+
+En master-pedidos: `size={bp.controlSize()}` (`xlarge` hasta 767 px, `large` desde ahí). La
+expresión exacta de D16, con la tablet, es `bp.tactil() ? 'xlarge' : 'large'`.
+
+**Pendiente: `2xlarge` en el celular y la tablet.** Sin descripción, `xlarge` deja la fila en 28 px,
+por debajo del piso de 44. El dueño aprobó `2xlarge` el 04-10-2026 justo para eso (fila de 44), pero
+la fila de D16 dice `xlarge` para toda la familia y ningún helper devuelve `2xlarge`. Falta que el
+dueño decida si en este componente el celular y la tablet pasan a `2xlarge` (y que D16 y
+`bp.controlSize()` lo recojan). Mientras no lo decida, manda la fila de D16: `xlarge`.
+
+## «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` -->
+
+| prop | atributo | tipo | default |
+|---|---|---|---|
+| `badge` | `badge` | `SuiBadgeConfig \| null \| string` | `null` |
+| `checked` | `checked` | `boolean` | `false` |
+| `description` | `description` | `null \| string` | `null` |
+| `disabled` | `disabled` | `boolean` | `false` |
+| `flip` | `flip` | `boolean` | `false` |
+| `label` | `label` | `string` | `''` |
+| `link` | `link` | `SuiLinkConfig \| null \| string` | `null` |
+| `size` | `size` | `"2xlarge" \| "large" \| "medium" \| "xlarge"` | `'medium'` |
+| `sublabel` | `sublabel` | `null \| string` | `null` |
+| `value` | `value` | `string` | — (requerido) |
+
+| evento | `event.detail` |
+|---|---|
+| `linkClick` | `MouseEvent` |
+| `selected` | `string` |
+| `suiChange` | `boolean` |
+| `suiRadioSelect` | `string` |
+
+| método | firma |
+|---|---|
+| `setChecked` | `setChecked(checked: boolean, tabStop?: boolean) => Promise<void>` |
+
+### Diferencias con el SUI Angular
+
+- **Eventos de Angular que aquí no existen:** `checkedChange`
+- **Eventos solo de aquí:** `suiChange`, `suiRadioSelect`
+<!-- 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` + `checkedChange`.
+- **`size` arranca en `medium`** (círculo de 20 px): sin `size={bp.controlSize()}` choca con la
+  regla de controles grandes (dueño, 28-09-2026) y con D16. Aun con `xlarge`, la fila sin
+  descripción queda en 28: si pasa a `2xlarge` está pendiente (ver D16).
+- **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.
+  Tampoco foco ni lector: va con `focusable="false"`, `aria-hidden` e `inert` (sin `inert`, axe
+  marca nested-interactive por su `tabindex="-1"`), y el radio es el contenedor
+  interno `.sui-radio-label__control` (círculo + textos), con nombre = `label` y descripción =
+  `description`. El link va fuera de él, como hermano (un botón dentro de un radio también es
+  nested-interactive, 09-10-2026); se ve igual, debajo del texto. Hasta el 04-10-2026 cada opción eran dos
+  paradas de Tab y dos radios anidados.
+- En `sui-radio-group`, un solo tab stop y flechas ↑ ↓ ← → (revisión 04-10-2026).
+- 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.
+
+## Bien y mal
+
+Sin size
+
+```html
+<!-- ❌ mal: sin size queda en medium, círculo de 20 en el teléfono y en la computadora -->
+<sui-radio-label value={d} label={d} />
+```
+
+```html
+<!-- ✅ bien -->
+<sui-radio-label size={bp.controlSize()} value={d} label={d} />
+```
+
+Franjas horarias en la computadora
+
+```html
+<!-- ❌ mal: medium en la computadora; D16 no baja de large (pages/customer/checkout/checkout.html:474) -->
+<sui-radio-label size={bp.isMobile() ? '2xlarge' : 'medium'} value={'' + f.inicioMs}
+  label={etiquetaFranja(f)} flip disabled={!f.disponible} />
+```
+
+```html
+<!-- ✅ bien (si el teléfono pasa a 2xlarge está pendiente, ver D16) -->
+<sui-radio-label size={bp.controlSize()} value={'' + f.inicioMs}
+  label={etiquetaFranja(f)} flip disabled={!f.disponible} />
+```
+
+Link sin descripción
+
+```html
+<!-- ❌ mal: link solo se dibuja con description; «Ver precios» no aparece -->
+<sui-radio-label value="pro" label="Plan Pro" link={{ label: 'Ver precios', href: '/precios' }} />
+```
+
+```html
+<!-- ✅ bien -->
+<sui-radio-label size={bp.controlSize()} value="pro" label="Plan Pro"
+  description="Facturación mensual." link={{ label: 'Ver precios', href: '/precios' }} />
+```
+
+## Ejemplo
+
+```html
+<sui-radio-group ngModel={motivo} onNgModelChange={(e) => (motivo = e.detail)} class="lista-vertical">
+  @for (m of motivos; track m) {
+    <sui-radio-label size={bp.controlSize()} value={m} label={m} />
+  }
+</sui-radio-group>
+```

package/docs/sui-rating/README.md

@@ -0,0 +1,325 @@
+---
+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
+
+<!-- generado por scripts/gen-docs.mjs — no editar a mano; `npm run docs` -->
+
+> **De dónde sale este doc.** El criterio es el del SUI Angular (`sui-rating`); la API es la de este
+> paquete, leída del código. Los ejemplos se pasaron de Angular de forma mecánica: lo literal va como
+> atributo (`only-icon`, `size="large"`), lo dinámico entre llaves (`size={expr}` → `el.size = expr`)
+> y los eventos como `onValueChange={…}` → `el.addEventListener('valueChange', …)`. `@if`, `@for` y
+> `<ng-template>` quedan como en Angular: se leen como pseudocódigo.
+>
+> **La API de aquí no es igual a la de Angular.** Lo que el texto nombre y figure en «Diferencias con
+> el SUI Angular» (dentro de API) aquí no existe.
+
+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 está
+> aprobado donde dice «canon»; lo que sigue en propuesta espera decisión.
+>
+> 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 | Pedir la nota en grande: en el teléfono y la tablet con `size="2xlarge"` (estrellas de 32 en botones de 44 × 44); en la computadora, `medium`. | `pages/customer/rate-order/rate-order.html:95` y `:169` (hoy `2xlarge` / `xlarge`, cortado con `bp.isMobile()`) | teléfono: canon (dueño, 04-10-2026): piso táctil 44 · computadora: D16, dueño 05-10-2026 (antes `xlarge`) · el «cuándo inline vs bar» sigue como propuesta |
+| `bar` | **Pedir** una nota en el celular: con `size="2xlarge"` las celdas miden 64 × 44 (36 en los demás sizes). | `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) · canon (aprobado por el dueño, 05-10-2026, bloque B2) (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») · canon (aprobado por el dueño, 05-10-2026, bloque B2) (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 | **No se usa**: es chico. Las filas y listas de la computadora (cada reseña, tablas, historial) van en `medium`. | D16, dueño 05-10-2026 (antes «web: filas y listas», propuesta) |
+| `medium` (default) | 20 | Computadora, tablet y celular chico: filas, listas, perfil, ficha y detalle. | D16, dueño 05-10-2026 |
+| `large` | 24 | Celular (380–767): filas, listas, perfil y ficha (un paso más que la computadora). Computadora: la nota grande de un resumen, la card de una calificación enviada. | celular: D16, dueño 05-10-2026 · resumen en la computadora: 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. | canon (aprobado por el dueño, 05-10-2026, bloque B8) |
+| `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». | canon (aprobado por el dueño, 05-10-2026, bloque B8) |
+| `max` | `5` (default) | Siempre 5 en notas: la fórmula de la nota asume 5. | canon (aprobado por el dueño, 05-10-2026, bloque B9) |
+| `max` | otro | Solo con `type="number"` (encuesta de 1 a 10). | canon (aprobado por el dueño, 05-10-2026, bloque B9) |
+| `alignment` | `inline` (default) | Solo los íconos; el número y el conteo los escribe la pantalla. | canon (aprobado por el dueño, 05-10-2026, bloque B2) |
+| `alignment` | `horizontal` | Junto con `reviewLink`. | canon (aprobado por el dueño, 05-10-2026, bloque B2) |
+| `alignment` | `vertical` | **No usar** (ver abajo). | canon (aprobado por el dueño, 05-10-2026, bloque B2) |
+| `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). | canon (aprobado por el dueño, 05-10-2026, bloque B6) |
+| `emojis` | lista | Dejar el default (cinco caras, de triste a feliz). Cambiarlo rompe la lectura de la escala. | canon (aprobado por el dueño, 05-10-2026, bloque B9) |
+| `ariaLabel` | texto | Decir qué se califica: «Califica al repartidor», «Nota del local». El default es «Calificación». | canon (aprobado por el dueño, 05-10-2026, bloque B5) |
+| `reason` / `reasonPlaceholder` / `reasonRows` | — | Solo en `bar-area`. El placeholder por defecto es «Cuéntanos por qué» (03-10-2026). | según el código |
+
+**Usos de hoy que rompen la regla:**
+
+- **1 `reviewCount`** (hasta el 03-10-2026 pintaba «Ratings» en inglés; ahora «calificaciones»):
+  `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 en la computadora** (en el teléfono ya van en `2xlarge`) como input:
+  `pages/customer/rate-order/rate-order.html:95` y `:169`. 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` | Abrevia «1.2K calificaciones» (la etiqueta está en español desde 03-10-2026). | Una lista de locales donde el conteo exacto no importa. |
+| `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: **D16, tamaño por dispositivo** (canon, dueño, 05-10-2026), que reemplaza al
+«tamaño por plataforma» del 03-10-2026 (mobile grande, web chico). La columna «mobile» es el celular de
+380 px o más y, en lo que se toca, también la tablet (`pointer: coarse`). La columna «web» es la
+computadora (`pointer: fine`) y, en lo que no se toca, también la tablet. En el celular chico
+(< 380 px) va `medium` a la vista, sin achicar el área de 44 de lo que se toca. **Nada en `small` ni
+`xsmall`**, salvo lo que el componente solo tiene en chico. En la app, `bp.isMobile()` mira solo el
+ancho (≤ 767 px); `bp.celular()` (380–767) y `bp.tactil()` (celular o pantalla táctil) ya miran los
+380 px y el puntero: son las dos señales que usa este componente (ver «Por dispositivo (D16)»).
+
+| uso | mobile | web | fuente |
+|---|---|---|---|
+| Mostrar en una fila o lista | `large` (24) | `medium` (20) | D16, dueño 05-10-2026 (antes `medium` / `small`) |
+| Mostrar en perfil o ficha | `large` (24) | `medium` (20) | D16, dueño 05-10-2026 |
+| La nota grande de un resumen | `xlarge` (28) | `large` (24) | propuesta, falta aprobación |
+| Pedir una nota | `2xlarge`: `inline` (estrellas de 32 en botones de 44 × 44) o `bar` (celdas de 64 × 44) | `bar` (64 × 36), o `inline` `medium` con mouse | canon (dueño, 04-10-2026): piso táctil 44 en el teléfono · web: D16, dueño 05-10-2026 (lo que se toca va `medium` en la computadora; antes `large`, propuesta) |
+
+```ts
+readonly bp = inject(BreakpointsService); // master-pedidos: src/app/services/breakpoints.service.ts
+```
+
+```html
+<sui-rating value={local.rating} readonly half-step
+  size={bp.celular() ? 'large' : 'medium'} aria-label="Nota del local" />
+```
+
+En `bar` el `size` no cuenta salvo `2xlarge` (celda de 44 de alto en vez de 36; íconos fijos de 20
+y número en 16), y en `cell` tampoco (32): el resto del tamaño por plataforma se elige en `inline`.
+
+| size | `inline`: glyph · lo que se toca | `bar`: alto de celda |
+|---|---|---|
+| `small` | 16 · 16 | 36 |
+| `medium` (default) | 20 · 20 | 36 |
+| `large` | 24 · 24 | 36 |
+| `xlarge` | 28 · 28 | 36 |
+| `2xlarge` | 32 · **44 × 44** (padding 6, sin gap entre estrellas) | **44** |
+
+`2xlarge` (canon (dueño, 04-10-2026): piso táctil 44 en el teléfono) es para **pedir** la nota en el teléfono. Para mostrar una
+nota de solo lectura sigue `medium`/`large`.
+
+Área táctil de cada forma de **pedir** la nota, medida en el `.scss`: `inline` `xlarge` 28 px
+(el botón es el ícono, sin padding) y `2xlarge` 44 px (32 + 6 + 6); `bar` 36 px (8 + 20 + 8 de cada
+celda) y en `2xlarge` 44 (12 + 20 + 12); `cell` 58 px (12 + 32 + 12 de padding y 2 de borde).
+
+### Por dispositivo (D16)
+
+`rating` no está en la tabla por componente de D16 (dueño, 05-10-2026), así que va por la regla
+general y tiene **dos filas según el modo**: mostrar una nota (`readonly`) es «lo que no se toca» y
+pedirla es «lo que se toca».
+
+| dispositivo | size | nota |
+|---|---|---|
+| celular chico (< 380 px) | mostrar `medium` · pedir `2xlarge` | D16 pide `medium` con área de 44 para pedir, pero solo `2xlarge` llega a 44: hasta que el DS estire el área (nota ¹ de D16), se queda el grande |
+| celular (380–767 px) | mostrar `large` · pedir `2xlarge` | mostrar sube un paso (P1 b); pedir: `inline` 44 × 44 o `bar` 64 × 44 |
+| tablet táctil (`pointer: coarse`) | mostrar `medium` · pedir `2xlarge` | se pide con el dedo: mismo piso de 44 que el celular |
+| computadora (`pointer: fine`) | mostrar `medium` · pedir `medium` | en `bar` el `size` no cuenta salvo `2xlarge` (celdas de 36) |
+
+Ultrawide (≥ 1920 px): igual que la computadora. `small` no se usa en ningún dispositivo. La nota
+grande de un resumen va un paso arriba de esta tabla (`large` en la computadora, `xlarge` en el
+celular), y eso sigue en propuesta.
+
+En master-pedidos, sin helper propio:
+
+- mostrar: `size={bp.celular() ? 'large' : 'medium'}` (resumen, en propuesta: `bp.celular() ? 'xlarge' : 'large'`)
+- pedir: `size={bp.tactil() ? '2xlarge' : 'medium'}`
+
+## API
+
+<!-- api:inicio -->
+<!-- generada: no editar a mano — `npm run docs` -->
+
+| prop | atributo | tipo | default |
+|---|---|---|---|
+| `alignment` | `alignment` | `"horizontal" \| "inline" \| "vertical"` | `'inline'` |
+| `appearance` | `appearance` | `"bar" \| "bar-area" \| "cell" \| "inline"` | `'inline'` |
+| `ariaLabel` | `aria-label` | `string` | `'Calificación'` |
+| `disabled` | `disabled` | `boolean` | `false` |
+| `emojis` | — (solo por propiedad JS) | `string[]` | `[
+  'pensive-face',
+  'confused-face',
+  'neutral-face',
+  'slightly-smiling-face',
+  'grinning-face-smiling-eyes',
+]` |
+| `halfStep` | `half-step` | `boolean` | `false` |
+| `max` | `max` | `number` | `5` |
+| `readonly` | `readonly` | `boolean` | `false` |
+| `reason` | `reason` | `string` | `''` |
+| `reasonPlaceholder` | `reason-placeholder` | `string` | `'Cuéntanos por qué'` |
+| `reasonRows` | `reason-rows` | `number` | `3` |
+| `reviewCount` | `review-count` | `null \| number` | `null` |
+| `reviewLink` | — (solo por propiedad JS) | `SuiRatingReviewLink \| null` | `null` |
+| `showValue` | `show-value` | `boolean` | `false` |
+| `size` | `size` | `"2xlarge" \| "large" \| "medium" \| "small" \| "xlarge"` | `'medium'` |
+| `type` | `type` | `"emoji" \| "heart" \| "number" \| "star"` | `'star'` |
+| `value` | `value` | `number` | `0` |
+
+| evento | `event.detail` |
+|---|---|
+| `reasonChange` | `string` |
+| `valueChange` | `number` |
+
+### Diferencias con el SUI Angular
+
+- **Props solo de aquí:** `disabled`
+<!-- api:fin -->
+
+<!-- textos:inicio -->
+### Textos
+
+Lo que el componente escribe solo sale de `provideSuiTextos` (español por defecto, se cambia en vivo; ver `docs/TEXTOS.md`). El input de la última columna le gana al texto global.
+
+| clave | por defecto | se pisa con |
+|---|---|---|
+| `calificacion.una` | calificación | — |
+| `calificacion.varias` | calificaciones | — |
+| `calificacion.nombre` | Calificación | `ariaLabel` |
+| `calificacion.motivo` | Cuéntanos por qué | `reasonPlaceholder` |
+| `calificacion.nota` | {nombre}: {valor} de {max} | — |
+<!-- textos: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 «calificaciones»** (en singular con 1; antes «Ratings») y `showValue`
+  formatea con punto.
+- **`reasonPlaceholder` por defecto dice «Cuéntanos por qué»** (hasta el 03-10-2026, «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.
+- **Roles (04-10-2026):** con `readonly` es una nota, no una pregunta: el host es `role="img"` con
+  «Calificación: 4,5 de 5» (más «, 120 calificaciones» si hay `reviewCount`), sin radios adentro; con
+  `reviewLink` pasa a `role="group"` para que el link siga alcanzable. Interactivo es
+  `role="radiogroup"` con un solo tab stop: → ↓ suben la nota, ← ↑ la bajan (como un radio
+  nativo), Home/End van a 1 y al máximo, sin vuelta. Cada flecha elige y emite `valueChange`. Si
+  la pantalla ya escribe la nota al lado, ponle `aria-hidden="true"` para que no se lea dos veces.
+
+## Bien y mal
+
+Lo favorito no es una nota
+
+```html
+<!-- ❌ mal: un rating de un corazón como ícono (components/ratings-detail/ratings-detail.html:45) -->
+<sui-rating type="heart" appearance="inline" readonly value="1" max="1" />
+```
+
+```html
+<!-- ✅ bien: ícono del mismo tamaño que las estrellas de al lado -->
+<sui-icon name="heart-3-fill" size={bp.celular() ? 28 : 24} aria-hidden="true" />
+```
+
+La nota grande de un resumen
+
+```html
+<!-- ❌ mal: tamaños invertidos, más chico en el celular (components/ratings-detail/ratings-detail.html:34) -->
+<sui-rating value={average()} readonly half-step
+  size={bp.isMobile() ? 'large' : 'xlarge'} />
+```
+
+```html
+<!-- ✅ bien: regla general de lo que no se toca, un paso más grande en el celular.
+     El paso extra del resumen (`xlarge` / `large`) sigue en propuesta, falta aprobación -->
+<sui-rating value={average()} readonly half-step
+  size={bp.celular() ? 'large' : 'medium'} />
+```
+
+La nota en una fila o lista
+
+```html
+<!-- ❌ mal: `small` fijo, 16 px también en el celular (pages/drivers/drivers.html:160, pages/customer/order-tracking/order-tracking.html:407) -->
+<sui-rating type="star" size="small" value={driver.rating} readonly half-step />
+```
+
+```html
+<!-- ✅ bien -->
+<sui-rating type="star" size={bp.celular() ? 'large' : 'medium'}
+  value={driver.rating} readonly half-step />
+```
+
+## Ejemplo
+
+```html
+<!-- Mostrar la nota del local (promedio, desde el agregado) -->
+<span class="nota">{notaTexto}</span>
+<sui-rating value={local.rating} readonly half-step
+  size={bp.celular() ? 'large' : 'medium'} aria-hidden="true" />
+
+<!-- Pedir la nota al repartidor -->
+<sui-rating appearance="bar" type="star" size={bp.tactil() ? '2xlarge' : 'medium'}
+  value={nota} onValueChange={(e) => (nota = e.detail)} aria-label="Califica al repartidor" />
+```