@ajuarezso/sui-stencil 0.0.0-stage → 0.1.0

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

@@ -0,0 +1,223 @@
+---
+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
+
+<!-- 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-progress-bar`); 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.
+
+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í; lo marcado canon está
+> aprobado; lo que sigue en propuesta espera decisió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. | — | canon (aprobado por el dueño, 05-10-2026, bloque B6) |
+
+**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 | Pendiente (P10). Era la barra de web en una card densa; D16 no deja nada en `small`, pero la opción recomendada de P10 (a) deja el saldo del repartidor en `small` como excepción escrita (decidido el 20-09-2026). | propuesta, espera P10 |
+| `medium` (default) | 6 px | Computadora, tablet y celular chico. Es la única altura de la guía. | según la guía del DS · D16, dueño 05-10-2026 (cuándo) |
+| `large` | 8 px | Celular de 380 px o más: lo normal y la barra principal (descarga, meta del día). | propuesta (P10 a), pendiente |
+| `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. | canon (aprobado por el dueño, 05-10-2026, bloque B9) |
+| `ariaLabel` o `ariaLabelledby` | **Uno de los dos es obligatorio** en la barra pelada: sin título visible, el lector de pantalla no sabe qué mide. `ariaLabelledby` apunta al id de un texto que ya se ve. | canon (aprobado por el dueño, 05-10-2026, bloque B13) |
+
+**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: **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, `BreakpointsService` ya
+tiene las señales de D16: `celular()` (380–767 px), `celularChico()`, `toque()` y `tactil()`.
+
+| uso | mobile | web | fuente |
+|---|---|---|---|
+| Dentro de una fila o card densa | pendiente (P10) | `medium` (6) | web: D16, dueño 05-10-2026 · mobile: espera P10 (la excepción del saldo en `small` vive en `sui-progress-bar-label`) |
+| Lo normal, y la barra que es lo principal (descarga, meta del día) | `large` (8): propuesta (P10 a), pendiente | `medium` (6) | web: D16, dueño 05-10-2026 · mobile: espera P10 |
+
+```ts
+readonly bp = inject(BreakpointsService); // master-pedidos: src/app/services/breakpoints.service.ts
+```
+
+Si P10 se cierra en (a) o (c):
+
+```html
+<sui-progress-bar value={progreso()} size={bp.celular() ? 'large' : 'medium'} aria-label="Subiendo la foto" />
+```
+
+Va `bp.celular()` y no `bp.isMobile()`: `isMobile()` también incluye el celular chico, que en lo que
+no se toca lleva el valor de web (D16, dueño 05-10-2026).
+
+### Por dispositivo (D16)
+
+No se toca: sube un paso solo en el celular de 380 px o más (P1 b). El celular chico y la tablet
+van con el valor de la computadora.
+
+| dispositivo | size | nota |
+|---|---|---|
+| celular chico (< 380 px) | `medium` (6) | valor «web» |
+| celular (380–767 px) | `large` (8): propuesta (P10 a), pendiente | valor «mobile»: un paso más que la computadora, si P10 lo confirma |
+| tablet táctil (`pointer: coarse`) | `medium` (6) | no se toca, no necesita crecer |
+| computadora (`pointer: fine`) | `medium` (6) | |
+
+Ultrawide (≥ 1920 px): igual que la computadora; el espacio extra va a ancho, no a una barra más gruesa.
+
+**Pendiente (P10):** el valor del celular y si `small` queda como excepción del saldo del
+repartidor (20-09-2026). Decide el dueño.
+
+En master-pedidos: no hay helper. Si P10 confirma `large` en el celular,
+`size={bp.celular() ? 'large' : 'medium'}`.
+
+## API
+
+<!-- api:inicio -->
+<!-- generada: no editar a mano — `npm run docs` -->
+
+| prop | atributo | tipo | default |
+|---|---|---|---|
+| `ariaLabel` | `aria-label` | `null \| string` | `null` |
+| `ariaLabelledby` | `aria-labelledby` | `null \| string` | `null` |
+| `color` | `color` | `"blue" \| "green" \| "orange" \| "purple" \| "red"` | `'blue'` |
+| `size` | `size` | `"large" \| "medium" \| "small" \| "xlarge"` | `'medium'` |
+| `value` | `value` | `number` | `0` |
+
+Eventos: ninguno.
+
+### Diferencias con el SUI Angular
+
+Ninguna en nombres de props, eventos y valores.
+<!-- 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 |
+|---|---|---|
+| `comun.progreso` | Progreso | `ariaLabel` |
+<!-- textos: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`. Nombre: `ariaLabel`, o `ariaLabelledby` (id de un texto visible), y si
+  no hay ninguno se llama «Progreso» (04-10-2026: antes quedaba sin nombre).
+
+## Bien y mal
+
+Barra pelada sin nombre
+
+```html
+<!-- ❌ mal: sin ariaLabel el lector anuncia «Progreso» y no qué mide (pages/overview/components/overview-visitors/overview-visitors.html:22) -->
+<sui-progress-bar value={device.percentage} color="orange" />
+```
+
+```html
+<!-- ✅ bien: el color sigue igual; si pasa a blue espera P9 -->
+<sui-progress-bar value={device.percentage} color="orange" ariaLabel={'Visitas desde ' + device.name} />
+```
+
+El valor como fracción
+
+```html
+<!-- ❌ mal: value es de 0 a 100; 0.6 pinta casi vacía -->
+<sui-progress-bar value={b.progreso} aria-label="Meta del día" />
+```
+
+```html
+<!-- ✅ bien -->
+<sui-progress-bar value={b.progreso * 100} aria-label="Meta del día" />
+```
+
+Título y número armados a mano
+
+```html
+<!-- ❌ mal: el texto va suelto, con otra tipografía y otro espaciado -->
+<p class="subida__texto">Subiendo la foto · {progreso()} %</p>
+<sui-progress-bar value={progreso()} />
+```
+
+```html
+<!-- ✅ bien -->
+<sui-progress-bar-label title="Subiendo la foto" value={progreso()} />
+```
+
+## Ejemplo
+
+```html
+<!-- Dentro de una fila que ya dice «Subiendo la foto · 64 %» -->
+<sui-progress-bar value={progreso()} aria-label="Subiendo la foto" />
+```

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

@@ -0,0 +1,222 @@
+---
+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
+
+<!-- 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-progress-bar-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/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; lo marcado canon está aprobado; lo que sigue en
+> propuesta espera decisió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 | canon (aprobado por el dueño, 05-10-2026, bloque B2) |
+| `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:539` | canon (aprobado por el dueño, 05-10-2026, bloque B4) |
+| `percentage` | `false` | El número ya está escrito al lado, o no significa nada. | — | canon (aprobado por el dueño, 05-10-2026, bloque B4) |
+| `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») · canon (aprobado por el dueño, 05-10-2026, bloque B9) (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:282` | canon (aprobado por el dueño, 05-10-2026, bloque B5) |
+
+**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:282` y `:539`) 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: **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, `BreakpointsService` ya
+tiene las señales de D16: `celular()` (380–767 px), `celularChico()`, `toque()` y `tactil()`.
+
+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) | pendiente (P10) | pendiente (P10) | P10 sigue abierta. D16 no deja nada en `small`, pero la opción recomendada de P10 (a) deja el saldo del repartidor en `small` como excepción escrita (decidido el 20-09-2026, ver el comentario de `pages/driver/driver-dashboard/driver-dashboard.html:279`). Decide el dueño |
+| Lo normal, y la barra que es lo principal (descarga, meta del día) | `large` (8): propuesta (P10 a), pendiente | `medium` (6) | web: D16, dueño 05-10-2026 · mobile: espera P10 |
+
+```ts
+readonly bp = inject(BreakpointsService); // master-pedidos: src/app/services/breakpoints.service.ts
+```
+
+Si P10 se cierra en (a) o (c), la barra normal va así (la meta del día, no el saldo):
+
+```html
+<sui-progress-bar-label title="Meta del día" value={metaPercent()}
+  size={bp.celular() ? 'large' : 'medium'} color={metaColor()} />
+```
+
+Hoy las 4 de la app tienen un size fijo para todos los dispositivos, y una va en `small`
+(`pages/driver/driver-dashboard/driver-dashboard.html:284`, el saldo, desde el 20-09-2026). Si se
+queda como excepción o sube a `medium` / `large` espera P10.
+
+### Por dispositivo (D16)
+
+No se toca: sube un paso solo en el celular de 380 px o más (P1 b). El celular chico y la tablet
+van con el valor de la computadora. El size solo cambia la barra; el título y el número no se mueven.
+
+| dispositivo | size | nota |
+|---|---|---|
+| celular chico (< 380 px) | `medium` (barra de 6) | valor «web» |
+| celular (380–767 px) | `large` (barra de 8): propuesta (P10 a), pendiente | valor «mobile»: un paso más que la computadora, si P10 lo confirma |
+| tablet táctil (`pointer: coarse`) | `medium` (barra de 6) | no se toca, no necesita crecer |
+| computadora (`pointer: fine`) | `medium` (barra de 6) | |
+
+Ultrawide (≥ 1920 px): igual que la computadora.
+
+**Pendiente (P10): el saldo del repartidor.** Va en `small` en todos los dispositivos desde el
+20-09-2026. La opción recomendada de P10 (a) lo deja así como excepción escrita; la (c) lo sube.
+Hasta que el dueño decida, esta tabla no se le aplica.
+
+En master-pedidos: no hay helper. Si P10 confirma `large` en el celular,
+`size={bp.celular() ? 'large' : 'medium'}` (y no `bp.isMobile()`, que también agranda la barra en
+el celular chico).
+
+## API
+
+<!-- api:inicio -->
+<!-- generada: no editar a mano — `npm run docs` -->
+
+| prop | atributo | tipo | default |
+|---|---|---|---|
+| `ariaLabel` | `aria-label` | `null \| string` | `null` |
+| `color` | `color` | `"blue" \| "green" \| "orange" \| "purple" \| "red"` | `'blue'` |
+| `description` | `description` | `string` | `''` |
+| `heading` | `heading` | `string` | `''` |
+| `link` | `link` | `SuiLinkConfig \| null \| string` | `null` |
+| `percentage` | `percentage` | `boolean \| string` | `true` |
+| `showBottom` | `show-bottom` | `boolean` | `false` |
+| `size` | `size` | `"large" \| "medium" \| "small" \| "xlarge"` | `'medium'` |
+| `type` | `type` | `"on-right" \| "on-top"` | `'on-top'` |
+| `value` | `value` | `number` | `0` |
+
+| evento | `event.detail` |
+|---|---|
+| `linkClick` | `void` |
+
+### Diferencias con el SUI Angular
+
+- **Props de Angular que aquí no existen:** `title`
+- **Props solo de aquí:** `heading`
+<!-- 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 `show-bottom`.**
+- **`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.
+- El `title` visible nombra la barra (`aria-labelledby`, 04-10-2026); sin título (`on-right`) y sin
+  `ariaLabel` se anuncia «Progreso».
+
+## Bien y mal
+
+El saldo en `small` de `pages/driver/driver-dashboard/driver-dashboard.html:284` no va aquí como
+❌: es la excepción del 20-09-2026 que P10 (a) propone escribir, y decide el dueño.
+
+La acción que no aparece
+
+```html
+<!-- ❌ mal: sin showBottom no se dibujan ni la descripción ni el link -->
+<sui-progress-bar-label title="Saldo restante" value="18" color="red"
+  link="Recargar" description="para seguir recibiendo pedidos" onLinkClick={() => abrirRecarga()} />
+```
+
+```html
+<!-- ✅ bien -->
+<sui-progress-bar-label title="Saldo restante" value="18" color="red" show-bottom
+  link="Recargar" description="para seguir recibiendo pedidos" onLinkClick={() => abrirRecarga()} />
+```
+
+Título en una barra `on-right`
+
+```html
+<!-- ❌ mal: on-right ignora title; el lector anuncia «Progreso» -->
+<sui-progress-bar-label type="on-right" title="Pedidos en Lince" value="72" />
+```
+
+```html
+<!-- ✅ bien: el nombre lo pone la fila; la barra lo recibe en ariaLabel -->
+<sui-progress-bar-label type="on-right" value="72" aria-label="Pedidos en Lince" />
+```
+
+## 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: medium (default); el valor del celular espera P10 -->
+
+<!-- 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"
+  show-bottom link="Recargar" description="para seguir recibiendo pedidos"
+  onLinkClick={() => abrirRecarga()} />
+```