@yewdiel21/motion-kit 0.9.1 → 0.14.0

package/src/components/timeline/engine.ts

@@ -0,0 +1,300 @@
+import { gsap, EASE, Flip, registerMotion } from '../../core/gsap';
+import { reduced } from '../../core/reduced';
+import { TIMING } from '../../core/timing';
+import { createScope } from '../../core/scope';
+import { inert, type Instance } from '../../core/types';
+import { dayKey, fromJson } from '../../core/dates';
+import { dayLabel, everyMinute, fullTime, relativeTime, toTime, type TimeInput } from '../../core/relative-time';
+import { blurIn, collapse } from '../../motion/micro';
+
+/*
+ * Timeline: events in order along a rail — dots with an icon or a state, a
+ * time ("hace 2 h", the full date in its title; refreshed every minute), a
+ * title, a description and small meta. When it comes into view the rail draws
+ * itself from the first dot (.8 s, wipe) and the events cascade in out of a
+ * blur (60 ms apart); the done stretch of the rail is filled in the accent up
+ * to the current event, whose dot breathes. add() drops an event in at the
+ * start or the end: the others glide to make room (layout reflow, the rail
+ * following), it comes in out of a blur, its dot pops and a soft highlight
+ * fades behind it; update() changes one in place (a new state pops its dot);
+ * remove() folds one away. 'alternate' puts the events on both sides of the
+ * rail when there is room; `group` heads each day with a chip on the rail.
+ */
+
+export type TimelineStatus = 'done' | 'current' | 'upcoming' | 'error';
+
+export interface TimelineEvent {
+  id: string;
+  title: string;
+  description?: string;
+  time?: TimeInput;
+  status?: TimelineStatus;
+  /** A short glyph in the dot (an emoji or one or two letters). */
+  icon?: string;
+  /** Small text under it (an author, a place). */
+  meta?: string;
+}
+
+export interface TimelineOptions {
+  events?: TimelineEvent[];
+  /** 'start' (default): the rail on the left; 'alternate': both sides on wide screens. */
+  layout?: 'start' | 'alternate';
+  /** A heading for each day (default false). */
+  group?: boolean;
+  /** Times as "hace 2 h", refreshed every minute (default true); false shows the date and time. */
+  relative?: boolean;
+  locale?: string;
+  /** Accessible name of the list (default 'Historial'). */
+  label?: string;
+}
+
+export interface TimelineInstance extends Instance {
+  add(event: TimelineEvent, at?: 'start' | 'end'): void;
+  update(id: string, patch: Partial<Omit<TimelineEvent, 'id'>>): void;
+  remove(id: string): void;
+  setEvents(events: TimelineEvent[]): void;
+  readonly events: TimelineEvent[];
+}
+
+const STATUS_LABEL: Record<TimelineStatus, string> = { done: 'Hecho', current: 'En curso', upcoming: 'Pendiente', error: 'Con error' };
+
+/** Events written as <li data-status data-time data-icon>Title<p>description</p></li>. */
+const readAuthored = (root: HTMLElement): TimelineEvent[] =>
+  [...root.querySelectorAll<HTMLElement>(':scope > ol > li, :scope > ul > li')].map((item, i) => {
+    const description = item.querySelector('p')?.textContent?.trim();
+    const title = [...item.childNodes].filter((node) => node.nodeType === Node.TEXT_NODE || (node instanceof HTMLElement && node.tagName !== 'P')).map((node) => node.textContent).join('').trim();
+    return {
+      id: item.id || `e${i}`,
+      title,
+      description,
+      time: item.dataset.time,
+      status: item.dataset.status as TimelineStatus | undefined,
+      icon: item.dataset.icon,
+      meta: item.dataset.meta,
+    };
+  });
+
+export function createTimeline(root: HTMLElement | null, options: TimelineOptions = {}): TimelineInstance {
+  if (!root) return inert({ add() {}, update() {}, remove() {}, setEvents() {}, events: [] });
+  registerMotion();
+  const scope = createScope();
+  const locale = options.locale ?? root.closest('[lang]')?.getAttribute('lang') ?? 'es';
+  const relative = options.relative !== false;
+  // JSON text too (data-mk-events through autoInit).
+  let events = (fromJson(options.events) ?? readAuthored(root)).map((event) => ({ ...event }));
+  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);
+  };
+
+  // Authored markup stays, out of sight; the engine draws its own list.
+  const holder = document.createElement('div');
+  holder.hidden = true;
+  holder.append(...root.childNodes);
+  const list = document.createElement('ol');
+  list.dataset.mkTimelineList = '';
+  list.setAttribute('aria-label', options.label ?? 'Historial');
+  const rail = document.createElement('span');
+  rail.dataset.mkTlRail = '';
+  rail.setAttribute('aria-hidden', 'true');
+  const progress = document.createElement('span');
+  progress.dataset.mkTlProgress = '';
+  rail.append(progress);
+  const wrap = document.createElement('div');
+  wrap.dataset.mkTlWrap = '';
+  wrap.append(rail, list);
+  root.append(wrap);
+  scope.add(() => {
+    for (const effect of effects) effect.kill();
+    effects.clear();
+    wrap.remove();
+    root.append(...holder.childNodes);
+  });
+  scope.attr(root, 'data-mk-layout', options.layout === 'alternate' ? 'alternate' : 'start');
+  scope.attr(root, 'data-mk-ready', '');
+
+  const timeText = (date: Date) => (relative ? relativeTime(date, new Date(), locale) : fullTime(date, locale));
+
+  const item = (event: TimelineEvent) => {
+    const li = document.createElement('li');
+    li.dataset.mkTlItem = '';
+    li.dataset.id = event.id;
+    li.dataset.status = event.status ?? 'done';
+    const dot = document.createElement('span');
+    dot.dataset.mkTlDot = '';
+    dot.setAttribute('aria-hidden', 'true');
+    dot.textContent = event.icon ?? '';
+    const body = document.createElement('div');
+    body.dataset.mkTlBody = '';
+    const date = toTime(event.time);
+    if (date) {
+      const time = document.createElement('time');
+      time.dataset.mkTlTime = '';
+      time.dateTime = date.toISOString();
+      time.title = fullTime(date, locale);
+      time.textContent = timeText(date);
+      body.append(time);
+    }
+    const title = document.createElement('strong');
+    title.dataset.mkTlTitle = '';
+    title.textContent = event.title;
+    body.append(title);
+    if (event.status && event.status !== 'done') {
+      const state = document.createElement('span');
+      state.className = 'mk-sr-only';
+      state.textContent = ` (${STATUS_LABEL[event.status]})`;
+      title.append(state);
+    }
+    if (event.description) {
+      const description = document.createElement('p');
+      description.dataset.mkTlDescription = '';
+      description.textContent = event.description;
+      body.append(description);
+    }
+    if (event.meta) {
+      const meta = document.createElement('span');
+      meta.dataset.mkTlMeta = '';
+      meta.textContent = event.meta;
+      body.append(meta);
+    }
+    li.append(dot, body);
+    return li;
+  };
+
+  const heading = (date: Date) => {
+    const li = document.createElement('li');
+    li.dataset.mkTlDay = '';
+    li.dataset.day = dayKey(date);
+    li.setAttribute('role', 'presentation');
+    li.dataset.flipId = `day-${li.dataset.day}`;
+    li.textContent = dayLabel(date, new Date(), locale);
+    return li;
+  };
+
+  /** The rail runs from the first dot to the last; its filled part reaches the current (or last done) event. */
+  const measureRail = () => {
+    const dots = [...list.querySelectorAll<HTMLElement>('[data-mk-tl-dot]')];
+    if (!dots.length) {
+      rail.hidden = true;
+      return;
+    }
+    rail.hidden = false;
+    // Centres measured against the wrapper, whatever positions the items.
+    const base = wrap.getBoundingClientRect().top;
+    const centre = (dot: HTMLElement) => {
+      const box = dot.getBoundingClientRect();
+      return box.top - base + box.height / 2;
+    };
+    const top = centre(dots[0]!);
+    const bottom = centre(dots[dots.length - 1]!);
+    rail.style.top = `${top}px`;
+    rail.style.height = `${Math.max(0, bottom - top)}px`;
+    const reached = [...list.querySelectorAll<HTMLElement>('[data-mk-tl-item]')].filter((li) => li.dataset.status === 'done' || li.dataset.status === 'current');
+    const last = reached[reached.length - 1]?.querySelector<HTMLElement>('[data-mk-tl-dot]');
+    progress.style.height = `${last ? Math.max(0, centre(last) - top) : 0}px`;
+  };
+  const itemOf = (id: string) => [...list.querySelectorAll<HTMLElement>('[data-mk-tl-item]')].find((li) => li.dataset.id === id) ?? null;
+
+  const render = () => {
+    const nodes: HTMLElement[] = [];
+    let day = '';
+    events.forEach((event, i) => {
+      const date = toTime(event.time);
+      if (options.group && date && dayKey(date) !== day) {
+        day = dayKey(date);
+        nodes.push(heading(date));
+      }
+      const element = item(event);
+      // 'alternate': the events take turns on each side of the rail.
+      element.dataset.side = i % 2 ? 'end' : 'start';
+      element.dataset.flipId = event.id;
+      nodes.push(element);
+    });
+    list.replaceChildren(...nodes);
+    measureRail();
+  };
+
+  const refreshTimes = () => {
+    for (const time of list.querySelectorAll<HTMLTimeElement>('[data-mk-tl-time]')) time.textContent = timeText(new Date(time.dateTime));
+    if (options.group) for (const day of list.querySelectorAll<HTMLElement>('[data-mk-tl-day]')) day.textContent = dayLabel(toTime(day.dataset.day!)!, new Date(), locale);
+  };
+  if (relative) scope.add(everyMinute(refreshTimes));
+  if (typeof ResizeObserver === 'function') scope.observe(new ResizeObserver(() => measureRail())).observe(list);
+
+  /** The entrance: the rail draws, the events cascade in. */
+  const enter = () => {
+    if (reduced()) return;
+    keep(gsap.fromTo(rail, { scaleY: 0 }, { scaleY: 1, transformOrigin: '50% 0%', duration: 0.8, ease: EASE.wipe, clearProps: 'transform' }));
+    keep(blurIn([...list.children], { from: 'rise', stagger: 0.06 }));
+  };
+
+  render();
+  if (typeof IntersectionObserver === 'function' && !reduced()) {
+    gsap.set([rail, ...list.children], { opacity: 0 });
+    const observer = scope.observe(
+      new IntersectionObserver((entries) => {
+        if (!entries.some((entry) => entry.isIntersecting)) return;
+        observer.disconnect();
+        gsap.set([rail, ...list.children], { clearProps: 'opacity' });
+        enter();
+      }, { threshold: 0.15 }),
+    );
+    observer.observe(root);
+  }
+
+  return {
+    add(event, at = 'end') {
+      if (scope.disposed) return;
+      // What is there glides to make room (the rail follows); the new event and a new day come in.
+      const state = reduced() ? null : Flip.getState([...list.children]);
+      events = at === 'start' ? [{ ...event }, ...events] : [...events, { ...event }];
+      render();
+      const added = itemOf(event.id);
+      if (!added || !state) return;
+      added.setAttribute('data-mk-tl-fresh', '');
+      scope.timeout(() => added.removeAttribute('data-mk-tl-fresh'), 1800);
+      keep(
+        Flip.from(state, {
+          targets: [...list.children],
+          duration: TIMING.layoutTravel,
+          ease: EASE.layoutReflow,
+          onUpdate: measureRail,
+          onComplete: measureRail,
+          onEnter: (entering) =>
+            gsap.fromTo(entering, { opacity: 0, y: at === 'start' ? -16 : 16, filter: 'blur(10px)' }, { opacity: 1, y: 0, filter: 'blur(0px)', duration: 0.45, ease: 'power2.out', clearProps: 'opacity,transform,filter' }),
+        }),
+      );
+      const dot = added.querySelector<HTMLElement>('[data-mk-tl-dot]')!;
+      keep(gsap.fromTo(dot, { scale: 0 }, { scale: 1, duration: 0.4, delay: 0.12, ease: EASE.pop, clearProps: 'transform' }));
+    },
+    update(id, patch) {
+      const event = events.find((entry) => entry.id === id);
+      if (!event || scope.disposed) return;
+      const statusChanged = patch.status && patch.status !== event.status;
+      Object.assign(event, patch);
+      render();
+      const dot = itemOf(id)?.querySelector<HTMLElement>('[data-mk-tl-dot]');
+      if (statusChanged && dot && !reduced()) keep(gsap.fromTo(dot, { scale: 0.6 }, { scale: 1, duration: 0.4, ease: EASE.pop, clearProps: 'transform' }));
+    },
+    remove(id) {
+      const element = itemOf(id);
+      events = events.filter((event) => event.id !== id);
+      if (!element) return render();
+      if (reduced()) return render();
+      keep(collapse(element, { onComplete: render }));
+    },
+    setEvents(next) {
+      if (scope.disposed) return;
+      events = next.map((event) => ({ ...event }));
+      render();
+      if (!reduced()) keep(blurIn([...list.children], { from: 'rise', stagger: 0.04 }));
+    },
+    get events() {
+      return events.map((event) => ({ ...event }));
+    },
+    destroy: () => scope.dispose(),
+  };
+}

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);