@yewdiel21/motion-kit 0.0.0-stage → 0.9.0

package/src/recipes/slot-text/README.md

@@ -0,0 +1,44 @@
+# slot-text
+
+Cuando el texto cambia, cada letra distinta sale rodando y entra la nueva (300 ms, curva con rebote `cubic-bezier(.34,1.56,.64,1)`), con una inclinación determinista de hasta 5° y 45 ms entre letras; el ancho de cada letra se ajusta. Las letras se agrupan por palabra para que el texto parta línea entre palabras.
+
+Origen: Stepbro — SlotText (`slot-text` en el kit), portado desde Kayro.
+
+## Vanilla / Astro
+
+```html
+<h1><span data-mk="slot-text" id="saludo">Hola</span></h1>
+```
+
+```js
+const slot = createSlotText(document.getElementById('saludo'));
+slot.set('Hello');
+```
+
+Los lectores de pantalla leen una copia en texto plano (`.mk-sr-only`); las letras animadas van con `aria-hidden`. Importa la CSS del paquete (o `slot-text.css`).
+
+## React
+
+```tsx
+<SlotText text={idioma === 'es' ? 'Hola' : 'Hello'} />
+```
+
+Con el hook, el elemento no debe tener hijos propios: `useSlotText(ref, texto)` sobre `<span ref={ref} />`.
+
+## Opciones
+
+| Opción | Por defecto | Qué hace |
+|---|---|---|
+| `direction` | `'down'` | Hacia dónde ruedan las letras |
+| `duration` | `300` | ms por letra |
+| `stagger` | `45` | ms entre letras |
+| `exitOffset` | `50` | ms entre la salida de la letra vieja y la entrada de la nueva |
+| `colorFade` | `280` | ms del fundido de cada letra |
+| `maxTilt` | `5` | Inclinación máxima, grados |
+| `text` | texto del elemento | Texto inicial (para frameworks) |
+
+## Controles
+
+`set(texto)`, `text`, `destroy()` (deja el texto actual como texto plano)
+
+Con movimiento reducido escribe el texto nuevo sin animar.

package/src/recipes/slot-text/create-slot-text.ts

@@ -0,0 +1,244 @@
+import { reduced } from '../../core/reduced';
+import { inert, warnOnce, type Instance } from '../../core/types';
+import { TIMING } from '../../core/timing';
+import { splitGraphemes } from '../../core/split';
+
+/*
+ * Stepbro's SlotText (ported from Kayro): when the text changes, each letter
+ * that differs rolls out and the new one rolls in (300 ms, a springy curve),
+ * with a slight deterministic tilt (≤ 5°) and a 45 ms cascade; letter boxes ease
+ * to their new width. Letters are grouped by word so lines only break between
+ * words. Screen readers get a plain copy; the rolling letters are aria-hidden.
+ */
+
+export interface SlotTextOptions {
+  direction?: 'down' | 'up';
+  /** ms per letter */
+  duration?: number;
+  /** ms between letters */
+  stagger?: number;
+  /** ms between the old letter leaving and the new one entering */
+  exitOffset?: number;
+  /** ms the letters take to fade */
+  colorFade?: number;
+  maxTilt?: number;
+  /** Initial text. Default: the element's text. Pass it when a framework owns the element (it must render no children). */
+  text?: string;
+  /** Add a visually hidden plain copy for screen readers (default). Turn off when you render your own. */
+  accessibleCopy?: boolean;
+}
+
+export interface SlotTextInstance extends Instance {
+  set(text: string): void;
+  readonly text: string;
+}
+
+const EASING = 'cubic-bezier(0.34, 1.56, 0.64, 1)';
+const RESIZE_EASING = 'cubic-bezier(0.2, 0, 0, 1)';
+const BOUNCE = 0.6;
+const VARIATION = { index: 12.9898, channel: 78.233, seed: 43758.5453, duration: 1, stagger: 2, tilt: 3 };
+const GLYPH = { tailDuration: 0.75, durationStrength: 0.45, tailStaggerStart: 0.5, tailStaggerStep: 0.25, staggerStrength: 0.25 };
+const WIDTH = { tailCollapseDelay: 0.55, tailCollapseDuration: 0.6, newSlotExpansion: 0.45, minimumChange: 0.5 };
+const COMPLETION_BUFFER = 80;
+const NBSP = ' ';
+
+const glyph = (letter: string) => (letter === ' ' ? NBSP : letter);
+const letters = (text: string) => splitGraphemes(text, Number.MAX_SAFE_INTEGER);
+
+/** A stable pseudo-random value in [-1, 1] for a letter and a channel. */
+const noise = (index: number, channel: number) => {
+  const value = Math.sin((index + 1) * VARIATION.index + channel * VARIATION.channel) * VARIATION.seed;
+  return (value - Math.floor(value)) * 2 - 1;
+};
+
+const face = (letter: string) => {
+  const element = document.createElement('span');
+  element.className = 'mk-slot__face';
+  element.textContent = glyph(letter);
+  return element;
+};
+
+const slot = (letter: string) => {
+  const element = document.createElement('span');
+  element.className = 'mk-slot__char';
+  element.dataset.char = letter;
+  const sizer = document.createElement('span');
+  sizer.className = 'mk-slot__sizer';
+  sizer.textContent = glyph(letter);
+  element.append(sizer, face(letter));
+  return element;
+};
+
+/** Letters grouped by word; a space is the last slot of the word before it. */
+function build(target: HTMLElement, text: string) {
+  const nodes: HTMLElement[] = [];
+  let word: HTMLElement | null = null;
+  for (const letter of letters(text)) {
+    if (letter === ' ') {
+      if (word) word.append(slot(letter));
+      else nodes.push(slot(letter));
+      word = null;
+      continue;
+    }
+    if (!word) {
+      word = document.createElement('span');
+      word.className = 'mk-slot__word';
+      nodes.push(word);
+    }
+    word.append(slot(letter));
+  }
+  target.replaceChildren(...nodes);
+}
+
+export function createSlotText(el: HTMLElement | null, options: SlotTextOptions = {}): SlotTextInstance {
+  if (!el) {
+    warnOnce('slot-text: missing element');
+    return inert({ set() {}, text: '' });
+  }
+  const {
+    direction = 'down',
+    duration: baseDuration = TIMING.slot.durationMs,
+    stagger = TIMING.slot.staggerMs,
+    exitOffset = TIMING.slot.exitOffsetMs,
+    colorFade = TIMING.slot.colorFadeMs,
+    maxTilt = TIMING.slot.maxTilt,
+  } = options;
+  const original = [...el.childNodes];
+  const originalText = el.textContent ?? '';
+  let text = options.text ?? originalText;
+  let timers: number[] = [];
+  let destroyed = false;
+
+  const copy = document.createElement('span');
+  copy.className = 'mk-sr-only';
+  copy.textContent = text;
+  const track = document.createElement('span');
+  track.className = 'mk-slot';
+  track.setAttribute('aria-hidden', 'true');
+  build(track, text);
+  if (options.accessibleCopy === false) {
+    track.removeAttribute('aria-hidden');
+    el.replaceChildren(track);
+  } else el.replaceChildren(copy, track);
+  el.dataset.mkReady = '';
+
+  const stop = () => {
+    for (const timer of timers) clearTimeout(timer);
+    timers = [];
+  };
+
+  const roll = (next: string) => {
+    const interrupted = timers.length > 0;
+    stop();
+    if (interrupted) build(track, text);
+    let slots = [...track.querySelectorAll<HTMLElement>('.mk-slot__char')];
+    if (!slots.length || reduced()) {
+      build(track, next);
+      return;
+    }
+    const current = slots.map((entry) => entry.dataset.char ?? '');
+    const target = letters(next);
+    for (let index = slots.length; index < Math.max(current.length, target.length); index += 1) {
+      const extra = slot('');
+      track.append(extra);
+      slots = [...slots, extra];
+    }
+    const firstFilled = slots.find((entry) => (entry.dataset.char ?? '') !== '') ?? slots[0];
+    const height = Math.ceil(firstFilled?.getBoundingClientRect().height ?? 0) || 18;
+    const changes = slots
+      .map((entry, index) => ({
+        index,
+        slot: entry,
+        sizer: entry.querySelector<HTMLElement>('.mk-slot__sizer'),
+        previous: entry.querySelector<HTMLElement>('.mk-slot__face'),
+        from: current[index] ?? '',
+        to: target[index] ?? '',
+        width: entry.getBoundingClientRect().width,
+      }))
+      .filter(({ from, to }) => from !== to);
+    if (!changes.length) {
+      build(track, next);
+      return;
+    }
+    for (const change of changes) if (change.sizer) change.sizer.textContent = glyph(change.to);
+    const measured = changes.map((change) => {
+      const width = change.sizer?.getBoundingClientRect().width ?? change.width;
+      return { ...change, targetWidth: width, resize: Math.abs(width - change.width) > WIDTH.minimumChange };
+    });
+
+    const later = (run: () => void, ms: number) => timers.push(window.setTimeout(run, ms));
+    const enterFrom = direction === 'down' ? -height : height;
+    const exitTo = -enterFrom;
+    let completion = 0;
+    const planned = measured.map((change) => {
+      const tail = change.to === '';
+      const vary = (strength: number, channel: number) => 1 + BOUNCE * strength * noise(change.index, channel);
+      const duration = Math.round(baseDuration * (tail ? GLYPH.tailDuration : 1) * vary(GLYPH.durationStrength, VARIATION.duration));
+      const order = tail ? target.length * GLYPH.tailStaggerStart + (change.index - target.length) * GLYPH.tailStaggerStep : change.index;
+      const delay = Math.round(order * stagger * vary(GLYPH.staggerStrength, VARIATION.stagger));
+      const tilt = Number((BOUNCE * maxTilt * noise(change.index, VARIATION.tilt)).toFixed(2));
+      const minimum = (factor: number) => Math.max(TIMING.slot.minResizeMs, Math.round(duration * factor));
+      const widthTiming =
+        change.to === ''
+          ? { delay: delay + Math.round(duration * WIDTH.tailCollapseDelay), duration: minimum(WIDTH.tailCollapseDuration) }
+          : change.from === ''
+            ? { delay, duration: minimum(WIDTH.newSlotExpansion) }
+            : { delay, duration };
+      if (change.resize) change.slot.style.width = `${change.width}px`;
+      if (change.from === '' || change.to === '') change.slot.classList.add('is-resizing');
+      const incoming = face(change.to);
+      incoming.style.transform = `translateY(${enterFrom}px) rotate(${tilt}deg)`;
+      incoming.style.opacity = '0';
+      change.slot.append(incoming);
+      completion = Math.max(completion, change.resize ? widthTiming.delay + widthTiming.duration : 0, delay + exitOffset + duration);
+      return { change, duration, delay, tilt, widthTiming, incoming };
+    });
+    void track.offsetWidth;
+    for (const { change, duration, delay, tilt, widthTiming, incoming } of planned) {
+      const transition = `transform ${duration}ms ${EASING}, opacity ${colorFade}ms linear`;
+      if (change.resize) {
+        later(() => {
+          change.slot.style.transition = `width ${widthTiming.duration}ms ${RESIZE_EASING}`;
+          change.slot.style.width = `${change.targetWidth}px`;
+        }, widthTiming.delay);
+      }
+      if (change.previous) {
+        const previous = change.previous;
+        later(() => {
+          previous.style.transition = transition;
+          previous.style.transform = `translateY(${exitTo}px) rotate(${-tilt}deg)`;
+          previous.style.opacity = '0';
+        }, delay);
+      }
+      later(() => {
+        incoming.style.transition = transition;
+        incoming.style.transform = 'translateY(0) rotate(0deg)';
+        incoming.style.opacity = '1';
+      }, delay + exitOffset);
+    }
+    later(() => {
+      timers = [];
+      build(track, next);
+    }, completion + COMPLETION_BUFFER);
+  };
+
+  return {
+    set(next: string) {
+      if (destroyed || next === text) return;
+      roll(next);
+      text = next;
+      copy.textContent = next;
+    },
+    get text() {
+      return text;
+    },
+    destroy() {
+      if (destroyed) return;
+      destroyed = true;
+      stop();
+      if (text === originalText) el.replaceChildren(...original);
+      else el.textContent = text;
+      delete el.dataset.mkReady;
+    },
+  };
+}

package/src/recipes/slot-text/slot-text.css

@@ -0,0 +1,42 @@
+/* slot-text: each letter sits in a slot whose face rolls out and in; the hidden sizer gives the slot its width. */
+.mk-slot {
+  display: inline;
+}
+
+.mk-slot__word {
+  display: inline-flex;
+  align-items: baseline;
+  white-space: pre;
+}
+
+.mk-slot__char {
+  position: relative;
+  display: inline-flex;
+  flex: none;
+  justify-content: center;
+  align-items: baseline;
+  overflow-x: visible;
+  overflow-y: clip;
+  /* Descenders stay inside the clip. */
+  overflow-clip-margin: 0.15em;
+  line-height: inherit;
+}
+
+.mk-slot__char.is-resizing {
+  overflow-x: clip;
+}
+
+.mk-slot__sizer {
+  visibility: hidden;
+  white-space: pre;
+}
+
+.mk-slot__face {
+  position: absolute;
+  inset: 0;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  white-space: pre;
+  will-change: transform;
+}

package/src/recipes/snap-strip/README.md

@@ -0,0 +1,31 @@
+# snap-strip
+
+Una tira horizontal de tarjetas con scroll-snap nativo que pasa a la siguiente cada 5 s mientras se ve (empieza medio segundo después de aparecer), espera 2 s después de un toque, arrastre o rueda antes de seguir y vuelve de la última a la primera.
+
+Origen: iyo.ai, tarjetas de producto en móvil (`product-card-mobile`, `CM`): cadencia 5000 ms, espera 2000 ms, `data-delay="500"`, tarjetas de 68vw. iyo usa el slider físico Smooothy con bucle clonado; aquí desliza el navegador con su propio snap.
+
+## HTML / Astro
+
+```html
+<div data-mk="snap-strip" data-mk-delay="500" class="mk-snap-strip" aria-label="Productos">
+  <article class="card">…</article>
+  <article class="card">…</article>
+  <article class="card">…</article>
+</div>
+```
+
+## React
+
+```tsx
+const ref = useRef<HTMLDivElement>(null);
+const strip = useSnapStrip(ref, { interval: 5000 });
+<button onClick={() => strip.current?.next()}>Siguiente</button>;
+```
+
+## API
+
+`createSnapStrip(root, { autoplay, interval, resume, delay })` → `{ next(), previous(), index, destroy }`. Variables: `--mk-snap-strip-item` (68vw), `--mk-snap-strip-gap`.
+
+## Accesibilidad
+
+Se para fuera de pantalla, con la pestaña oculta y mientras se toca. Con movimiento reducido no avanza sola y `next()` / `previous()` saltan sin animación. Si lo usas con autoplay en contenido importante, añade botones de anterior / siguiente.

package/src/recipes/snap-strip/create-snap-strip.ts

@@ -0,0 +1,133 @@
+import { reduced } from '../../core/reduced';
+import { createScope } from '../../core/scope';
+import { TIMING } from '../../core/timing';
+import { inert, warnOnce, type Instance } from '../../core/types';
+
+/*
+ * iyo.ai's phone cards: a native scroll-snap strip that moves on by one card
+ * every 5 s while it is on screen (starting `delay` ms after it shows), waits
+ * 2 s after a touch, drag or wheel before carrying on, and wraps from the last
+ * card to the first. iyo drives it with Smooothy; this keeps the browser's own
+ * scrolling and snapping instead of a physics slider.
+ */
+
+export interface SnapStripOptions {
+  autoplay?: boolean;
+  /** Milliseconds between cards (iyo: 5000). */
+  interval?: number;
+  /** Milliseconds to wait after the reader touches it (iyo: 2000). */
+  resume?: number;
+  /** Milliseconds after it shows before autoplay starts (iyo's data-delay: 500). */
+  delay?: number;
+}
+
+export interface SnapStripInstance extends Instance {
+  next(): void;
+  previous(): void;
+  /** Index of the card nearest the start edge. */
+  readonly index: number;
+}
+
+export function createSnapStrip(root: HTMLElement | null, options: SnapStripOptions = {}): SnapStripInstance {
+  if (!root || root.children.length < 2) {
+    warnOnce('snap-strip: needs a strip with at least two cards');
+    return inert({ next() {}, previous() {}, index: 0 });
+  }
+  const t = TIMING.snapStrip;
+  const { autoplay = true, interval = t.interval, resume = t.resume, delay = t.delay } = options;
+  const scope = createScope();
+  const items = () => [...root.children] as HTMLElement[];
+  const startScroll = root.scrollLeft;
+  let timer: ReturnType<typeof setInterval> | undefined;
+  let waiting: ReturnType<typeof setTimeout> | undefined;
+  let visible = typeof IntersectionObserver !== 'function';
+  let touching = false;
+
+  const offsetOf = (item: HTMLElement) => item.getBoundingClientRect().left - root.getBoundingClientRect().left;
+  const nearest = () => {
+    let best = 0;
+    items().forEach((item, i, all) => {
+      if (Math.abs(offsetOf(item)) < Math.abs(offsetOf(all[best]!))) best = i;
+    });
+    return best;
+  };
+  const move = (step: number) => {
+    if (scope.disposed) return;
+    const all = items();
+    const target = all[(nearest() + step + all.length) % all.length]!;
+    root.scrollTo({ left: offsetOf(target) + root.scrollLeft, behavior: reduced() ? 'instant' : 'smooth' });
+  };
+
+  const stop = () => {
+    clearInterval(timer);
+    timer = undefined;
+  };
+  const start = () => {
+    if (scope.disposed || !autoplay || reduced() || !visible || touching || document.hidden || timer) return;
+    timer = setInterval(() => move(1), interval);
+  };
+  const later = (fn: () => void, ms: number) => {
+    clearTimeout(waiting);
+    waiting = setTimeout(fn, ms);
+  };
+  scope.add(() => {
+    stop();
+    clearTimeout(waiting);
+  });
+
+  const hold = () => {
+    touching = true;
+    stop();
+  };
+  const release = () => {
+    if (!touching) return;
+    later(() => {
+      touching = false;
+      start();
+    }, resume);
+  };
+  scope.on(root, 'pointerdown', hold, { passive: true });
+  scope.on(root, 'touchstart', hold, { passive: true });
+  scope.on(window, 'pointerup', release, { passive: true });
+  scope.on(window, 'pointercancel', release, { passive: true });
+  scope.on(window, 'touchend', release, { passive: true });
+  scope.on(
+    root,
+    'wheel',
+    () => {
+      hold();
+      release();
+    },
+    { passive: true },
+  );
+  scope.on(document, 'visibilitychange', () => {
+    stop();
+    start();
+  });
+
+  if (typeof IntersectionObserver === 'function') {
+    const observer = scope.observe(
+      new IntersectionObserver(([entry]) => {
+        visible = Boolean(entry?.isIntersecting);
+        stop();
+        if (visible) later(start, delay);
+        else clearTimeout(waiting);
+      }),
+    );
+    observer.observe(root);
+  } else later(start, delay);
+
+  scope.add(() => {
+    root.scrollLeft = startScroll;
+  });
+  scope.attr(root, 'data-mk-ready', '');
+
+  return {
+    next: () => move(1),
+    previous: () => move(-1),
+    get index() {
+      return nearest();
+    },
+    destroy: () => scope.dispose(),
+  };
+}

package/src/recipes/snap-strip/snap-strip.css

@@ -0,0 +1,23 @@
+/* iyo.ai's phone cards: a strip of cards that snaps to each one. */
+.mk-snap-strip {
+  --mk-snap-strip-item: 68vw;
+  --mk-snap-strip-gap: 0.75rem;
+  display: flex;
+  gap: var(--mk-snap-strip-gap);
+  overflow-x: auto;
+  overscroll-behavior-inline: contain;
+  scroll-snap-type: x mandatory;
+  scrollbar-width: none;
+}
+.mk-snap-strip::-webkit-scrollbar {
+  display: none;
+}
+.mk-snap-strip > * {
+  flex: 0 0 var(--mk-snap-strip-item);
+  scroll-snap-align: start;
+}
+@media (prefers-reduced-motion: reduce) {
+  .mk-snap-strip {
+    scroll-behavior: auto;
+  }
+}

package/src/recipes/sortable/README.md

@@ -0,0 +1,88 @@
+# sortable
+
+El arrastre para reordenar de Stepbro Tasks (`useDragReorder`, modo "transform"):
+
+- **Levantar:** pasados 6 px el elemento se convierte en una copia flotante (0.18 s, `power2.out`) que crece un 3 % y gana sombra. El hueco que deja queda invisible.
+- **Seguir:** la copia sigue al puntero con un resorte (rigidez 1100, amortiguación 38; más pesada cuanto más grande) y se inclina según la velocidad y la aceleración, como si colgara del punto por donde la agarraste (resorte 170/13, hasta 14°).
+- **Hacer sitio:** los demás no cambian de sitio en el DOM mientras arrastras: se deslizan (0.62 s, resorte .52) para abrir el hueco donde caería.
+- **Soltar:** la copia aterriza en su sitio nuevo (0.42 s, resorte .62) y, si cambia de lista, se funde con una copia con el estilo de la lista nueva (0.28 s).
+- **Bordes:** cerca del borde (56 px) el contenedor que hace scroll se desplaza solo, hasta 16 px por frame.
+- **Cancelar:** Escape (o soltar donde estaba) la devuelve a su sitio.
+
+En pantallas táctiles solo se arrastra desde `[data-mk-sort-handle]`, para que la lista siga haciendo scroll. Teclado (añadido): Espacio o Enter levanta, flechas arriba/abajo mueven, izquierda/derecha cambian de lista, Espacio o Enter suelta, Escape lo devuelve; cada paso se anuncia.
+
+Origen: Stepbro Tasks `useDragReorder` (`stepbro-tasks.js`, líneas 39021–39330).
+
+## HTML / Astro
+
+```html
+<ul data-mk="sortable" class="lista">
+  <li data-mk-item data-mk-id="1">Comprar pan</li>
+  <li data-mk-item data-mk-id="2">Llamar a Ana</li>
+  <li data-mk-item data-mk-id="3">Pagar la luz <button data-mk-sort-handle aria-label="Mover">⋮⋮</button></li>
+</ul>
+
+<script>
+  import { autoInit } from '@yewdiel21/motion-kit/auto';
+  autoInit();
+  document.querySelector('.lista').addEventListener('mk:reorder', (event) => {
+    const { id, toIndex, afterId } = event.detail;
+    guardarOrden(id, afterId); // el DOM ya está reordenado
+  });
+</script>
+```
+
+Varias listas (kanban):
+
+```html
+<div data-mk="sortable" class="tablero">
+  <ul data-mk-sortable-group="pendiente" aria-label="Pendiente">…</ul>
+  <ul data-mk-sortable-group="hecho" aria-label="Hecho">…</ul>
+  <ul data-mk-sortable-group="archivo" data-mk-sortable-locked>…</ul>
+</div>
+```
+
+Con JS: `createSortable(el, opciones)`. Atributos de opciones: `data-mk-handle`, `data-mk-mutate="false"`, `data-mk-auto-scroll="false"`.
+
+## React
+
+```tsx
+const ref = useRef<HTMLUListElement>(null);
+const [tareas, setTareas] = useState(lista);
+useSortable(ref, {
+  onReorder: ({ fromIndex, toIndex }) => setTareas((t) => moveItem(t, fromIndex, toIndex)),
+});
+
+<ul ref={ref}>
+  {tareas.map((t) => (
+    <li key={t.id} data-mk-item data-mk-id={t.id}>{t.titulo}</li>
+  ))}
+</ul>
+```
+
+En React el motor no toca el orden del DOM (`mutate: false`): llama `onReorder`, espera a que React pinte el nuevo orden y aterriza ahí. Si tu estado no cambia (por ejemplo, el servidor lo rechaza), todo vuelve a su sitio.
+
+## API
+
+`createSortable(root, opciones)` → `{ cancel(), dragging, destroy }`.
+
+| Opción | Por defecto | Qué hace |
+|---|---|---|
+| `mutate` | `true` (`false` en `useSortable`) | El motor mueve el elemento en el DOM al soltar |
+| `handle` | `false` | Solo se arrastra desde `[data-mk-sort-handle]` (siempre en táctil) |
+| `autoScroll` | `true` | Desplaza el contenedor cerca de los bordes |
+| `follow` | `{ stiffness: 1100, damping: 38 }` | Resorte de la copia flotante |
+| `labels` | español | `lifted`, `moved`, `dropped` (funciones de posición y total), `cancelled` |
+| `onReorder` | — | `(detalle) => void` |
+
+`detalle` (también en el evento `mk:reorder`, cancelable): `id`, `item`, `fromGroup`, `toGroup`, `fromIndex`, `toIndex`, `groupChanged`, `afterId`, `beforeId` (el vecino en el destino, para guardar el orden en un servidor como hace Stepbro). `moveItem(lista, desde, hasta)` mueve una entrada de un array.
+
+Partes: `[data-mk-item]` con `data-mk-id`, `[data-mk-sort-handle]`, `[data-mk-sortable-group]` (opcional; `data-mk-sortable-locked` no acepta elementos). Durante el arrastre: `[data-mk-sorting]` en la raíz, `[data-mk-dragging]` en el hueco, `[data-mk-sortable-clone]` en la copia; levantado con teclado: `[data-mk-sort-grabbed]`.
+
+## Variables CSS
+
+`--mk-sortable-shadow` (sombra de la copia; usa `--mk-lift`, de 0 a 1).
+
+## Accesibilidad
+
+Los elementos sin asa reciben `tabindex="0"` para poder levantarlos con el teclado; los anuncios van a una región `aria-live`. Un clic corto (menos de 6 px) sigue siendo un clic; tras arrastrar, el clic se descarta. Los controles dentro de un elemento (botones, enlaces, campos) no inician el arrastre. Con movimiento reducido la copia sigue al puntero sin resorte ni inclinación y aterriza al instante.