@yewdiel21/motion-kit 0.9.1 → 0.14.0

package/src/components/resizable-panel/engine.ts

@@ -0,0 +1,551 @@
+import { gsap, EASE, registerMotion } from '../../core/gsap';
+import { reduced } from '../../core/reduced';
+import { createScope } from '../../core/scope';
+import { inert, type Instance } from '../../core/types';
+import { fromJson } from '../../core/dates';
+import { requestFrame } from '../../core/frame';
+
+/*
+ * Resizable panels: panels side by side (or stacked) with a separator between
+ * each pair that drags (mouse, pen, touch) and moves with the keyboard (the
+ * WAI-ARIA window splitter). A separator is a hairline with a grip that grows
+ * in the accent on hover and while dragging, and a bubble shows the two sizes
+ * ("32 % · 68 %") while it moves. Past a panel's limit the drag gives a quarter
+ * of the way (rubber band) and springs back on release (.45 s, swing). A
+ * collapsible panel dragged well under its minimum snaps shut (.3 s, swing)
+ * and opens again when dragged back out, with Enter on its separator, or with
+ * the separator's buttons (handleButtons). A double click on a separator puts
+ * the first sizes back (.45 s, signature). Sizes can be remembered.
+ */
+
+export type PanelOrientation = 'horizontal' | 'vertical';
+
+export interface ResizablePanelOptions {
+  /** 'horizontal' (default): side by side; 'vertical': stacked. */
+  orientation?: PanelOrientation;
+  /** Sizes in percent, one per panel (default: data-size on the panels, else equal). */
+  sizes?: number[];
+  /** Smallest size of a panel in percent (default 10; data-min on a panel wins). */
+  min?: number;
+  /** Largest size of a panel in percent (default 100; data-max on a panel wins). */
+  max?: number;
+  /** Panels (indexes) that snap shut when dragged well under their minimum; data-collapsible on a panel too. */
+  collapsible?: number[];
+  /** Panels that start shut. */
+  collapsed?: number[];
+  /** Arrow keys move this many percent (default 5; Shift: four times). */
+  step?: number;
+  /** Remember sizes in localStorage under this key. */
+  storageKey?: string;
+  /** Buttons on each separator to shut and open the panels beside it. */
+  handleButtons?: boolean;
+  /** Names of the panels, for the separators' labels (default: data-label, else "panel 1"…). */
+  labels?: string[];
+  /** While it moves (once a frame). */
+  onResize?: (sizes: number[]) => void;
+  /** When a drag, a key or an animation ends. */
+  onResizeEnd?: (sizes: number[]) => void;
+  onCollapse?: (index: number, collapsed: boolean) => void;
+}
+
+export interface ResizablePanelInstance extends Instance {
+  setSizes(sizes: number[], animate?: boolean): void;
+  collapse(index: number): void;
+  expand(index: number): void;
+  toggle(index: number): void;
+  /** The first sizes again. */
+  reset(): void;
+  setOrientation(orientation: PanelOrientation): void;
+  readonly sizes: number[];
+  readonly collapsed: number[];
+  readonly orientation: PanelOrientation;
+}
+
+const CHEVRON = (path: string) => `<svg aria-hidden="true" width="12" height="12" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.6" stroke-linecap="round" stroke-linejoin="round"><path d="${path}"/></svg>`;
+const ARROWS = { left: CHEVRON('M15 6l-6 6 6 6'), right: CHEVRON('M9 6l6 6-6 6'), up: CHEVRON('M6 15l6-6 6 6'), down: CHEVRON('M6 9l6 6 6-6') };
+let sequence = 0;
+
+const round = (n: number) => Math.round(n * 10) / 10;
+
+/** Sizes that add up to 100: missing ones share what is left, then all scale to 100 (all missing: equal). */
+export function normaliseSizes(sizes: Array<number | undefined>, count: number): number[] {
+  const given = Array.from({ length: count }, (_, i) => {
+    const size = sizes[i];
+    return typeof size === 'number' && Number.isFinite(size) && size >= 0 ? size : null;
+  });
+  const known = given.reduce<number>((sum, size) => sum + (size ?? 0), 0);
+  const missing = given.filter((size) => size === null).length;
+  const share = missing ? Math.max(0, 100 - known) / missing : 0;
+  const list = given.map((size) => size ?? share);
+  const total = list.reduce((sum, size) => sum + size, 0);
+  if (!total) return Array.from({ length: count }, () => 100 / count);
+  return list.map((size) => (size / total) * 100);
+}
+
+export function createResizablePanel(root: HTMLElement | null, options: ResizablePanelOptions = {}): ResizablePanelInstance {
+  if (!root) {
+    return inert({ setSizes() {}, collapse() {}, expand() {}, toggle() {}, reset() {}, setOrientation() {}, sizes: [], collapsed: [], orientation: 'horizontal' as PanelOrientation });
+  }
+  registerMotion();
+  const scope = createScope();
+  const uid = `mk-rp-${++sequence}`;
+  const panels = [...root.children].filter((child): child is HTMLElement => child instanceof HTMLElement && !child.hasAttribute('data-mk-resize-handle'));
+  const count = panels.length;
+  let orientation: PanelOrientation = options.orientation === 'vertical' ? 'vertical' : 'horizontal';
+  const step = options.step && options.step > 0 ? options.step : 5;
+  const number = (value: string | undefined) => (value !== undefined && value !== '' && Number.isFinite(Number(value)) ? Number(value) : undefined);
+  const mins = panels.map((panel) => Math.max(0, number(panel.dataset.min) ?? options.min ?? 10));
+  const maxs = panels.map((panel) => Math.min(100, number(panel.dataset.max) ?? options.max ?? 100));
+  const collapsibleList = fromJson(options.collapsible) ?? [];
+  const canCollapse = panels.map((panel, i) => panel.hasAttribute('data-collapsible') || collapsibleList.includes(i));
+  const names = panels.map((panel, i) => options.labels?.[i] ?? panel.dataset.label ?? panel.getAttribute('aria-label') ?? `panel ${i + 1}`);
+  const initial = normaliseSizes(fromJson(options.sizes) ?? panels.map((panel) => number(panel.dataset.size)), count);
+  let sizes = [...initial];
+  const collapsed = new Set<number>((fromJson(options.collapsed) ?? []).filter((i) => canCollapse[i]));
+  /** What a panel had before it shut, to open back to. */
+  const before = new Map<number, number>();
+  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);
+  };
+
+  // Remembered sizes win over the given ones.
+  const storage = (() => {
+    try {
+      return options.storageKey ? window.localStorage : null;
+    } catch {
+      return null;
+    }
+  })();
+  if (storage && options.storageKey) {
+    try {
+      const saved = JSON.parse(storage.getItem(options.storageKey) ?? 'null') as { sizes?: number[]; collapsed?: number[] } | null;
+      if (saved?.sizes?.length === count) {
+        sizes = normaliseSizes(saved.sizes, count);
+        collapsed.clear();
+        for (const i of saved.collapsed ?? []) if (canCollapse[i]) collapsed.add(i);
+      }
+    } catch {
+      // Unreadable: the given sizes stand.
+    }
+  }
+  // A shut panel gives its room to its neighbour; it opens back to what it had.
+  for (const i of collapsed) {
+    if (sizes[i]! > 0) {
+      before.set(i, sizes[i]!);
+      const neighbour = i + 1 < count ? i + 1 : i - 1;
+      if (neighbour >= 0) sizes[neighbour]! += sizes[i]!;
+      sizes[i] = 0;
+    }
+  }
+
+  // ── The parts ────────────────────────────────────────────────────────────
+  scope.attr(root, 'data-mk-ready', '');
+  scope.attr(root, 'data-mk-orientation', orientation);
+  panels.forEach((panel, i) => {
+    scope.attr(panel, 'data-mk-panel', '');
+    if (!panel.id) scope.attr(panel, 'id', `${uid}-panel-${i}`);
+    scope.attr(panel, 'style', panel.getAttribute('style'));
+  });
+  const bubble = document.createElement('span');
+  bubble.dataset.mkResizeBubble = '';
+  bubble.setAttribute('aria-hidden', 'true');
+  bubble.hidden = true;
+  const handles = panels.slice(0, -1).map((panel, i) => {
+    const handle = document.createElement('div');
+    handle.dataset.mkResizeHandle = '';
+    handle.dataset.index = String(i);
+    handle.setAttribute('role', 'separator');
+    handle.tabIndex = 0;
+    handle.setAttribute('aria-controls', panel.id);
+    handle.setAttribute('aria-label', `Redimensionar ${names[i]} y ${names[i + 1]}`);
+    const grip = document.createElement('span');
+    grip.dataset.mkResizeGrip = '';
+    grip.setAttribute('aria-hidden', 'true');
+    handle.append(grip);
+    if (options.handleButtons) {
+      for (const [side, target] of [['start', i], ['end', i + 1]] as const) {
+        if (!canCollapse[target]) continue;
+        const button = document.createElement('button');
+        button.type = 'button';
+        button.tabIndex = -1;
+        button.dataset.mkResizeButton = side;
+        handle.append(button);
+      }
+    }
+    panel.after(handle);
+    return handle;
+  });
+  root.append(bubble);
+  scope.add(() => {
+    for (const effect of effects) effect.kill();
+    effects.clear();
+    for (const handle of handles) handle.remove();
+    bubble.remove();
+    for (const panel of panels) panel.removeAttribute('data-mk-collapsed');
+  });
+
+  // ── Drawing the sizes ────────────────────────────────────────────────────
+  const horizontal = () => orientation === 'horizontal';
+  const apply = (next: number[]) => {
+    panels.forEach((panel, i) => {
+      const size = Math.max(0, next[i]!);
+      panel.style.flex = `${round(size * 100) / 100} 1 0px`;
+      panel.toggleAttribute('data-mk-collapsed', collapsed.has(i) && size < 0.5);
+    });
+    handles.forEach((handle, i) => {
+      // A separator pushed to an edge by a shut panel keeps its buttons inside.
+      const edge = i === count - 2 && collapsed.has(i + 1) && next[i + 1]! < 0.5 ? 'end' : i === 0 && collapsed.has(0) && next[0]! < 0.5 ? 'start' : null;
+      if (edge) handle.dataset.edge = edge;
+      else delete handle.dataset.edge;
+      handle.setAttribute('aria-valuenow', String(Math.round(Math.max(0, next[i]!))));
+      handle.setAttribute('aria-valuemin', String(canCollapse[i] ? 0 : Math.round(mins[i]!)));
+      handle.setAttribute('aria-valuemax', String(Math.round(Math.min(maxs[i]!, 100 - (canCollapse[i + 1] ? 0 : mins[i + 1]!)))));
+      handle.setAttribute('aria-valuetext', `${Math.round(Math.max(0, next[i]!))} %${collapsed.has(i) ? ', cerrado' : ''}`);
+      for (const button of handle.querySelectorAll<HTMLButtonElement>('[data-mk-resize-button]')) {
+        const start = button.dataset.mkResizeButton === 'start';
+        const index = start ? i : i + 1;
+        const shut = collapsed.has(index);
+        // The arrow points where the panel goes: toward its edge to shut it, away to open it.
+        button.innerHTML = horizontal() ? (start === !shut ? ARROWS.left : ARROWS.right) : start === !shut ? ARROWS.up : ARROWS.down;
+        const label = `${shut ? 'Abrir' : 'Cerrar'} ${names[index]}`;
+        button.setAttribute('aria-label', label);
+        button.title = label;
+      }
+    });
+  };
+  const paintOrientation = () => {
+    root.setAttribute('data-mk-orientation', orientation);
+    for (const handle of handles) handle.setAttribute('aria-orientation', horizontal() ? 'vertical' : 'horizontal');
+  };
+  paintOrientation();
+  apply(sizes);
+
+  const save = () => {
+    if (!storage || !options.storageKey) return;
+    try {
+      storage.setItem(options.storageKey, JSON.stringify({ sizes: sizes.map(round), collapsed: [...collapsed] }));
+    } catch {
+      // Full or blocked: not remembered.
+    }
+  };
+  let pendingNotify: (() => void) | null = null;
+  const notify = () => {
+    if (pendingNotify || !options.onResize) return;
+    pendingNotify = requestFrame(() => {
+      pendingNotify = null;
+      options.onResize?.(sizes.map(round));
+    });
+  };
+  scope.add(() => pendingNotify?.());
+  const settle = () => {
+    save();
+    options.onResizeEnd?.(sizes.map(round));
+    root.dispatchEvent(new CustomEvent('mk:resize', { bubbles: true, detail: { sizes: sizes.map(round) } }));
+  };
+
+  let tween: gsap.core.Tween | null = null;
+  /** Glide to `target` (a spring by default). */
+  const animateTo = (target: number[], { duration = 0.45, ease = EASE.signature, done }: { duration?: number; ease?: string; done?: () => void } = {}) => {
+    tween?.kill();
+    if (reduced()) {
+      sizes = target;
+      apply(sizes);
+      done?.();
+      return;
+    }
+    const from = [...sizes];
+    const progress = { t: 0 };
+    tween = gsap.to(progress, {
+      t: 1,
+      duration,
+      ease,
+      onUpdate: () => {
+        sizes = from.map((size, i) => Math.max(0, size + (target[i]! - size) * progress.t));
+        apply(sizes);
+        notify();
+      },
+      onComplete: () => {
+        sizes = [...target];
+        apply(sizes);
+        tween = null;
+        done?.();
+      },
+    });
+    keep(tween);
+  };
+
+  // ── Limits ───────────────────────────────────────────────────────────────
+  const lowest = (i: number) => (collapsed.has(i) ? 0 : mins[i]!);
+  /** How far the separator `i` may move (in percent) from `start` sizes: [most negative, most positive]. */
+  const room = (i: number, start: number[]) => {
+    const a = start[i]!;
+    const b = start[i + 1]!;
+    const down = Math.max(lowest(i) - a, b - maxs[i + 1]!);
+    const up = Math.min(maxs[i]! - a, b - lowest(i + 1));
+    return [Math.min(0, down), Math.max(0, up)] as const;
+  };
+
+  const setCollapsed = (index: number, shut: boolean, animate = true) => {
+    if (!canCollapse[index] || collapsed.has(index) === shut) return;
+    // The neighbour that gives or takes the room: the next panel, or the one before the last.
+    const neighbour = index + 1 < count ? index + 1 : index - 1;
+    const target = [...sizes];
+    if (shut) {
+      before.set(index, sizes[index]! > 0.5 ? sizes[index]! : before.get(index) ?? initial[index]!);
+      target[neighbour] = sizes[neighbour]! + sizes[index]!;
+      target[index] = 0;
+      collapsed.add(index);
+    } else {
+      collapsed.delete(index);
+      const wanted = Math.max(mins[index]!, before.get(index) ?? initial[index]!);
+      const give = Math.min(wanted, Math.max(0, sizes[neighbour]! - mins[neighbour]!));
+      target[index] = give;
+      target[neighbour] = sizes[neighbour]! - give;
+    }
+    const finish = () => {
+      settle();
+      options.onCollapse?.(index, shut);
+      root.dispatchEvent(new CustomEvent('mk:collapse', { bubbles: true, detail: { index, collapsed: shut } }));
+    };
+    status.textContent = `${names[index]} ${shut ? 'cerrado' : 'abierto'}`;
+    if (animate) animateTo(target, { duration: 0.3, ease: EASE.swatch, done: finish });
+    else {
+      sizes = target;
+      apply(sizes);
+      finish();
+    }
+  };
+
+  const status = document.createElement('span');
+  status.className = 'mk-sr-only';
+  status.setAttribute('role', 'status');
+  root.append(status);
+  scope.add(() => status.remove());
+
+  // ── Dragging ─────────────────────────────────────────────────────────────
+  interface Drag {
+    index: number;
+    pointerId: number;
+    start: number[];
+    origin: number;
+    /** Pixels the panels share (the root without its separators). */
+    space: number;
+    moved: boolean;
+  }
+  let drag: Drag | null = null;
+  const spaceOf = () => {
+    const box = root.getBoundingClientRect();
+    const handlesSize = handles.reduce((sum, handle) => sum + (horizontal() ? handle.offsetWidth : handle.offsetHeight), 0);
+    return Math.max(1, (horizontal() ? box.width : box.height) - handlesSize);
+  };
+  const showBubble = (i: number, at: number) => {
+    bubble.hidden = false;
+    bubble.textContent = `${Math.round(sizes[i]!)} % · ${Math.round(sizes[i + 1]!)} %`;
+    const handle = handles[i]!;
+    const box = handle.getBoundingClientRect();
+    const rootBox = root.getBoundingClientRect();
+    if (horizontal()) {
+      bubble.style.left = `${box.left - rootBox.left + box.width / 2}px`;
+      bubble.style.top = `${Math.max(16, Math.min(rootBox.height - 16, at - rootBox.top))}px`;
+    } else {
+      bubble.style.top = `${box.top - rootBox.top + box.height / 2}px`;
+      bubble.style.left = `${Math.max(40, Math.min(rootBox.width - 40, at - rootBox.left))}px`;
+    }
+  };
+  const hideBubble = () => {
+    if (bubble.hidden) return;
+    if (reduced()) {
+      bubble.hidden = true;
+      return;
+    }
+    // Opacity only: the bubble is centred with CSS translate, which transforms would reset.
+    keep(gsap.to(bubble, { opacity: 0, duration: 0.18, ease: 'power1.in', onComplete: () => {
+      bubble.hidden = true;
+      gsap.set(bubble, { clearProps: 'opacity' });
+    } }));
+  };
+
+  const move = (event: PointerEvent) => {
+    if (!drag || event.pointerId !== drag.pointerId) return;
+    event.preventDefault();
+    const i = drag.index;
+    const position = horizontal() ? event.clientX : event.clientY;
+    const wanted = ((position - drag.origin) / drag.space) * 100;
+    if (!drag.moved && Math.abs(wanted) > 0.2) {
+      drag.moved = true;
+      handles[i]!.setAttribute('data-mk-dragging', '');
+      if (!reduced()) keep(gsap.fromTo(bubble, { opacity: 0 }, { opacity: 1, duration: 0.2, ease: 'power1.out', clearProps: 'opacity' }));
+    }
+    // A collapsible panel dragged well under its minimum snaps shut; dragged back out, it opens.
+    for (const [index, sign] of [[i, 1], [i + 1, -1]] as const) {
+      if (!canCollapse[index]) continue;
+      const size = drag.start[index]! + sign * wanted;
+      const threshold = mins[index]! / 2;
+      if (!collapsed.has(index) && size < threshold) {
+        collapsed.add(index);
+        before.set(index, drag.start[index]! > 0.5 ? drag.start[index]! : before.get(index) ?? initial[index]!);
+        const target = [...drag.start];
+        target[index] = 0;
+        target[index === i ? i + 1 : i] = drag.start[i]! + drag.start[i + 1]!;
+        // If the drag is over when it lands, it settles then.
+        animateTo(target, { duration: 0.3, ease: EASE.swatch, done: () => (drag ? undefined : settle()) });
+        status.textContent = `${names[index]} cerrado`;
+        options.onCollapse?.(index, true);
+        return;
+      }
+      if (collapsed.has(index)) {
+        // Still shut while the pointer stays near it.
+        if (size <= threshold) return;
+        collapsed.delete(index);
+        status.textContent = `${names[index]} abierto`;
+        options.onCollapse?.(index, false);
+      }
+    }
+    if (tween) return;
+    const [down, up] = room(i, drag.start);
+    // Past a limit the panel gives a quarter of the way (rubber band).
+    const delta = wanted < down ? down + (wanted - down) / 4 : wanted > up ? up + (wanted - up) / 4 : wanted;
+    const next = [...drag.start];
+    next[i] = Math.max(0, drag.start[i]! + delta);
+    next[i + 1] = Math.max(0, drag.start[i + 1]! - delta);
+    sizes = next;
+    apply(sizes);
+    showBubble(i, horizontal() ? event.clientY : event.clientX);
+    notify();
+  };
+  const end = (event: PointerEvent) => {
+    if (!drag || event.pointerId !== drag.pointerId) return;
+    const { index } = drag;
+    const moved = drag.moved;
+    drag = null;
+    window.removeEventListener('pointermove', move);
+    window.removeEventListener('pointerup', end);
+    window.removeEventListener('pointercancel', end);
+    handles[index]!.removeAttribute('data-mk-dragging');
+    root.removeAttribute('data-mk-resizing');
+    hideBubble();
+    // A snap on its way settles when it lands.
+    if (!moved || tween) return;
+    // Back inside the limits with a spring, if the drag went past them.
+    const clamped = [...sizes];
+    for (const i of [index, index + 1]) {
+      if (collapsed.has(i)) continue;
+      const fixed = Math.min(maxs[i]!, Math.max(mins[i]!, clamped[i]!));
+      const other = i === index ? index + 1 : index;
+      clamped[other] = clamped[other]! + clamped[i]! - fixed;
+      clamped[i] = fixed;
+    }
+    if (clamped.some((size, i) => Math.abs(size - sizes[i]!) > 0.05)) animateTo(clamped, { duration: 0.45, ease: EASE.swatch, done: settle });
+    else settle();
+    // The grip settles with a little pop.
+    const grip = handles[index]!.querySelector('[data-mk-resize-grip]');
+    if (grip && !reduced()) keep(gsap.fromTo(grip, { scale: 1.25 }, { scale: 1, duration: 0.4, ease: EASE.pop, clearProps: 'transform' }));
+  };
+  scope.add(() => {
+    window.removeEventListener('pointermove', move);
+    window.removeEventListener('pointerup', end);
+    window.removeEventListener('pointercancel', end);
+  });
+
+  handles.forEach((handle, i) => {
+    scope.on(handle, 'pointerdown', (event) => {
+      const pointer = event as PointerEvent;
+      if (pointer.button !== 0 || (pointer.target as Element).closest('[data-mk-resize-button]')) return;
+      pointer.preventDefault();
+      handle.focus({ preventScroll: true });
+      tween?.kill();
+      tween = null;
+      drag = { index: i, pointerId: pointer.pointerId, start: [...sizes], origin: horizontal() ? pointer.clientX : pointer.clientY, space: spaceOf(), moved: false };
+      root.setAttribute('data-mk-resizing', '');
+      window.addEventListener('pointermove', move, { passive: false });
+      window.addEventListener('pointerup', end);
+      window.addEventListener('pointercancel', end);
+    });
+    scope.on(handle, 'dblclick', (event) => {
+      if ((event.target as Element).closest('[data-mk-resize-button]')) return;
+      collapsed.clear();
+      status.textContent = 'Tamaños iniciales';
+      animateTo([...initial], { done: settle });
+    });
+    scope.on(handle, 'click', (event) => {
+      const button = (event.target as Element).closest<HTMLElement>('[data-mk-resize-button]');
+      if (!button) return;
+      const index = button.dataset.mkResizeButton === 'start' ? i : i + 1;
+      setCollapsed(index, !collapsed.has(index));
+    });
+    scope.on(handle, 'keydown', (event) => {
+      const key = event as KeyboardEvent;
+      const less = horizontal() ? 'ArrowLeft' : 'ArrowUp';
+      const more = horizontal() ? 'ArrowRight' : 'ArrowDown';
+      let delta: number | null = null;
+      const [down, up] = room(i, sizes);
+      if (key.key === less) delta = -step * (key.shiftKey ? 4 : 1);
+      else if (key.key === more) delta = step * (key.shiftKey ? 4 : 1);
+      else if (key.key === 'Home') delta = down;
+      else if (key.key === 'End') delta = up;
+      else if (key.key === 'Enter') {
+        key.preventDefault();
+        // The panel before it shuts or opens (or the one after, when only that one can).
+        const index = canCollapse[i] ? i : canCollapse[i + 1] ? i + 1 : -1;
+        if (index >= 0) setCollapsed(index, !collapsed.has(index));
+        return;
+      }
+      if (delta === null) return;
+      key.preventDefault();
+      const moveBy = Math.max(down, Math.min(up, delta));
+      if (Math.abs(moveBy) < 0.01) {
+        // At the limit: a nudge says so.
+        if (!reduced()) keep(gsap.fromTo(handle.querySelector('[data-mk-resize-grip]'), { [horizontal() ? 'x' : 'y']: Math.sign(delta) * 3 }, { [horizontal() ? 'x' : 'y']: 0, duration: 0.4, ease: EASE.pop, clearProps: 'transform' }));
+        return;
+      }
+      const target = [...sizes];
+      target[i] = sizes[i]! + moveBy;
+      target[i + 1] = sizes[i + 1]! - moveBy;
+      animateTo(target, { duration: 0.2, ease: 'power2.out', done: settle });
+    });
+  });
+
+  return {
+    setSizes(next, animate = true) {
+      if (scope.disposed) return;
+      const target = normaliseSizes(next, count);
+      collapsed.clear();
+      target.forEach((size, i) => {
+        if (size < 0.5 && canCollapse[i]) collapsed.add(i);
+      });
+      if (animate) animateTo(target, { done: settle });
+      else {
+        tween?.kill();
+        sizes = target;
+        apply(sizes);
+      }
+    },
+    collapse: (index) => setCollapsed(index, true),
+    expand: (index) => setCollapsed(index, false),
+    toggle: (index) => setCollapsed(index, !collapsed.has(index)),
+    reset() {
+      collapsed.clear();
+      animateTo([...initial], { done: settle });
+    },
+    setOrientation(next) {
+      if (next === orientation || scope.disposed) return;
+      orientation = next;
+      paintOrientation();
+      apply(sizes);
+    },
+    get sizes() {
+      return sizes.map(round);
+    },
+    get collapsed() {
+      return [...collapsed];
+    },
+    get orientation() {
+      return orientation;
+    },
+    destroy: () => scope.dispose(),
+  };
+}

package/src/components/resizable-panel/react.tsx

@@ -0,0 +1,74 @@
+'use client';
+import { Children, forwardRef, useImperativeHandle, useRef, type HTMLAttributes } from 'react';
+import { useIsomorphicLayoutEffect, useLatest } from '../../react/use-recipe';
+import { createResizablePanel, type ResizablePanelInstance, type ResizablePanelOptions } from './engine';
+
+export interface ResizablePanelProps extends Omit<HTMLAttributes<HTMLDivElement>, 'onResize'>, ResizablePanelOptions {}
+
+export type ResizablePanelHandle = Pick<ResizablePanelInstance, 'setSizes' | 'collapse' | 'expand' | 'toggle' | 'reset'>;
+
+/**
+ * <ResizablePanel sizes={[25, 75]} collapsible={[0]} onResizeEnd={save}><aside /><main /></ResizablePanel>.
+ * New `sizes` glide there; adding or taking away a panel starts it again.
+ */
+export const ResizablePanel = forwardRef<ResizablePanelHandle, ResizablePanelProps>(function ResizablePanel(
+  { orientation, sizes, min, max, collapsible, collapsed, step, storageKey, handleButtons, labels, onResize, onResizeEnd, onCollapse, className, children, ...props },
+  handle,
+) {
+  const ref = useRef<HTMLDivElement>(null);
+  const instance = useRef<ResizablePanelInstance | null>(null);
+  const resize = useLatest(onResize);
+  const resizeEnd = useLatest(onResizeEnd);
+  const collapse = useLatest(onCollapse);
+  const shown = useRef(sizes);
+  useImperativeHandle(
+    handle,
+    () => ({
+      setSizes: (next, animate) => instance.current?.setSizes(next, animate),
+      collapse: (index) => instance.current?.collapse(index),
+      expand: (index) => instance.current?.expand(index),
+      toggle: (index) => instance.current?.toggle(index),
+      reset: () => instance.current?.reset(),
+    }),
+    [],
+  );
+  const count = Children.count(children);
+  useIsomorphicLayoutEffect(() => {
+    const created = createResizablePanel(ref.current, {
+      orientation,
+      sizes: shown.current,
+      min,
+      max,
+      collapsible,
+      collapsed,
+      step,
+      storageKey,
+      handleButtons,
+      labels,
+      onResize: (next) => resize.current?.(next),
+      onResizeEnd: (next) => resizeEnd.current?.(next),
+      onCollapse: (index, shut) => collapse.current?.(index, shut),
+    });
+    instance.current = created;
+    return () => {
+      created.destroy();
+      instance.current = null;
+    };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [count, min, max, String(collapsible), step, storageKey, handleButtons, String(labels)]);
+  useIsomorphicLayoutEffect(() => {
+    if (orientation) instance.current?.setOrientation(orientation);
+  }, [orientation]);
+  const sizesKey = JSON.stringify(sizes ?? null);
+  useIsomorphicLayoutEffect(() => {
+    if (!sizes || JSON.stringify(shown.current ?? null) === sizesKey) return;
+    shown.current = sizes;
+    instance.current?.setSizes(sizes);
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [sizesKey]);
+  return (
+    <div {...props} ref={ref} className={['mk-resizable-panel', className].filter(Boolean).join(' ')}>
+      {children}
+    </div>
+  );
+});