@ajuarezso/sui-design-system 0.19.0 → 0.20.0

package/docs/sui-logo/README.md

@@ -0,0 +1,152 @@
+---
+name: sui-logo
+selector: sui-logo
+resumen: El logo de Master Pedidos (la M y la palabra), dibujado en SVG y coloreable
+alternativas: [sui-brand-logo (logos de OTRAS marcas: WhatsApp, Google, Apple…), sui-avatar (el logo de un local, que es una foto)]
+---
+
+# sui-logo
+
+Story: [Atoms/Logo](https://sui-design-system.web.app/?path=/docs/atoms-logo--docs)
+
+## Cuándo usarlo / cuándo no
+
+**Úsalo** siempre que aparezca la marca Master Pedidos: barras, login, «Acerca de», la pantalla
+de actualización, las páginas públicas.
+
+**No lo uses** para:
+
+- El logo de un local: es una foto, va en `sui-avatar`.
+- Logos de terceros: `sui-brand-logo`.
+- El splash nativo (`index.html`): se pinta antes de que arranque Angular, así que es una copia a
+  mano en SVG. Si se cambia el logo, hay que tocar las dos.
+
+**Nunca un PNG o un SVG suelto del logo**: con `sui-logo` el color sigue al tema y el dibujo es
+uno solo.
+
+## Qué variante usar
+
+> **La guía del DS no tiene este componente**: es propio de SUI, porque es la marca de la app.
+> Todo lo de abajo es **propuesta, falta aprobación**; los ejemplos salen de cómo se usa hoy.
+>
+> Uso medido el 03-10-2026 en `master-pedidos/src/app`: 10 logos en 8 archivos, sin contar
+> prototipos ni vitrinas. 4 `horizontal`, 3 `stacked`, 3 `markOnly`; 7 con `[height]` y 3 con `size`.
+
+### `orientation` y `markOnly`
+
+| valor | cuándo | ejemplo real de la app | fuente |
+|---|---|---|---|
+| `horizontal` (default) | Barras y cabeceras: la M a la izquierda y la palabra en dos líneas. | `layouts/public/public-layout.html:4` · `pages/public/pedido-en-vivo/pedido-en-vivo.html:72` · `pages/role-selector/role-selector.html:10` | propuesta |
+| `stacked` | Pantallas de marca centradas: la M arriba y la palabra abajo. | `pages/empresa/about/about.html:12` · `components/ota-update/ota-update.html:118` | propuesta |
+| `[markOnly]="true"` | Donde la palabra no entra o ya está escrita al lado: nav mobile, login. | `layouts/public/public-layout.html:6` · `pages/auth/login/login.html:3` | propuesta |
+
+No existe la versión de una sola línea («Master Pedidos» en un renglón): es otro dibujo.
+
+### `size` y `height`
+
+`size` fija el **alto**; el ancho sale solo.
+
+| valor | alto | cuándo | fuente |
+|---|---|---|---|
+| `xs` / `sm` | 16 / 20 | No usar hoy: la palabra no se lee (con `markOnly` sí sirve). | propuesta |
+| `md` (default) | 24 | Barra de una página pública. | propuesta |
+| `lg` | 32 | Nav pública, login. | propuesta |
+| `xl` | 40 | Pantalla de actualización. | propuesta |
+| `2xl` | 48 | Selector de rol. | propuesta |
+| `height` | libre | **Solo para más de 48 px**: el apilado de 120 en «Acerca de» y en la actualización. | propuesta |
+
+**Usos de hoy que romperían la propuesta: 4 `[height]` que van a la escala.**
+`components/ota-update/ota-update.html:17` (`40` → `size="xl"`),
+`pages/public/pedido-en-vivo/pedido-en-vivo.html:72` (`22` → `md`),
+`layouts/public/public-layout.html:6` (`28` → `lg`), `pages/customer/about/about.html:19` (`44` → `xl` o `2xl`).
+
+### `markColor` y `textColor`
+
+| combinación | cuándo | fuente |
+|---|---|---|
+| de marca (default): M `--sui-primary-base` + palabra `--sui-text-strong-950` | Sobre fondo claro. **No hace falta pasar los colores**: ya son el default. | propuesta |
+| monocromo: todo `--sui-text-strong-950` | Login y nav pública, donde el naranja ya está en el botón principal. | propuesta |
+| blanco: todo `--sui-static-white` | Sobre naranja o sobre foto. `static-white` no cambia con el tema. | propuesta |
+| cualquier otro color | No usar. | propuesta |
+
+**Usos de hoy redundantes: 6** pasan a mano los colores que ya son el default (no rompen nada,
+sobran): `components/ota-update/ota-update.html:17`, `pages/role-selector/role-selector.html:10`,
+`pages/empresa/about/about.html:12`.
+
+**Logo que no pasa por el componente: 1.** `components/landing-footer/landing-footer.html:7` usa
+`assets/landing/logo-blanco.png` → `sui-logo` con los dos colores en `--sui-static-white`.
+
+### `decorative` y `ariaLabel`
+
+| input | cuándo | fuente |
+|---|---|---|
+| `[decorative]="true"` | Cuando al lado ya está escrito «Master Pedidos» (el título de «Acerca de»): así el lector de pantalla no lo dice dos veces. | propuesta |
+| `ariaLabel` | No tocar: ya dice «Master Pedidos». | propuesta |
+
+## Tamaño en mobile y en web
+
+En mobile se lee y se toca con el dedo, así que va más grande; en web, más chico. En las
+pantallas que se usan en los dos (panel del local, super admin) se elige con el servicio de
+breakpoints de la app (`bp`, en `services/breakpoints.service.ts`); en las que solo existen en
+el celular (cliente, repartidor) va directo el valor de mobile. Todo es **propuesta**.
+
+| uso | mobile | web |
+|---|---|---|
+| barra | `[markOnly]="true"` `size="lg"` | `horizontal` `size="lg"` |
+| pantalla de entrada (selector de rol, login) | `2xl` (48) | `xl` (40) |
+| pantalla de marca («Acerca de», actualización) | `stacked` `[height]="120"` | igual |
+
+```html
+<sui-logo size="lg" [markOnly]="bp.isMobile()" />
+```
+
+En la barra no cambia el alto, cambia la forma: en mobile no entra la palabra. Es lo que ya hace
+`layouts/public/public-layout.html:4`–`:6`, con dos logos y CSS.
+
+## «No usar»: por qué no hoy y cuándo sí
+
+| qué | por qué no hoy | cuándo sí, en un flujo nuevo |
+|---|---|---|
+| `size` `xs`, `sm` con palabra | la palabra no se lee | con `markOnly`: el ícono chico en una firma o un pie de página |
+| un color fuera de los tres | la marca es naranja, negra o blanca | ninguno previsto |
+
+## API
+
+<!-- api:inicio -->
+<!-- generada: no editar a mano — `npm run docs` -->
+
+| input | tipo | default |
+|---|---|---|
+| `orientation` | `'horizontal' \| 'stacked'` | `'horizontal'` |
+| `markOnly` | `boolean` | `false` |
+| `size` | `'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| '2xl'` | `'md'` |
+| `height` | `number \| string \| null` | `null` |
+| `markColor` | `string` | `'var(--sui-primary-base)'` |
+| `textColor` | `string` | `'var(--sui-text-strong-950)'` |
+| `decorative` | `boolean` | `false` |
+| `ariaLabel` | `string` | `'Master Pedidos'` |
+
+Outputs: ninguno.
+<!-- api:fin -->
+
+## Trampas
+
+- **`height` gana sobre `size`.** Un número son px; un string es cualquier valor CSS (`'60%'`).
+- **Los colores van por custom property**: `markColor="var(--sui-primary-base)"` funciona; un
+  `fill` puesto desde afuera, no.
+- **Con `markOnly`, `orientation` no hace nada.**
+- **No trae padding**: el `viewBox` es justo el dibujo. El aire lo pone quien lo usa.
+- **No es `sui-brand-logo`**: ese sirve logos de otras marcas como imágenes que no se pueden teñir.
+
+## Ejemplo
+
+```html
+<!-- Barra de una página pública -->
+<sui-logo size="md" />
+
+<!-- «Acerca de»: el título ya dice el nombre -->
+<sui-logo orientation="stacked" [height]="120" [decorative]="true" />
+
+<!-- Sobre el fondo naranja -->
+<sui-logo [markOnly]="true" size="2xl" markColor="var(--sui-static-white)" />
+```

package/docs/sui-payment-icon/README.md

@@ -0,0 +1,98 @@
+---
+name: sui-payment-icon
+selector: sui-payment-icon
+resumen: El círculo de color de un pago de servicio (agua, gas, luz, internet, alquiler…)
+alternativas: [sui-key-icon (cualquier otro ícono en círculo), sui-brand-logo (el logo de un medio de pago con marca)]
+---
+
+# sui-payment-icon
+
+Story: [Atoms/Icon/Payment Icon](https://sui-design-system.web.app/?path=/docs/atoms-icon-payment-icon--docs)
+
+## Cuándo usarlo / cuándo no
+
+**Úsalo** para identificar el **tipo de un pago de servicio** en una lista: agua, gas, luz,
+donación, internet, teléfono, alquiler, impuestos. Es un `sui-key-icon` `lighter` con el ícono y
+el color ya elegidos.
+
+**No lo uses** para:
+
+- **Medios de pago** (Yape, Plin, efectivo, tarjeta): no están aquí. Este componente es de
+  **servicios**, no de cómo se paga.
+- Cualquier otro ícono en círculo: `sui-key-icon`.
+
+## Qué variante usar
+
+> **La guía del DS no tiene página para este componente.** Todo es **propuesta, falta
+> aprobación**.
+>
+> Uso medido el 03-10-2026 en `master-pedidos/src/app`: **0 usos**.
+
+### `type`
+
+| valor | ícono y color | cuándo | fuente |
+|---|---|---|---|
+| `water` | gota, celeste | No usar hoy. | propuesta |
+| `gas` | fuego, rojo | No usar hoy. | propuesta |
+| `electricity` | foco, amarillo | No usar hoy. | propuesta |
+| `donate` | mano con corazón, rosa | No usar hoy. | propuesta |
+| `internet` | wifi, azul | No usar hoy. | propuesta |
+| `phone` | celular, naranja | No usar hoy. | propuesta |
+| `rent` | casa, verde | No usar hoy. | propuesta |
+| `tax` | documento, morado | No usar hoy. | propuesta |
+
+### `size` y `ariaLabel`
+
+| input | cuándo | fuente |
+|---|---|---|
+| `size` `40` (default) | El único tamaño del Figma. Los demás (32, 48, 56, 64) heredan la escala de `sui-key-icon`. | propuesta |
+| `ariaLabel` | Solo si al lado no está escrito el servicio. Si no, es decorativo. | propuesta |
+
+Usos de hoy que rompen la regla: **0**.
+
+## Tamaño en mobile y en web
+
+En mobile se lee y se toca con el dedo, así que va más grande; en web, más chico. En las
+pantallas que se usan en los dos (panel del local, super admin) se elige con el servicio de
+breakpoints de la app (`bp`, en `services/breakpoints.service.ts`); en las que solo existen en
+el celular (cliente, repartidor) va directo el valor de mobile. Todo es **propuesta**.
+
+| uso | mobile | web |
+|---|---|---|
+| fila de una lista | `40` | `32` |
+
+```html
+<sui-payment-icon type="electricity" [size]="bp.isMobile() ? 40 : 32" />
+```
+
+## «No usar»: por qué no hoy y cuándo sí
+
+| qué | por qué no hoy | cuándo sí, en un flujo nuevo |
+|---|---|---|
+| todo el componente (0 usos) | la app no maneja pagos de servicios | si el local registra sus gastos fijos por tipo (luz, agua, internet, alquiler), o si la billetera paga servicios |
+
+## API
+
+<!-- api:inicio -->
+<!-- generada: no editar a mano — `npm run docs` -->
+
+| input | tipo | default |
+|---|---|---|
+| `type` | `SuiPaymentIconType` | — (requerido) |
+| `size` | `32 \| 40 \| 48 \| 56 \| 64` | `40` |
+| `ariaLabel` | `string \| null` | `null` |
+
+Outputs: ninguno.
+<!-- api:fin -->
+
+## Trampas
+
+- **No es para medios de pago**: no hay Yape, Plin ni tarjeta.
+- **`type` decide el ícono y el color**: no se pueden cambiar. Si necesitas otro, usa `sui-key-icon`.
+- **`size` es un número**: `[size]="48"`.
+
+## Ejemplo
+
+```html
+<sui-payment-icon type="electricity" />
+```

package/docs/sui-progress-bar/README.md

@@ -0,0 +1,132 @@
+---
+name: sui-progress-bar
+selector: sui-progress-bar
+resumen: Barra que muestra cuánto falta para completar algo, pintada con el estado de lo que mide
+alternativas: [sui-progress-bar-label (la misma barra con título, número y descripción), sui-circular-progress-bar (el avance en un círculo, junto a un título), un gráfico (repartir un total entre partes)]
+---
+
+# sui-progress-bar
+
+Story: [Atoms/Progress/Progress Bar](https://sui-design-system.web.app/?path=/docs/atoms-progress-progress-bar--docs)
+
+## Cuándo usarlo / cuándo no
+
+**Úsalo** para mostrar **cuánto avanzó algo hacia un final**: una descarga, una foto que se sube,
+la meta del día, el saldo que queda. Va pelada (sin texto) solo cuando otra cosa de la pantalla ya
+dice qué mide y cuánto.
+
+**No lo uses** para:
+
+- Una barra con título o número visible: `sui-progress-bar-label` (la arma con la tipografía y el
+  espaciado del DS).
+- **Repartir un total entre partes** (visitas por dispositivo, ventas por canal): eso no es un
+  avance hacia algo, es una proporción. Va un gráfico, o la barra en `blue` si es una sola cifra.
+- Una espera sin porcentaje conocido: un spinner o un skeleton.
+
+## Qué variante usar
+
+> **La guía del DS lo define como «un gráfico simple para mostrar qué tan completo está algo»**
+> y trae cuatro colores (`blue` default, `red`, `orange`, `green`), una sola altura, `value` y
+> `max`. No dice cuándo usar cada color. Cada color apunta a un token de estado
+> (`--sui-state-*`), igual que el badge: de ahí sale su significado, que es el mismo que el del
+> badge aprobado. Lo marcado «según la guía del DS» sale de ahí; el resto es **propuesta, falta
+> aprobación**.
+>
+> Uso medido el 03-10-2026 en `master-pedidos/src/app`: **2 barras peladas en 1 pantalla**
+> (`overview-visitors`), sin contar prototipos ni vitrinas (`master-preview`,
+> `master-prototipos`, `mockup-sheets-*`, `dx/*`, `_guia-*`, `master-rutina`, `master-medico`,
+> `master-ejercicios`, `dev-index`). Las otras 4 barras de la app usan `sui-progress-bar-label`.
+
+### `color` — el estado de lo que mide
+
+| color | token | cuándo | ejemplo | fuente |
+|---|---|---|---|---|
+| `blue` (default) | `information` | Avance neutro: no hay nada que juzgar. | Subir una foto, descargar, pasos de un formulario | según la guía del DS (default y token) · propuesta (cuándo) |
+| `green` | `success` | Se cumplió o va bien. | Meta cumplida, saldo alto | según la guía del DS (token) · propuesta (cuándo) |
+| `orange` | `warning` | Va en curso y pide atención. | Saldo bajando, meta del día a medias | según la guía del DS (token) · propuesta (cuándo) |
+| `red` | `error` | Se perdió o se acabó. | Meta perdida, saldo agotado | según la guía del DS (token) · propuesta (cuándo) |
+| `purple` | `feature` | **No usar** (ver abajo). Extensión SUI. | — | propuesta, falta aprobación |
+
+**Ojo con el naranja**: en este proyecto el `orange` de estado (`--sui-state-warning-base`) es
+el mismo `#fa7319` de la marca. Una barra naranja sin un juicio detrás se lee como «marca», no
+como «atención».
+
+### `size`
+
+| size | alto | cuándo | fuente |
+|---|---|---|---|
+| `small` | 4 px | Web: dentro de una card o una fila densa. | propuesta, falta aprobación |
+| `medium` (default) | 6 px | Web: lo normal y la barra principal. Mobile: dentro de una fila densa. Es la única altura de la guía. | según la guía del DS |
+| `large` | 8 px | Mobile: lo normal y la barra principal (descarga, meta del día). | propuesta, falta aprobación |
+| `xlarge` | 10 px | **No usar** (ver abajo). | propuesta, falta aprobación |
+
+### `value` y `ariaLabel`
+
+| propiedad | regla | fuente |
+|---|---|---|
+| `value` | Siempre de 0 a 100. Si el dato viene como fracción (0,6) o como «3 de 5», se convierte antes. | propuesta, falta aprobación |
+| `ariaLabel` | **Obligatorio** en la barra pelada: sin título visible, el lector de pantalla no sabe qué mide. | propuesta, falta aprobación |
+
+**Usos de hoy que rompen la regla — a discutir, 2:**
+`pages/overview/components/overview-visitors/overview-visitors.html:22` y `:45` pintan en
+`orange` cómo se reparten las visitas por dispositivo. No es un avance ni pide atención: con esta
+regla va `blue`, o mejor un gráfico. Tampoco llevan `ariaLabel`.
+
+## No usar: por qué no hoy y cuándo sí
+
+| qué | por qué no hoy | cuándo sí, en un flujo nuevo |
+|---|---|---|
+| `color="purple"` | No está en la guía y no hay caso. | El avance de una función en prueba, con el mismo morado que el badge «Beta». |
+| `size="xlarge"` | Ninguna barra es lo único de su pantalla. | Una pantalla de carga larga, donde la barra es lo único (importar la carta de un local). |
+
+## 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 |
+|---|---|---|---|
+| Dentro de una fila o card densa | `medium` (6) | `small` (4) | propuesta, falta aprobación |
+| Lo normal, y la barra que es lo principal (descarga, meta del día) | `large` (8) | `medium` (6) | propuesta, falta aprobación |
+
+```ts
+readonly bp = inject(BreakpointsService); // master-pedidos: src/app/services/breakpoints.service.ts
+```
+
+```html
+<sui-progress-bar [value]="progreso()" [size]="bp.isMobile() ? 'medium' : 'small'" ariaLabel="Subiendo la foto" />
+```
+
+## API
+
+<!-- api:inicio -->
+<!-- generada: no editar a mano — `npm run docs` -->
+
+| input | tipo | default |
+|---|---|---|
+| `value` | `number` | `0` |
+| `color` | `'blue' \| 'green' \| 'orange' \| 'red' \| 'purple'` | `'blue'` |
+| `size` | `'small' \| 'medium' \| 'large' \| 'xlarge'` | `'medium'` |
+| `ariaLabel` | `string \| null` | `null` |
+
+Outputs: ninguno.
+<!-- api:fin -->
+
+## Trampas
+
+- **No hay `max`** (la guía sí lo tiene): `value` es un porcentaje de 0 a 100, con tope.
+- **El default es `blue`**, no el naranja de la marca.
+- El azul de la barra es `--sui-state-information-base`, **no** `--sui-primary-base` (que en
+  este proyecto es naranja).
+- El ancho es el 100 % del padre: dentro de un flex, dale `flex: 1` o un ancho.
+- Lleva `role="progressbar"` con `aria-valuenow`; la animación se apaga con
+  `prefers-reduced-motion`.
+
+## Ejemplo
+
+```html
+<!-- Dentro de una fila que ya dice «Subiendo la foto · 64 %» -->
+<sui-progress-bar [value]="progreso()" ariaLabel="Subiendo la foto" />
+```

package/docs/sui-progress-bar-label/README.md

@@ -0,0 +1,143 @@
+---
+name: sui-progress-bar-label
+selector: sui-progress-bar-label
+resumen: La barra de progreso con lo que mide, cuánto va y, si hace falta, qué hacer
+alternativas: [sui-progress-bar (la barra pelada, cuando otra cosa ya la rotula), sui-circular-progress-bar (el avance en un círculo, junto a un título)]
+---
+
+# sui-progress-bar-label
+
+Story: [Atoms/Progress/Progress Bar Label](https://sui-design-system.web.app/?path=/docs/atoms-progress-progress-bar-label--docs)
+
+## Cuándo usarlo / cuándo no
+
+**Úsalo** siempre que una barra de progreso lleve **título o número visible**: «Descargando
+actualización 64 %», «Meta del día · 3 de 5 entregas», «Saldo restante · S/ 12.40 de S/ 20.00».
+Arma la barra (`sui-progress-bar` adentro), el título, el número y una fila opcional con
+descripción y link, con el espaciado del DS.
+
+**No lo uses** para:
+
+- Una barra que ya está rotulada por la fila donde vive: `sui-progress-bar`.
+- Un avance que va en un cuadrado al lado de un título: `sui-circular-progress-bar`.
+- Repartir un total entre partes: un gráfico.
+
+## Qué variante usar
+
+> **La guía del DS no tiene una página propia para esto**: son los ejemplos «With Label» y
+> «Advanced» de la página de la barra de progreso (título + «80%», y debajo un link
+> «Upgrade» con una descripción). No dice cuándo usar cada forma. Lo marcado «según la guía del
+> DS» sale de esos ejemplos; el resto es **propuesta, falta aprobación**.
+>
+> Uso medido el 03-10-2026 en `master-pedidos/src/app`: **4 en 3 pantallas** (la descarga del
+> OTA, el saldo y la meta del día en el dashboard del repartidor, el saldo en la billetera), sin
+> contar prototipos ni vitrinas (`master-preview`, `master-prototipos`, `mockup-sheets-*`,
+> `dx/*`, `_guia-*`, `master-rutina`, `master-medico`, `master-ejercicios`, `dev-index`). Todas
+> `on-top`; 3 con `percentage` de texto; 1 con `showBottom`; ninguna con `link`.
+
+`color` y `size` se eligen con las tablas de `sui-progress-bar`: el color es el **estado de lo
+que mide** (blue neutro, green cumplido, orange pide atención, red perdido o agotado).
+
+| propiedad | valor | cuándo | ejemplo real | fuente |
+|---|---|---|---|---|
+| `type` | `on-top` (default) | Título y número arriba, barra abajo. Lo normal. | Las 4 de la app | según la guía del DS («With Label») |
+| `type` | `on-right` | Sin título: barra y número en una línea, dentro de una fila que ya dice qué mide a la izquierda. | Pedidos por distrito en una tabla | propuesta, falta aprobación |
+| `title` | texto | Qué mide, en sentence case, sin punto: «Saldo restante», «Meta del día». | `pages/driver/driver-wallet/driver-wallet.html:43` | según la guía del DS |
+| `percentage` | `true` (default) | El porcentaje es la unidad que importa (una descarga). | `components/ota-update/ota-update.html:132` | según la guía del DS («80%») |
+| `percentage` | texto | Hay una unidad real: entregas, soles. «3 de 5 entregas», «S/ 12.40 de S/ 20.00». | `pages/driver/driver-dashboard/driver-dashboard.html:512` | propuesta, falta aprobación |
+| `percentage` | `false` | El número ya está escrito al lado, o no significa nada. | — | propuesta, falta aprobación |
+| `showBottom` + `description` | texto | Qué está pasando o qué hacer mientras avanza: «No cierres la app, estamos dejando todo listo.» | `components/ota-update/ota-update.html:132` | según la guía del DS («Advanced») |
+| `link` | texto o `{ label, href }` | La acción que resuelve lo que la barra avisa: «Recargar» cuando el saldo está en rojo. Va con `showBottom`. | — (sin usos) | según la guía del DS («Upgrade») · propuesta (cuándo) |
+| `ariaLabel` | texto | Lo que mide, si el título no alcanza («Saldo restante sobre el saldo de cortesía»). | `pages/driver/driver-dashboard/driver-dashboard.html:240` | propuesta, falta aprobación |
+
+**Usos de hoy que rompen la regla — a discutir, 1:**
+`components/ota-update/ota-update.html:132` pinta la descarga en `orange`. Una descarga es avance
+neutro: con la regla de color va `blue`. En la app el naranja se lee como la marca, así que puede
+ser una decisión de marca y no un error: decide el dueño. Las de saldo y meta (`driver-wallet:43`,
+`driver-dashboard:240` y `:512`) ya pintan verde, naranja y rojo según el estado: cumplen.
+
+## No usar: por qué no hoy y cuándo sí
+
+| qué | por qué no hoy | cuándo sí, en un flujo nuevo |
+|---|---|---|
+| `type="on-right"` | Ninguna barra de hoy vive en una fila con su nombre al lado. | Una tabla del super admin con el avance por distrito o por local. |
+| `link` | Ninguna barra de hoy ofrece la acción que la resuelve. | «Recargar» bajo el saldo del repartidor cuando está en rojo. |
+
+## 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.
+
+El `size` solo cambia la barra; el título y el número no cambian de tamaño.
+
+| uso | mobile | web | fuente |
+|---|---|---|---|
+| Dentro de una card o fila densa (saldo en el dashboard) | `medium` (6) | `small` (4) | propuesta, falta aprobación |
+| Lo normal, y la barra que es lo principal (descarga, meta del día) | `large` (8) | `medium` (6) | propuesta, falta aprobación |
+
+```ts
+readonly bp = inject(BreakpointsService); // master-pedidos: src/app/services/breakpoints.service.ts
+```
+
+```html
+<sui-progress-bar-label title="Saldo restante" [value]="balancePercent()"
+  [size]="bp.isMobile() ? 'large' : 'medium'" [color]="balanceColor()" />
+```
+
+Hoy las 4 de la app tienen un size fijo para las dos plataformas.
+
+## API
+
+<!-- api:inicio -->
+<!-- generada: no editar a mano — `npm run docs` -->
+
+| input | tipo | default |
+|---|---|---|
+| `value` | `number` | `0` |
+| `type` | `'on-top' \| 'on-right'` | `'on-top'` |
+| `title` | `string` | `''` |
+| `percentage` | `boolean \| string` | `true` |
+| `showBottom` | `boolean` | `false` |
+| `description` | `string` | `''` |
+| `link` | `SuiLinkConfig \| string \| null` | `null` |
+| `color` | `'blue' \| 'green' \| 'orange' \| 'red' \| 'purple'` | `'blue'` |
+| `size` | `'small' \| 'medium' \| 'large' \| 'xlarge'` | `'medium'` |
+| `ariaLabel` | `string \| null` | `null` |
+
+| output | payload |
+|---|---|
+| `linkClick` | `void` |
+<!-- api:fin -->
+
+Output: `(linkClick)`. Con `link` de texto el `<a>` no navega y solo emite; con
+`{ label, href }` navega y además emite.
+
+## Trampas
+
+- **`description` y `link` solo se ven con `[showBottom]="true"`.**
+- **`on-right` ignora `title`, `description` y `link`**: solo barra y número.
+- `percentage` acepta `true`, `false` o un texto: un texto vacío vuelve al porcentaje.
+- El porcentaje automático se redondea (`64.6` → «65%»).
+- El link se pinta en el azul de información, no en el naranja de la marca.
+- Si no hay `title` y `percentage` es `false`, no se dibuja la fila de arriba.
+- Tiene el strip del `title` nativo: no aparece el tooltip gris del navegador.
+
+## Ejemplo
+
+```html
+<!-- Meta del día del repartidor -->
+<sui-progress-bar-label
+  title="Meta del día"
+  [value]="hechas / meta * 100"
+  [percentage]="hechas + ' de ' + meta + ' entregas'"
+  [color]="perdida ? 'red' : cumplida ? 'green' : 'orange'"
+  size="large" />
+
+<!-- Saldo en rojo, con la acción que lo resuelve -->
+<sui-progress-bar-label
+  title="Saldo restante" [value]="18" percentage="S/ 3.60 de S/ 20.00" color="red"
+  [showBottom]="true" link="Recargar" description="para seguir recibiendo pedidos"
+  (linkClick)="abrirRecarga()" />
+```

package/docs/sui-radio/README.md

@@ -0,0 +1,134 @@
+---
+name: sui-radio
+selector: sui-radio
+resumen: El círculo solo para elegir una opción de una lista corta, sin texto propio
+alternativas: [sui-radio-label (círculo con su texto, lista densa), sui-radio-card (opción con peso o que se toca en el teléfono), sui-select (más de 6 opciones), sui-segmented-control (2-4 modos que se aplican al instante), sui-checkbox (varias a la vez)]
+---
+
+# sui-radio
+
+Story: [Atoms/Checkbox, Radio & Switch/Radio](https://sui-design-system.web.app/?path=/docs/atoms-checkbox-radio-switch-radio--docs)
+
+## Cuándo usarlo / cuándo no
+
+**Úsalo** para elegir **una** opción de una lista corta, solo como círculo: cuando el texto vive
+en otra parte (una columna «Por defecto» en una tabla, una fila propia con foto y precio).
+Va dentro de un `sui-radio-group`, que es el que hace que elegir una desmarque la otra.
+
+**No lo uses** para:
+
+- Un círculo con su texto en una lista densa (franjas horarias): `sui-radio-label`.
+- Opciones con peso (ícono, descripción, borde) o que se tocan en el teléfono: `sui-radio-card`
+  (método de pago, tipo de entrega, motivos de cancelación). Crece con `bp.controlSize()`; el
+  radio-label no tiene `size`.
+- Más de ~6 opciones: `sui-select`.
+- 2-4 modos de la misma vista que se aplican al instante: `sui-segmented-control`.
+- Varias a la vez: `sui-checkbox`.
+
+Regla corta: **lista densa de texto → radio-label · con peso o en el teléfono → radio-card · muchas → select · sin texto → este.**
+
+## Qué variante usar
+
+> **La guía del DS lo define como control para «una sola selección de una lista corta de
+> opciones»**, y su ejemplo con label es una lista de motivos para reportar algo («Spam»,
+> «Acoso», «Infringe las reglas»). Muestra deshabilitado, con label y con label avanzado. No
+> trae do/don't de tamaños.
+>
+> Uso medido el 03-10-2026 en `master-pedidos/src/app` (misma exclusión que `sui-badge`):
+> **2 `sui-radio` en 2 archivos**, ambos en modo suelto (`standaloneChecked`), con tamaño
+> dinámico. Más **1 `<input type="radio">` nativo**.
+
+### Estado y modo
+
+| qué | cuándo | fuente |
+|---|---|---|
+| dentro de `sui-radio-group` + `[value]` | Siempre que haya más de una opción. El grupo hace la exclusión y se enchufa a `[(ngModel)]`. | según la guía del DS (es un radio group) |
+| suelto con `[(standaloneChecked)]` | Solo cuando la exclusión la hace la fila o el padre (la fila de opciones del detalle de producto). **Suelto, al tocarlo se desmarca** como un checkbox. | propuesta, falta aprobación |
+| `disabled` | La opción existe pero no aplica ahora (una variante agotada). | según la guía del DS |
+
+### `size`
+
+| size | px | 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` (default) | 20 | Solo dentro de un componente que fija su escala (detalle de producto). Es el único tamaño de la guía. | según la guía del DS (único tamaño); el «cuándo» es propuesta |
+
+**Usos de hoy que rompen la regla:**
+
+- **1 radio nativo → `sui-radio-card type="basic"`:**
+  `pages/driver/driver-order-detail/driver-order-detail.html:812` (motivos de cancelación del
+  repartidor, el mismo caso del ejemplo de la guía). La pantalla hermana del local ya lo resolvió
+  así: `pages/orders/orders.html:566`.
+- **1 suelto que se puede desincronizar:** `pages/super-admin/master-settings/master-settings.html:105`
+  (categoría por defecto). Usa `[standaloneChecked]` + `$event && …`: al tocar el que ya está
+  elegido, el círculo se apaga por dentro pero el padre sigue diciendo que es el elegido. Va en
+  un `sui-radio-group` con `[ngModel]`.
+
+## Tamaño en mobile y en web
+
+| uso | mobile | web |
+|---|---|---|
+| círculo en una fila o tabla | `xlarge` (28 px) | `large` (24 px) |
+| dentro de un componente que fija su escala | lo que pase el padre | lo que pase el padre |
+
+```html
+<sui-radio [size]="bp.controlSize()" … />   <!-- isMobile() ? 'xlarge' : 'large' -->
+```
+
+El más grande mide 28 px: el área táctil de 44 px la tiene que dar la fila.
+
+## «No usar»: por qué no hoy y cuándo sí
+
+| qué | por qué no hoy | cuándo sí, en un flujo nuevo |
+|---|---|---|
+| suelto (`standaloneChecked`) fuera de una fila propia | se desmarca al tocarlo de nuevo: no es un radio | nunca como grupo; solo como dibujo dentro de una fila que maneja el clic |
+
+## API
+
+<!-- api:inicio -->
+<!-- generada: no editar a mano — `npm run docs` -->
+
+### `sui-radio`
+
+| input | tipo | default |
+|---|---|---|
+| `size` | `'medium' \| 'large' \| 'xlarge'` | `'medium'` |
+| `value` | `SuiRadioValue` | `null` |
+| `disabled` | `boolean` | `false` |
+| `standaloneChecked` · model, `[(standaloneChecked)]` | `boolean` | `false` |
+
+Outputs: ninguno.
+
+### `sui-radio-group`
+
+Inputs: ninguno.
+
+Outputs: ninguno.
+<!-- api:fin -->
+
+`sui-radio-group`: sin inputs; implementa `ControlValueAccessor` (`[(ngModel)]`, `formControlName`)
+y proyecta los radios (`sui-radio`, `sui-radio-label`, `sui-radio-card`).
+
+## Trampas
+
+- **Suelto, togglea.** `standaloneChecked` se invierte con cada toque: se puede desmarcar. Para
+  semántica de radio, `sui-radio-group`.
+- **`sui-radio-group` no tiene `value`**: se maneja con `[(ngModel)]` o un form control.
+- **`sui-radio-group` es `inline-flex` en fila con gap 16.** Para lista vertical hay que darle
+  `flex-direction: column; align-items: flex-start` desde afuera.
+- **Deshabilitar el control del grupo no deshabilita los radios** (`setDisabledState` no hace
+  nada): pasa `[disabled]` a cada uno.
+- No hay `small`: el más chico es `medium` (20 px).
+- Sin marcar, en foco, el círculo se pinta del color de marca: viene del Figma, no es un error.
+- No dibuja texto ni `aria-label`: pelado, pon el texto en un `<label>` o usa `sui-radio-label`.
+
+## Ejemplo
+
+```html
+<sui-radio-group [(ngModel)]="categoriaPorDefecto">
+  @for (cat of categorias; track cat.id) {
+    <sui-radio [size]="bp.controlSize()" [value]="cat.id" [attr.aria-label]="cat.nombre" />
+  }
+</sui-radio-group>
+```