@yewdiel21/motion-kit 0.10.0 → 0.15.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/toolbar/README.md

@@ -0,0 +1,46 @@
+# toolbar
+
+Barra de herramientas con selector elástico tipo slime, etiquetas flotantes y navegación con flechas.
+
+## Instalación
+
+```tsx
+import '@yewdiel21/motion-kit/css';
+import { Toolbar } from '@yewdiel21/motion-kit/react';
+```
+
+```sh
+npx @yewdiel21/motion-kit add toolbar --react --elements
+```
+
+## React
+
+```tsx
+<Toolbar value={tool} onChange={setTool} aria-label="Herramientas"><button data-mk-tool="draw" aria-label="Dibujar">✎</button><button data-mk-tool="erase" aria-label="Borrar">⌫</button></Toolbar>
+```
+
+Los callbacks del ejemplo (`ask`, `run`, `setTool`, `setVolume`) pertenecen a tu aplicación. React acepta `className`, `style` y atributos HTML. Los componentes con estado exponen `instanceRef` (excepto PillButton).
+
+## HTML / Astro
+
+```html
+<mk-toolbar aria-label="Herramientas" value="draw"><button data-mk-tool="draw" aria-label="Dibujar">✎</button><button data-mk-tool="erase" aria-label="Borrar">⌫</button></mk-toolbar>
+<script type="module">
+  import { defineElements } from '@yewdiel21/motion-kit/elements';
+  defineElements(['mk-toolbar']);
+</script>
+```
+
+En Astro usa un `<script>` procesado por Astro. En HTML directo el import requiere bundler o import map. También puedes usar `import { createToolbar } from '@yewdiel21/motion-kit'` y llamar a la factory con el contenedor y las mismas opciones. Al desmontar, llama a `instance.destroy()`.
+
+## Opciones
+
+value: data-mk-tool elegido. orientation: vertical (por defecto) u horizontal. tips: etiquetas (true). onChange(value): selección del usuario. Instancia: setValue(value, notify?), value.
+
+Los nombres camelCase se escriben como atributos kebab-case. Los arrays y objetos se pasan como JSON. Los booleanos aceptan atributo vacío o `"false"`.
+
+## Estilos y accesibilidad
+
+Variables: --mk-toolbar-tool, --mk-toolbar-rail, --mk-toolbar-blob, --mk-toolbar-on-rail, --mk-toolbar-on-blob.
+
+Respeta los colores del tema, foco visible y `prefers-reduced-motion`. Los gráficos incluyen una tabla accesible y selección con flechas, Home, End y Escape. Heatmap usa arriba/abajo para un día e izquierda/derecha para una semana. Toolbar usa flechas y Home/End; OrbitMenu cierra con Escape y devuelve el foco. Los controles conservan nombres accesibles; VoiceDots anuncia los estados sin leer cada fotograma.

package/src/components/toolbar/element.ts

@@ -0,0 +1,30 @@
+import { MkElement, defineElement, type OptionType } from '../../elements/base';
+import { createToolbar, type ToolbarInstance } from './engine';
+
+/**
+ * <mk-toolbar class="mk-toolbar" aria-label="Herramientas" value="lapiz">
+ *   <button data-mk-tool="lapiz" aria-label="Lápiz">…svg…</button> …
+ * </mk-toolbar>
+ * The chosen tool's blob stretches like slime to the next one. Emits mk:change ({value}).
+ */
+export class MkToolbarElement extends MkElement<ToolbarInstance> {
+  static options: Record<string, OptionType> = { value: 'string', orientation: 'string', tips: 'boolean' };
+
+  protected create(options: Record<string, unknown>) {
+    return createToolbar(this, options);
+  }
+
+  get value() {
+    return this.instance?.value ?? '';
+  }
+
+  set value(next: string) { this.instance?.setValue(next); }
+  setValue(value: string, notify = false) { this.instance?.setValue(value, notify); }
+
+  attributeChangedCallback(name: string, previous: string | null, next: string | null) {
+    if (name === 'value' && this.instance) { if (next !== null) this.instance.setValue(next); return; }
+    super.attributeChangedCallback(name, previous, next);
+  }
+}
+
+export const defineToolbar = () => defineElement('mk-toolbar', MkToolbarElement);

package/src/components/toolbar/engine.ts

@@ -0,0 +1,230 @@
+import { gsap, EASE, registerMotion } from '../../core/gsap';
+import { reduced } from '../../core/reduced';
+import { createScope } from '../../core/scope';
+import { inert, warnOnce, type Instance } from '../../core/types';
+import { press } from '../../motion/micro';
+
+/*
+ * Toolbar: a rail of tools where one is chosen, marked by a light blob under
+ * its icon. Choosing another stretches the blob like slime: its leading edge
+ * reaches the new tool first (.2 s) while it narrows, then the trailing edge
+ * lets go and catches up on the swatch curve (.38,.49,0,1.5), so it wobbles
+ * into place; choosing the same tool squeezes it. A label slides out beside
+ * the tool under the pointer (or focus) and glides between tools. A toolbar
+ * for the keyboard: arrows and Home/End move and choose (roving tabindex),
+ * each tool says aria-pressed. Vertical by default, or horizontal.
+ */
+
+export interface ToolbarOptions {
+  /** The chosen tool (its data-mk-tool, else its position); default: the first one. */
+  value?: string;
+  /** Default 'vertical'. */
+  orientation?: 'vertical' | 'horizontal';
+  /** The label beside the tool under the pointer or focus (default true). */
+  tips?: boolean;
+  onChange?: (value: string) => void;
+}
+
+export interface ToolbarInstance extends Instance {
+  setValue(value: string, notify?: boolean): void;
+  readonly value: string;
+}
+
+export function createToolbar(root: HTMLElement | null, options: ToolbarOptions = {}): ToolbarInstance {
+  const tools = root ? [...root.querySelectorAll<HTMLButtonElement>('button')] : [];
+  if (!root || !tools.length) {
+    if (root) warnOnce('toolbar: needs at least one <button>');
+    return inert({ setValue() {}, value: '' });
+  }
+  registerMotion();
+  const scope = createScope();
+  const vertical = options.orientation !== 'horizontal';
+  const valueOf = (tool: HTMLElement) => tool.dataset.mkTool ?? String(tools.indexOf(tool as HTMLButtonElement));
+  const labelOf = (tool: HTMLElement) => tool.getAttribute('aria-label') ?? tool.title ?? tool.textContent?.trim() ?? '';
+
+  scope.attr(root, 'role', 'toolbar');
+  scope.attr(root, 'aria-orientation', vertical ? 'vertical' : 'horizontal');
+  scope.attr(root, 'data-mk-orientation', vertical ? 'vertical' : 'horizontal');
+  for (const tool of tools) {
+    scope.attr(tool, 'type', tool.getAttribute('type') ?? 'button');
+    scope.attr(tool, 'aria-pressed', 'false');
+    scope.attr(tool, 'tabindex', '-1');
+    // A title would show the browser's own tooltip over ours.
+    if (options.tips !== false && tool.title) {
+      scope.attr(tool, 'aria-label', tool.getAttribute('aria-label') ?? tool.title);
+      scope.attr(tool, 'title', null);
+    }
+  }
+
+  const blob = document.createElement('span');
+  blob.dataset.mkToolbarBlob = '';
+  blob.setAttribute('aria-hidden', 'true');
+  root.prepend(blob);
+  const tip = document.createElement('span');
+  tip.dataset.mkToolbarTip = '';
+  tip.setAttribute('aria-hidden', 'true');
+  tip.hidden = true;
+  if (options.tips !== false) root.append(tip);
+  scope.add(() => {
+    gsap.killTweensOf([blob, tip]);
+    blob.remove();
+    tip.remove();
+  });
+  scope.attr(root, 'data-mk-ready', '');
+
+  const find = (value: string | undefined) => tools.find((tool) => valueOf(tool) === value);
+  let current = find(options.value) ?? tools.find((tool) => !tool.disabled) ?? tools[0]!;
+
+  /** Where a tool sits inside the rail (offsets, so transforms on the rail do not count). */
+  const box = (tool: HTMLElement) => ({ start: vertical ? tool.offsetTop : tool.offsetLeft, size: vertical ? tool.offsetHeight : tool.offsetWidth, cross: vertical ? tool.offsetLeft : tool.offsetTop, crossSize: vertical ? tool.offsetWidth : tool.offsetHeight });
+  const along = vertical ? 'y' : 'x';
+  const across = vertical ? 'x' : 'y';
+  const length = vertical ? 'height' : 'width';
+  const thickness = vertical ? 'width' : 'height';
+
+  let timeline: gsap.core.Timeline | null = null;
+  const place = () => {
+    const at = box(current);
+    timeline?.kill();
+    gsap.set(blob, { [along]: at.start, [across]: at.cross, [length]: at.size, [thickness]: at.crossSize, scaleX: 1, scaleY: 1 });
+  };
+
+  /** The slime: the leading edge reaches the tool, then the trailing edge lets go and wobbles in. */
+  const slide = (from: HTMLElement, to: HTMLElement) => {
+    if (reduced() || from === to) return place();
+    const a = box(from);
+    const b = box(to);
+    const forward = b.start > a.start;
+    const reach = forward ? b.start + b.size - a.start : a.start + a.size - b.start;
+    const squeeze = vertical ? { scaleX: 0.84 } : { scaleY: 0.84 };
+    const relax = vertical ? { scaleX: 1 } : { scaleY: 1 };
+    timeline?.kill();
+    timeline = gsap.timeline();
+    timeline.to(blob, { [along]: forward ? a.start : b.start, [length]: reach, ...squeeze, duration: 0.2, ease: 'power2.in' }, 0);
+    timeline.to(blob, { [along]: b.start, [length]: b.size, duration: 0.42, ease: EASE.swatch }, 0.16);
+    timeline.to(blob, { ...relax, duration: 0.5, ease: 'elastic.out(1, 0.45)' }, 0.18);
+  };
+
+  const squish = () => {
+    if (reduced()) return;
+    timeline?.kill();
+    place();
+    timeline = gsap.timeline();
+    timeline.to(blob, { scaleX: 0.88, scaleY: 0.88, duration: 0.1, ease: 'power2.out' }).to(blob, { scaleX: 1, scaleY: 1, duration: 0.45, ease: 'elastic.out(1, 0.4)' });
+  };
+
+  const paint = () => {
+    for (const tool of tools) {
+      tool.setAttribute('aria-pressed', String(tool === current));
+      tool.setAttribute('tabindex', tool === current ? '0' : '-1');
+    }
+  };
+
+  // ── The label beside a tool ───────────────────────────────────────────────
+  let tipFor: HTMLElement | null = null;
+  let tipTimer: ReturnType<typeof setTimeout> | undefined;
+  scope.add(() => clearTimeout(tipTimer));
+  const showTip = (tool: HTMLElement, linger = 0) => {
+    if (options.tips === false) return;
+    clearTimeout(tipTimer);
+    const text = labelOf(tool);
+    if (!text) return hideTip();
+    const at = box(tool);
+    const appearing = tip.hidden;
+    const changed = tipFor !== tool;
+    tipFor = tool;
+    tip.textContent = text;
+    tip.hidden = false;
+    const tipSize = vertical ? tip.offsetHeight : tip.offsetWidth;
+    const spot = at.start + at.size / 2 - tipSize / 2;
+    if (appearing || reduced()) {
+      gsap.killTweensOf(tip);
+      gsap.set(tip, { [along]: spot });
+      if (!reduced()) gsap.fromTo(tip, { opacity: 0, [across]: -8, filter: 'blur(4px)', scale: 0.9 }, { opacity: 1, [across]: 0, filter: 'blur(0px)', scale: 1, duration: 0.28, ease: EASE.pop });
+      else gsap.set(tip, { opacity: 1, [across]: 0, scale: 1, filter: 'none' });
+    } else if (changed) {
+      gsap.to(tip, { [along]: spot, opacity: 1, [across]: 0, scale: 1, filter: 'blur(0px)', duration: 0.32, ease: EASE.swatch, overwrite: 'auto' });
+    }
+    if (linger) tipTimer = setTimeout(hideTip, linger);
+  };
+  const hideTip = () => {
+    clearTimeout(tipTimer);
+    tipFor = null;
+    if (tip.hidden) return;
+    if (reduced()) {
+      tip.hidden = true;
+      return;
+    }
+    gsap.to(tip, { opacity: 0, [across]: -6, filter: 'blur(4px)', scale: 0.92, duration: 0.18, ease: 'power2.in', overwrite: 'auto', onComplete: () => {
+      tip.hidden = true;
+    } });
+  };
+
+  const choose = (tool: HTMLElement, notify: boolean) => {
+    if ((tool as HTMLButtonElement).disabled) return;
+    const previous = current;
+    current = tool as HTMLButtonElement;
+    paint();
+    if (previous === current) squish();
+    else slide(previous, current);
+    if (previous === current || !notify) return;
+    const value = valueOf(current);
+    options.onChange?.(value);
+    root.dispatchEvent(new CustomEvent('mk:change', { bubbles: true, detail: { value } }));
+  };
+
+  scope.on(root, 'click', (event) => {
+    const tool = (event.target as Element).closest<HTMLButtonElement>('button');
+    if (!tool || !tools.includes(tool)) return;
+    press(tool);
+    choose(tool, true);
+    showTip(tool, 1200);
+  });
+  scope.on(root, 'pointerover', (event) => {
+    const tool = (event.target as Element).closest<HTMLButtonElement>('button');
+    if (tool && tools.includes(tool) && (event as PointerEvent).pointerType !== 'touch') showTip(tool);
+  });
+  scope.on(root, 'pointerleave', () => {
+    tipTimer = setTimeout(hideTip, 120);
+  });
+  scope.on(root, 'focusin', (event) => {
+    const tool = event.target as HTMLElement;
+    if (tools.includes(tool as HTMLButtonElement) && tool.matches(':focus-visible')) showTip(tool);
+  });
+  scope.on(root, 'focusout', (event) => {
+    if (!root.contains((event as FocusEvent).relatedTarget as Node)) hideTip();
+  });
+  scope.on(root, 'keydown', (event) => {
+    const key = (event as KeyboardEvent).key;
+    const enabled = tools.filter((tool) => !tool.disabled);
+    const at = enabled.indexOf(document.activeElement as HTMLButtonElement);
+    if (at < 0) return;
+    const next =
+      key === 'ArrowDown' || key === 'ArrowRight' ? enabled[(at + 1) % enabled.length]
+      : key === 'ArrowUp' || key === 'ArrowLeft' ? enabled[(at - 1 + enabled.length) % enabled.length]
+      : key === 'Home' ? enabled[0]
+      : key === 'End' ? enabled[enabled.length - 1]
+      : null;
+    if (!next) return;
+    event.preventDefault();
+    choose(next, true);
+    next.focus();
+    showTip(next, 1200);
+  });
+
+  if (typeof ResizeObserver === 'function') scope.observe(new ResizeObserver(() => place())).observe(root);
+
+  paint();
+  place();
+
+  return {
+    setValue(value, notify = false) {
+      const tool = find(value);
+      if (tool) choose(tool, notify);
+    },
+    get value() {
+      return valueOf(current);
+    },
+    destroy: () => scope.dispose(),
+  };
+}

package/src/components/toolbar/react.tsx

@@ -0,0 +1,34 @@
+'use client';
+import { useRef, type HTMLAttributes, type MutableRefObject } from 'react';
+import { useIsomorphicLayoutEffect, useLatest } from '../../react/use-recipe';
+import { createToolbar, type ToolbarInstance, type ToolbarOptions } from './engine';
+
+export interface ToolbarProps extends Omit<HTMLAttributes<HTMLDivElement>, 'onChange'>, ToolbarOptions {
+  instanceRef?: MutableRefObject<ToolbarInstance | null>;
+}
+
+/** <Toolbar aria-label="Herramientas" value={tool} onChange={setTool}><button data-mk-tool="lapiz" aria-label="Lápiz">…</button></Toolbar> */
+export function Toolbar({ value, orientation, tips, onChange, instanceRef, className, children, ...props }: ToolbarProps) {
+  const ref = useRef<HTMLDivElement>(null);
+  const changed = useLatest(onChange);
+  const instance = useRef<ToolbarInstance | null>(null);
+  useIsomorphicLayoutEffect(() => {
+    const created = createToolbar(ref.current, { value, orientation, tips, onChange: (next) => changed.current?.(next) });
+    instance.current = created;
+    if (instanceRef) instanceRef.current = created;
+    return () => {
+      created.destroy();
+      instance.current = null;
+      if (instanceRef) instanceRef.current = null;
+    };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [orientation, tips]);
+  useIsomorphicLayoutEffect(() => {
+    if (value !== undefined && instance.current && instance.current.value !== value) instance.current.setValue(value);
+  }, [value]);
+  return (
+    <div {...props} ref={ref} className={['mk-toolbar', className].filter(Boolean).join(' ')}>
+      {children}
+    </div>
+  );
+}