@ajuarezso/sui-design-system 0.20.0 → 0.22.0

package/docs/sui-textarea/README.md

@@ -0,0 +1,160 @@
+---
+name: sui-textarea
+selector: sui-textarea
+resumen: Campo de varias líneas para un texto libre (motivo, nota al repartidor, descripción)
+alternativas: [sui-input (un dato de una línea), sui-rich-editor (texto con formato, hoy sin uso), sui-select (motivos que se pueden elegir de una lista)]
+---
+
+# sui-textarea
+
+Story: [Molecules/Input/Textarea](https://sui-design-system.web.app/?path=/docs/molecules-input-textarea--docs)
+
+## Cuándo usarlo / cuándo no
+
+**Úsalo** para un texto que la persona redacta y que puede ocupar más de una línea: el motivo de
+un rechazo o una cancelación, la nota para el repartidor, la descripción de un producto, un
+comentario al calificar.
+
+**No lo uses** para:
+
+- Un dato de una línea (nombre, referencia corta, URL, un slug): `sui-input`. Hoy hay uno así:
+  «Personaliza tu url» en `pages/mi-negocio/mi-negocio.html:706`.
+- Un motivo que se puede elegir de una lista cerrada: radios o `sui-select`, y la opción «Otro»
+  abre el textarea (como ya hace `pages/envios/envios.html:819`, que además corta a 200 a mano con
+  `.slice(0, 200)` en vez de `[maxLength]="200"`).
+- Texto con negritas o enlaces: no hay caso hoy (ver `sui-rich-editor`).
+- Un `<textarea>` nativo: queda **1** (`pages/products/add-product/add-product.html:155`).
+
+Regla corta: **se redacta y puede pasar de una línea → textarea · una línea → input · se elige → select.**
+
+## Qué variante usar
+
+> **La guía del DS lo presenta con contador de caracteres y su propia manija para agrandarlo**
+> («78/200»), y aparte una versión simple sin contador. No dice cuándo va cada una.
+>
+> Uso medido el 03-10-2026 en `master-pedidos/src/app` (misma exclusión que `sui-badge`, más
+> `master-ejercicios`): **50 usos en 29 archivos**. `rows`: 32 en 3, 13 en 2, 4 en 4, 1 en 8.
+> Con `maxLength`: 8. Con `resizable=false`: 2. 38 con label, 12 sin.
+
+| prop | cuándo | fuente |
+|---|---|---|
+| `label` | Siempre, salvo cuando la pregunta ya está escrita justo encima (la calificación: «¿Qué te gustó?»). | según la guía del DS (ejemplo con label) |
+| `required` | Motivo obligatorio (rechazar, anular). | según la guía del DS (`Enter Your Message*`) |
+| `sublabel` | **«(Opcional)»**, con paréntesis, cuando no es obligatorio, en vez de «(opcional)» dentro del label. Sin paréntesis queda pegado al label. | según la guía del DS (`(Optional)`) y canon (README de `sui-form-label`) |
+| `tooltip` | Hoy sin caso. | según la guía del DS (ícono de info del label) |
+| `hint` | Para quién es el texto: «Lo va a leer el cliente», «Solo lo ve tu equipo». | según la guía del DS (ejemplo con hint) |
+| `error` + `errorMessage` | Motivo obligatorio vacío. El mensaje reemplaza al hint y el contador se pone rojo. | según la guía del DS (`Has Error`) |
+| `placeholder` | Un ejemplo de lo que se espera: «Ej. frágil, tocar el timbre, entregar en recepción». Elipsis `…`. | canon (CANON-SUI §5.2) |
+| `maxLength` | **Siempre que otro lo va a leer** (cliente, repartidor, local) o se guarda en la base: muestra «n/200» y corta el exceso. 200 para motivos y notas; 500 para descripciones. | según la guía del DS (su ejemplo principal lleva contador); los topes son propuesta |
+| `size` | El mismo de los inputs del formulario: `large` en mobile, `medium` en web. Ver «Tamaño en mobile y en web». | canon (aprobado por el dueño, 03-10-2026), extensión SUI; el «cuándo» es propuesta, falta aprobación |
+| `rows` | `3` por defecto (motivos, notas). `2` para una nota corta en un formulario largo. `4` o más solo para una descripción larga. | propuesta, falta aprobación |
+| `resizable` | `true` en web. En mobile **`false`**: la manija no se puede arrastrar con el dedo y parece un adorno. | según la guía del DS (versión con y sin manija); el «cuándo» es propuesta |
+| `readonly` | Mostrar un texto ya enviado con la misma forma del campo (copiar un mensaje). | propuesta, falta aprobación |
+| `disabled` | Mientras se envía. | según la guía del DS |
+| `autocomplete` | No hace falta: ningún texto libre se autocompleta. | propuesta, falta aprobación |
+
+**Usos de hoy que rompen la regla:**
+
+- **3 `sublabel="Opcional"` sin paréntesis** (se lee «Notas adicionalesOpcional») → «(Opcional)»:
+  `pages/customer/checkout/checkout.html:209`, `pages/self-delivery/self-delivery.html:101`,
+  `components/add-product-modal/add-product-modal.html:184`.
+- **9 «(opcional)» dentro del label** → `sublabel="(Opcional)"`: `pages/super-admin/super-admin.html:333`
+  («Notas (opcional)»), `pages/super-admin/master-orders/master-orders.html:795`,
+  `components/cuenta-bloqueada/cuenta-bloqueada.html:21`.
+- **Textos que lee otra persona sin `maxLength`** (42 de 50 no lo tienen). Los que más importan:
+  `pages/envios/envios.html:419` («Nota para el repartidor»), `pages/customer/checkout/checkout.html:209`
+  («Notas adicionales»), `pages/super-admin/master-users/master-users.html:266` («Motivo (lo va a leer)»).
+- **4 placeholders con `...`**: `pages/customer/checkout/checkout.html:209`,
+  `pages/self-delivery/self-delivery.html:101`, `pages/driver/driver-order-detail/driver-order-detail.html:823`.
+
+## Tamaño en mobile y en web
+
+Tiene `size` con **los mismos nombres que `sui-input`** (`xsmall` · `small` · `medium` · `large` ·
+`xlarge`): cambia el padding y el radio, y el texto arranca en la misma línea vertical que el del
+input del mismo tamaño. El alto lo siguen poniendo las `rows`. `medium` es el de la guía del DS y el
+default (padding 10/12, radio 12); el resto es extensión SUI.
+
+| size | padding (arriba/der · izq) | radio | fuente |
+|---|---|---|---|
+| `xlarge` | 14 · 16 | 12 | canon (aprobado por el dueño, 03-10-2026), extensión SUI |
+| `large` | 12 · 14 | 12 | canon (aprobado por el dueño, 03-10-2026), extensión SUI |
+| `medium` (default) | 10 · 12 | 12 | según la guía del DS |
+| `small` | 8 · 10 | 10 | canon (aprobado por el dueño, 03-10-2026), extensión SUI |
+| `xsmall` | 6 · 8 | 8 | canon (aprobado por el dueño, 03-10-2026), extensión SUI |
+
+**En mobile (≤ 767 px) la letra sube sola a 16/24** (Paragraph/Medium), como el input sube a 16:
+evita el zoom de iOS al enfocar y el textarea deja de verse más chico que los campos de arriba. Por
+eso cada fila mide 24 px en el teléfono y 20 en web (3 filas ≈ 72 + padding en mobile, 60 + padding
+en web): el área que se toca siempre pasa los 44 px.
+
+En large y xlarge el texto sube a 16 px (regla del 03-10-2026): en esos dos tamaños va en 16/24
+también en web, así que cada fila mide 24 en las dos plataformas.
+
+| uso | mobile | web | fuente |
+|---|---|---|---|
+| motivo, nota | el `size` del formulario (`large` si los inputs van en `large`), `rows=3`, `[resizable]="false"` | `medium`, `rows=3`, manija | propuesta, falta aprobación |
+| descripción larga | igual, `rows=4` | `medium`, `rows=4` | propuesta, falta aprobación |
+
+```html
+<sui-textarea [size]="bp.isMobile() ? 'large' : 'medium'" [rows]="3"
+              [resizable]="!bp.isMobile()" … />   <!-- bp = BreakpointsService -->
+```
+
+## «No usar»: por qué no hoy y cuándo sí
+
+| qué | por qué no hoy | cuándo sí, en un flujo nuevo |
+|---|---|---|
+| `tooltip` | el hint alcanza | un campo del panel con una regla que no entra en una línea («qué puede ver el cliente») |
+| `rows` 6 o más | ningún texto de la app es tan largo | términos y condiciones propios de un local, o la descripción larga de una campaña |
+| `autocomplete` | un texto libre no se autocompleta | — |
+
+## API
+
+<!-- api:inicio -->
+<!-- generada: no editar a mano — `npm run docs` -->
+
+| input | tipo | default |
+|---|---|---|
+| `rows` | `number` | `4` |
+| `size` | `'xsmall' \| 'small' \| 'medium' \| 'large' \| 'xlarge'` | `'medium'` |
+| `placeholder` | `string` | `''` |
+| `disabled` | `boolean` | `false` |
+| `readonly` | `boolean` | `false` |
+| `error` | `boolean` | `false` |
+| `errorMessage` | `string \| null` | `null` |
+| `label` | `string \| null` | `null` |
+| `hint` | `string \| null` | `null` |
+| `autocomplete` | `string \| null` | `null` |
+| `resizable` | `boolean` | `true` |
+| `maxLength` | `number \| null` | `null` |
+| `sublabel` | `string \| null` | `null` |
+| `required` | `boolean` | `false` |
+| `tooltip` | `string \| null` | `null` |
+| `value` · model, `[(value)]` | `string` | `''` |
+
+Outputs: ninguno.
+<!-- api:fin -->
+
+`value` es `model<string>`. Implementa `ControlValueAccessor` (`formControlName`, `[(ngModel)]`).
+
+## Trampas
+
+- **`maxLength` con L mayúscula** (en `sui-input` es `maxlength`). Con el nombre equivocado Angular
+  no avisa en un atributo plano y el tope no se aplica.
+- Sin `maxLength` **no hay contador**; la manija sale igual mientras `resizable` sea `true`.
+- El tope también corta lo que se pega (no solo lo que se tipea).
+- El hint lleva siempre el ícono `information-fill`, también el neutro (así está en el Figma).
+- El `size` no cambia el alto: eso lo deciden las `rows`. Lo que alinea con el input es el padding.
+- `error` sin `errorMessage` pinta el borde y no dice qué falta.
+
+## Ejemplo
+
+```html
+<sui-textarea label="Nota para el repartidor" sublabel="(Opcional)" [rows]="3" [maxLength]="200"
+              [size]="bp.isMobile() ? 'large' : 'medium'" placeholder="Ej. frágil, tocar el timbre, entregar en recepción"
+              [resizable]="!bp.isMobile()" [(value)]="nota" />
+
+<sui-textarea label="Motivo del rechazo" [required]="true" [rows]="3" [maxLength]="200"
+              hint="Lo va a leer el local" [error]="intentado() && !motivo()"
+              errorMessage="Escribe el motivo" [(value)]="motivo" />
+```

package/docs/sui-time-picker/README.md

@@ -0,0 +1,240 @@
+---
+name: sui-time-picker
+selector: sui-time-picker
+resumen: Campo para elegir una hora del día, con columnas de hora, minuto y AM/PM
+alternativas: [sui-tab-chips + sui-radio-label (día y franja de entrega de un pedido programado), sui-select (pocas horas fijas), sui-input type="time" (hora libre con el selector del sistema)]
+---
+
+# sui-time-picker
+
+Story: [Molecules/Date & Time/Time Picker](https://sui-design-system.web.app/?path=/docs/molecules-date-time-time-picker--docs)
+
+## Cuándo usarlo / cuándo no
+
+**Úsalo** para una **hora del día** que la persona escribe con libertad: el horario de apertura y
+cierre del local, el turno del repartidor, «Cerrar hasta las 9:30 PM».
+
+**No lo uses** para:
+
+- **La hora de entrega de un pedido programado**: no se elige una hora libre, se elige una
+  **franja** que el local puede cumplir. Va la hoja del checkout (`sui-tab-chips` para el día y
+  `sui-radio-label` con `flip` para cada franja). Es la maqueta aprobada, y el propio código
+  descartó `sui-time-picker-item` para esas filas porque son densas y sin separación
+  (`checkout.html:475`).
+- Pocas horas fijas («12:00», «13:00», «14:00»): `sui-select`.
+- Una duración («30 min», «1 h»): no hay componente de duración; un `sui-select` o
+  `sui-tab-chips` con los valores (ver Trampas: los presets de este componente no son duraciones).
+
+Regla corta: **hora libre del día → time-picker · franja de entrega → la hoja del checkout ·
+pocas horas → select.**
+
+## Qué variante usar
+
+> **La guía del DS no tiene página para este componente.** Todo es **propuesta, falta
+> aprobación**, aunque ya sea práctica de la app.
+>
+> Uso medido el 03-10-2026 en `master-pedidos/src/app` (sin prototipos ni vitrinas): **7 usos en
+> 4 pantallas** — horario del local (`weekly-schedule-editor`, 2), turnos del repartidor
+> (`driver-schedule`, 2), votaciones de cierre y recargo (`driver-dashboard`, 2) y el cierre del
+> local en la central (`central-inicio`, 1). Los 7 van con `size="medium"`, `format="12h"`,
+> `[durationPresets]="[]"` y footer. `step`: 5 en 5 usos, 30 en 2.
+
+### `format`
+
+| valor | cuándo | fuente |
+|---|---|---|
+| `12h` (default) | Siempre: en Perú la hora se dice «9:30 PM». Los 7 usos lo llevan. | propuesta |
+| `24h` | No usar en la app. | no usar |
+
+### `step`
+
+| valor | cuándo | fuente |
+|---|---|---|
+| `5` (default) | Horas reales que la persona conoce al minuto: apertura y cierre del local, «cerrar hasta». Con saltos de 30 se redondeaban cierres reales (comentario en `weekly-schedule-editor.html:41`). | propuesta |
+| `30` | Bloques de un turno, que se planifican por media hora (`driver-schedule.html:142`). | propuesta |
+| `15` | Citas o reservas en cuartos de hora. Sin caso hoy. | propuesta |
+| `1` | No usar: 60 opciones en la columna para una precisión que nadie pide. | no usar |
+
+### `durationPresets`, `showFooter`, `inline`
+
+| input | valor | cuándo | fuente |
+|---|---|---|---|
+| `durationPresets` | `[]` | **Siempre.** Los presets de fábrica (15 min, 30 min, 45 min, 1 h) ponen la hora como «tiempo desde la medianoche»: «30 min» deja 12:30 AM. Los 7 usos los apagan. | propuesta |
+| `durationPresets` | lista propia | No usar mientras se lean como hora del día. | no usar |
+| `showFooter` | `true` (default) | Cancelar/Aplicar: la hora no cambia hasta confirmar. Es lo correcto cuando la hora se guarda o publica algo (el horario del local). | propuesta |
+| `showFooter` | `false` | Se aplica al tocar cada columna. Solo dentro de un formulario que ya tiene su propio «Guardar». | propuesta |
+| `inline` | `true` | El panel es el contenido, dentro de un `sui-modal` (sin campo ni popover). | propuesta |
+
+### `size`, `label`, `hint`, `error`, `required`, `disabled`
+
+| input | cuándo | fuente |
+|---|---|---|
+| `size="medium"` (40 px, default) | Siempre: es el más grande que hay (ver «Tamaño»). | propuesta |
+| `size="small"` (36 px) | Filas densas en web. | propuesta |
+| `label` | Siempre, corto y en verbo o momento: «Abre», «Cierra», «Inicio», «Cerrar hasta». | propuesta |
+| `sublabel` / `tooltip` | «Opcional» o una aclaración que no entra en el label. | propuesta |
+| `hint` | Qué pasa con esa hora: «Se reabre sola a medianoche». | propuesta |
+| `error` + `errorMessage` | La hora no cuadra: «Cierra antes de abrir». | propuesta |
+| `required` | La hora es obligatoria para guardar. | propuesta |
+| `disabled` | Mientras se guarda (como hacen el horario y los turnos). | propuesta |
+| `placeholder` | Lo que se elige: «Hora de cierre». El default «Seleccionar hora» sirve. | propuesta |
+
+Usos de hoy que rompen la regla: **0**. Los 7 cumplen `12h`, `durationPresets=[]` y `label`.
+
+### Las piezas que trae (exportadas, sin carpeta ni story propias)
+
+| pieza | qué es | cuándo suelta | fuente |
+|---|---|---|---|
+| `sui-time-picker-item` | una fila de la columna (36 px) | No usar: para filas de horario que se tocan con el pulgar va `sui-radio-label` (`checkout.html:475`). | no usar |
+| `sui-time-picker-duration` | la pastilla de un preset | No usar: es la de los presets de duración. | no usar |
+| `sui-time-picker-status` | pastilla Disponible/Ocupado/En reunión/Desconectado | No usar: sus textos de fábrica están en inglés y el estado del repartidor ya tiene su badge. | no usar |
+
+## Tamaño en mobile y en web
+
+En mobile se toca con el dedo: lo que se toca mide **44 px o más**. En web, con mouse, va más
+chico. En pantallas de los dos se elige con el servicio de breakpoints de la app (`bp`, en
+`services/breakpoints.service.ts`).
+
+`size` tiene `small` (36), `medium` (40, default) y **`large` (48)**, extensión SUI: mide lo mismo
+que `sui-input` y `sui-select` `large`, que van al lado en los formularios de horario. Con `large`
+el panel también crece: **filas de 44** y **Cancelar / Aplicar en `large` (48)**. En mobile
+(≤ 767 px) las filas miden 44 con cualquier `size`.
+
+| pieza | `small` · `medium` en web | `large` | mobile (cualquier size) | fuente |
+|---|---|---|---|---|
+| campo (trigger) | 36 · 40 | 48 | el del `size` | 36/40: medido · 48: canon (aprobado por el dueño, 03-10-2026), extensión SUI |
+| fila de la columna | 36 | 44 | 44 | 36: Figma · 44: canon (aprobado por el dueño, 03-10-2026), extensión SUI |
+| Cancelar / Aplicar | 36 | 48 | el del `size` | canon (aprobado por el dueño, 03-10-2026), extensión SUI |
+
+En large y xlarge el texto sube a 16 px (regla del 03-10-2026): con `large`, la hora del campo y la
+de las filas van en 16/24; la fila sigue en 44 (el padding bajó de 12 a 10).
+
+| uso | mobile | web | fuente |
+|---|---|---|---|
+| horario en un formulario | `large` | `medium`, o `small` en filas densas | propuesta, falta aprobación |
+
+```html
+<sui-time-picker label="Cierra" format="12h" [step]="5" [durationPresets]="[]"
+                 [size]="bp.isMobile() ? 'large' : 'medium'"
+                 [value]="cierre()" (valueChange)="cierre.set($event)" />
+```
+
+## «No usar»: por qué no hoy y cuándo sí
+
+Nada se borra del DS. Lo marcado «no usar» no tiene caso en la app de hoy; si un flujo nuevo cae
+en la columna de la derecha, se usa (aprobado por el dueño, 03-10-2026).
+
+| qué | por qué no hoy | cuándo sí, en un flujo nuevo |
+|---|---|---|
+| `format="24h"` | en Perú se dice «9:30 PM» | una pantalla técnica del super admin (registro de eventos) donde se comparan horas |
+| `step="1"` | 60 opciones sin necesidad | registrar la hora exacta de un hecho (hora real de entrega en un reclamo) |
+| `durationPresets` (cualquiera) | se leen como hora desde la medianoche, no como duración | si el DS los cambia para sumar sobre la hora elegida («en 30 min») |
+| `sui-time-picker-item` suelto | fila de 36 px, densa | una lista desplegable de horas en web |
+| `sui-time-picker-duration` suelto | es parte de los presets | — |
+| `sui-time-picker-status` | textos en inglés; el estado del repartidor ya tiene su badge | un panel de disponibilidad del equipo del local, con los textos en español |
+
+## API
+
+<!-- api:inicio -->
+<!-- generada: no editar a mano — `npm run docs` -->
+
+### `sui-time-picker`
+
+| input | tipo | default |
+|---|---|---|
+| `label` | `string \| null` | `null` |
+| `sublabel` | `string \| null` | `null` |
+| `required` | `boolean` | `false` |
+| `tooltip` | `string \| null` | `null` |
+| `hint` | `string \| null` | `null` |
+| `errorMessage` | `string \| null` | `null` |
+| `error` | `boolean` | `false` |
+| `placeholder` | `string` | `'Seleccionar hora'` |
+| `disabled` | `boolean` | `false` |
+| `size` | `'small' \| 'medium' \| 'large'` | `'medium'` |
+| `format` | `'12h' \| '24h'` | `'12h'` |
+| `step` | `number` | `5` |
+| `durationPresets` | `readonly SuiTimeDurationPreset[]` | `DEFAULT_DURATION_PRESETS` |
+| `inline` | `boolean` | `false` |
+| `showFooter` | `boolean` | `true` |
+| `value` · model, `[(value)]` | `SuiTimeValue \| null` | `null` |
+
+Outputs: ninguno.
+
+### `sui-time-picker-duration`
+
+| input | tipo | default |
+|---|---|---|
+| `label` | `string` | — (requerido) |
+| `active` | `boolean` | `false` |
+| `disabled` | `boolean` | `false` |
+
+| output | payload |
+|---|---|
+| `clicked` | `Event` |
+
+### `sui-time-picker-item`
+
+| input | tipo | default |
+|---|---|---|
+| `time` | `string` | — (requerido) |
+| `meridiem` | `string \| null` | `null` |
+| `rightTime` | `string \| null` | `null` |
+| `rightMeridiem` | `string \| null` | `null` |
+| `direction` | `'right' \| 'center'` | `'right'` |
+| `active` | `boolean` | `false` |
+| `highlighted` | `boolean` | `false` |
+| `disabled` | `boolean` | `false` |
+
+| output | payload |
+|---|---|
+| `clicked` | `Event` |
+
+### `sui-time-picker-status`
+
+| input | tipo | default |
+|---|---|---|
+| `type` | `'available' \| 'busy' \| 'in-meeting' \| 'offline'` | `'available'` |
+| `label` | `string \| null` | `null` |
+| `selected` | `boolean` | `false` |
+| `disabled` | `boolean` | `false` |
+
+| output | payload |
+|---|---|
+| `clicked` | `Event` |
+<!-- api:fin -->
+
+Es `ControlValueAccessor`; `writeValue` acepta también un string `"21:30"`.
+
+```ts
+interface SuiTimeValue { hours: number; minutes: number; }   // hours en 0–23 aunque el format sea 12h
+interface SuiTimeDurationPreset { label: string; minutes: number; }
+```
+
+## Trampas
+
+- **Los presets de duración no son duraciones**: «30 min» pone la hora en 00:30 (12:30 AM). Por eso
+  se pasan siempre `[durationPresets]="[]"`. Sin eso, el panel muestra cuatro pastillas que
+  rompen la hora.
+- **`value.hours` va de 0 a 23** aunque se muestre en 12h: 9:30 PM es `{ hours: 21, minutes: 30 }`.
+- **Al abrir sin valor arranca en 9:00 AM**, no vacío.
+- **Cerrar con clic afuera o Escape descarta** lo elegido, igual que Cancelar.
+- Con `step` que no contiene el minuto guardado (21:37 con step 5), la columna de minutos no
+  marca ninguno.
+- Cancelar / Aplicar solo crecen con `size="large"`: con `medium` en mobile siguen en 36. En el
+  teléfono va `large`.
+- El panel flota con el overlay del DS (como `sui-select`): se da vuelta si no entra abajo.
+- `sui-time-picker-status` dice «Disponible», «Ocupado», «En reunión» y «Desconectado» por
+  defecto (antes venían en inglés del Figma); `label` sigue sirviendo para cambiarlo.
+- El atributo `title` del host se borra solo (no sale el tooltip gris del navegador).
+
+## Ejemplo
+
+```html
+<!-- Horario del local: abre / cierra -->
+<sui-time-picker label="Abre" format="12h" [step]="5" [durationPresets]="[]"
+                 [value]="apertura()" (valueChange)="apertura.set($event)" />
+<sui-time-picker label="Cierra" format="12h" [step]="5" [durationPresets]="[]"
+                 [error]="cierraAntes()" errorMessage="Cierra antes de abrir"
+                 [value]="cierre()" (valueChange)="cierre.set($event)" />
+```

package/docs/sui-toast/README.md

@@ -0,0 +1,190 @@
+---
+name: sui-toast
+selector: sui-toast-outlet
+resumen: Aviso efímero que confirma el resultado de una acción y se va solo; se dispara con SuiToastService
+alternativas: [sui-alert (aviso que se queda, en su contexto), sui-banner (toda la app), sui-notification (fila de la bandeja, con hora), sui-form-hint (error de un campo)]
+---
+
+# sui-toast
+
+Story: [Molecules/Feedback/Toast](https://sui-design-system.web.app/?path=/docs/molecules-feedback-toast--docs)
+
+No hay una etiqueta `<sui-toast>`: el toast son **dos piezas**. `SuiToastService` (se inyecta y se
+llama: `toast.success(…)`) y `<sui-toast-outlet />`, que se monta **una sola vez** en la raíz de
+la app y dibuja la pila. Cada toast es, por dentro, un `sui-alert` `size="large"`. El apilado, la
+salida y los tiempos copian a Sonner (la librería de toasts que usa la guía del DS).
+
+## Cuándo usarlo / cuándo no
+
+**Úsalo** para el **resultado de algo que la persona acaba de hacer** («Cambios guardados», «No
+se pudo eliminar el producto») y para un aviso que **llega mientras usa la app** y no necesita
+quedarse (un push con la app abierta, «Nueva versión disponible»). Aparece, se lee y se va.
+
+**No lo uses** para:
+
+- Algo que tiene que seguir visible para que la persona actúe: un error que bloquea, un motivo
+  de rechazo, un «no puedes eliminar tu cuenta porque…». Eso es `sui-alert`, ahí mismo. Un toast
+  con `duration: Infinity` y sin acción es un alert mal puesto.
+- Un **error al cargar** una pantalla: el toast se va y deja la pantalla vacía sin explicación.
+  Va un `sui-alert` `filled` o un `sui-empty-state` con «Reintentar».
+- El error de un campo de formulario: `sui-form-hint` o el `errorMessage` del input.
+- Algo de toda la app que dura (plan vencido): `sui-banner`.
+
+Regla corta (canon, la misma del alert): **contexto → alert · toda la app → banner · efímero →
+toast · bandeja → notification.**
+
+## Qué variante usar
+
+> La guía del DS define el toast pero no dice cuándo va cada tipo. Lo marcado «según la guía del
+> DS» sale de su texto o de su código publicado; «canon» es lo ya aprobado (README de `sui-alert`,
+> `docs/CANON-SUI.md` o un pedido del dueño escrito en el código); el resto es **propuesta**.
+>
+> Uso medido el 03-10-2026 en `master-pedidos/src/app` (sin prototipos, vitrinas ni tests):
+> **~700 llamadas en 106 archivos**; de ellas, **560 con título fijo** (en 102 archivos) — 348 `error`,
+> 179 `success`, 23 `info`, 10 `warning`, 0 `feature` — más 3 `show()`. El resto arma el título con variables.
+
+### Lo que sí dice la guía del DS
+
+- **Para qué es**: feedback **breve** en tamaño compacto; varios se pueden **apilar**.
+- **Una línea**: lo arma con un alert `small` (título solo, sin descripción) de 360 px de ancho.
+  SUI lo arma con un alert `large`, que sí admite descripción.
+- **Defaults**: relleno `stroke`, posición `bottom-center`, cerrable. SUI arranca en
+  `stroke-dark` y `bottom-right`.
+- **Ojo con la palabra «notification»**: en la guía, una notification es un aviso temporal en una
+  esquina con título, descripción y acción (un pago, una actualización). En SUI ese caso **también
+  es un toast** (`description` + `action`); `sui-notification` es otra cosa: la fila de la bandeja.
+
+### El tipo — qué método llamar
+
+| método | cuándo | ejemplo real de la app | fuente |
+|---|---|---|---|
+| `success()` | La acción salió como se esperaba. Dice **qué** quedó hecho. | `pages/sales-channels/instagram/instagram.ts:102` («Cambios guardados») | propuesta (sigue la regla canon del alert) |
+| `error()` | La acción **no** salió. Dice qué no se pudo, nunca «Error al…» ni el mensaje técnico. | `pages/driver/driver-profile/driver-profile.ts:516` («No se pudo guardar el vehículo») | canon (copy: `docs/CANON-SUI.md` §5.7) |
+| `warning()` | Salió, **pero** con un pero que la persona tiene que saber. | `pages/super-admin/master-promos/master-promos.ts:171` («Push enviada, pero ningún cliente está dentro del radio») | propuesta |
+| `info()` | Algo que **llega** y no es el resultado de lo que hiciste: un push con la app abierta, una versión nueva. | `core/services/aviso-unico.service.ts:52` · `core/services/update.service.ts:59` | propuesta |
+| `feature()` | No usar hoy (0 usos). **Cuándo sí:** avisar una función nueva en el momento en que se activa («Ya puedes programar tus pedidos»). | — | propuesta |
+| `show({ variant })` | Lo mismo que los de arriba, cuando hace falta pasar todo junto. | `pages/empresa/about/about.ts:103` | según el componente |
+
+### `style` — el relleno
+
+| style | cuándo | fuente |
+|---|---|---|
+| `stroke-dark` (default SUI) | **Siempre.** Flota sobre cualquier pantalla y el oscuro contrasta con todas. | canon (README de `sui-alert`: «default del toast») |
+| `stroke` (default de la guía) | No usar hoy: blanco sobre blanco se confunde con el contenido. **Cuándo sí:** una pantalla de fondo oscuro (una landing), donde el oscuro se pierde. | propuesta |
+| `lighter` · `light` · `filled` | No usar hoy: un toast que pesa más que el oscuro compite con el botón principal, y si tiene que pesar más, no es un toast. **Cuándo sí:** ninguno previsto; ese caso es un alert o un modal. | propuesta |
+
+### Tiempo, cierre, acción y texto
+
+| opción | valor | cuándo | fuente |
+|---|---|---|---|
+| `duration` | `4000` (default) | Un título corto. | según el componente (valor de Sonner) |
+| `duration` | `6000` | Título más `description`, o un título largo que no se alcanza a leer en 4 s. | propuesta |
+| `duration` | `60_000` | Los avisos de un pedido que llegan con la app abierta: tiempo de verlos sin quedarse tapando. | canon (pedido del dueño, 28-09-2026, en `aviso-unico.service.ts`) |
+| `duration` | `Infinity` | **Solo con `action`**: hay algo que hacer y no se puede perder («Actualizar»). Sin acción, es un alert. | propuesta |
+| `dismissible` | `true` (default) | Siempre: la X permite quitarlo antes. La guía lo trae cerrable por defecto. | según la guía del DS |
+| `dismissible` | `false` | No usar hoy. **Cuándo sí:** un toast de progreso que se reemplaza solo usando el mismo `id` («Subiendo foto…» → «Foto subida»). | propuesta (la guía muestra un ejemplo no cerrable) |
+| `action` | `{ label, onClick, keepOpen? }` | **Una** acción corta que resuelve ahí mismo: «Actualizar», «Deshacer», «Reintentar». Se dibuja como link subrayado. | propuesta |
+| `title` | frase corta | Qué pasó, en sentence case, **sin punto final**. Una idea. | canon (copy de la app) |
+| `description` | segunda frase | Si hace falta una segunda frase, va aquí y no pegada al título con un punto. | propuesta |
+| `position` | `bottom-right` (default) | Siempre. En mobile toda posición pasa a ancho completo; las `bottom-*` quedan abajo, por encima de la barra inferior. | propuesta |
+| `position` | `top-*` | No usar hoy. **Cuándo sí:** una pantalla con una barra de acción fija abajo que el toast taparía. | propuesta |
+| `position` | `bottom-left` · `bottom-center` | No usar hoy: dos esquinas abren dos pilas. **Cuándo sí:** si se decide cambiar la esquina de toda la app, con `setDefaultPosition()`, una sola vez. | propuesta |
+| `id` | texto | Para reemplazar un toast en curso o no repetir el mismo aviso. | según el componente |
+
+### Usos de hoy que rompen la regla
+
+- **Rompen el canon — 3 toasts de error que no se van y no tienen acción → `sui-alert`** en el
+  modal de eliminar cuenta: `pages/empresa/about/about.ts:103`, `pages/repartidor/about/about.ts:97`,
+  `pages/customer/about/about.ts:135` («No puedes eliminar tu cuenta» + el motivo, `duration: Infinity`).
+- **Rompen el canon de copy — 104 errores que empiezan con «Error…»** («Error al cargar productos»)
+  → «No se pudo…»: `pages/products/products.ts:415`, `pages/customers/customers.ts:244`,
+  `pages/settings/team/team.ts:315`. Y **26** que concatenan `e.message` al texto (puede salir
+  texto técnico o en inglés).
+- **Rompen el canon de copy — 5 títulos en minúscula:** `pages/driver/driver-profile/driver-profile.ts:538`
+  («ubicación activada»), `:552`, `:597`, `:614`, `pages/driver/driver-order-detail/driver-order-detail.ts:438`.
+- **Romperían la propuesta — 47 errores al cargar como toast** → alert o empty state con
+  «Reintentar»: `pages/products/products.ts:415`, `pages/driver/driver-history/driver-history.ts:198`.
+- **Romperían la propuesta — 126 títulos con punto final**, casi todos dos frases en una →
+  título + `description`: `components/map-picker-modal/map-picker-modal.ts:260` («Permiso denegado.
+  Usa la barra de búsqueda…»), `core/services/compartir-viaje.service.ts:78`. 62 pasan de 60
+  caracteres.
+
+## Tamaño en mobile y en web
+
+El toast **no tiene `size`**: siempre es un alert `large`.
+
+| uso | mobile (≤ 767 px) | web | fuente |
+|---|---|---|---|
+| ancho | todo el ancho, con margen lateral | hasta 360 px, en la esquina | según el componente |
+| dónde | abajo, por encima de la barra inferior (nativa en iOS) | abajo a la derecha | según el componente |
+| la X de cerrar | se ve de 20 px; **se toca en 40 × 40** | igual | canon (aprobado por el dueño, 03-10-2026): área táctil invisible, extensión SUI |
+| la acción | link `medium` (20 px de alto) | link `medium` | según el componente |
+
+No hay patrón `bp.isMobile()`: el outlet ya cambia solo por breakpoint. Lo que sí cambia por
+plataforma es el largo del texto: en mobile el título envuelve antes, así que una sola idea por toast.
+
+## «No usar»: por qué no hoy y cuándo sí
+
+Nada se borra del DS. Si un flujo nuevo cae en la columna de la derecha, se usa.
+
+| qué | por qué no hoy | cuándo sí, en un flujo nuevo |
+|---|---|---|
+| `feature()` | no hay novedades que se anuncien al activarlas | «Ya puedes programar tus pedidos», justo cuando se activa |
+| `style` `stroke` | blanco sobre blanco | una pantalla de fondo oscuro (landing) |
+| `style` `lighter`, `light`, `filled` | un toast que pesa más ya no es un toast | ninguno previsto: es un alert o un modal |
+| `dismissible: false` | todo toast se puede quitar | un toast de progreso que se reemplaza con el mismo `id` |
+| `position` distinta de la default | dos pilas en dos esquinas | una pantalla con barra fija abajo (`top-*`), o mover toda la app con `setDefaultPosition()` |
+| `duration: Infinity` sin `action` | no se va y no hay nada que hacer | ninguno: eso es un alert |
+
+## API
+
+<!-- api:inicio -->
+<!-- generada: no editar a mano — `npm run docs` -->
+
+Inputs: ninguno.
+
+Outputs: ninguno.
+<!-- api:fin -->
+
+## Trampas
+
+- **La X se toca en 40 × 40** aunque se vea de 20 (un `::before` invisible sobre su `<button>`,
+  desde 03-10-2026). Solo llega a la app cuando deje de usar su copia local del toast (ver abajo).
+- **La app no usa el servicio del paquete.** `master-pedidos` tiene una copia local en
+  `src/app/components/sui/sui-toast/` y el outlet montado en `app.ts:66` es esa copia. La API es la
+  misma; la diferencia es que la copia lee la altura de la barra nativa desde `LiquidGlassService`,
+  y la del paquete desde el token `SUI_TAB_BAR`. Si inyectas `SuiToastService` del paquete en la
+  app, **no aparece nada**: su outlet no está montado. Migrar = importar del paquete y proveer
+  `SUI_TAB_BAR`.
+- **El comentario de `style` miente:** dice `// default 'stroke'`, pero el código pone `'stroke-dark'`.
+- **Sin outlet no hay toasts:** el temporizador de cierre vive en el outlet, no en el servicio. Si el
+  outlet no está montado, los toasts se acumulan en el signal y nunca se ven ni se van.
+- `dismissible` arranca en `true` aquí y en `false` en `sui-alert` y `sui-banner`.
+- La acción cierra el toast al tocarla, salvo `keepOpen: true`.
+- Al pasar el dedo o el mouse por la pila se abre en abanico y se queda abierta 1,2 s después de
+  cerrar uno, para seguir tocando (patrón Sonner).
+- La pila lleva `aria-live="polite"`: el lector de pantalla anuncia cada toast.
+- El título es texto plano; la `description` del alert interno va por `innerHTML`: no le pases
+  texto escrito por el usuario sin sanear.
+
+## Ejemplo
+
+```ts
+private readonly toast = inject(SuiToastService);
+
+guardar() {
+  this.toast.success('Cambios guardados');
+}
+
+fallo() {
+  this.toast.error('No se pudo eliminar el producto', { description: 'Revisa tu conexión y vuelve a intentar.', duration: 6000 });
+}
+
+versionNueva(v: string) {
+  this.toast.info('Nueva versión disponible', {
+    description: `Actualiza para usar la versión ${v}.`,
+    duration: Infinity,
+    action: { label: 'Actualizar', onClick: () => location.reload() },
+  });
+}
+```