@yewdiel21/motion-kit 0.10.0 → 0.15.0

package/src/components/toolbar/toolbar.css

@@ -0,0 +1,121 @@
+/* toolbar — a dark rail of round tools; a light blob sits under the chosen one and stretches like slime to the next.
+   The label beside a tool is a small dark pill. In the dark theme the rail turns light and the blob dark. */
+.mk-toolbar,
+mk-toolbar {
+  --mk-toolbar-rail: color-mix(in srgb, var(--mk-text) 86%, var(--mk-bg));
+  --mk-toolbar-on-rail: var(--mk-bg);
+  --mk-toolbar-blob: var(--mk-bg);
+  --mk-toolbar-on-blob: var(--mk-text);
+  --mk-toolbar-tool: 3.5rem;
+  position: relative;
+  display: inline-flex;
+  width: max-content;
+  max-width: 100%;
+  flex-direction: column;
+  gap: 0.25rem;
+  padding: 0.5rem;
+  border-radius: var(--mk-radius-full);
+  background: var(--mk-toolbar-rail);
+  box-shadow: 0 10px 30px -12px var(--mk-shadow-color, rgb(0 0 0 / 0.35));
+}
+
+:is(.mk-toolbar, mk-toolbar)[data-mk-orientation='horizontal'] {
+  flex-direction: row;
+}
+
+:is(.mk-toolbar, mk-toolbar) > button {
+  position: relative;
+  z-index: 1;
+  display: grid;
+  place-items: center;
+  width: var(--mk-toolbar-tool);
+  height: var(--mk-toolbar-tool);
+  padding: 0;
+  border: 0;
+  border-radius: var(--mk-radius-full);
+  background: transparent;
+  color: var(--mk-toolbar-on-rail);
+  cursor: pointer;
+  transition: color 0.2s ease;
+  -webkit-tap-highlight-color: transparent;
+}
+
+:is(.mk-toolbar, mk-toolbar) > button svg {
+  width: 1.5rem;
+  height: 1.5rem;
+  transition: transform 0.35s var(--mk-ease-swatch);
+}
+
+/* The chosen tool's icon turns dark as the blob arrives under it. */
+:is(.mk-toolbar, mk-toolbar) > button[aria-pressed='true'] {
+  color: var(--mk-toolbar-on-blob);
+  transition-delay: 0.12s;
+}
+
+@media (hover: hover) {
+  :is(.mk-toolbar, mk-toolbar) > button:hover svg {
+    transform: scale(1.1);
+  }
+}
+
+:is(.mk-toolbar, mk-toolbar) > button:focus-visible {
+  outline: 2px solid var(--mk-accent);
+  outline-offset: 2px;
+}
+
+:is(.mk-toolbar, mk-toolbar) > button:disabled {
+  cursor: not-allowed;
+  opacity: 0.4;
+}
+
+[data-mk-toolbar-blob] {
+  position: absolute;
+  top: 0;
+  left: 0;
+  width: var(--mk-toolbar-tool);
+  height: var(--mk-toolbar-tool);
+  border-radius: var(--mk-radius-full);
+  background: var(--mk-toolbar-blob);
+  pointer-events: none;
+  will-change: transform, height, width;
+}
+
+[data-mk-toolbar-tip] {
+  position: absolute;
+  top: 0;
+  left: calc(100% + 0.75rem);
+  z-index: 2;
+  padding: 0.4rem 0.9rem;
+  border-radius: var(--mk-radius-full);
+  background: var(--mk-toolbar-rail);
+  color: var(--mk-toolbar-on-rail);
+  font: 500 0.875rem/1.2 var(--mk-font);
+  white-space: nowrap;
+  pointer-events: none;
+}
+
+:is(.mk-toolbar, mk-toolbar)[data-mk-orientation='horizontal'] [data-mk-toolbar-tip] {
+  top: auto;
+  bottom: calc(100% + 0.75rem);
+  left: 0;
+}
+
+[data-mk-toolbar-tip][hidden] {
+  display: none;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  :is(.mk-toolbar, mk-toolbar) > button,
+  :is(.mk-toolbar, mk-toolbar) > button svg {
+    transition: none;
+  }
+}
+
+@media (forced-colors: active) {
+  [data-mk-toolbar-blob] {
+    background: Highlight;
+  }
+  :is(.mk-toolbar, mk-toolbar) > button[aria-pressed='true'] {
+    color: HighlightText;
+  }
+}

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

package/src/components/tooltip/tooltip.css

@@ -0,0 +1,78 @@
+/* tooltip — Melon Mind's inverse glass in a compact 8 px bubble: .8125rem text, at most 18rem wide, a 12 × 6 px arrow
+   that points at the trigger's centre. It lives in the top layer, so the reset below undoes the popover UA styles. */
+.mk-tooltip,
+mk-tooltip {
+  display: inline-flex;
+}
+
+[data-mk-tooltip-bubble] {
+  --mk-tooltip-bg: var(--mk-glass-inverse, rgb(24 24 24 / 0.9));
+  position: fixed;
+  inset: auto;
+  z-index: 2147483000;
+  box-sizing: border-box;
+  width: max-content;
+  max-width: min(18rem, calc(100vw - 16px));
+  margin: 0;
+  padding: 0.4rem 0.65rem;
+  border: 0;
+  border-radius: 8px;
+  overflow: visible;
+  background: var(--mk-tooltip-bg);
+  color: var(--mk-on-glass-inverse, #fff);
+  box-shadow: 0 8px 24px -10px color-mix(in srgb, var(--mk-shadow-color, #000) 45%, transparent);
+  font: 500 0.8125rem/1.35 var(--mk-font, system-ui, sans-serif);
+  text-align: start;
+  overflow-wrap: anywhere;
+  pointer-events: none;
+  -webkit-backdrop-filter: blur(12px);
+  backdrop-filter: blur(12px);
+}
+
+[data-mk-tooltip-bubble][data-mk-interactive] {
+  pointer-events: auto;
+}
+
+[data-mk-tooltip-bubble][hidden] {
+  display: none;
+}
+
+/* A triangle outside the bubble's edge (no overlap, so the translucent glass is not doubled). */
+[data-mk-tooltip-arrow] {
+  position: absolute;
+  background: var(--mk-tooltip-bg);
+}
+
+[data-mk-tooltip-bubble][data-mk-side='top'] > [data-mk-tooltip-arrow],
+[data-mk-tooltip-bubble][data-mk-side='bottom'] > [data-mk-tooltip-arrow] {
+  left: calc(var(--mk-tooltip-arrow, 50%) - 6px);
+  width: 12px;
+  height: 6px;
+}
+
+[data-mk-tooltip-bubble][data-mk-side='top'] > [data-mk-tooltip-arrow] {
+  top: 100%;
+  clip-path: polygon(0 0, 100% 0, 50% 100%);
+}
+
+[data-mk-tooltip-bubble][data-mk-side='bottom'] > [data-mk-tooltip-arrow] {
+  bottom: 100%;
+  clip-path: polygon(50% 0, 100% 100%, 0 100%);
+}
+
+[data-mk-tooltip-bubble][data-mk-side='left'] > [data-mk-tooltip-arrow],
+[data-mk-tooltip-bubble][data-mk-side='right'] > [data-mk-tooltip-arrow] {
+  top: calc(var(--mk-tooltip-arrow, 50%) - 6px);
+  width: 6px;
+  height: 12px;
+}
+
+[data-mk-tooltip-bubble][data-mk-side='left'] > [data-mk-tooltip-arrow] {
+  left: 100%;
+  clip-path: polygon(0 0, 100% 50%, 0 100%);
+}
+
+[data-mk-tooltip-bubble][data-mk-side='right'] > [data-mk-tooltip-arrow] {
+  right: 100%;
+  clip-path: polygon(100% 0, 100% 100%, 0 50%);
+}

package/src/components/tree-view/README.md

@@ -0,0 +1,61 @@
+# tree-view
+
+Árbol jerárquico con nodos expandibles, checkboxes y búsqueda. Una rama se abre por su altura (.32 s, curva signature) mientras sus hijos entran deslizándose desde un blur, 25 ms entre uno y otro, y su flecha gira; al cerrarse hace lo mismo al revés. La fila seleccionada va sobre una píldora que se desliza hasta cada nueva elección (.3 s, curva swing).
+
+Con `checkable`, las casillas tienen tres estados: la palomita se dibuja sola y la casilla hace pop; una rama con solo algunos hijos marcados muestra un guion. Marcar una rama marca todo lo que tiene dentro. La búsqueda resalta las letras que coinciden (sin importar tildes ni mayúsculas), abre las ramas que las contienen y oculta lo demás; al borrarla vuelve lo que estaba abierto. `loadChildren()` llena una rama la primera vez que se abre (mientras tanto, una fila «Cargando…»).
+
+## HTML / Astro
+
+```html
+<mk-tree-view class="mk-tree-view" checkable search="Filtrar carpetas" expanded="docs"
+  nodes='[{"id":"docs","label":"Documentos","icon":"📁","children":[
+            {"id":"cv","label":"Currículum.pdf","icon":"📄"},
+            {"id":"facturas","label":"Facturas","icon":"📁","children":[{"id":"f1","label":"Enero"},{"id":"f2","label":"Febrero"}]}]},
+          {"id":"fotos","label":"Fotos","icon":"🖼️","children":[{"id":"playa","label":"Playa"}]}]'></mk-tree-view>
+
+<script>
+  const tree = document.querySelector('mk-tree-view');
+  tree.addEventListener('mk:check', (event) => console.log(event.detail.checked));
+  tree.addEventListener('mk:select', (event) => console.log(event.detail.node));
+</script>
+```
+
+`expanded="all"` abre todas las ramas; `search` sin texto activa la búsqueda con su texto por defecto.
+
+## React
+
+```tsx
+const tree = useRef<TreeViewHandle>(null);
+
+<TreeView ref={tree} nodes={carpetas} checkable checked={ids} onCheck={setIds} search expanded={['docs']} />;
+
+tree.current?.expandAll();
+```
+
+## Opciones
+
+| Opción | Atributo | Por defecto | Qué hace |
+|---|---|---|---|
+| `nodes` | `nodes` (JSON) | `[]` | `{ id, label, children?, icon?, disabled?, hasChildren?, data? }[]`. |
+| `checkable` | `checkable` | `false` | Casillas de tres estados. |
+| `checked` | `checked` (lista con comas) | `[]` | Ids marcados (una rama marca lo que tiene dentro). |
+| `expanded` | `expanded` (lista o `all`) | `[]` | Ramas abiertas al empezar; `true` abre todas. |
+| `selected` | `selected` | — | Id seleccionado (sin casillas). |
+| `search` | `search` | `false` | Campo de búsqueda; un texto es su marcador. |
+| `label` | `label` | `'Árbol'` | Nombre accesible. |
+| `loadChildren(node)` | — | — | Hijos de un nodo con `hasChildren`, la primera vez que se abre. |
+| `renderLabel(node, element, query)` | — | — | Dibujar la etiqueta a mano (lo usan `json-viewer` y `file-explorer`). |
+| `searchText(node)` | — | la etiqueta | El texto donde busca la búsqueda. |
+| `onSelect(node)`, `onCheck(ids)`, `onExpand(node, abierto)` | — | — | Cada cambio. |
+
+## API y eventos
+
+`expand(id)`, `collapse(id)`, `toggle(id)`, `expandAll()`, `collapseAll()`, `reveal(id)` (abre lo que tiene encima y lo muestra), `select(id, notify = false)`, `setChecked(ids)`, `filter(texto)`, `setNodes(nodes)`, `focusItem(id)`, `selected`, `checked`, `expanded`, `element`, `destroy()`. Eventos `mk:select` con `{ id, node }`, `mk:check` con `{ checked }` y `mk:expand` con `{ id, expanded }`.
+
+## Teclado
+
+↑ ↓ mueven, → abre o entra, ← cierra o sube, Inicio y Fin van a los extremos, `*` abre las ramas hermanas, Intro selecciona, Espacio marca (o selecciona) y escribir salta a la etiqueta que empieza así. Desde la búsqueda, ↓ entra al árbol.
+
+## Accesibilidad
+
+Patrón de árbol de WAI-ARIA: `role="tree"` con `treeitem` que llevan `aria-level`, `aria-setsize`, `aria-posinset`, `aria-expanded`, `aria-selected` o `aria-checked` (`mixed` para el guion), y un solo elemento tabulable (tabindex móvil). Un estado discreto anuncia las coincidencias y cada casilla marcada. Con movimiento reducido las ramas se abren y la píldora salta sin animación.

package/src/components/tree-view/element.ts

@@ -0,0 +1,32 @@
+import { MkElement, defineElement, type OptionType } from '../../elements/base';
+import { createTreeView, type TreeNode, type TreeViewInstance } from './engine';
+
+/**
+ * <mk-tree-view class="mk-tree-view" checkable search
+ *   nodes='[{"id":"a","label":"Proyectos","children":[{"id":"a1","label":"Melon"}]}]'></mk-tree-view>
+ * Emits mk:select ({id, node}), mk:check ({checked}), mk:expand ({id, expanded}).
+ */
+export class MkTreeViewElement extends MkElement<TreeViewInstance> {
+  static options: Record<string, OptionType> = { nodes: 'json', checkable: 'boolean', checked: 'list', expanded: 'list', selected: 'string', search: 'string', label: 'string', icons: 'boolean', draggable: 'boolean' };
+
+  protected create(options: Record<string, unknown>) {
+    // search="" (present without text) turns the field on with its default placeholder.
+    const search = this.hasAttribute('search') ? (this.getAttribute('search') || true) : undefined;
+    const expanded = this.getAttribute('expanded') === 'all' ? true : options.expanded;
+    return createTreeView(this, { ...options, search, expanded } as Parameters<typeof createTreeView>[1]);
+  }
+
+  attributeChangedCallback(name: string, previous: string | null, next: string | null) {
+    if (previous === next || !this.instance) return;
+    if (name === 'nodes') {
+      try {
+        this.instance.setNodes(JSON.parse(next ?? '[]') as TreeNode[]);
+      } catch {
+        // Malformed JSON: keep the current nodes.
+      }
+    } else if (name === 'selected') this.instance.select(next);
+    else super.attributeChangedCallback(name, previous, next);
+  }
+}
+
+export const defineTreeView = () => defineElement('mk-tree-view', MkTreeViewElement);