@yewdiel21/motion-kit 0.0.0-stage → 0.9.0

package/src/recipes/sortable/create-sortable.ts

@@ -0,0 +1,863 @@
+import { gsap, EASE, registerMotion } from '../../core/gsap';
+import { reduced } from '../../core/reduced';
+import { createScope } from '../../core/scope';
+import { clearStyles } from '../../core/styles';
+import { TIMING } from '../../core/timing';
+import { inert, warnOnce, type Instance } from '../../core/types';
+import { captureLayout, reflowLayout } from '../../motion/layout';
+
+/*
+ * Stepbro's drag reorder (Tasks useDragReorder, "transform" mode). Past 6 px
+ * the item lifts (0.18 s) into a floating copy that follows the pointer on a
+ * spring (1100/38, heavier when bigger) and tilts with its speed (spring
+ * 170/13, up to 14°); the item it left is a hidden slot. The others never
+ * change place in the DOM while dragging: they slide (0.62 s, spring .52) to
+ * open a gap where the item would land. On release the copy lands in its new
+ * place (0.42 s, spring .62) and the list is reordered: by the engine
+ * (`mutate`, vanilla) or by the app (`onReorder`, then the engine waits for the
+ * DOM to change). Edges auto-scroll (56 px, up to 16 px a frame); Escape
+ * cancels; on touch only [data-mk-sort-handle] drags, so the list still
+ * scrolls. Keyboard (added): Space/Enter lifts, arrows move, Space/Enter drops,
+ * Escape cancels, each step announced.
+ * Parts: [data-mk-sortable-group] (optional; data-mk-sortable-locked refuses
+ * drops), [data-mk-item] with data-mk-id, [data-mk-sort-handle].
+ */
+
+export interface SortableLabels {
+  lifted?: (position: number, total: number) => string;
+  moved?: (position: number, total: number, group: string) => string;
+  dropped?: (position: number, total: number) => string;
+  cancelled?: string;
+}
+
+export interface SortableOptions {
+  /** Reorder the DOM on drop (default). Off when a framework renders the list: answer onReorder. */
+  mutate?: boolean;
+  /** Drag only from [data-mk-sort-handle] (always so on touch screens). */
+  handle?: boolean;
+  autoScroll?: boolean;
+  /** The floating copy's spring (Stepbro: 1100 / 38). */
+  follow?: { stiffness?: number; damping?: number };
+  labels?: SortableLabels;
+  onReorder?: (detail: ReorderDetail) => void;
+}
+
+export interface ReorderDetail {
+  id: string;
+  item: HTMLElement;
+  fromGroup: string;
+  toGroup: string;
+  fromIndex: number;
+  toIndex: number;
+  groupChanged: boolean;
+  /** Neighbours at the destination (Stepbro sends one to its API as the anchor). */
+  afterId: string | null;
+  beforeId: string | null;
+}
+
+export interface SortableInstance extends Instance {
+  /** Stop a drag in progress: the item flies back. */
+  cancel(): void;
+  readonly dragging: boolean;
+}
+
+const GROUP = '[data-mk-sortable-group]';
+const ITEM = '[data-mk-item]';
+const HANDLE = '[data-mk-sort-handle]';
+const INTERACTIVE = [
+  'a[href]',
+  'button',
+  'input',
+  'select',
+  'textarea',
+  '[contenteditable="true"]',
+  '[role="button"]',
+  '[role="slider"]',
+  '[data-clickable="true"]',
+].join(',');
+const THRESHOLD = 6;
+const TILT = { max: 14, vel: 2e-3, accel: 45e-5, stiffness: 170, damping: 13, hang: 0.4, refArea: 24000 };
+const EDGE = 56;
+const MAX_SCROLL = 16;
+const TRANSFORMS = ['transform', 'translate', 'rotate', 'scale'];
+
+const LABELS: Required<SortableLabels> = {
+  lifted: (position, total) =>
+    `Elemento levantado, posición ${position} de ${total}. Flechas para mover, Espacio para soltar, Escape para cancelar.`,
+  moved: (position, total, group) => (group ? `${group}, posición ${position} de ${total}.` : `Posición ${position} de ${total}.`),
+  dropped: (position, total) => `Elemento soltado en la posición ${position} de ${total}.`,
+  cancelled: 'Movimiento cancelado.',
+};
+
+interface Measured {
+  el: HTMLElement;
+  top: number;
+  height: number;
+}
+
+interface MeasuredGroup {
+  el: HTMLElement;
+  rect: DOMRect;
+  locked: boolean;
+  items: Measured[];
+}
+
+interface Layer {
+  el: HTMLElement;
+  ox: number;
+  oy: number;
+}
+
+interface Press {
+  item: HTMLElement;
+  group: HTMLElement;
+  index: number;
+  startX: number;
+  startY: number;
+  grabX: number;
+  grabY: number;
+  width: number;
+  height: number;
+}
+
+export function createSortable(root: HTMLElement | null, options: SortableOptions = {}): SortableInstance {
+  if (!root) {
+    warnOnce('sortable: missing root');
+    return inert({ cancel() {}, dragging: false });
+  }
+  registerMotion();
+  const scope = createScope();
+  const { mutate = true, autoScroll = true } = options;
+  const follow = { stiffness: 1100, damping: 38, ...options.follow };
+  const labels = { ...LABELS, ...options.labels };
+
+  // ── Structure ─────────────────────────────────────────────────────────────
+  const groups = () => {
+    const list = [...root.querySelectorAll<HTMLElement>(GROUP)];
+    if (root.matches(GROUP)) list.unshift(root);
+    else if (!list.length) list.push(root);
+    return list;
+  };
+  const ownerOf = (item: HTMLElement) => {
+    const group = item.parentElement?.closest<HTMLElement>(GROUP);
+    return group && root.contains(group) ? group : root;
+  };
+  const itemsOf = (group: HTMLElement) => [...group.querySelectorAll<HTMLElement>(ITEM)].filter((item) => ownerOf(item) === group);
+  const keyOf = (group: HTMLElement) => group.dataset.mkSortableGroup ?? '';
+  const isLocked = (group: HTMLElement) => group.hasAttribute('data-mk-sortable-locked') && group.dataset.mkSortableLocked !== 'false';
+  const idOf = (item: HTMLElement) => {
+    if (item.dataset.mkId !== undefined) return item.dataset.mkId;
+    warnOnce('sortable: give each [data-mk-item] a data-mk-id');
+    return String(itemsOf(ownerOf(item)).indexOf(item));
+  };
+  const findItem = (id: string) => [...root.querySelectorAll<HTMLElement>(ITEM)].find((item) => item.dataset.mkId === id) ?? null;
+  // Reading a transform makes GSAP write translate/rotate/scale: none inline; untouch() takes them off.
+  const touched = new Set<HTMLElement>();
+  const transformY = (el: HTMLElement) => {
+    touched.add(el);
+    return Number(gsap.getProperty(el, 'y')) || 0;
+  };
+  const transformX = (el: HTMLElement) => {
+    touched.add(el);
+    return Number(gsap.getProperty(el, 'x')) || 0;
+  };
+  const untouch = () => {
+    const idle = [...touched].filter((el) => !gsap.isTweening(el));
+    for (const el of idle) touched.delete(el);
+    clearStyles(idle, TRANSFORMS);
+  };
+
+  const makeDetail = (item: HTMLElement, from: { group: HTMLElement; index: number }, to: { group: HTMLElement; index: number }) => {
+    const others = itemsOf(to.group).filter((el) => el !== item);
+    const after = others[to.index - 1];
+    const before = others[to.index];
+    const detail: ReorderDetail = {
+      id: idOf(item),
+      item,
+      fromGroup: keyOf(from.group),
+      toGroup: keyOf(to.group),
+      fromIndex: from.index,
+      toIndex: to.index,
+      groupChanged: from.group !== to.group,
+      afterId: after ? idOf(after) : null,
+      beforeId: after ? null : before ? idOf(before) : null,
+    };
+    return detail;
+  };
+
+  const moveDom = (item: HTMLElement, group: HTMLElement, index: number) => {
+    const focused = item.contains(document.activeElement) ? (document.activeElement as HTMLElement) : null;
+    const others = itemsOf(group).filter((el) => el !== item);
+    const before = others[index];
+    if (before) before.before(item);
+    else if (others.length) others[others.length - 1]!.after(item);
+    else group.append(item);
+    focused?.focus({ preventScroll: true });
+  };
+
+  /** Resolves when the app has changed the list (or false after `ms` without a change). */
+  const waiting = new Set<() => void>();
+  scope.add(() => {
+    for (const stop of [...waiting]) stop();
+  });
+  const domChange = (ms = 400) =>
+    new Promise<boolean>((resolve) => {
+      let done = false;
+      const finish = (changed: boolean) => {
+        if (done) return;
+        done = true;
+        waiting.delete(stop);
+        observer.disconnect();
+        clearTimeout(timer);
+        resolve(changed);
+      };
+      const stop = () => finish(false);
+      waiting.add(stop);
+      const observer = new MutationObserver((records) => {
+        if (
+          records.some((record) =>
+            [...record.addedNodes, ...record.removedNodes].some((node) => node instanceof HTMLElement && node.matches(ITEM)),
+          )
+        )
+          finish(true);
+      });
+      observer.observe(root, { childList: true, subtree: true });
+      const timer = setTimeout(stop, ms);
+    });
+
+  // ── Live region (keyboard) ────────────────────────────────────────────────
+  let live: HTMLElement | null = null;
+  const announce = (text: string) => {
+    if (!live) {
+      live = document.createElement('div');
+      live.setAttribute('aria-live', 'assertive');
+      live.setAttribute('role', 'status');
+      Object.assign(live.style, {
+        position: 'absolute',
+        width: '1px',
+        height: '1px',
+        overflow: 'hidden',
+        clipPath: 'inset(50%)',
+        whiteSpace: 'nowrap',
+      });
+      document.body.append(live);
+      const created = live;
+      scope.add(() => created.remove());
+    }
+    live.textContent = text;
+  };
+
+  // ── Pointer drag ──────────────────────────────────────────────────────────
+  const pointer = { x: 0, y: 0 };
+  let press: Press | null = null;
+  let dragging = false;
+  let floating = { x: 0, y: 0, width: 0, tilt: 0, lift: 0, fade: 0 };
+  let layers: Layer[] = [];
+  let lifting: gsap.core.Tween | null = null;
+  let landing: gsap.core.Timeline | null = null;
+  let layout: { groups: MeasuredGroup[]; source: MeasuredGroup; dragTop: number; shift: number } | null = null;
+  const shifted = new Map<HTMLElement, number>();
+  let placement: { group: HTMLElement; index: number } | null = null;
+  let physics: {
+    vx: number;
+    vy: number;
+    tiltV: number;
+    fvx: number;
+    fvy: number;
+    armX: number;
+    armY: number;
+    mass: number;
+    x: number;
+    y: number;
+    t: number;
+  } | null = null;
+  let scrollers: Array<{ el: HTMLElement | null; y: boolean; x: boolean }> = [];
+  let draggedEls = new Set<HTMLElement>();
+
+  const render = () => {
+    const { x, y, width, tilt, lift, fade } = floating;
+    layers.forEach((layer, i) => {
+      const style = layer.el.style;
+      style.transform = `translate3d(${x - layer.ox}px, ${y - layer.oy}px, 0) rotate(${tilt}deg) scale(${1 + lift * 0.03})`;
+      style.width = `${width}px`;
+      style.setProperty('--mk-lift', lift.toFixed(3));
+      if (layers.length > 1) style.opacity = String(i === 0 ? 1 - fade : fade);
+    });
+  };
+
+  /** A copy of `source` floating in `parent` (position fixed), so the parent's CSS still styles it. */
+  const makeLayer = (source: HTMLElement, parent: HTMLElement, grabX: number, grabY: number): Layer => {
+    const el = source.cloneNode(true) as HTMLElement;
+    for (const name of ['data-mk-item', 'data-mk-id', 'data-mk-dragging', 'data-mk-sort-grabbed', 'data-flip-id', 'id', 'tabindex'])
+      el.removeAttribute(name);
+    for (const child of el.querySelectorAll('[id]')) child.removeAttribute('id');
+    el.dataset.mkSortableClone = '';
+    el.setAttribute('aria-hidden', 'true');
+    el.inert = true;
+    Object.assign(el.style, {
+      position: 'fixed',
+      top: '0',
+      left: '0',
+      margin: '0',
+      boxSizing: 'border-box',
+      zIndex: '9999',
+      pointerEvents: 'none',
+      willChange: 'transform',
+      transform: 'none',
+      transformOrigin: `${grabX}px ${grabY}px`,
+      translate: 'none',
+      rotate: 'none',
+      scale: 'none',
+      visibility: 'visible',
+    });
+    parent.append(el);
+    // A transformed ancestor would anchor `fixed` to itself: measure that offset once.
+    const box = el.getBoundingClientRect();
+    return { el, ox: box.left, oy: box.top };
+  };
+
+  const measure = () => {
+    if (!press) return;
+    const item = press.item;
+    const measured = groups().map((group) => ({
+      el: group,
+      rect: group.getBoundingClientRect(),
+      locked: isLocked(group),
+      items: itemsOf(group).map((el) => {
+        const box = el.getBoundingClientRect();
+        return { el, top: box.top - transformY(el), height: box.height };
+      }),
+    }));
+    const source = measured.find((group) => group.el === press!.group) ?? measured[0]!;
+    const index = source.items.findIndex((entry) => entry.el === item);
+    const dragged = source.items[index];
+    if (!dragged) return;
+    const next = source.items[index + 1];
+    const previous = source.items[index - 1];
+    // The gap an item leaves: its height plus the space to its neighbour (gap or margins).
+    const spacing = next
+      ? next.top - (dragged.top + dragged.height)
+      : previous
+        ? dragged.top - (previous.top + previous.height)
+        : parseFloat(getComputedStyle(source.el).rowGap) || 0;
+    layout = { groups: measured, source, dragTop: dragged.top, shift: dragged.height + Math.max(0, spacing) };
+  };
+
+  const applyShift = (target: MeasuredGroup, index: number) => {
+    if (!layout || !press) return;
+    const item = press.item;
+    const next = new Map<HTMLElement, number>();
+    for (const entry of layout.source.items) if (entry.top > layout.dragTop) next.set(entry.el, -layout.shift);
+    target.items
+      .filter((entry) => entry.el !== item)
+      .forEach((entry, i) => {
+        if (i >= index) next.set(entry.el, (next.get(entry.el) ?? 0) + layout!.shift);
+      });
+    for (const el of shifted.keys()) if (!next.has(el)) next.set(el, 0);
+    for (const [el, y] of next) {
+      if ((shifted.get(el) ?? 0) === y) continue;
+      shifted.set(el, y);
+      touched.add(el);
+      gsap.to(el, { y, duration: reduced() ? 0 : TIMING.sortable.shift, ease: EASE.layoutReflow, overwrite: 'auto' });
+    }
+  };
+
+  const unshift = (animated: boolean) => {
+    const els = [...shifted.keys()];
+    shifted.clear();
+    if (!els.length) return;
+    if (animated && !reduced()) {
+      gsap.to(els, {
+        y: 0,
+        duration: TIMING.sortable.shift,
+        ease: EASE.layoutReflow,
+        overwrite: 'auto',
+        onComplete: () => {
+          clearStyles(els, TRANSFORMS);
+          for (const el of els) touched.delete(el);
+        },
+      });
+    } else {
+      gsap.killTweensOf(els);
+      clearStyles(els, TRANSFORMS);
+    }
+  };
+
+  const place = () => {
+    if (!layout || !press) return;
+    const all = layout.groups;
+    const inside = (rect: DOMRect) => pointer.x >= rect.left && pointer.x <= rect.right;
+    const target =
+      all.length <= 1
+        ? all[0]
+        : (all.find(({ rect }) => inside(rect) && pointer.y >= rect.top && pointer.y <= rect.bottom) ??
+          all.find(({ rect }) => inside(rect)));
+    if (!target || target.locked) return;
+    const others = target.items.filter((entry) => entry.el !== press!.item);
+    let index = 0;
+    for (const entry of others) {
+      if (pointer.y < entry.top + entry.height / 2) break;
+      index++;
+    }
+    applyShift(target, index);
+    placement = { group: target.el, index };
+  };
+
+  const tick = () => {
+    if (!physics || !press) return;
+    const target = { x: pointer.x - press.grabX, y: pointer.y - press.grabY };
+    if (reduced()) {
+      floating.x = target.x;
+      floating.y = target.y;
+      render();
+      return;
+    }
+    const P = physics;
+    const now = performance.now();
+    const dt = Math.min((now - P.t) / 1000, 1 / 30);
+    if (dt <= 0) return;
+    P.t = now;
+    // Smoothed pointer velocity, then a torque from velocity and acceleration about the grab point.
+    const k = 1 - Math.exp(-dt / 0.05);
+    const ax = ((pointer.x - P.x) / dt - P.vx) * k;
+    const ay = ((pointer.y - P.y) / dt - P.vy) * k;
+    P.vx += ax;
+    P.vy += ay;
+    P.x = pointer.x;
+    P.y = pointer.y;
+    const torque = (P.vx * TILT.vel + (ax / dt) * TILT.accel) * P.armY - (P.vy * TILT.vel + (ay / dt) * TILT.accel) * P.armX;
+    const tilt = TILT.max * Math.tanh(torque / TILT.max);
+    P.tiltV += (((tilt - floating.tilt) * TILT.stiffness - P.tiltV * TILT.damping) * dt) / P.mass;
+    floating.tilt += P.tiltV * dt;
+    P.fvx += (((target.x - floating.x) * follow.stiffness - P.fvx * follow.damping) * dt) / P.mass;
+    P.fvy += (((target.y - floating.y) * follow.stiffness - P.fvy * follow.damping) * dt) / P.mass;
+    floating.x += P.fvx * dt;
+    floating.y += P.fvy * dt;
+    render();
+  };
+
+  const scrollStep = (distance: number) => Math.ceil(MAX_SCROLL * Math.min(1, distance / EDGE));
+  const scrollTick = () => {
+    for (const scroller of scrollers) {
+      const el = scroller.el;
+      const box = el ? el.getBoundingClientRect() : { top: 0, left: 0, bottom: innerHeight, right: innerWidth };
+      const top = el ? el.scrollTop : scrollY;
+      const left = el ? el.scrollLeft : scrollX;
+      const height = el ? el.clientHeight : innerHeight;
+      const width = el ? el.clientWidth : innerWidth;
+      const fullHeight = el ? el.scrollHeight : document.documentElement.scrollHeight;
+      const fullWidth = el ? el.scrollWidth : document.documentElement.scrollWidth;
+      let dy = 0;
+      let dx = 0;
+      if (scroller.y) {
+        if (pointer.y < box.top + EDGE && top > 0) dy = -scrollStep(box.top + EDGE - pointer.y);
+        else if (pointer.y > box.bottom - EDGE && top + height < fullHeight - 1) dy = scrollStep(pointer.y - (box.bottom - EDGE));
+      }
+      if (scroller.x) {
+        if (pointer.x < box.left + EDGE && left > 0) dx = -scrollStep(box.left + EDGE - pointer.x);
+        else if (pointer.x > box.right - EDGE && left + width < fullWidth - 1) dx = scrollStep(pointer.x - (box.right - EDGE));
+      }
+      if (dx || dy) {
+        if (el) el.scrollBy(dx, dy);
+        else window.scrollBy(dx, dy);
+        measure();
+        place();
+        return;
+      }
+    }
+  };
+  const startScroll = () => {
+    scrollers = [];
+    for (let el: HTMLElement | null = root; el && el !== document.body && el !== document.documentElement; el = el.parentElement) {
+      const style = getComputedStyle(el);
+      const y = /(auto|scroll)/.test(style.overflowY) && el.scrollHeight > el.clientHeight + 1;
+      const x = /(auto|scroll)/.test(style.overflowX) && el.scrollWidth > el.clientWidth + 1;
+      if (x || y) scrollers.push({ el, x, y });
+    }
+    const page = document.documentElement;
+    scrollers.push({ el: null, y: page.scrollHeight > innerHeight + 1, x: page.scrollWidth > innerWidth + 1 });
+    gsap.ticker.add(scrollTick);
+  };
+
+  const start = () => {
+    if (!press) return;
+    const { item, group, startX, startY, grabX, grabY, width, height } = press;
+    dragging = true;
+    floating = { x: startX - grabX, y: startY - grabY, width, tilt: 0, lift: reduced() ? 1 : 0, fade: 0 };
+    layers = [makeLayer(item, group, grabX, grabY)];
+    draggedEls = new Set([item]);
+    item.setAttribute('data-mk-dragging', '');
+    root.setAttribute('data-mk-sorting', '');
+    if (!reduced()) lifting = gsap.to(floating, { lift: 1, duration: TIMING.sortable.lift, ease: 'power2.out', onUpdate: render });
+    const halfW = width / 2 || 1;
+    const halfH = height / 2 || 1;
+    physics = {
+      vx: 0,
+      vy: 0,
+      tiltV: 0,
+      fvx: 0,
+      fvy: 0,
+      armX: (halfW - grabX) / halfW,
+      armY: Math.max((halfH - grabY) / halfH, TILT.hang),
+      mass: Math.min(2.5, Math.max(1, Math.sqrt((width * height) / TILT.refArea))),
+      x: pointer.x,
+      y: pointer.y,
+      t: performance.now(),
+    };
+    gsap.ticker.add(tick);
+    measure();
+    if (autoScroll) startScroll();
+    placement = { group, index: press.index };
+    render();
+  };
+
+  const finish = () => {
+    landing = null;
+    lifting?.kill();
+    lifting = null;
+    for (const layer of layers) layer.el.remove();
+    layers = [];
+    for (const el of draggedEls) el.removeAttribute('data-mk-dragging');
+    draggedEls.clear();
+    root.removeAttribute('data-mk-sorting');
+    dragging = false;
+    untouch();
+  };
+
+  const land = (target: HTMLElement | null) => {
+    lifting?.kill();
+    lifting = null;
+    const item = target && target.isConnected ? target : null;
+    if (!item || reduced()) {
+      finish();
+      return;
+    }
+    if (!draggedEls.has(item)) {
+      item.setAttribute('data-mk-dragging', '');
+      draggedEls.add(item);
+    }
+    const box = item.getBoundingClientRect();
+    // Arriving somewhere else: cross-fade to a copy styled by the new place (Stepbro's "floatingTo").
+    if (layers.length === 1 && ownerOf(item) !== layers[0]!.el.parentElement) {
+      const origin = layers[0]!.el.style.transformOrigin.split(' ').map(parseFloat);
+      layers.push(makeLayer(item, ownerOf(item), origin[0] ?? 0, origin[1] ?? 0));
+      render();
+    }
+    landing = gsap.timeline({ onComplete: finish });
+    landing.to(
+      floating,
+      {
+        x: box.left - transformX(item),
+        y: box.top - transformY(item),
+        width: box.width,
+        tilt: 0,
+        lift: 0,
+        duration: TIMING.sortable.land,
+        ease: EASE.sortableLand,
+        onUpdate: render,
+      },
+      0,
+    );
+    landing.to(floating, { fade: 1, duration: TIMING.sortable.landFade, ease: 'power1.inOut', onUpdate: render }, 0);
+  };
+
+  const stopTracking = () => {
+    window.removeEventListener('pointermove', onMove);
+    window.removeEventListener('pointerup', onUp);
+    window.removeEventListener('pointercancel', onCancel);
+    window.removeEventListener('keydown', onEscape);
+    gsap.ticker.remove(tick);
+    gsap.ticker.remove(scrollTick);
+    physics = null;
+    scrollers = [];
+  };
+
+  const swallowClick = () => {
+    const swallow = (event: Event) => {
+      event.preventDefault();
+      event.stopPropagation();
+    };
+    window.addEventListener('click', swallow, { capture: true, once: true });
+    setTimeout(() => window.removeEventListener('click', swallow, { capture: true }), 0);
+  };
+
+  const drop = async () => {
+    const current = press;
+    const target = placement;
+    const started = dragging;
+    stopTracking();
+    press = null;
+    placement = null;
+    layout = null;
+    if (!current || !started) return;
+    swallowClick();
+    const { item } = current;
+    const origin = { group: current.group, index: current.index };
+    if (!target || (target.group === origin.group && target.index === origin.index)) {
+      unshift(true);
+      land(item);
+      return;
+    }
+    const detail = makeDetail(item, origin, target);
+    if (!root.dispatchEvent(new CustomEvent<ReorderDetail>('mk:reorder', { bubbles: true, cancelable: true, detail }))) {
+      unshift(true);
+      land(item);
+      return;
+    }
+    if (mutate) {
+      moveDom(item, target.group, target.index);
+      unshift(false);
+      options.onReorder?.(detail);
+      land(item);
+      return;
+    }
+    const changed = domChange();
+    options.onReorder?.(detail);
+    const answered = await changed;
+    if (scope.disposed) return;
+    if (!answered) {
+      // The app kept the order: everything flies back.
+      unshift(true);
+      land(item.isConnected ? item : findItem(detail.id));
+      return;
+    }
+    unshift(false);
+    land(findItem(detail.id) ?? item);
+  };
+
+  const cancel = () => {
+    const current = press;
+    const started = dragging;
+    stopTracking();
+    press = null;
+    placement = null;
+    layout = null;
+    if (!current || !started) return;
+    unshift(true);
+    land(current.item);
+  };
+
+  function onMove(event: PointerEvent) {
+    if (!press) return;
+    pointer.x = event.clientX;
+    pointer.y = event.clientY;
+    if (!dragging) {
+      const dx = event.clientX - press.startX;
+      const dy = event.clientY - press.startY;
+      if (dx * dx + dy * dy < THRESHOLD * THRESHOLD) return;
+      start();
+    }
+    event.preventDefault();
+    place();
+  }
+  function onUp() {
+    void drop();
+  }
+  function onCancel() {
+    cancel();
+  }
+  function onEscape(event: KeyboardEvent) {
+    if (event.key === 'Escape') cancel();
+  }
+
+  scope.on(root, 'pointerdown', (event) => {
+    const down = event as PointerEvent;
+    const target = down.target as Element | null;
+    if (down.button > 0 || press || keyboard || !target) return;
+    const item = target.closest<HTMLElement>(ITEM);
+    if (!item || !root.contains(item)) return;
+    const onHandle = Boolean(target.closest(HANDLE));
+    const coarse = window.matchMedia?.('(pointer: coarse)').matches === true;
+    if ((options.handle || coarse) && !onHandle) return;
+    const control = target.closest(INTERACTIVE);
+    if (!onHandle && control && control !== item && item.contains(control)) return;
+    landing?.progress(1);
+    const group = ownerOf(item);
+    const box = item.getBoundingClientRect();
+    press = {
+      item,
+      group,
+      index: itemsOf(group).indexOf(item),
+      startX: down.clientX,
+      startY: down.clientY,
+      grabX: down.clientX - box.left,
+      grabY: down.clientY - box.top,
+      width: box.width,
+      height: box.height,
+    };
+    pointer.x = down.clientX;
+    pointer.y = down.clientY;
+    down.preventDefault();
+    window.addEventListener('pointermove', onMove, { passive: false });
+    window.addEventListener('pointerup', onUp);
+    window.addEventListener('pointercancel', onCancel);
+    window.addEventListener('keydown', onEscape);
+  });
+  // Links and images inside items must not start the browser's own drag.
+  scope.on(root, 'dragstart', (event) => {
+    if ((event.target as Element | null)?.closest?.(ITEM)) event.preventDefault();
+  });
+
+  // ── Keyboard ──────────────────────────────────────────────────────────────
+  let keyboard: { item: HTMLElement; startGroup: HTMLElement; startIndex: number } | null = null;
+  let moving = false;
+  let flipping: gsap.core.Timeline | null = null;
+
+  const positionOf = (item: HTMLElement) => {
+    const list = itemsOf(ownerOf(item));
+    return { position: list.indexOf(item) + 1, total: list.length };
+  };
+  const groupName = (group: HTMLElement) => group.getAttribute('aria-label') ?? (groups().length > 1 ? keyOf(group) : '');
+
+  /** Move an item by keyboard: reorder now (DOM or app) and let the list reflow. */
+  const commit = async (item: HTMLElement, group: HTMLElement, index: number) => {
+    const from = { group: ownerOf(item), index: itemsOf(ownerOf(item)).indexOf(item) };
+    if (from.group === group && from.index === index) return item;
+    const detail = makeDetail(item, from, { group, index });
+    if (!root.dispatchEvent(new CustomEvent<ReorderDetail>('mk:reorder', { bubbles: true, cancelable: true, detail }))) return item;
+    moving = true;
+    // Taken first: measuring can move the focus away (moving a node blurs it).
+    const focused = item.contains(document.activeElement) ? (document.activeElement as HTMLElement) : item;
+    const captured = captureLayout(root, ITEM);
+    let current: HTMLElement = item;
+    if (mutate) {
+      moveDom(item, group, index);
+      options.onReorder?.(detail);
+    } else {
+      const changed = domChange();
+      options.onReorder?.(detail);
+      await changed;
+      current = findItem(detail.id) ?? item;
+    }
+    const target = current === item ? focused : current;
+    if (target.isConnected && document.activeElement !== target) target.focus({ preventScroll: true });
+    moving = false;
+    if (scope.disposed) return current;
+    // Flip tags elements with auto ids; take them off once the reflow is over.
+    const untag = () => {
+      for (const el of root.querySelectorAll<HTMLElement>('[data-flip-id^="auto-"]')) {
+        el.removeAttribute('data-flip-id');
+        touched.add(el);
+      }
+      untouch();
+    };
+    flipping?.progress(1);
+    flipping = reflowLayout(root, ITEM, captured);
+    if (flipping) flipping.eventCallback('onComplete', untag);
+    else untag();
+    return current;
+  };
+
+  const release = (announcement?: string) => {
+    if (!keyboard) return;
+    keyboard.item.removeAttribute('data-mk-sort-grabbed');
+    keyboard = null;
+    if (announcement) announce(announcement);
+  };
+
+  scope.on(root, 'keydown', (event) => {
+    const key = event as KeyboardEvent;
+    const target = key.target as HTMLElement | null;
+    const item = target?.closest<HTMLElement>(ITEM);
+    if (!item || !root.contains(item) || dragging) return;
+    const handle = target!.closest(HANDLE);
+    if (target !== item && !(handle && item.contains(handle))) return;
+    const lift = key.key === ' ' || key.key === 'Enter';
+    if (keyboard && keyboard.item !== item) release();
+    if (!keyboard) {
+      if (!lift) return;
+      key.preventDefault();
+      keyboard = { item, startGroup: ownerOf(item), startIndex: itemsOf(ownerOf(item)).indexOf(item) };
+      item.setAttribute('data-mk-sort-grabbed', '');
+      const { position, total } = positionOf(item);
+      announce(labels.lifted(position, total));
+      return;
+    }
+    const grabbed = keyboard;
+    const group = ownerOf(item);
+    const list = itemsOf(group);
+    const index = list.indexOf(item);
+    let to: { group: HTMLElement; index: number } | null = null;
+    if (key.key === 'ArrowUp' || key.key === 'ArrowDown') {
+      const next = Math.min(list.length - 1, Math.max(0, index + (key.key === 'ArrowUp' ? -1 : 1)));
+      to = { group, index: next };
+    } else if (key.key === 'ArrowLeft' || key.key === 'ArrowRight') {
+      const open = groups().filter((candidate) => candidate === group || !isLocked(candidate));
+      const next = open[open.indexOf(group) + (key.key === 'ArrowLeft' ? -1 : 1)];
+      if (next) to = { group: next, index: Math.min(index, itemsOf(next).length) };
+    } else if (lift) {
+      key.preventDefault();
+      const { position, total } = positionOf(item);
+      release(labels.dropped(position, total));
+      return;
+    } else if (key.key === 'Escape') {
+      key.preventDefault();
+      void commit(item, grabbed.startGroup, grabbed.startIndex).then(() => release(labels.cancelled));
+      return;
+    } else return;
+    key.preventDefault();
+    if (!to) return;
+    void commit(item, to.group, to.index).then((moved) => {
+      if (!keyboard) return;
+      if (moved !== keyboard.item) {
+        keyboard.item.removeAttribute('data-mk-sort-grabbed');
+        keyboard.item = moved;
+        moved.setAttribute('data-mk-sort-grabbed', '');
+      }
+      const { position, total } = positionOf(moved);
+      announce(labels.moved(position, total, groupName(ownerOf(moved))));
+    });
+  });
+  // Space on a button handle would click it on keyup.
+  scope.on(root, 'keyup', (event) => {
+    if ((event as KeyboardEvent).key === ' ' && (event.target as Element | null)?.closest(HANDLE)) event.preventDefault();
+  });
+  scope.on(root, 'focusout', (event) => {
+    if (!keyboard || moving) return;
+    const next = (event as FocusEvent).relatedTarget as Node | null;
+    if (next && keyboard.item.contains(next)) return;
+    release();
+  });
+
+  // Items must take focus for the keyboard: those without a handle get tabindex 0.
+  const focusable = (item: HTMLElement) => {
+    if (item.querySelector(HANDLE) || item.hasAttribute('tabindex') || item.matches(INTERACTIVE)) return;
+    scope.attr(item, 'tabindex', '0');
+  };
+  for (const item of root.querySelectorAll<HTMLElement>(ITEM)) focusable(item);
+  scope
+    .observe(
+      new MutationObserver(() => {
+        for (const item of root.querySelectorAll<HTMLElement>(`${ITEM}:not([tabindex])`)) focusable(item);
+      }),
+    )
+    .observe(root, { childList: true, subtree: true });
+
+  root.dataset.mkReady = '';
+
+  return {
+    cancel,
+    get dragging() {
+      return dragging;
+    },
+    destroy() {
+      stopTracking();
+      press = null;
+      landing?.kill();
+      flipping?.progress(1);
+      unshift(false);
+      finish();
+      release();
+      scope.dispose();
+      delete root.dataset.mkReady;
+    },
+  };
+}
+
+/** Move one entry of an array (for onReorder in a single list): moveItem(list, fromIndex, toIndex). */
+export function moveItem<T>(list: readonly T[], from: number, to: number): T[] {
+  const next = list.slice();
+  const [entry] = next.splice(from, 1);
+  if (entry !== undefined) next.splice(Math.min(Math.max(to, 0), next.length), 0, entry);
+  return next;
+}