@ajuarezso/sui-design-system 0.20.0 → 0.22.0

package/docs/sui-popover/README.md

@@ -0,0 +1,178 @@
+---
+name: sui-popover
+selector: sui-popover
+resumen: Panel con flecha que señala un elemento de la pantalla y explica algo nuevo, con una o dos acciones; sirve para recorridos de bienvenida
+alternativas: [sui-tooltip (ayuda corta al pasar el mouse, sin acciones), sui-alert (aviso dentro del contenido), sui-modal (algo que pide decidir antes de seguir)]
+---
+
+# sui-popover
+
+Story: [Molecules/Popover](https://sui-design-system.web.app/?path=/docs/molecules-popover--docs)
+
+Es **solo el panel**: no se abre solo, no se ancla al elemento ni se cierra al tocar afuera. Quien
+lo usa decide cuándo mostrarlo y dónde ponerlo (un overlay del CDK, o posicionado a mano junto al
+elemento). `position` solo mueve la flecha.
+
+## Cuándo usarlo / cuándo no
+
+**Úsalo** para **señalar una parte de la pantalla** y decir algo que la persona todavía no sabe,
+con un paso a seguir: el recorrido de bienvenida del panel del local la primera vez que entra, o
+una función nueva que conviene mostrar donde está («Aquí programas tus pedidos»).
+
+**No lo uses** para:
+
+- La explicación de un ícono o un término sin acción: en web es `sui-tooltip`; en mobile, texto
+  visible o un `sui-modal-sheet`.
+- Un aviso que no señala nada en particular: `sui-alert` o `sui-toast`.
+- Pedir una decisión que bloquea («¿Cancelar el pedido?»): `sui-modal`.
+- Un menú de opciones: `sui-dropdown-menu`.
+
+## Qué variante usar
+
+> La guía del DS dice para qué es, pero no cuándo va cada pie ni cada posición. Lo marcado «según la
+> guía del DS» sale de su texto; «canon» es lo ya aprobado en la app; el resto es **propuesta**.
+>
+> Uso medido el 03-10-2026 en `master-pedidos/src/app`: **0 usos**, y ningún recorrido de
+> bienvenida hecho a mano. Todo lo de abajo es para el primer flujo que lo necesite.
+
+### Lo que sí dice la guía del DS
+
+- **Para qué es**: llamar la atención sobre **elementos específicos** de la interfaz.
+- Se posiciona arriba, abajo o a los costados del elemento que señala.
+- La guía no dice nada del pie con pasos; eso viene del Figma del DS (pie con puntos, con texto o
+  con dos botones a lo ancho).
+
+### `footer` — el pie
+
+| footer | cuándo | fuente |
+|---|---|---|
+| `stretch` (default) | Un aviso suelto con dos salidas a lo ancho: «Ahora no» / «Probar». Con `doubleButton=false`, una sola: «Entendido». | propuesta |
+| `stepper` | Un **recorrido de varios pasos**: los puntos dicen en cuál va y cuántos faltan. | propuesta |
+| `none` | Solo informa y se cierra con la X: «Aquí ves lo que ganaste hoy». | propuesta |
+| `text-stepper` | Recorridos de más de 5 pasos, donde los puntos ya no se cuentan: «Paso 3 de 7» (en español desde 03-10-2026). | propuesta |
+
+### Botones del pie
+
+| prop | valor | cuándo | fuente |
+|---|---|---|---|
+| `doubleButton` | `true` (default) | Desde el segundo paso de un recorrido («Atrás» / «Siguiente»), o un aviso suelto con «Ahora no» / «Probar». | propuesta |
+| `doubleButton` | `false` | El primer paso de un recorrido o un aviso suelto con una sola salida («Entendido»). | propuesta |
+| `backLabel` · `nextLabel` | texto en español | Los defaults ya son «Atrás» y «Siguiente» (03-10-2026); el último paso pasa `nextLabel="Listo"`. | canon (copy de la app: tuteo, sentence case) |
+| orden | secundario a la izquierda, primario a la derecha | Ya lo hace el componente (stroke neutral + filled primary), igual que `sui-modal-footer`. | canon (orden de botones de la app) |
+| `step` | `{ current, total }` | Con `stepper`. Sin `step`, el componente asume **1 de 4**. | propuesta |
+
+### Flecha, ícono, texto y cierre
+
+| prop | valor | cuándo | fuente |
+|---|---|---|---|
+| `tail` | `true` (default) | Siempre que señala algo: la flecha es lo que dice «es esto». | según la guía del DS (se posiciona junto al elemento) |
+| `tail` | `false` | No usar hoy. **Cuándo sí:** la bienvenida inicial de un recorrido, centrada, sin elemento al que apuntar. | propuesta |
+| `position` | `top-*` | El popover va **debajo** del elemento (la flecha arriba). Lo normal: el elemento sigue a la vista. | propuesta |
+| `position` | `bottom-*` | El elemento está abajo (la barra de pestañas): el popover va encima. | propuesta |
+| `position` | `left-*` · `right-*` | Elementos de una barra lateral (el sidebar del panel). | propuesta |
+| `position` | `*-left` · `*-center` · `*-right` | Alinea la flecha con el elemento cuando el popover no puede centrarse sobre él (está cerca de un borde). | propuesta |
+| `icon` | el de lo que se explica | Siempre uno que diga el tema (`calendar-schedule-line` para programar). El default es un ícono de persona. | propuesta |
+| `icon` | `null` | Cuando el texto ya basta y el ícono sería decoración. | propuesta |
+| `title` | frase corta | Qué es, en sentence case y sin punto final. | canon (copy de la app) |
+| `description` | una o dos frases | Qué hace o por qué importa. | propuesta |
+| `dismissIcon` | `true` (default) | Siempre: un recorrido se puede saltar. | propuesta |
+| `dismissIcon` | `false` | No usar hoy. **Cuándo sí:** un paso que no se puede saltar porque sin él no funciona lo siguiente. | propuesta |
+| `[data-slot=body]` | contenido propio | No usar hoy. **Cuándo sí:** el paso necesita una imagen o una lista en vez de título y texto. | propuesta |
+
+## Tamaño en mobile y en web
+
+El panel mide **320 px** de ancho fijo: cabe en un teléfono de 360 px o más con 16 px de margen a
+cada lado; en uno más angosto se sale. El `size` cambia **los botones del pie**:
+
+| size | botones del pie | fuente |
+|---|---|---|
+| `small` (default) | 36 px (`sui-button` `small`) | Figma |
+| `medium` | 40 px (`sui-button` `medium`) | canon (aprobado por el dueño, 03-10-2026): extensión SUI |
+
+La X se ve de 24 y **se toca en 40 × 40** en los dos (un `::before` invisible sobre su botón,
+extensión SUI 03-10-2026).
+
+| uso | mobile | web | fuente |
+|---|---|---|---|
+| el panel | 320 px (cabe desde 352 px de pantalla) | 320 px | según el componente |
+| botones del pie | `medium` (40) | `small` (36) | propuesta: el tamaño es extensión SUI aprobada (03-10-2026); el «cuándo» falta aprobarlo |
+| la X | se ve de 24, se toca en 40 | igual | canon (aprobado por el dueño, 03-10-2026) |
+
+```html
+<sui-popover footer="stretch" [size]="bp.isMobile() ? 'medium' : 'small'" … />
+```
+
+En mobile, si el recorrido es la bienvenida de la app, conviene una pantalla o un
+`sui-modal-sheet` por paso en vez del popover (propuesta, falta aprobación).
+
+## «No usar»: por qué no hoy y cuándo sí
+
+Hoy el popover entero tiene **0 usos**; esto es lo que no se usaría aunque llegue un flujo nuevo.
+
+| qué | por qué no hoy | cuándo sí, en un flujo nuevo |
+|---|---|---|
+| el componente | no hay recorridos ni funciones nuevas que señalar | el recorrido de bienvenida del panel del local; mostrar dónde está una función nueva |
+| `footer="text-stepper"` | ningún recorrido largo hoy | recorridos de más de 5 pasos, donde los puntos ya no se cuentan («Paso 3 de 7») |
+| `tail=false` | todo popover señala algo | la bienvenida inicial, centrada |
+| `dismissIcon=false` | un recorrido siempre se puede saltar | un paso sin el que no funciona el siguiente |
+| `[data-slot=body]` | título y texto alcanzan | un paso con imagen o lista |
+
+## API
+
+<!-- api:inicio -->
+<!-- generada: no editar a mano — `npm run docs` -->
+
+| input | tipo | default |
+|---|---|---|
+| `position` | `'top-left' \| 'top-center' \| 'top-right' \| 'bottom-left' \| 'bottom-center' \| 'bottom-right' \| 'right-top' \| 'right-center' \| 'right-bottom' \| 'left-top' \| 'left-center' \| 'left-bottom'` | `'top-left'` |
+| `tail` | `boolean` | `true` |
+| `icon` | `string \| null` | `'user-6-line'` |
+| `title` | `string` | `''` |
+| `description` | `string \| null` | `null` |
+| `dismissIcon` | `boolean` | `true` |
+| `footer` | `'none' \| 'stretch' \| 'text-stepper' \| 'stepper'` | `'stretch'` |
+| `backLabel` | `string` | `'Atrás'` |
+| `nextLabel` | `string` | `'Siguiente'` |
+| `doubleButton` | `boolean` | `true` |
+| `step` | `{ current: number; total: number } \| null` | `null` |
+| `size` | `'small' \| 'medium'` | `'small'` |
+
+| output | payload |
+|---|---|
+| `dismissed` | `void` |
+| `back` | `void` |
+| `next` | `void` |
+<!-- api:fin -->
+
+Slot: `[data-slot=body]` reemplaza título y descripción.
+
+## Trampas
+
+- **Textos por defecto en español** (desde 03-10-2026): «Atrás», «Siguiente» y, en `text-stepper`,
+  «Paso X de N» (este último no se puede cambiar).
+- **El ícono por defecto es una persona** (`user-6-line`). Si no quieres ícono, `[icon]="null"`.
+- **`step` vacío = 1 de 4**: con `stepper` o `text-stepper`, pásalo siempre.
+- **No se posiciona solo**: `position` cambia dónde sale la flecha, no dónde aparece el panel.
+  Tampoco se cierra al tocar afuera ni con Escape; cierra quien escucha `(dismissed)`.
+- `position` se lee «borde de la flecha, luego su lugar»: `top-left` es flecha **arriba a la
+  izquierda**, o sea, el popover queda **debajo** del elemento.
+- El host lleva `role="dialog"` con `aria-label` = `title` y borra el `title` nativo.
+- Los botones del pie no tienen `disabled`: si un paso no puede avanzar, se maneja desde `(next)`.
+- **`stretch` reparte el ancho entre los dos botones** y en los steppers miden 80 px como mínimo
+  (crecen si el texto no entra). Hasta el 03-10-2026 no pasaba: el `.scss` apuntaba a
+  `.sui-popover__btn` y el template pone `.sui-popover__action`.
+
+## Ejemplo
+
+```html
+<!-- Paso 2 de 3 de un recorrido -->
+<sui-popover position="top-left" icon="calendar-schedule-line"
+  title="Programa tus pedidos" description="Elige el día y la hora, y el pedido entra solo a la cocina."
+  footer="stepper" [step]="{ current: 2, total: 3 }"
+  backLabel="Atrás" nextLabel="Siguiente"
+  (back)="anterior()" (next)="siguiente()" (dismissed)="saltar()" />
+
+<!-- Aviso suelto con una sola salida -->
+<sui-popover position="bottom-center" icon="wallet-3-line" title="Aquí ves lo que ganaste hoy"
+  [doubleButton]="false" nextLabel="Entendido" (next)="cerrar()" (dismissed)="cerrar()" />
+```

package/docs/sui-product-card/README.md

@@ -0,0 +1,173 @@
+---
+name: sui-product-card
+selector: sui-product-card
+resumen: Tarjeta de un producto de la carta con foto, nombre, descripción, precio y el botón para agregar (o editar)
+alternativas: [sui-store-card (un local, no un producto), sui-card (cualquier otro contenido), sui-content-card (un producto en una fila, sin foto grande)]
+---
+
+# sui-product-card
+
+Story: [Molecules/Product Card](https://sui-design-system.web.app/?path=/docs/molecules-product-card--docs)
+
+## Cuándo usarlo / cuándo no
+
+**Úsalo** para cada producto en una grilla de la carta: la carta del local que ve el cliente y la
+grilla de productos que ve el dueño del local (con el lápiz).
+
+**No lo uses** para:
+
+- Un producto dentro del carrito, del checkout o del detalle de un pedido: ahí va una fila (sin
+  foto grande, con cantidad y subtotal).
+- Un local: `sui-store-card`.
+- Una promo o una campaña: tienen su propio carrusel.
+
+Regla corta: **producto en la grilla de la carta → product-card · producto en una lista de pedido
+→ fila.**
+
+## Qué variante usar
+
+> **La guía del DS no tiene página de la product card.** Es un componente propio de SUI, portado
+> de la carta de la app. La card **dibuja, no decide**: el precio, si se vende ahora y la
+> etiqueta de no disponible le llegan ya resueltos.
+>
+> Uso medido el 03-10-2026 en `master-pedidos/src/app` (misma exclusión que `sui-card`): **3
+> product-cards en 2 archivos**: la carta del cliente
+> (`pages/customer/restaurant-menu/restaurant-menu.html:324` y `:387`) y la grilla del local
+> (`pages/products/products.html:145`, con `action="edit"`).
+
+### Las piezas
+
+| prop | cuándo | fuente |
+|---|---|---|
+| `name`, `price` (obligatorios) | Siempre. El precio sale con 2 decimales y punto: «S/ 35.00». | propuesta |
+| `description` | Una línea que diga qué trae: «Con hierbas aromáticas y papas nativas». | propuesta |
+| `image` como objeto `{ url, fallbackUrl, position }` | Lo normal: `url` = la miniatura, `fallbackUrl` = la foto grande por si la miniatura no carga, `position` = encuadre vertical guardado. | propuesta (así lo hace la carta) |
+| `image` como string | Solo la url, sin respaldo. | propuesta |
+| `image = null` + `fallback` | Sin foto: banda de color con el nombre (default). La carta pasa `{ color }` para variar el color por visita con `SUI_PRODUCT_FALLBACK_COLORS`. | propuesta |
+| `available=false` + `unavailableLabel` | Agotado o fuera de horario; la etiqueta dice cuál («Agotado», «Desde las 12 m.»). Se atenúa y pierde el «+». | propuesta |
+| `quantity` | Cuántos hay en el carrito: con más de 0, el «+» pasa a stepper (− / cantidad / +). | propuesta |
+| `closed` | El local no recibe pedidos: se ve, no se agrega. | propuesta |
+| `action="add"` (default) | La carta del cliente. | propuesta |
+| `action="edit"` | La grilla del dueño: lápiz siempre (también en agotado, que es justo el que quiere tocar), nunca stepper. | propuesta |
+| `currencySymbol` | Default `S/`. No se cambia: la app cobra en soles. | propuesta |
+| `fallback.variant="icon"` | Ver «No usar». | propuesta |
+
+Outputs: `openDetail` (toque en la card), `add`, `increment`, `decrement`, `edit`.
+
+**Usos de hoy que rompen las reglas:** 0. **Falta en el DS:** el precio tachado y la chapa de
+descuento. La carta los dibuja afuera (`pages/customer/restaurant-menu/restaurant-menu.scss:426`,
+deuda anotada): cuando se pueda publicar, va un input `precioLista`.
+
+## Tamaño en mobile y en web
+
+El ancho lo da la grilla y la card llena su celda. El `size` cambia **los botones del pie**
+(«+», lápiz y stepper), en la escala del `sui-button`:
+
+| size | «+» / lápiz | stepper (cada lado) | glyph | fuente |
+|---|---|---|---|---|
+| `small` (default) | 36 × 36 | 34 × 36 | 18 / 16 | lo que había en el DS |
+| `medium` | 40 × 40 | 40 × 40 (pill de 104) | 20 | canon (aprobado por el dueño, 03-10-2026): extensión SUI |
+
+En `medium` el stepper (104 px) no entra al lado del precio en la grilla de 2 columnas de mobile:
+el pie envuelve y el stepper baja a su propia línea, a la derecha. El «+» y el lápiz sí siguen al
+lado del precio.
+
+| uso | mobile | web | fuente |
+|---|---|---|---|
+| grilla de la carta | 2 columnas (`1fr 1fr`, gap 12) | `repeat(auto-fill, minmax(220px, 1fr))` desde 600 px y `minmax(180px, 1fr)` en desktop | lo que hay en la app |
+| botón «+», lápiz, stepper | `medium` (40) | `small` (36) | propuesta: el tamaño es extensión SUI aprobada (03-10-2026); el «cuándo» falta aprobarlo |
+
+```html
+<sui-product-card [size]="bp.isMobile() ? 'medium' : 'small'" … />
+```
+
+## Precio con descuento
+
+`precioLista` es el precio de referencia. Si es **mayor** que `price`, la card pinta el precio en
+rojo con la chapa del ahorro al lado (`-25%`, calculada: no se pasa) y el de referencia tachado
+debajo. Igual o menor, o `null`, se ignora. Rojo `--sui-red-700` (5.26:1 sobre blanco, AA) y en
+oscuro `--sui-red-400`; no `--sui-state-error-base`, que da 3.66:1. Propuesta, falta aprobación
+del dueño: reemplaza el bloque que la app dibuja afuera en `restaurant-menu.scss` (precio tachado
+por `::after` y chapa por `::before` sobre `.product__price`), que se borra al migrar.
+
+## «No usar»: por qué no hoy y cuándo sí
+
+| qué | por qué no hoy | cuándo sí, en un flujo nuevo |
+|---|---|---|
+| `fallback: { variant: 'icon' }` | la banda con el nombre dice más que un ícono | una carta de códigos (repuestos, ferretería) donde el nombre no ayuda a reconocerlo |
+| `currencySymbol` distinto de `S/` | la app solo cobra en soles | si algún día se cobra en dólares |
+
+## API
+
+<!-- api:inicio -->
+<!-- generada: no editar a mano — `npm run docs` -->
+
+| input | tipo | default |
+|---|---|---|
+| `name` | `string` | — (requerido) |
+| `description` | `string` | `''` |
+| `price` | `number` | — (requerido) |
+| `image` | `SuiProductCardImage \| string \| null` | `null` |
+| `available` | `boolean` | `true` |
+| `quantity` | `number` | `0` |
+| `closed` | `boolean` | `false` |
+| `currencySymbol` | `string` | `'S/'` |
+| `fallback` | `SuiProductCardFallback \| null` | `null` |
+| `unavailableLabel` | `string` | `'Agotado'` |
+| `action` | `'add' \| 'edit'` | `'add'` |
+| `precioLista` | `number \| null` | `null` |
+| `size` | `'small' \| 'medium'` | `'small'` |
+
+| output | payload |
+|---|---|
+| `openDetail` | `void` |
+| `add` | `void` |
+| `increment` | `void` |
+| `decrement` | `void` |
+| `edit` | `void` |
+<!-- api:fin -->
+
+```ts
+interface SuiProductCardImage { url: string; fallbackUrl?: string; position?: number; }
+interface SuiProductCardFallback { variant?: 'name' | 'icon'; color?: string | null; }
+```
+
+`SUI_PRODUCT_FALLBACK_COLORS` (exportada): los colores `--sui-state-*-base` para la banda.
+
+## Trampas
+
+- **El host lleva `content-visibility: auto`**: las cards fuera de pantalla no se pintan. Al
+  imprimir ya no pasa (el componente lo apaga en `@media print`). En una captura de página
+  completa (shot-scraper `--full`) sí pueden salir en blanco: el opt-out es
+  `sui-product-card { content-visibility: visible; }` desde afuera.
+- **Necesita una celda con alto**: el host es `height: 100%` y la foto usa `NgOptimizedImage`
+  `fill`. En un contenedor sin alto la card colapsa; ponla en una grilla.
+- **La card es un `<div>`, no un `<button>`** (desde 03-10-2026): lo que abre el detalle es
+  `.product__hit`, un botón invisible estirado sobre toda la card con el nombre como
+  `aria-label`; los botones del pie van por encima (`z-index` 2). Así no hay un botón dentro de
+  otro. Un estilo de afuera que apunte a `button.product` ya no engancha.
+- **La app pinta hoy el descuento por fuera** con `::before`/`::after` sobre `.product__price`: si
+  se pasa `precioLista` hay que borrar ese bloque en el mismo cambio, o salen dos tachados.
+- Con `quantity === 1` el «−» pasa a basurero («Quitar del carrito»).
+- El color sin foto es determinista por nombre: el mismo producto siempre sale del mismo color,
+  salvo que pases `fallback.color`.
+- Cada url nueva vuelve a mostrar el barrido de carga; si la miniatura falla, intenta con
+  `fallbackUrl` antes de apagarlo.
+
+## Ejemplo
+
+```html
+<sui-product-card
+  [name]="p.name"
+  [description]="p.description ?? ''"
+  [price]="p.price"
+  [image]="p.thumbnailUrl ? { url: p.thumbnailUrl, fallbackUrl: p.imageUrl, position: p.imagePosition ?? 50 } : null"
+  [available]="disponibleAhora(p)"
+  [unavailableLabel]="etiquetaNoDisponible(p)"
+  [quantity]="cantidadEnCarrito(p)"
+  [closed]="noSePuedePedir()"
+  (openDetail)="abrirDetalle(p)"
+  (add)="agregar(p)"
+  (increment)="sumar(p)"
+  (decrement)="restar(p)" />
+```

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

@@ -0,0 +1,160 @@
+---
+name: sui-radio-card
+selector: sui-radio-card
+resumen: Opción con tarjeta (ícono o foto, título, descripción y el radio) para elegir UNA de una lista corta
+alternativas: [sui-radio-label (la misma elección sin tarjeta, en un formulario denso), sui-select (lista larga o que no entra en pantalla), sui-segmented-control (2–4 vistas de la misma pantalla), sui-checkbox-card (se pueden elegir varias), sui-switch-card (se prende o se apaga un ajuste)]
+---
+
+# sui-radio-card
+
+Story: [Molecules/Card/Radio Card](https://sui-design-system.web.app/?path=/docs/molecules-card-radio-card--docs)
+
+## Cuándo usarlo / cuándo no
+
+**Úsalo** para elegir una sola opción de una lista corta cuando cada opción merece explicarse:
+«Delivery / Recojo en tienda», cómo cobrar («A mi saldo / Por Yape»), el medio de pago, el motivo
+de una cancelación, el modo de asignación de repartidores.
+
+**No lo uses** para:
+
+- Varias opciones que se suman: `sui-checkbox-card`.
+- Un ajuste que se prende o se apaga: `sui-switch-card`.
+- Una lista larga (más de 6–7 opciones) o que crece con los datos: `sui-select`.
+- Cambiar de vista dentro de la misma pantalla: `sui-segmented-control` o tabs.
+
+Regla corta: **una de pocas, con explicación → radio-card · una de muchas → select · varias →
+checkbox-card.**
+
+## Qué variante usar
+
+> **La guía del DS no tiene página de la radio card.** De la guía sale solo lo del radio que lleva
+> adentro: **«para elegir una sola opción de una lista corta»**. El resto es práctica de la app
+> («propuesta») o regla ya aprobada («canon»).
+>
+> Uso medido el 03-10-2026 en `master-pedidos/src/app` (misma exclusión que `sui-card`): **31
+> radio-cards en 14 archivos**. Tipos: 23 `left-icon` (3 de ellos con emoji animado por
+> `iconSrc`), 6 `basic`, 1 `avatar`, 1 `company`. Tamaños: 24 `bp.controlSize()`, 4 `medium`, 1
+> `xlarge` fijo, 1 dinámico, 1 sin `size`. 6 con `sublabel`, 3 con `disabled`, 1 con `badge`.
+
+### `type` (el leading)
+
+| type | cuándo | fuente |
+|---|---|---|
+| `left-icon` con `icon` | Lo normal: un ícono Remix que dice de qué va la opción (`truck-line` Delivery, `store-2-line` Recojo). | propuesta (práctica de la app) |
+| `left-icon` con `iconSrc` | Emoji animado cuando la elección es de las grandes del rol (el vehículo del repartidor, el rol al registrarse, el tipo de mandadito). Los emojis van de `assets/emojis/` o `FLUENT_EMOJI_ANIM`. | propuesta |
+| `left-icon` con `emoji` | Lo mismo con un nombre de `SuiEmoji` en vez de una URL. Hoy 0 usos; vale igual. | propuesta |
+| `basic` | Opciones de texto puro: motivos de cancelación, quién paga el envío, los premios de una meta. | propuesta |
+| `avatar` (`imageUrl`) | El logo redondo de un medio de pago (Yape, Plin, efectivo en el checkout). | propuesta |
+| `company` (`imageUrl`) | Elegir entre tus locales (cambiar de negocio en mi-negocio). | propuesta |
+| `brand`, `card-provider` | Ver «No usar». | propuesta |
+
+### Las piezas
+
+| prop | cuándo | fuente |
+|---|---|---|
+| `value` (obligatorio) | Siempre, aunque no haya grupo. Es lo que emite `selected`. | propuesta |
+| `label` | Siempre. El nombre de la opción, corto: «Delivery», «Lo antes posible». | propuesta |
+| `description` | Casi siempre: la consecuencia de elegirla («Lo revisamos y te transferimos. Puede tardar unas horas.»). | propuesta |
+| `sublabel` | Una precisión corta entre paréntesis («(canal estable)», «(sin OTA)»). Nunca la explicación: eso es `description`. | propuesta |
+| `badge` | Marca una opción frente a las otras: «Por defecto». Con string sale azul `light`; pasa el objeto con el color que corresponda según el badge (un «Por defecto» es `gray`). | propuesta |
+| `disabled` | La opción existe pero hoy no se puede: di por qué en la `description` («El local está cerrado ahora»). | propuesta |
+| `checked` / `[(ngModel)]` / `sui-radio-group` | El estado: `[checked]` + `(selected)` sueltos (lo normal en la app), o `ngModel` con `name` (checkout), o dentro de un `sui-radio-group`. | propuesta |
+
+### `size` (el radio de adentro)
+
+| size | cuándo | fuente |
+|---|---|---|
+| `xlarge` (28) | Mobile, vía `bp.controlSize()`. | canon (aprobado por el dueño, 28-09-2026: «componentes grandes») |
+| `large` (24) | Desktop, vía `bp.controlSize()`. | canon (aprobado por el dueño, 28-09-2026) |
+| `medium` (20, default) | No usar en pantallas nuevas. | canon (aprobado por el dueño, 28-09-2026) |
+
+**Usos de hoy que rompen las reglas:**
+
+- **5 sin el size del breakpoint**: `components/por-cobrar-card/por-cobrar-card.html:38` y `:48`,
+  `pages/driver/driver-dashboard/driver-dashboard.html:581`,
+  `pages/super-admin/master-orders/master-orders.html:720` (los cuatro en `medium`) y
+  `pages/mi-negocio/mi-negocio.html:22` (sin `size`). Además `pages/customer/mandadito/mandadito.html:30`
+  va en `xlarge` fijo (en web debería ser `large`).
+- **A revisar:** `pages/super-admin/master-orders/master-orders.html:720` lista a los repartidores
+  candidatos, una lista que crece con la flota (con muchos, `sui-select` o una lista con búsqueda).
+  `pages/role-selector/role-selector.html:24` usa la radio como botón: elegir ya avanza, sin
+  `[checked]`.
+
+## Tamaño en mobile y en web
+
+La card entera es el área táctil (≥ 72 de alto con descripción, 16 de padding): llega al piso de
+44 sola. El `size` cambia solo el radio.
+
+| uso | mobile | web |
+|---|---|---|
+| toda radio-card | `xlarge` (radio 28) | `large` (radio 24) |
+
+```html
+<sui-radio-card [size]="bp.controlSize()" … />   <!-- isMobile() ? 'xlarge' : 'large' -->
+```
+
+## «No usar»: por qué no hoy y cuándo sí
+
+| qué | por qué no hoy | cuándo sí, en un flujo nuevo |
+|---|---|---|
+| `type="brand"` (0 usos) | no hay servicios de terceros que elegir | elegir el canal por el que te contactamos (WhatsApp, correo) con su logo (`brand`) |
+| `type="card-provider"` (0 usos) | no hay pago con tarjeta guardada | elegir una tarjeta guardada en el checkout, cuando entre Culqi / Niubiz |
+| `size="medium"` | el radio de 20 se pierde en el teléfono | una tabla densa solo de desktop |
+
+## API
+
+<!-- api:inicio -->
+<!-- generada: no editar a mano — `npm run docs` -->
+
+| input | tipo | default |
+|---|---|---|
+| `type` | `'basic' \| 'left-icon' \| 'avatar' \| 'card-provider' \| 'brand' \| 'company'` | `'basic'` |
+| `size` | `'medium' \| 'large' \| 'xlarge'` | `'medium'` |
+| `value` | `string` | — (requerido) |
+| `label` | `string` | `''` |
+| `sublabel` | `string \| null` | `null` |
+| `description` | `string \| null` | `null` |
+| `icon` | `string \| null` | `null` |
+| `emoji` | `SuiEmojiName \| null` | `null` |
+| `iconSrc` | `string \| null` | `null` |
+| `imageUrl` | `string \| null` | `null` |
+| `brand` | `SuiBrandLogoCompany \| null` | `null` |
+| `badge` | `SuiBadgeConfig \| string \| null` | `null` |
+| `disabled` | `boolean` | `false` |
+| `checked` · model, `[(checked)]` | `boolean` | `false` |
+
+| output | payload |
+|---|---|
+| `selected` | `string` |
+<!-- api:fin -->
+
+Implementa `ControlValueAccessor` (el valor del form es el `value` elegido). Dentro de un
+`sui-radio-group`, el grupo decide cuál está marcada.
+
+## Trampas
+
+- **`value` es obligatorio** aunque la uses suelta: sin él Angular tira error de input requerido.
+- **Precedencia del leading en `left-icon`: `icon` > `emoji` > `iconSrc`.** Si pasas `icon` y
+  `iconSrc`, gana el ícono.
+- Con `iconSrc` el círculo pasa a modo «relleno» (sin padding): el emoji ocupa los 40 × 40.
+- `avatar`, `company` y `card-provider` leen la imagen de **`imageUrl`**; `brand` lee `brand` (o
+  `imageUrl` si la marca no está en el catálogo). No hay slot para proyectar el leading (a
+  diferencia de `sui-checkbox-card`).
+- Suelta (sin grupo), elegirla la marca pero **no desmarca a las otras**: el padre tiene que
+  bindear `[checked]` de todas a la misma señal.
+- `badge` con string sale **azul `light` `small`** (en `sui-content-label` sale naranja).
+- `size` cambia solo el radio, no el padding ni el alto de la card.
+
+## Ejemplo
+
+```html
+<sui-radio-card
+  [size]="bp.controlSize()"
+  type="left-icon"
+  value="pickup"
+  icon="store-2-line"
+  label="Recojo en tienda"
+  description="Lo recoges en el local"
+  [checked]="modo() === 'pickup'"
+  (selected)="modo.set('pickup')" />
+```

package/docs/sui-rating/README.md

@@ -90,11 +90,11 @@ lista cargada, que viene con tope. La fórmula depende de `n`: otro denominador
 | `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 |
+| `reason` / `reasonPlaceholder` / `reasonRows` | — | Solo en `bar-area`. El placeholder por defecto es «Cuéntanos por qué» (03-10-2026). | propuesta, falta aprobación |
 
 **Usos de hoy que rompen la regla:**
 
-- **1 `reviewCount`** (pinta «Ratings» en inglés):
+- **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"`.
@@ -110,7 +110,7 @@ lista cargada, que viene con tope. La fórmula depende de `n`: otro denominador
 | `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. |
+| `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
@@ -160,7 +160,7 @@ plataforma solo se elige en `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!'` |
+| `reasonPlaceholder` | `string` | `'Cuéntanos por qué'` |
 | `reasonRows` | `number` | `3` |
 
 | output | payload |
@@ -175,8 +175,9 @@ Implementa `ControlValueAccessor` sobre `value` (sirve con `formControlName`). `
 
 - **`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!»).
+- **`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