@ajuarezso/sui-stencil 0.0.0-stage → 0.1.0

package/docs/sui-toast/README.md

@@ -0,0 +1,297 @@
+---
+name: sui-toast
+selector: sui-toast
+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
+
+<!-- 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-toast`); 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: [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`, un pedido del dueño escrito en el código o su aprobación del 05-10-2026); lo que
+> quede en **propuesta** espera decisión.
+>
+> Uso medido el 04-10-2026 en `master-pedidos/src/app` (sin prototipos, vitrinas ni tests):
+> **705 llamadas en 108 archivos**, todas con el `SuiToastService` de la copia local. El desglose
+> por tipo está abajo, en «Usos de hoy que rompen la regla».
+
+### 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») | canon (aprobado por el dueño, 05-10-2026, bloque B2; 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») | canon (aprobado por el dueño, 05-10-2026, bloque B2) |
+| `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` | canon (aprobado por el dueño, 05-10-2026, bloque B2) |
+| `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»). | — | canon (aprobado por el dueño, 05-10-2026, bloque B6) |
+| `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. | canon (aprobado por el dueño, 05-10-2026, bloque B6) |
+| `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. | canon (aprobado por el dueño, 05-10-2026, bloque B6) |
+
+### 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. | canon (aprobado por el dueño, 05-10-2026, bloque B9) |
+| `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. | canon (aprobado por el dueño, 05-10-2026, bloque B9) |
+| `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»). | canon (aprobado por el dueño, 05-10-2026, bloque B6; 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. | canon (aprobado por el dueño, 05-10-2026, bloque B9) |
+| `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. | canon (CLAUDE.md «Canon de UI» → `docs/VOZ-Y-ESCRITURA.md` «Toasts: la regla completa»: dos frases nunca en el título; D10) |
+| `position` | `bottom-right` (default) | Siempre. En mobile toda posición pasa a ancho completo; las `bottom-*` quedan abajo, por encima de la barra inferior. | canon (aprobado por el dueño, 05-10-2026, bloque B9) |
+| `position` | `top-*` | No usar hoy. **Cuándo sí:** una pantalla con una barra de acción fija abajo que el toast taparía. | canon (aprobado por el dueño, 05-10-2026, bloque B6) |
+| `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. | canon (aprobado por el dueño, 05-10-2026, bloque B6) |
+| `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
+
+Medido de nuevo el 04-10-2026: 705 llamadas en 108 archivos. Con el título escrito entre comillas
+simples: 328 `error`, 123 `success`, 18 `info`, 5 `warning`, 0 `feature`, más 3 `show()`; el resto
+arma el título con variables. La pasada de copy del 03-10-2026 en la app ya corrigió casi todos los
+«Error al…», los títulos en minúscula, los títulos con punto final y los 3 toasts sin acción y con
+`duration: Infinity` de «Acerca de» (ahora duran 6 s). Queda:
+
+- **Rompe el canon de copy — 1 error que empieza con «Error…»:**
+  `pages/driver/driver-order-detail/driver-order-detail.ts:1647` («Error al cancelar el pedido»; línea al 06-10-2026).
+- **Rompen el canon de copy — 18 errores que muestran `e.message`** cuando existe (puede salir
+  texto técnico o en inglés): `components/transfer-tenant-modal/transfer-tenant-modal.ts:84`,
+  `pages/driver/driver-dashboard/driver-dashboard.ts:1706`, `pages/central/central-gastos/central-gastos.ts:185`
+  (y `:205`). Algunos de esos textos de respaldo además llevan punto final
+  (`pages/super-admin/master-viajes/master-viajes.ts:243`, «No se pudo habilitar.»; líneas al 06-10-2026).
+- **Romperían la propuesta — 57 errores al cargar como toast** («No se pudo cargar…») → alert o
+  empty state con «Reintentar»: `pages/driver/driver-history/driver-history.ts:200`,
+  `pages/settings/team/team.ts:308`.
+
+## 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 44 × 44** | se ve de 20; se toca en 40 × 40 | canon (dueño, 04-10-2026): piso táctil 44 en el teléfono (antes 40, pedido del 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.
+
+### Por dispositivo (D16)
+
+El toast no tiene `size` (siempre es un alert `large`): no hay size que elegir por dispositivo ni
+nada que pasar desde la app (en master-pedidos no lleva `bp`). Ancho y posición los resuelve el
+outlet solo, por ancho, y está bien así.
+
+Lo que **sí** queda corto es la X de cerrar, que se toca:
+
+| dispositivo | área de la X hoy | D16 pide |
+|---|---|---|
+| celular chico y celular (≤ 767 px) | 44 × 44 | 44 × 44 (cumple) |
+| tablet táctil (`pointer: coarse`, más de 767 px) | **40 × 40** | 44 × 44 |
+| computadora (`pointer: fine`) | 40 × 40 | sin piso de 44 (cumple) |
+
+**Pendiente del DS**, no de la app: el área de 44 se prende con `@media (max-width: 767px)`
+(`sui-toast-outlet.scss:182`), así que el iPad apaisado y la tablet ancha se quedan en 40. Se
+arregla con el mixin `sui-tactil` (`@media (max-width: 767px), (pointer: coarse)`) que propone la
+sección 0 de las decisiones D16; mientras no exista, no hay nada que la app pueda pasar para
+corregirlo.
+
+## «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` -->
+
+| prop | atributo | tipo | default |
+|---|---|---|---|
+| `closeLabel` | `close-label` | `string` | `'Cerrar'` |
+| `defaultPosition` | `default-position` | `"bottom-center" \| "bottom-left" \| "bottom-right" \| "top-center" \| "top-left" \| "top-right"` | `'bottom-right'` |
+| `regionLabel` | `region-label` | `string` | `'Notificaciones'` |
+| `tabBarOffset` | `tab-bar-offset` | `number` | `0` |
+
+Eventos: ninguno.
+
+| método | firma |
+|---|---|
+| `dismiss` | `dismiss(id: string) => Promise<void>` |
+| `error` | `error(title: string, opts?: Partial<SuiToastData>) => Promise<string>` |
+| `feature` | `feature(title: string, opts?: Partial<SuiToastData>) => Promise<string>` |
+| `info` | `info(title: string, opts?: Partial<SuiToastData>) => Promise<string>` |
+| `show` | `show(config: SuiToastData) => Promise<string>` |
+| `success` | `success(title: string, opts?: Partial<SuiToastData>) => Promise<string>` |
+| `warning` | `warning(title: string, opts?: Partial<SuiToastData>) => Promise<string>` |
+
+### Diferencias con el SUI Angular
+
+- **Props solo de aquí:** `closeLabel`, `defaultPosition`, `regionLabel`, `tabBarOffset`
+<!-- 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 |
+|---|---|---|
+| `notificacion.region` | Notificaciones | — |
+| `comun.cerrar` | Cerrar | — |
+<!-- textos:fin -->
+
+## Trampas
+
+- **La X se toca en 44 × 44 en el teléfono** (40 × 40 en web) aunque se vea de 20 (un `::before`
+  invisible sobre su `<button>`; 44 desde el 04-10-2026). La copia local de la app tiene el mismo arreglo (commit 2c637a19).
+- **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`.
+- **`CLAUDE.md` de la app dice que el toast es `ngx-sonner`: está desactualizado.** `ngx-sonner`
+  no está instalado y nadie lo importa; las 705 llamadas usan el `SuiToastService` de la copia
+  local. Ese es el canon en la app hoy (`toast.success(…)`, el mismo nombre de método que Sonner).
+- **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, una vez. El
+  `sui-alert` de adentro va con `ariaRole="none"` (desde el 04-10-2026): antes llevaba su propio
+  `role="alert"` y el toast se podía anunciar dos veces y de forma asertiva.
+- El título es texto plano; la `description` del alert interno va por `innerHTML`: no le pases
+  texto escrito por el usuario sin sanear.
+
+## Bien y mal
+
+El copy del error
+
+```ts
+// ❌ mal: «Error al…» en vez de decir qué no se pudo (pages/driver/driver-order-detail/driver-order-detail.ts:1647)
+this.toast.error('Error al cancelar el pedido');
+```
+
+```ts
+// ✅ bien
+this.toast.error('No se pudo cancelar el pedido');
+```
+
+El mensaje técnico en el título
+
+```ts
+// ❌ mal: e.message puede ser técnico o en inglés (pages/driver/driver-dashboard/driver-dashboard.ts:1706)
+this.toast.error((e instanceof Error && e.message) || 'No se pudo abrir la votación');
+```
+
+```ts
+// ✅ bien: el detalle va a la consola; la persona lee qué no se pudo
+console.error('[votación]', e);
+this.toast.error('No se pudo abrir la votación');
+```
+
+Un error al cargar la pantalla (sigue en propuesta: ver «Usos de hoy que rompen la regla»)
+
+```ts
+// ❌ mal: el toast se va y deja la lista vacía sin explicación (pages/driver/driver-history/driver-history.ts:200)
+this.toast.error('No se pudo cargar el historial');
+```
+
+```ts
+// ✅ bien: la pantalla queda con un sui-alert o un sui-empty-state con «Reintentar»
+this.errorAlCargar.set(true);
+```
+
+## 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() },
+  });
+}
+```

package/docs/sui-tooltip/README.md

@@ -0,0 +1,271 @@
+---
+name: sui-tooltip
+selector: sui-tooltip
+resumen: Directiva que muestra una ayuda corta al pasar el mouse o al enfocar un elemento; solo web, no sirve con el dedo
+alternativas: [sui-form-hint (ayuda visible bajo un campo), sui-modal-sheet (explicación que se abre al tocar, en mobile), sui-popover (panel que señala algo y pide una acción)]
+---
+
+# sui-tooltip
+
+<!-- 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-tooltip`); 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: [Molecules/Tooltip](https://sui-design-system.web.app/?path=/docs/molecules-tooltip--docs)
+
+Es una **directiva**, no una etiqueta: se pone sobre el elemento que explica
+(`<button suiTooltip="Editar">`). El globo lo dibuja `sui-tooltip-panel` en el overlay del CDK.
+
+## Cuándo usarlo / cuándo no
+
+**Úsalo** en **web** para dar contexto a algo que se puede tocar o enfocar: el nombre de un botón
+de solo ícono («Editar», «Exportar»), o qué significa un término al lado de un dato («Tarifa de
+servicio»). Es un extra: la pantalla tiene que entenderse sin él.
+
+**No lo uses** para:
+
+- **Mobile.** No hay hover: la directiva solo escucha `mouseenter` y `focus`. Con el dedo depende de
+  cómo el navegador imite el mouse: a veces abre, se cierra al hacer scroll y no se cierra al tocar
+  afuera. En las pantallas del cliente y del repartidor, la explicación va **visible** (una línea bajo
+  el dato, `sui-form-hint`) o en un `sui-modal-sheet` que se abre al tocar el ícono.
+- Información que hace falta para decidir (un precio, una condición): eso se escribe en la pantalla.
+- Un elemento que no se puede enfocar (`<svg>`, `<span>`): con teclado nunca aparece. El host tiene
+  que ser un botón.
+- Algo que pide una acción («Siguiente», «Entendido»): eso es `sui-popover`.
+
+## Qué variante usar
+
+> La guía del DS dice para qué es y cómo se llaman sus tamaños, pero no cuándo va cada uno. Lo
+> marcado «según la guía del DS» sale de su texto o su código publicado; lo marcado canon lo aprobó
+> el dueño (05-10-2026); lo que sigue en **propuesta** espera decisión.
+>
+> Uso medido el 04-10-2026 en `master-pedidos/src/app` (sin prototipos ni vitrinas): **0 tooltips**.
+> Los 6 que había el 03-10-2026 (2 `suiTooltip` sobre un `<svg>` en el panel del local y 4
+> `suiTooltipLarge` en el flujo de compra del cliente) pasaron a texto visible en el commit
+> `77ac547a` de la app.
+
+### Lo que sí dice la guía del DS
+
+- **Para qué es**: agrega contexto a elementos **interactivos** y aparece al pasar el mouse o con el
+  **foco del teclado**. Por eso no sirve con el dedo.
+- **Tres tamaños**, con nombres corridos un paso respecto a SUI (tabla abajo).
+- **Default**: tema `dark` y tamaño intermedio. SUI arranca en tema `light`.
+- La flecha siempre está; la posición sigue al espacio disponible.
+
+### `size` (input `suiTooltipSize`) — equivalencia con la guía
+
+| SUI | guía | qué es | cuándo | fuente |
+|---|---|---|---|---|
+| `small` (caja de 20 px en `dark`, 22 en `light` por el borde; 24 con la flecha; texto 12) | `xsmall` | texto de una línea, chico | No usar: es chico. El nombre de un ícono también va en `medium`. | escala según la guía del DS · no usarlo: canon (dueño, 05-10-2026, D16), reemplaza el «cuándo» del bloque B1 |
+| `medium` (caja de 28 px en `dark`, 30 en `light`; 34 con la flecha; texto 14) — default SUI | `small` (default de la guía) | texto de una línea | Lo normal: una frase corta que explica, o el nombre de un ícono. | escala según la guía del DS · cuándo: canon (aprobado por el dueño, 05-10-2026, bloque B1) · el nombre de un ícono: canon (dueño, 05-10-2026, D16) |
+| `large` (280 px, título + descripción + ícono) | `medium` | contenido rico | Explicar un término con título y una o dos frases. Se activa solo al usar `suiTooltipLarge`. | escala según la guía del DS · cuándo: canon (aprobado por el dueño, 05-10-2026, bloque B1) |
+| `xlarge` (320 px) | — | rico, más ancho | No usar hoy. Extensión de SUI. **Cuándo sí:** una explicación rica que en 280 px queda en más de cuatro líneas. | propuesta |
+
+### Contenido: `suiTooltip` o `suiTooltipLarge`
+
+| input | cuándo | ejemplo real de la app | fuente |
+|---|---|---|---|
+| `suiTooltip="…"` | Una frase, sin punto final. | (sin uso hoy) | canon (aprobado por el dueño, 05-10-2026, bloque B4) |
+| `suiTooltipLarge={{ title, description, icon }}` | Un término que necesita título y explicación. | (sin uso hoy) | canon (aprobado por el dueño, 05-10-2026, bloque B9) |
+| `suiTooltipLarge.dismissible: true` | No usar hoy: lo deja abierto hasta tocar la X o Escape, que es lo que hace un popover. **Cuándo sí:** en web, una explicación larga que la persona lee con calma mientras mueve el mouse. | (sin uso hoy) | canon (aprobado por el dueño, 05-10-2026, bloque B6) |
+
+### `theme`, `position` y el resto
+
+| prop | valor | cuándo | fuente |
+|---|---|---|---|
+| `theme` | `auto` | **Siempre.** Oscuro sobre la app en claro (lo que pide la guía) y claro sobre la app en oscuro. | propuesta (la guía: `dark` por default) |
+| `theme` | `dark` | Igual que `auto` en modo claro, pero no se invierte en modo oscuro. | según la guía del DS (default) |
+| `theme` | `light` (default SUI) | No usar hoy: sobre una página clara parece una card más. **Cuándo sí:** ya lo da `auto` en modo oscuro. | propuesta |
+| `position` | `top` (default) | Siempre que haya espacio. Si no lo hay, el CDK lo da vuelta solo. | canon (aprobado por el dueño, 05-10-2026, bloque B9) |
+| `position` | `right` · `left` | Íconos de una barra lateral angosta (el sidebar colapsado). | canon (aprobado por el dueño, 05-10-2026, bloque B9) |
+| `position` | `bottom` · `*-start` · `*-end` | Un elemento pegado al borde de arriba o a un costado de la pantalla. | canon (aprobado por el dueño, 05-10-2026, bloque B9) |
+| `delay` | `200` (default) | Siempre: evita que se abra al cruzar con el mouse. | canon (aprobado por el dueño, 05-10-2026, bloque B9) |
+| `delay` | otro valor | No usar hoy. **Cuándo sí:** ninguno previsto. | canon (aprobado por el dueño, 05-10-2026, bloque B9) |
+| `disabled` | `true` | Cuando lo que dice ya está a la vista (el sidebar expandido muestra el nombre). | canon (aprobado por el dueño, 05-10-2026, bloque B8) |
+| `showArrow` | `true` (default) | Siempre: la flecha dice de qué elemento habla. | según la guía del DS |
+| `showArrow` | `false` | No usar hoy. **Cuándo sí:** sobre un punto de un gráfico, donde la flecha tapa el dato. | canon (aprobado por el dueño, 05-10-2026, bloque B6) |
+
+### Usos de hoy que rompen la regla
+
+Ninguno (04-10-2026). Los 6 que rompían la regla ya se corrigieron en la app (commit `77ac547a`):
+la tarifa de servicio del cliente se explica con una línea visible (`core/service-fee.ts:31`) y los
+dos `<svg>` con tooltip del panel del local pasaron a subtítulo
+(`components/customer-segments/customer-segments.html:6`, `components/product-categories/product-categories.html:6`).
+
+## Tamaño en mobile y en web
+
+| uso | mobile | web | fuente |
+|---|---|---|---|
+| nombre de un ícono | no aplica: el ícono lleva el nombre escrito o `aria-label` | `medium` | mobile: canon (aprobado por el dueño, 05-10-2026, bloque B7) · web: canon (dueño, 05-10-2026, D16), antes `small` |
+| frase que explica | no aplica: el texto va visible bajo el dato (`sui-form-hint`) | `medium` | canon (aprobado por el dueño, 05-10-2026, bloque B7) |
+| explicación con título | no aplica: `sui-modal-sheet` al tocar el ícono | `large` (automático con `suiTooltipLarge`) | canon (aprobado por el dueño, 05-10-2026, bloque B7) |
+
+En pantallas que se usan en los dos (panel del local, super admin), el tooltip se apaga en el
+celular y en la tablet táctil, y la ayuda se muestra de otra forma:
+
+```html
+<button class="info" type="button" aria-label="Qué es la tarifa de servicio"
+  suiTooltipLarge={tarifa} theme="auto" disabled={bp.tactil()}
+  onClick={() => bp.tactil() && abrirExplicacion()}>
+  <sui-icon name="information-line" size="16" />
+</button>
+```
+
+### Por dispositivo (D16)
+
+Fila `tooltip` de la tabla D16 (dueño, 05-10-2026). Solo existe donde hay mouse: con el dedo no hay
+hover, y eso incluye la tablet aunque sea ancha.
+
+| dispositivo | size | nota |
+|---|---|---|
+| celular chico (< 380 px) | no aplica | sin hover: texto visible o un `sui-modal-sheet` al tocar |
+| celular (380–767 px) | no aplica | igual que el celular chico |
+| tablet táctil (`pointer: coarse`) | no aplica | también sin hover; `bp.isMobile()` no la apaga (mide más de 767), `bp.tactil()` sí |
+| computadora (`pointer: fine`) | `medium` (default) | también el nombre de un ícono; `large` sale solo con `suiTooltipLarge`; `small` no se usa |
+
+Ultrawide (≥ 1920 px): igual que la computadora.
+
+En master-pedidos: sin helper de tamaño (`medium` es el default, no se pasa `suiTooltipSize`); se
+apaga con `disabled={bp.tactil()}` y la ayuda va por otro lado.
+
+## «No usar»: por qué no hoy y cuándo sí
+
+| qué | por qué no hoy | cuándo sí, en un flujo nuevo |
+|---|---|---|
+| cualquier tooltip en mobile | no hay hover; con el dedo abre de casualidad | nunca: texto visible o un sheet |
+| `suiTooltipSize="xlarge"` | 280 px alcanzan para lo que hay | una explicación rica que en 280 px pasa de cuatro líneas |
+| `dismissible: true` | queda abierto como un popover | en web, una explicación larga para leer con calma |
+| `theme="light"` | sobre página clara parece una card | ya lo da `auto` en modo oscuro |
+| `showArrow=false` | la flecha dice de qué habla | sobre un punto de un gráfico |
+| `delay` distinto de 200 | se abriría al cruzar con el mouse | ninguno previsto |
+
+## API
+
+<!-- api:inicio -->
+<!-- generada: no editar a mano — `npm run docs` -->
+
+| prop | atributo | tipo | default |
+|---|---|---|---|
+| `content` | `content` | `string` | `''` |
+| `delay` | `delay` | `number` | `200` |
+| `description` | `description` | `null \| string` | `null` |
+| `disabled` | `disabled` | `boolean` | `false` |
+| `dismissible` | `dismissible` | `boolean` | `false` |
+| `icon` | `icon` | `null \| string` | `null` |
+| `large` | `large` | `boolean` | `false` |
+| `position` | `position` | `"bottom" \| "bottom-end" \| "bottom-start" \| "left" \| "right" \| "top" \| "top-end" \| "top-start"` | `'top'` |
+| `showArrow` | `show-arrow` | `boolean` | `true` |
+| `size` | `size` | `"large" \| "medium" \| "small" \| "xlarge"` | `'medium'` |
+| `theme` | `theme` | `"auto" \| "dark" \| "light"` | `'light'` |
+| `titleText` | `title-text` | `null \| string` | `null` |
+
+| evento | `event.detail` |
+|---|---|
+| `suiDismiss` | `void` |
+
+Slots: `(por defecto)`.
+
+### Diferencias con el SUI Angular
+
+- **Props de Angular que aquí no existen:** `suiTooltip`, `suiTooltipLarge`, `suiTooltipSize`
+- **Props solo de aquí:** `content`, `description`, `dismissible`, `icon`, `large`, `size`, `titleText`
+- **Eventos solo de aquí:** `suiDismiss`
+<!-- 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.cerrar` | Cerrar | — |
+<!-- textos:fin -->
+
+```ts
+interface SuiTooltipLargeData {
+  title: string;
+  description?: string;
+  icon?: string;          // RemixIcon sin el prefijo ri-
+  dismissible?: boolean;  // true = se queda abierto hasta la X o Escape
+}
+```
+
+`SuiTooltipPanel` (`sui-tooltip-panel`) es el globo que monta la directiva; también se exporta, pero
+no se usa directo en pantallas.
+
+## Trampas
+
+- **El tamaño se pasa como `suiTooltipSize`**, no como `size`: así no choca con el `size` del
+  componente que lo lleva (`<sui-button size="medium" suiTooltip="…">`).
+- **`position`, `theme`, `delay` y `disabled` sí se llaman así, sin prefijo**: si el host es un
+  componente con un input del mismo nombre (`disabled` de `sui-button`), el valor llega a los dos.
+- **`suiTooltipSize="large"` con `suiTooltip` de texto dibuja una caja vacía**: el tamaño rico solo
+  lee `suiTooltipLarge`. Con `suiTooltipLarge` el tamaño pasa a `large` solo.
+- **Defaults distintos a la guía**: tema `light` (la guía, `dark`) y nombres de tamaño corridos un paso.
+- Se cierra al hacer scroll en cualquier contenedor y con Escape. Con `dismissible`, no se cierra al
+  sacar el mouse.
+- Pone `aria-describedby` en el host y le borra el `title` nativo (si no, saldría además el globo
+  gris del navegador).
+- En `dark`, el ícono del tooltip rico usa un gris fijo del `.scss`, no un token.
+
+## Bien y mal
+
+Tooltip sobre un ícono suelto
+
+```html
+<!-- ❌ mal: un <svg> no se enfoca (con teclado nunca aparece) y en el celular no hay hover (components/customer-segments/customer-segments.html, antes de 77ac547a) -->
+<svg suiTooltip="Ingresos por tipo de cliente" position="top" width="16" height="16" viewBox="0 0 16 16">…</svg>
+```
+
+```html
+<!-- ✅ bien: si es una aclaración del título, va escrita -->
+<p class="customer-segments__subtitle">Ingresos por tipo de cliente</p>
+```
+
+Explicación en una pantalla del cliente
+
+```html
+<!-- ❌ mal: el carrito se usa en el celular, sin hover; la tarifa queda sin explicar (pages/customer/cart/cart.html, antes de 77ac547a) -->
+<button type="button" aria-label="Qué es la tarifa de servicio" suiTooltipLarge={serviceFeeTooltip} theme="dark">
+  <sui-icon name="information-line" size="14" />
+</button>
+```
+
+```html
+<!-- ✅ bien: la explicación va visible bajo el dato -->
+<span class="cart__fee-hint">{serviceFeeExplicacion}</span>
+```
+
+Tamaño rico con texto plano
+
+```html
+<!-- ❌ mal: suiTooltipSize="large" solo lee suiTooltipLarge: con texto dibuja una caja vacía (ver Trampas) -->
+<sui-compact-button icon="download-2-line" aria-label="Exportar" suiTooltip="Exportar" suiTooltipSize="large" theme="auto" />
+```
+
+```html
+<!-- ✅ bien: el nombre de un ícono va en medium, el default -->
+<sui-compact-button icon="download-2-line" aria-label="Exportar" suiTooltip="Exportar" theme="auto" />
+```
+
+## Ejemplo
+
+```html
+<!-- Nombre de un botón de solo ícono, en web -->
+<sui-compact-button icon="download-2-line" aria-label="Exportar" suiTooltip="Exportar" theme="auto" />
+
+<!-- Término con explicación, en web -->
+<button type="button" aria-label="Qué es la tarifa de servicio"
+  suiTooltipLarge={{ title: 'Tarifa de servicio', description: 'Nos ayuda a mantener la plataforma funcionando.', icon: 'information-line' }}
+  theme="auto">
+  <sui-icon name="information-line" size="16" />
+</button>
+```