@ajuarezso/sui-design-system 0.20.0 → 0.21.0

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() },
+  });
+}
+```

package/docs/sui-tooltip/README.md

@@ -0,0 +1,201 @@
+---
+name: sui-tooltip
+selector: "[suiTooltip], [suiTooltipLarge]"
+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
+
+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; el resto es **propuesta**.
+>
+> Uso medido el 03-10-2026 en `master-pedidos/src/app` (sin prototipos ni vitrinas): **6 tooltips**
+> en 6 archivos — 2 `suiTooltip` de texto en el panel del local y 4 `suiTooltipLarge` en el flujo de
+> compra del cliente.
+
+### 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` (24 px de alto, texto 12) | `xsmall` | texto de una línea, chico | El nombre de un ícono en una tabla o barra densa. | escala según la guía del DS · cuándo: propuesta |
+| `medium` (34 px, texto 14) — default SUI | `small` (default de la guía) | texto de una línea | Lo normal: una frase corta que explica. | escala según la guía del DS · cuándo: propuesta |
+| `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: propuesta |
+| `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. | `components/customer-segments/customer-segments.html:8` («Ingresos por tipo de cliente») | propuesta |
+| `[suiTooltipLarge]="{ title, description, icon }"` | Un término que necesita título y explicación. | `core/service-fee.ts:33` («Tarifa de servicio») | propuesta |
+| `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. | `core/service-fee.ts:39` (hoy en `true`, en pantallas solo de mobile) | propuesta |
+
+### `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. Hoy lo usan los 4 del cliente. | 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. | propuesta |
+| `position` | `right` · `left` | Íconos de una barra lateral angosta (el sidebar colapsado). | propuesta |
+| `position` | `bottom` · `*-start` · `*-end` | Un elemento pegado al borde de arriba o a un costado de la pantalla. | propuesta |
+| `delay` | `200` (default) | Siempre: evita que se abra al cruzar con el mouse. | propuesta |
+| `delay` | otro valor | No usar hoy. **Cuándo sí:** ninguno previsto. | propuesta |
+| `disabled` | `true` | Cuando lo que dice ya está a la vista (el sidebar expandido muestra el nombre). | propuesta |
+| `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. | propuesta |
+
+### Usos de hoy que rompen la regla
+
+- **4 tooltips en pantallas que solo existen en el celular** (la explicación de la tarifa de
+  servicio del cliente): `pages/customer/cart/cart.html:177`, `pages/customer/checkout/checkout.html:366`,
+  `pages/customer/confirmation/confirmation.html:188`, `pages/customer/order-tracking/order-tracking.html:684`.
+  Rompen la guía (hover o foco). Pasarían a un `sui-modal-sheet` al tocar el ícono, con el mismo
+  texto de `core/service-fee.ts`.
+- **2 tooltips sobre un `<svg>` que no se puede enfocar** (y con `#a3a3a3` suelto):
+  `components/customer-segments/customer-segments.html:8`, `components/product-categories/product-categories.html:8`.
+  Ni el teclado ni el dedo llegan. El host pasaría a un botón de solo ícono con `aria-label`.
+
+## 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` | `small` | propuesta |
+| frase que explica | no aplica: el texto va visible bajo el dato (`sui-form-hint`) | `medium` | propuesta |
+| explicación con título | no aplica: `sui-modal-sheet` al tocar el ícono | `large` (automático con `[suiTooltipLarge]`) | propuesta |
+
+En pantallas que se usan en los dos (panel del local, super admin), el tooltip se apaga en mobile
+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.isMobile()"
+  (click)="bp.isMobile() && abrirExplicacion()">
+  <sui-icon name="information-line" [size]="16" />
+</button>
+```
+
+## «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` -->
+
+### `[suiTooltip], [suiTooltipLarge]`
+
+| input | tipo | default |
+|---|---|---|
+| `suiTooltip` | `string` | `''` |
+| `suiTooltipLarge` | `SuiTooltipLargeData \| null` | `null` |
+| `position` | `'top' \| 'top-start' \| 'top-end' \| 'right' \| 'bottom' \| 'bottom-start' \| 'bottom-end' \| 'left'` | `'top'` |
+| `suiTooltipSize` (propiedad `size`) | `'small' \| 'medium' \| 'large' \| 'xlarge'` | `'medium'` |
+| `theme` | `'light' \| 'dark' \| 'auto'` | `'light'` |
+| `delay` | `number` | `200` |
+| `disabled` | `boolean` | `false` |
+| `showArrow` | `boolean` | `true` |
+
+Outputs: ninguno.
+
+### `sui-tooltip-panel`
+
+| input | tipo | default |
+|---|---|---|
+| `text` | `string` | `''` |
+| `position` | `'top' \| 'top-start' \| 'top-end' \| 'right' \| 'bottom' \| 'bottom-start' \| 'bottom-end' \| 'left'` | `'top'` |
+| `size` | `'small' \| 'medium' \| 'large' \| 'xlarge'` | `'medium'` |
+| `theme` | `'light' \| 'dark'` | `'light'` |
+| `showArrow` | `boolean` | `true` |
+| `title` | `string \| null` | `null` |
+| `description` | `string \| null` | `null` |
+| `icon` | `string \| null` | `null` |
+| `dismissible` | `boolean` | `false` |
+
+| output | payload |
+|---|---|
+| `dismissed` | `void` |
+<!-- api: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="small" 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.
+
+## Ejemplo
+
+```html
+<!-- Nombre de un botón de solo ícono, en web -->
+<sui-compact-button icon="download-2-line" ariaLabel="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>
+```