@yewdiel21/motion-kit 0.10.0 → 0.14.0

package/src/components/timeline/react.tsx

@@ -0,0 +1,59 @@
+'use client';
+import { useRef, type HTMLAttributes } from 'react';
+import { useIsomorphicLayoutEffect } from '../../react/use-recipe';
+import { createTimeline, type TimelineEvent, type TimelineInstance, type TimelineOptions } from './engine';
+
+export interface TimelineProps extends Omit<HTMLAttributes<HTMLDivElement>, 'children'>, Omit<TimelineOptions, 'events'> {
+  events: TimelineEvent[];
+}
+
+/**
+ * <Timeline events={history} group />. Changing `events` updates in place: an event added at either end grows in,
+ * one that changes state recolours its dot, one that goes folds away.
+ */
+export function Timeline({ events, layout, group, relative, locale, label, className, ...props }: TimelineProps) {
+  const ref = useRef<HTMLDivElement>(null);
+  const instance = useRef<TimelineInstance | null>(null);
+  const shown = useRef<TimelineEvent[]>(events);
+  useIsomorphicLayoutEffect(() => {
+    const created = createTimeline(ref.current, { events: shown.current, layout, group, relative, locale, label });
+    instance.current = created;
+    return () => {
+      created.destroy();
+      instance.current = null;
+    };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [layout, group, relative, locale, label]);
+  const key = JSON.stringify(events);
+  useIsomorphicLayoutEffect(() => {
+    const timeline = instance.current;
+    const before = shown.current;
+    shown.current = events;
+    if (!timeline || JSON.stringify(timeline.events) === key) return;
+    const ids = new Set(before.map((event) => event.id));
+    const fresh = events.filter((event) => !ids.has(event.id));
+    const kept = events.filter((event) => ids.has(event.id));
+    const gone = before.filter((old) => !events.some((event) => event.id === old.id));
+    const stayed = before.filter((old) => !gone.includes(old));
+    const sameOrder = kept.every((event, i) => stayed[i]?.id === event.id);
+    /** The events that stayed take their changes (a new state recolours a dot). */
+    const patch = () => {
+      for (const event of kept) {
+        const old = before.find((entry) => entry.id === event.id);
+        // Keys the new version dropped are cleared too.
+        if (old && JSON.stringify(old) !== JSON.stringify(event)) timeline.update(event.id, { ...Object.fromEntries(Object.keys(old).map((name) => [name, undefined])), ...event });
+      }
+    };
+    const first = events[0]?.id;
+    const last = events[events.length - 1]?.id;
+    // One event added at an end grows in; one taken out folds away; anything else is redrawn.
+    if (sameOrder && !gone.length && fresh.length === 1 && (fresh[0]!.id === first || fresh[0]!.id === last)) {
+      patch();
+      timeline.add(fresh[0]!, fresh[0]!.id === first ? 'start' : 'end');
+    } else if (sameOrder && !fresh.length && gone.length <= 1) {
+      patch();
+      if (gone[0]) timeline.remove(gone[0].id);
+    } else timeline.setEvents(events);
+  }, [key]);
+  return <div {...props} ref={ref} className={['mk-timeline', className].filter(Boolean).join(' ')} />;
+}

package/src/components/timeline/timeline.css

@@ -0,0 +1,218 @@
+/* timeline — a 2 px rail (outline-soft) behind 2rem dots, its done stretch in the accent; dots by state (done: accent,
+   current: accent-soft with a ring that breathes, upcoming: dashed, error: error); a muted time, a 600 title, a muted
+   description; days are chips on the rail. 'alternate' puts the events on both sides of a centred rail when the timeline
+   is 520 px wide or more. */
+.mk-timeline,
+mk-timeline {
+  container-type: inline-size;
+  display: block;
+  min-width: 0;
+  color: var(--mk-text);
+}
+
+[data-mk-tl-wrap] {
+  position: relative;
+}
+
+[data-mk-timeline-list] {
+  display: grid;
+  gap: 1.1rem;
+  margin: 0;
+  padding: 0;
+  list-style: none;
+}
+
+[data-mk-tl-rail] {
+  position: absolute;
+  left: calc(1rem - 1px);
+  width: 2px;
+  overflow: hidden;
+  border-radius: 2px;
+  background: var(--mk-outline-soft);
+}
+
+[data-mk-tl-rail][hidden] {
+  display: none;
+}
+
+[data-mk-tl-progress] {
+  display: block;
+  width: 100%;
+  border-radius: inherit;
+  background: var(--mk-accent);
+  transition: height 0.5s cubic-bezier(0.38, 0.49, 0, 1);
+}
+
+[data-mk-tl-item] {
+  display: grid;
+  grid-template-columns: 2rem minmax(0, 1fr);
+  align-items: start;
+  column-gap: 0.85rem;
+}
+
+[data-mk-tl-dot] {
+  position: relative;
+  z-index: 1;
+  display: grid;
+  place-items: center;
+  width: 2rem;
+  height: 2rem;
+  border-radius: 50%;
+  background: var(--mk-accent);
+  color: var(--mk-on-accent);
+  box-shadow: 0 0 0 4px var(--mk-surface-1, var(--mk-bg));
+  font-size: 0.8125rem;
+  font-weight: 700;
+  line-height: 1;
+}
+
+[data-mk-tl-dot]:empty::after {
+  content: '';
+  width: 0.5rem;
+  height: 0.5rem;
+  border-radius: 50%;
+  background: currentColor;
+}
+
+[data-mk-tl-item][data-status='current'] [data-mk-tl-dot] {
+  background: var(--mk-accent-soft);
+  color: var(--mk-on-accent-soft, var(--mk-text));
+  animation: mk-tl-breathe 2.2s ease-in-out infinite;
+}
+
+[data-mk-tl-item][data-status='upcoming'] [data-mk-tl-dot] {
+  background: var(--mk-surface-1, var(--mk-bg));
+  color: var(--mk-muted);
+  outline: 2px dashed var(--mk-outline);
+  outline-offset: -2px;
+}
+
+[data-mk-tl-item][data-status='error'] [data-mk-tl-dot] {
+  background: var(--mk-error, #c62828);
+  color: var(--mk-on-error, #fff);
+}
+
+@keyframes mk-tl-breathe {
+  0%,
+  100% {
+    box-shadow: 0 0 0 4px var(--mk-surface-1, var(--mk-bg)), 0 0 0 4px color-mix(in srgb, var(--mk-accent) 45%, transparent);
+  }
+
+  50% {
+    box-shadow: 0 0 0 4px var(--mk-surface-1, var(--mk-bg)), 0 0 0 9px color-mix(in srgb, var(--mk-accent) 0%, transparent);
+  }
+}
+
+[data-mk-tl-body] {
+  position: relative;
+  isolation: isolate;
+  display: grid;
+  justify-self: start;
+  gap: 0.2rem;
+  min-width: 0;
+  padding-top: 0.25rem;
+}
+
+/* A new event: a soft accent highlight behind it that fades. */
+[data-mk-tl-fresh] [data-mk-tl-body]::before {
+  content: '';
+  position: absolute;
+  inset: -0.125rem -0.625rem -0.375rem;
+  z-index: -1;
+  border-radius: 12px;
+  background: var(--mk-accent-soft);
+  animation: mk-tl-fresh 1.8s ease-out both;
+  pointer-events: none;
+}
+
+@keyframes mk-tl-fresh {
+  from {
+    opacity: 0.75;
+  }
+
+  to {
+    opacity: 0;
+  }
+}
+
+[data-mk-tl-time],
+[data-mk-tl-meta] {
+  color: var(--mk-muted);
+  font-size: 0.75rem;
+}
+
+[data-mk-tl-title] {
+  font-weight: 600;
+  line-height: 1.35;
+  overflow-wrap: anywhere;
+}
+
+[data-mk-tl-item][data-status='upcoming'] [data-mk-tl-title] {
+  color: var(--mk-muted);
+}
+
+[data-mk-tl-description] {
+  margin: 0;
+  color: var(--mk-muted);
+  font-size: 0.875rem;
+  line-height: 1.5;
+  overflow-wrap: anywhere;
+}
+
+/* A day is a small chip on the rail (it hides the line behind it). */
+[data-mk-tl-day] {
+  position: relative;
+  z-index: 1;
+  justify-self: start;
+  margin-top: 0.35rem;
+  padding: 0.25rem 0.625rem;
+  border-radius: 8px;
+  background: var(--mk-surface-3);
+  color: var(--mk-muted);
+  font-size: 0.6875rem;
+  font-weight: 700;
+  letter-spacing: 0.04em;
+  text-transform: uppercase;
+}
+
+@container (min-width: 520px) {
+  :is(.mk-timeline, mk-timeline)[data-mk-layout='alternate'] [data-mk-tl-rail] {
+    left: calc(50% - 1px);
+  }
+
+  :is(.mk-timeline, mk-timeline)[data-mk-layout='alternate'] [data-mk-tl-item] {
+    grid-template-columns: minmax(0, 1fr) 2rem minmax(0, 1fr);
+  }
+
+  :is(.mk-timeline, mk-timeline)[data-mk-layout='alternate'] [data-mk-tl-dot] {
+    grid-row: 1;
+    grid-column: 2;
+  }
+
+  :is(.mk-timeline, mk-timeline)[data-mk-layout='alternate'] [data-mk-tl-item][data-side='start'] [data-mk-tl-body] {
+    grid-row: 1;
+    grid-column: 1;
+    justify-self: end;
+    text-align: end;
+  }
+
+  :is(.mk-timeline, mk-timeline)[data-mk-layout='alternate'] [data-mk-tl-item][data-side='end'] [data-mk-tl-body] {
+    grid-row: 1;
+    grid-column: 3;
+  }
+
+  :is(.mk-timeline, mk-timeline)[data-mk-layout='alternate'] [data-mk-tl-day] {
+    justify-self: center;
+  }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  [data-mk-tl-item][data-status='current'] [data-mk-tl-dot] {
+    animation: none;
+    box-shadow: 0 0 0 4px var(--mk-surface-1, var(--mk-bg)), 0 0 0 6px color-mix(in srgb, var(--mk-accent) 45%, transparent);
+  }
+
+  [data-mk-tl-progress] {
+    transition: none;
+  }
+}

package/src/components/tooltip/README.md

@@ -0,0 +1,46 @@
+# tooltip
+
+Descripción breve junto a su disparador. Aparece cuando el puntero se detiene sobre él (400 ms), en cuanto el foco del teclado llega (al momento) o con una pulsación larga en pantallas táctiles (500 ms). Toma el lado preferido, cambia al opuesto si no cabe, se mantiene dentro de la ventana y apunta con una flecha al centro del disparador. Vive en la capa superior (API `popover`), así que ningún `overflow` lo recorta.
+
+Movimiento (línea Melon Mind): sale de la flecha con un pop (escala .85, 4 px hacia el disparador, blur 4 → 0, .22 s) y se va en .12 s. Si pasas a otro tooltip en menos de .4 s, aparece al instante con un fundido simple («caliente»). El texto nuevo cambia con un fundido.
+
+## HTML / Astro
+
+```html
+<mk-tooltip class="mk-tooltip" content="Copiar enlace">
+  <button class="mk-button mk-button--icon" aria-label="Copiar">⧉</button>
+</mk-tooltip>
+
+<!-- Sin content usa el title del disparador (y lo quita, para que no salga el del navegador). -->
+<mk-tooltip placement="right"><button title="Ajustes">⚙</button></mk-tooltip>
+```
+
+## React
+
+```tsx
+<Tooltip content={copied ? 'Copiado' : 'Copiar enlace'}>
+  <button onClick={copy}>⧉</button>
+</Tooltip>
+```
+
+El primer elemento enfocable dentro es el disparador (o `[data-mk-tooltip-trigger]`). Si no hay ninguno, el propio contenedor recibe `tabindex="0"`.
+
+## Opciones
+
+| Opción | Atributo | Por defecto | Qué hace |
+|---|---|---|---|
+| `content` | `content` | el `title` del disparador | Texto del tooltip. |
+| `placement` | `placement` | `'top'` | `top`, `bottom`, `left`, `right` o `auto` (el lado con más espacio). |
+| `openDelay` | `open-delay` | `400` | Espera al señalar, en ms. |
+| `closeDelay` | `close-delay` | `100` | Espera al salir, en ms. |
+| `interactive` | `interactive` | `false` | El puntero puede entrar en el tooltip (enlaces, texto seleccionable). |
+| `arrow` | `arrow` | `true` | Flecha hacia el disparador. |
+| `onOpenChange(open)` | — | — | Al abrirse o cerrarse. |
+
+## API y eventos
+
+`open()`, `close()`, `setContent(texto)` (un texto vacío lo oculta), `isOpen`, `destroy()`. Evento `mk:open-change` con `{ open }`.
+
+## Accesibilidad
+
+`role="tooltip"` y `aria-describedby` en el disparador. Escape lo oculta sin mover el foco (WCAG 1.4.13). Con movimiento reducido aparece y desaparece sin animación. Variable CSS: `--mk-tooltip-bg` (cristal invertido).

package/src/components/tooltip/element.ts

@@ -0,0 +1,22 @@
+import { MkElement, defineElement, type OptionType } from '../../elements/base';
+import { createTooltip, type TooltipInstance } from './engine';
+
+/**
+ * <mk-tooltip class="mk-tooltip" content="Copiar enlace"><button>…</button></mk-tooltip>
+ * Without `content`, the trigger's title. Emits mk:open-change ({open}).
+ */
+export class MkTooltipElement extends MkElement<TooltipInstance> {
+  static options: Record<string, OptionType> = { content: 'string', placement: 'string', openDelay: 'number', closeDelay: 'number', interactive: 'boolean', arrow: 'boolean' };
+
+  protected create(options: Record<string, unknown>) {
+    return createTooltip(this, options);
+  }
+
+  attributeChangedCallback(name: string, previous: string | null, next: string | null) {
+    if (previous === next || !this.instance) return;
+    if (name === 'content') this.instance.setContent(next ?? '');
+    else super.attributeChangedCallback(name, previous, next);
+  }
+}
+
+export const defineTooltip = () => defineElement('mk-tooltip', MkTooltipElement);

package/src/components/tooltip/engine.ts

@@ -0,0 +1,288 @@
+import { gsap, EASE, registerMotion } from '../../core/gsap';
+import { requestFrame } from '../../core/frame';
+import { reduced } from '../../core/reduced';
+import { createScope } from '../../core/scope';
+import { inert, type Instance } from '../../core/types';
+import { originOf, place, type Placement } from '../../core/position';
+
+/*
+ * Tooltip: a short description beside its trigger, shown when the pointer
+ * rests on it (400 ms), when keyboard focus reaches it (at once) or on a long
+ * press (500 ms, touch). It takes the preferred side, flips when that side has
+ * no room, stays inside the viewport and points an arrow at the trigger's
+ * centre; it lives in the top layer (popover API) so no overflow clips it.
+ * Motion (Melon Mind): it pops from the arrow (scale .85, 4 px toward the
+ * trigger, blur 4 → 0, .22 s, pop curve) and fades out in .12 s; moving to
+ * another tooltip within .4 s shows it at once with a plain fade (warm), and
+ * new text cross-fades. Escape hides it (WCAG 1.4.13); with `interactive` the
+ * pointer can move onto it. The trigger is described by it (aria-describedby).
+ */
+
+export interface TooltipOptions {
+  /** Text of the bubble (default: the trigger's title, which is removed so the browser's own does not show). */
+  content?: string;
+  /** Preferred side (default 'top'); 'auto' takes the roomiest. */
+  placement?: Placement;
+  /** Hover delay in ms (default 400). Focus shows it at once. */
+  openDelay?: number;
+  /** Delay before hiding when the pointer leaves, in ms (default 100). */
+  closeDelay?: number;
+  /** The pointer can move onto the bubble (links, selectable text). */
+  interactive?: boolean;
+  /** Arrow pointing at the trigger (default true). */
+  arrow?: boolean;
+  onOpenChange?: (open: boolean) => void;
+}
+
+export interface TooltipInstance extends Instance {
+  open(): void;
+  close(): void;
+  /** New text; an open tooltip cross-fades to it. Empty text hides it. */
+  setContent(text: string): void;
+  readonly isOpen: boolean;
+}
+
+const FOCUSABLE = 'a[href], button, input, select, textarea, summary, [tabindex]:not([tabindex="-1"]), [contenteditable="true"]';
+/** A tooltip shown within this long after another one hid skips the delay and the pop. */
+const WARM = 400;
+let sequence = 0;
+let current: { hide(instant: boolean): void } | null = null;
+let lastHidden = -Infinity;
+const now = () => (typeof performance !== 'undefined' ? performance.now() : Date.now());
+
+export function createTooltip(root: HTMLElement | null, options: TooltipOptions = {}): TooltipInstance {
+  if (!root) return inert({ open() {}, close() {}, setContent() {}, isOpen: false });
+  registerMotion();
+  const scope = createScope();
+  const trigger = root.querySelector<HTMLElement>('[data-mk-tooltip-trigger]') ?? (root.matches(FOCUSABLE) ? root : root.querySelector<HTMLElement>(FOCUSABLE)) ?? root;
+  const title = trigger.getAttribute('title');
+  if (title !== null) scope.attr(trigger, 'title', null);
+  let text = options.content ?? title ?? '';
+  // Keyboard users must be able to reach what the tooltip describes.
+  if (!trigger.matches(FOCUSABLE)) scope.attr(trigger, 'tabindex', '0');
+  const openDelay = Number.isFinite(options.openDelay) ? Math.max(0, options.openDelay!) : 400;
+  const closeDelay = Number.isFinite(options.closeDelay) ? Math.max(0, options.closeDelay!) : 100;
+  const placement = options.placement ?? 'top';
+  const withArrow = options.arrow !== false;
+
+  const bubble = document.createElement('div');
+  bubble.dataset.mkTooltipBubble = '';
+  bubble.setAttribute('role', 'tooltip');
+  bubble.id = `mk-tooltip-${++sequence}`;
+  if (options.interactive) bubble.dataset.mkInteractive = '';
+  const label = document.createElement('span');
+  label.dataset.mkTooltipText = '';
+  label.textContent = text;
+  bubble.append(label);
+  if (withArrow) {
+    const arrow = document.createElement('span');
+    arrow.dataset.mkTooltipArrow = '';
+    arrow.setAttribute('aria-hidden', 'true');
+    bubble.append(arrow);
+  }
+  // The top layer (popover API) escapes every overflow; without it the bubble hangs from <body>.
+  const topLayer = typeof bubble.showPopover === 'function';
+  if (topLayer) {
+    bubble.setAttribute('popover', 'manual');
+    root.append(bubble);
+  } else {
+    bubble.hidden = true;
+    document.body.append(bubble);
+  }
+  scope.add(() => bubble.remove());
+  scope.attr(trigger, 'aria-describedby', [trigger.getAttribute('aria-describedby'), bubble.id].filter(Boolean).join(' '));
+  scope.attr(root, 'data-mk-open', null);
+  scope.attr(root, 'data-mk-ready', '');
+
+  const effects = new Set<gsap.core.Animation>();
+  const keep = (animation: gsap.core.Animation | null) => {
+    if (!animation) return;
+    effects.add(animation);
+    // Finished ones leave as new ones arrive: the animation's own onComplete stays untouched.
+    for (const effect of effects) if (effect.totalProgress() === 1) effects.delete(effect);
+  };
+  let motion: gsap.core.Animation | null = null;
+  scope.add(() => {
+    motion?.kill();
+    for (const effect of effects) effect.kill();
+    effects.clear();
+  });
+
+  let isOpen = false;
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const cancel = () => {
+    clearTimeout(timer);
+    timer = undefined;
+  };
+  const later = (fn: () => void, ms: number) => {
+    cancel();
+    timer = setTimeout(fn, ms);
+  };
+  scope.add(cancel);
+
+  const shown = () => (topLayer ? bubble.matches(':popover-open') : !bubble.hidden);
+  const reveal = () => {
+    if (shown()) return;
+    if (topLayer) bubble.showPopover();
+    else bubble.hidden = false;
+  };
+  const conceal = () => {
+    if (!shown()) return;
+    if (topLayer) bubble.hidePopover();
+    else bubble.hidden = true;
+  };
+
+  const position = () => {
+    const anchor = trigger.getBoundingClientRect();
+    const box = bubble.getBoundingClientRect();
+    const placed = place(anchor, { width: box.width, height: box.height }, { placement, gap: withArrow ? 10 : 6 });
+    bubble.style.left = `${placed.x}px`;
+    bubble.style.top = `${placed.y}px`;
+    bubble.dataset.mkSide = placed.side;
+    bubble.style.setProperty('--mk-tooltip-arrow', `${placed.arrow}px`);
+    return placed;
+  };
+  let pending: (() => void) | null = null;
+  const follow = () => {
+    if (!isOpen || pending) return;
+    pending = requestFrame(() => {
+      pending = null;
+      if (isOpen) position();
+    });
+  };
+  scope.add(() => pending?.());
+
+  const announce = (open: boolean) => {
+    if (open) root.setAttribute('data-mk-open', '');
+    else root.removeAttribute('data-mk-open');
+    options.onOpenChange?.(open);
+    root.dispatchEvent(new CustomEvent('mk:open-change', { bubbles: true, detail: { open } }));
+  };
+
+  const controller = {
+    hide: (instant: boolean) => hide(instant),
+  };
+
+  const show = () => {
+    cancel();
+    if (isOpen || scope.disposed || !text) return;
+    const warm = current !== null || now() - lastHidden < WARM;
+    if (current && current !== controller) current.hide(true);
+    current = controller;
+    isOpen = true;
+    motion?.kill();
+    reveal();
+    const placed = position();
+    if (!reduced()) {
+      if (warm) motion = gsap.fromTo(bubble, { opacity: 0 }, { opacity: 1, duration: 0.1, ease: 'power1.out', clearProps: 'opacity' });
+      else {
+        const toward = 4;
+        const offset = placed.side === 'top' ? { x: 0, y: toward } : placed.side === 'bottom' ? { x: 0, y: -toward } : placed.side === 'left' ? { x: toward, y: 0 } : { x: -toward, y: 0 };
+        gsap.set(bubble, { transformOrigin: originOf(placed) });
+        motion = gsap.fromTo(
+          bubble,
+          { opacity: 0, scale: 0.85, filter: 'blur(4px)', ...offset },
+          { opacity: 1, scale: 1, filter: 'blur(0px)', x: 0, y: 0, duration: 0.22, ease: EASE.pop, clearProps: 'opacity,scale,filter,transform,transformOrigin' },
+        );
+      }
+    }
+    announce(true);
+  };
+
+  const hide = (instant = false) => {
+    cancel();
+    if (!isOpen) return;
+    isOpen = false;
+    if (current === controller) current = null;
+    lastHidden = now();
+    motion?.kill();
+    const finish = () => {
+      conceal();
+      gsap.set(bubble, { clearProps: 'opacity,scale,filter,transform,transformOrigin' });
+    };
+    if (instant || reduced()) finish();
+    else motion = gsap.to(bubble, { opacity: 0, scale: 0.96, duration: 0.12, ease: 'power2.in', onComplete: finish });
+    announce(false);
+  };
+  scope.add(() => {
+    if (current === controller) current = null;
+  });
+
+  /** The last input: focus after a click is not keyboard focus. */
+  let pointerInput = false;
+  scope.on(document, 'pointerdown', () => (pointerInput = true), true);
+  scope.on(document, 'keydown', () => (pointerInput = false), true);
+
+  scope.on(trigger, 'pointerenter', (event) => {
+    if ((event as PointerEvent).pointerType === 'touch') return;
+    later(show, current || now() - lastHidden < WARM ? 0 : openDelay);
+  });
+  scope.on(trigger, 'pointerleave', (event) => {
+    if ((event as PointerEvent).pointerType === 'touch') return;
+    later(() => hide(), closeDelay);
+  });
+  // Touch: a long press shows it for a moment.
+  scope.on(trigger, 'pointerdown', (event) => {
+    if ((event as PointerEvent).pointerType === 'touch') later(show, 500);
+  });
+  for (const type of ['pointerup', 'pointercancel']) {
+    scope.on(trigger, type, (event) => {
+      if ((event as PointerEvent).pointerType !== 'touch') return;
+      if (isOpen) later(() => hide(), 1500);
+      else cancel();
+    });
+  }
+  if (options.interactive) {
+    scope.on(bubble, 'pointerenter', cancel);
+    scope.on(bubble, 'pointerleave', () => later(() => hide(), closeDelay));
+  }
+  scope.on(trigger, 'focusin', () => {
+    if (!pointerInput) show();
+  });
+  scope.on(trigger, 'focusout', (event) => {
+    if (options.interactive && bubble.contains((event as FocusEvent).relatedTarget as Node | null)) return;
+    hide();
+  });
+  scope.on(document, 'keydown', (event) => {
+    if ((event as KeyboardEvent).key === 'Escape' && isOpen) hide();
+  });
+  scope.on(window, 'resize', follow);
+  scope.on(window, 'scroll', follow, { capture: true, passive: true });
+  scope.add(() => {
+    if (isOpen) conceal();
+  });
+
+  return {
+    open: show,
+    close: () => hide(),
+    setContent(next) {
+      if (scope.disposed) return;
+      text = next;
+      if (!text) {
+        label.textContent = '';
+        hide();
+        return;
+      }
+      if (!isOpen || reduced() || label.textContent === text) {
+        label.textContent = text;
+        if (isOpen) position();
+        return;
+      }
+      gsap.killTweensOf(label);
+      keep(
+        gsap
+          .timeline()
+          .to(label, { opacity: 0, filter: 'blur(3px)', duration: 0.1, ease: 'power1.in' })
+          .call(() => {
+            label.textContent = text;
+            if (isOpen) position();
+          })
+          .to(label, { opacity: 1, filter: 'blur(0px)', duration: 0.16, ease: 'power1.out', clearProps: 'opacity,filter' }),
+      );
+    },
+    get isOpen() {
+      return isOpen;
+    },
+    destroy: () => scope.dispose(),
+  };
+}

package/src/components/tooltip/react.tsx

@@ -0,0 +1,30 @@
+'use client';
+import { useRef, type HTMLAttributes } from 'react';
+import { useIsomorphicLayoutEffect, useLatest } from '../../react/use-recipe';
+import { createTooltip, type TooltipInstance, type TooltipOptions } from './engine';
+
+export interface TooltipProps extends HTMLAttributes<HTMLSpanElement>, TooltipOptions {}
+
+/** <Tooltip content="Copiar enlace"><button>…</button></Tooltip>: the first focusable child is the trigger. */
+export function Tooltip({ content, placement, openDelay, closeDelay, interactive, arrow, onOpenChange, className, children, ...props }: TooltipProps) {
+  const ref = useRef<HTMLSpanElement>(null);
+  const instance = useRef<TooltipInstance | null>(null);
+  const change = useLatest(onOpenChange);
+  useIsomorphicLayoutEffect(() => {
+    const created = createTooltip(ref.current, { content, placement, openDelay, closeDelay, interactive, arrow, onOpenChange: (open) => change.current?.(open) });
+    instance.current = created;
+    return () => {
+      created.destroy();
+      instance.current = null;
+    };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [placement, openDelay, closeDelay, interactive, arrow]);
+  useIsomorphicLayoutEffect(() => {
+    instance.current?.setContent(content ?? '');
+  }, [content]);
+  return (
+    <span {...props} ref={ref} className={['mk-tooltip', className].filter(Boolean).join(' ')}>
+      {children}
+    </span>
+  );
+}