@yewdiel21/motion-kit 0.0.0-stage → 0.9.0

package/src/recipes/sortable/sortable.css

@@ -0,0 +1,40 @@
+/* sortable — Stepbro's drag reorder (Tasks): the item lifts into a floating copy that tilts; the others make room. */
+[data-mk-sorting] {
+  -webkit-user-select: none;
+  user-select: none;
+  cursor: grabbing;
+}
+
+/* The slot the item left (its floating copy is on top). */
+[data-mk-item][data-mk-dragging] {
+  visibility: hidden;
+}
+
+/* The floating copy: its shadow grows with the lift (0 → 1). */
+[data-mk-sortable-clone] {
+  --mk-lift: 0;
+  box-shadow: var(
+    --mk-sortable-shadow,
+    0 calc(12px * var(--mk-lift)) calc(32px * var(--mk-lift)) rgb(0 0 0 / calc(0.22 * var(--mk-lift))),
+    0 0 0 1px var(--md-sys-color-outline-variant) inset
+  );
+  cursor: grabbing;
+}
+
+[data-mk-sort-handle] {
+  cursor: grab;
+  touch-action: none;
+}
+
+[data-mk-sorting] [data-mk-sort-handle] {
+  cursor: grabbing;
+}
+
+/* Lifted with the keyboard. */
+[data-mk-item][data-mk-sort-grabbed] {
+  position: relative;
+  z-index: 1;
+  box-shadow:
+    0 12px 32px rgb(0 0 0 / 0.22),
+    0 0 0 2px var(--mk-accent);
+}

package/src/recipes/spring-cards/README.md

@@ -0,0 +1,48 @@
+# spring-cards
+
+Tarjetas en abanico: entran escalando con rebote, cada una tiene un resorte que arranca desplazado al azar y vuelve a su sitio, y el cursor las empuja al pasar cerca.
+
+Origen: spencergabor.com — portada (Hero.vue, `useSpring`).
+
+## Vanilla / Astro
+
+```html
+<div data-mk="spring-cards" class="cards">
+  <div data-mk-card><div class="mk-card__shadow"></div><img src="a.jpg" alt=""></div>
+  <div data-mk-card><div class="mk-card__shadow"></div><img src="b.jpg" alt=""></div>
+</div>
+```
+
+Con `autoInit()` (de `@yewdiel21/motion-kit/auto`) las opciones van como `data-mk-<opción>` en kebab-case. Sin `autoInit`: `createSpringCards(el, opciones)`.
+
+## React
+
+```tsx
+const ref = useRef<HTMLDivElement>(null);
+useSpringCards(ref);
+return <div ref={ref} data-mk="spring-cards">{/* data-mk-card … */}</div>;
+```
+
+## Opciones
+
+| Opción | Por defecto | Qué hace |
+|---|---|---|
+| `selector` | `'[data-mk-card]'` | Tarjetas dentro del root |
+| `initialOffset` | `100` | Desplazamiento inicial aleatorio, ±px |
+| `releaseAfter` | `100` | ms hasta soltar los resortes |
+| `push` | `.4` | Fuerza del empuje del cursor |
+| `falloff` | `6` | Exponente de caída con la distancia: (1 − d)^falloff |
+| `damping` | `.9` | Amortiguación por frame del empuje |
+| `stiffness / friction` | `.05 / .8` | Resorte |
+| `entrance` | `true` | Entrada escalando |
+| `stagger / delay` | `.08 / .4` | Segundos |
+
+## Controles
+
+`destroy()`
+
+## CSS
+
+Cada hijo de `[data-mk-card]` se traslada con `--mk-x/--mk-y` y rota `--mk-tilt − --mk-velocity·.25deg`. Las inclinaciones por defecto (2°, −3°, 6°, −2°) y el desfase vertical (`--mk-ty`) se cambian con esas variables.
+
+Con `prefers-reduced-motion: reduce` la receta deja el contenido en su estado final, sin animar.

package/src/recipes/spring-cards/create-spring-cards.ts

@@ -0,0 +1,140 @@
+import { gsap, ELASTIC, registerMotion } from '../../core/gsap';
+import { entrances, reduced } from '../../core/reduced';
+import { createSpring, type Spring } from '../../core/spring';
+import { whileVisible } from '../../core/loop';
+import { bindPointer, pointer, takeMovement } from '../../core/pointer';
+import { clamp } from '../../core/math';
+import { createScope } from '../../core/scope';
+import { inert, warnOnce, type Instance } from '../../core/types';
+
+/*
+ * spencergabor.com hero: each card owns a spring that starts at a random offset
+ * and is pulled home shortly after; pointer movement near a card adds velocity
+ * with a (1 − distance)^falloff · push weight. CSS turns the variables into
+ * translate/rotate (see spring-cards.css).
+ */
+
+export interface SpringCardsOptions {
+  /** Cards inside the root. */
+  selector?: string;
+  /** Random start offset range, ±px. */
+  initialOffset?: number;
+  /** Delay before the springs are pulled to rest, ms. */
+  releaseAfter?: number;
+  /** Strength of the pointer push. */
+  push?: number;
+  /** Exponent of the distance falloff. */
+  falloff?: number;
+  /** Per-frame decay of the pushed velocity. */
+  damping?: number;
+  stiffness?: number;
+  friction?: number;
+  /** Scale-in entrance. */
+  entrance?: boolean;
+  stagger?: number;
+  delay?: number;
+}
+
+export type SpringCardsInstance = Instance;
+
+const VARS = ['--mk-x', '--mk-y', '--mk-velocity'] as const;
+
+interface Card {
+  el: HTMLElement;
+  spring: Spring;
+  push: { x: number; y: number };
+  cx: number;
+  cy: number;
+}
+
+const rand = (min: number, max: number) => Math.random() * (max - min) + min;
+
+export function createSpringCards(root: HTMLElement | null, options: SpringCardsOptions = {}): SpringCardsInstance {
+  const o = {
+    selector: '[data-mk-card]',
+    initialOffset: 100,
+    releaseAfter: 100,
+    push: 0.4,
+    falloff: 6,
+    damping: 0.9,
+    stiffness: 0.05,
+    friction: 0.8,
+    entrance: true,
+    stagger: 0.08,
+    delay: 0.4,
+    ...options,
+  };
+  const elements = root ? [...root.querySelectorAll<HTMLElement>(o.selector)] : [];
+  if (!root || !elements.length) {
+    warnOnce(`spring-cards: no "${o.selector}" inside the root`);
+    return inert();
+  }
+
+  registerMotion();
+  const scope = createScope();
+  const ctx = gsap.context(() => {});
+  scope.add(() => ctx.revert());
+
+  if (o.entrance && entrances()) {
+    ctx.add(() => gsap.fromTo(elements, { scale: 0 }, { scale: 1, duration: 1, ease: ELASTIC, stagger: o.stagger, delay: o.delay }));
+  }
+  root.dataset.mkReady = '';
+  scope.add(() => {
+    delete root.dataset.mkReady;
+    elements.forEach((el) => VARS.forEach((name) => el.style.removeProperty(name)));
+  });
+
+  if (reduced()) return { destroy: () => scope.dispose() };
+
+  scope.add(bindPointer());
+  const cards: Card[] = elements.map((el) => {
+    const spring = createSpring(o.stiffness, o.friction);
+    spring.current.x = spring.target.x = rand(-o.initialOffset, o.initialOffset);
+    spring.current.y = spring.target.y = rand(-o.initialOffset, o.initialOffset);
+    return { el, spring, push: { x: 0, y: 0 }, cx: 0, cy: 0 };
+  });
+  scope.timeout(() => cards.forEach(({ spring }) => (spring.target.x = spring.target.y = 0)), o.releaseAfter);
+
+  // Centres in page coordinates; the card element is only scaled, never translated.
+  const measure = () =>
+    cards.forEach((card) => {
+      const rect = card.el.getBoundingClientRect();
+      card.cx = rect.left + scrollX + rect.width / 2;
+      card.cy = rect.top + scrollY + rect.height / 2;
+    });
+  measure();
+  scope.observe(new ResizeObserver(measure)).observe(root);
+
+  scope.add(
+    whileVisible(root, (dt) => {
+      const movement = takeMovement();
+      const mx = clamp(movement.mx, -80, 80);
+      const my = clamp(movement.my, -80, 80);
+      const decay = Math.pow(o.damping, dt);
+
+      for (const card of cards) {
+        const { spring, push } = card;
+        push.x *= decay;
+        push.y *= decay;
+        spring.current.x += push.x * dt;
+        spring.current.y += push.y * dt;
+        spring.update(dt);
+
+        if (pointer.active) {
+          const dx = ((pointer.x + scrollX - card.cx) / innerWidth) * 2;
+          const dy = ((pointer.y + scrollY - card.cy) / innerHeight) * 2;
+          const k = Math.pow(Math.max(0, 1 - Math.hypot(dx, dy)), o.falloff) * o.push;
+          push.x += mx * k;
+          push.y += my * k;
+        }
+
+        const style = card.el.style;
+        style.setProperty('--mk-x', spring.current.x.toFixed(2));
+        style.setProperty('--mk-y', spring.current.y.toFixed(2));
+        style.setProperty('--mk-velocity', (spring.velocity.x - spring.velocity.y).toFixed(3));
+      }
+    }),
+  );
+
+  return { destroy: () => scope.dispose() };
+}

package/src/recipes/spring-cards/spring-cards.css

@@ -0,0 +1,23 @@
+/* spring-cards — card geometry and tilt from spencergabor.com (Hero) */
+
+[data-mk-card] {
+  display: grid;
+  border-radius: var(--mk-radius-card);
+}
+
+/* Every layer of the card (shadow, image) follows the spring */
+[data-mk-card] > * {
+  grid-area: 1 / 1;
+  border-radius: inherit;
+  translate: calc(var(--mk-x, 0) * 1px) calc(var(--mk-y, 0) * 1px + var(--mk-ty, 0%));
+  rotate: calc(var(--mk-tilt, 0deg) - var(--mk-velocity, 0) * 0.25deg);
+}
+
+[data-mk-card]:nth-child(4n + 1) { --mk-tilt: 2deg; --mk-ty: 5%; }
+[data-mk-card]:nth-child(4n + 2) { --mk-tilt: -3deg; --mk-ty: -6%; }
+[data-mk-card]:nth-child(4n + 3) { --mk-tilt: 6deg; --mk-ty: 5%; }
+[data-mk-card]:nth-child(4n + 4) { --mk-tilt: -2deg; --mk-ty: -4%; }
+
+.mk-card__shadow {
+  box-shadow: var(--mk-shadow);
+}

package/src/recipes/stretch-footer/README.md

@@ -0,0 +1,44 @@
+# stretch-footer
+
+Footer fijo detrás de la página que aparece al final del scroll; su título gigante se estira de 0 a 1 en vertical siguiendo el scroll suavizado.
+
+Origen: spencergabor.com — Footer.vue.
+
+## Vanilla / Astro
+
+```html
+<main style="position:relative; z-index:1; background:#fff">…</main>
+<div data-mk-phantom aria-hidden="true"></div>
+<footer data-mk="stretch-footer">
+  <p data-mk-footer-title data-mk="fit-text">Contacto</p>
+  <ul>…enlaces…</ul>
+</footer>
+```
+
+Con `autoInit()` (de `@yewdiel21/motion-kit/auto`) las opciones van como `data-mk-<opción>` en kebab-case. Sin `autoInit`: `createStretchFooter(el, opciones)`.
+
+## React
+
+```tsx
+const footer = useRef<HTMLElement>(null);
+const phantom = useRef<HTMLDivElement>(null);
+useStretchFooter(footer, { phantomRef: phantom });
+```
+
+## Opciones
+
+| Opción | Por defecto | Qué hace |
+|---|---|---|
+| `phantom` | `'[data-mk-phantom]'` | Espaciador al final del flujo (100dvh) |
+| `title` | `'[data-mk-footer-title]'` | Título que se estira |
+| `lambda` | `.9` | Suavizado del scroll |
+
+## Controles
+
+`destroy()`
+
+## CSS
+
+El contenido de la página debe quedar encima: `main { position: relative; z-index: 1; background: … }`.
+
+Con `prefers-reduced-motion: reduce` la receta deja el contenido en su estado final, sin animar.

package/src/recipes/stretch-footer/create-stretch-footer.ts

@@ -0,0 +1,69 @@
+import { registerMotion } from '../../core/gsap';
+import { reduced } from '../../core/reduced';
+import { whileVisible } from '../../core/loop';
+import { damp, mapRange } from '../../core/math';
+import { createScope } from '../../core/scope';
+import { inert, warnOnce, type Instance } from '../../core/types';
+
+/*
+ * spencergabor.com footer: fixed behind the page and revealed by a 100dvh
+ * "phantom" at the end of the flow. Smoothed scroll g = damp(g, scrollY, λ)
+ * drives the title's scaleY (0 → 1) and lifts the footer from "title on the
+ * bottom edge" to its resting place.
+ */
+
+export interface StretchFooterOptions {
+  /** Spacer at the end of the flow; defaults to `[data-mk-phantom]` in the document. */
+  phantom?: HTMLElement | null;
+  /** Stretching title; defaults to `[data-mk-footer-title]` inside the footer. */
+  title?: HTMLElement | null;
+  /** Scroll smoothing (higher follows faster). */
+  lambda?: number;
+}
+
+export type StretchFooterInstance = Instance;
+
+export function createStretchFooter(footer: HTMLElement | null, options: StretchFooterOptions = {}): StretchFooterInstance {
+  const phantom = options.phantom ?? document.querySelector<HTMLElement>('[data-mk-phantom]');
+  const title = options.title ?? footer?.querySelector<HTMLElement>('[data-mk-footer-title]') ?? null;
+  if (!footer || !phantom || !title) {
+    warnOnce('stretch-footer: needs the footer, a [data-mk-phantom] spacer and a [data-mk-footer-title]');
+    return inert();
+  }
+  registerMotion();
+  const scope = createScope();
+  footer.dataset.mkReady = '';
+  scope.add(() => {
+    delete footer.dataset.mkReady;
+    footer.style.removeProperty('--mk-footer-scale');
+    footer.style.removeProperty('--mk-footer-offset');
+    if (!footer.getAttribute('style')) footer.removeAttribute('style');
+  });
+  if (reduced()) return { destroy: () => scope.dispose() };
+
+  const lambda = options.lambda ?? 0.9;
+  let phantomTop = 0;
+  let titleBottom = 0;
+  let viewport = innerHeight;
+  let g = scrollY;
+
+  const measure = () => {
+    phantomTop = phantom.offsetTop;
+    titleBottom = title.offsetTop + title.offsetHeight;
+    viewport = innerHeight;
+  };
+  measure();
+  scope.observe(new ResizeObserver(measure)).observe(document.body);
+  scope.on(window, 'resize', measure);
+
+  const update = (dt: number) => {
+    g = damp(g, scrollY, lambda, dt);
+    const start = phantomTop - viewport;
+    footer.style.setProperty('--mk-footer-scale', mapRange(g, start, phantomTop, 0, 1, true).toFixed(4));
+    footer.style.setProperty('--mk-footer-offset', mapRange(g, start, phantomTop, viewport - titleBottom, 0, true).toFixed(2));
+  };
+  update(100); // settle on the current scroll position before the first frame
+  scope.add(whileVisible(phantom, update, '0px'));
+
+  return { destroy: () => scope.dispose() };
+}

package/src/recipes/stretch-footer/stretch-footer.css

@@ -0,0 +1,28 @@
+/*
+ * stretch-footer — spencergabor.com (Footer). The page content must sit above it:
+ * give <main> `position: relative; z-index: 1; background: <page colour>`.
+ */
+
+[data-mk-phantom] {
+  height: 100dvh;
+  pointer-events: none;
+}
+
+[data-mk~="stretch-footer"],
+.mk-stretch-footer {
+  position: fixed;
+  inset: auto 0 0;
+  z-index: 0;
+  height: 100dvh;
+  display: flex;
+  flex-direction: column;
+  justify-content: flex-end;
+  translate: 0 calc(var(--mk-footer-offset, 0) * 1px);
+}
+
+[data-mk-footer-title] {
+  align-self: flex-start;
+  line-height: 0.8;
+  transform: scaleY(var(--mk-footer-scale, 1));
+  transform-origin: 50% 100%;
+}

package/src/recipes/tabs/README.md

@@ -0,0 +1,39 @@
+# tabs
+
+Un indicador se desliza hasta la pestaña elegida en 0.45 s con la curva signature. Si la lista hace scroll, centra la pestaña. Flechas (según orientación), Inicio y Fin cambian la selección.
+
+Origen: Stepbro — PrettyTabs (`tabs`, `tabs-indicator` en el kit: `Flip.fit`, 0.45 s, `prettyTabsSlide`).
+
+## Vanilla / Astro
+
+```html
+<div data-mk="tabs" class="mk-segmented">
+  <button data-mk-tab aria-selected="true">Día</button>
+  <button data-mk-tab>Semana</button>
+  <button data-mk-tab>Mes</button>
+  <span data-mk-indicator></span>
+</div>
+```
+
+Escucha el cambio con `mk:tab` (`event.detail.index`, `event.detail.tab`). Sin `autoInit`: `createTabs(el, opciones)`.
+
+## React
+
+```tsx
+const ref = useRef<HTMLDivElement>(null);
+useTabs(ref, { onSelect: (i) => setView(views[i]) });
+```
+
+## Opciones
+
+| Opción | Por defecto | Qué hace |
+|---|---|---|
+| `orientation` | `'horizontal'` | `'vertical'` usa ↑ ↓ y pone `aria-orientation` |
+| `duration` | `.45` | Segundos del deslizamiento |
+| `onSelect` | — | `(index, tab) => void` |
+
+## Controles
+
+`select(index)`, `index`, `destroy()`
+
+La receta pone `role="tablist"`, `role="tab"`, `aria-selected` y `tabindex` y los restaura al destruirse. Con movimiento reducido el indicador salta sin deslizarse.

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

@@ -0,0 +1,91 @@
+import { gsap, registerMotion } from '../../core/gsap';
+import { createScope } from '../../core/scope';
+import { inert, warnOnce, type Instance } from '../../core/types';
+import { TIMING } from '../../core/timing';
+import { slideIndicator } from '../../motion/indicator';
+
+/*
+ * Stepbro's PrettyTabs: an indicator slides onto the selected tab in 0.45 s on
+ * the signature curve; a scrolling tab list centres the selection. Arrow keys
+ * (by orientation), Home and End move the selection.
+ */
+
+export interface TabsOptions {
+  orientation?: 'horizontal' | 'vertical';
+  duration?: number;
+  onSelect?: (index: number, tab: HTMLElement) => void;
+}
+
+export interface TabsInstance extends Instance {
+  select(index: number): void;
+  readonly index: number;
+}
+
+export function createTabs(root: HTMLElement | null, options: TabsOptions = {}): TabsInstance {
+  const tabs = root ? [...root.querySelectorAll<HTMLElement>('[data-mk-tab]')] : [];
+  if (!root || !tabs.length) {
+    warnOnce('tabs: needs at least one [data-mk-tab]');
+    return inert({ select() {}, index: 0 });
+  }
+  registerMotion();
+  const { orientation = 'horizontal', duration = TIMING.indicator } = options;
+  const indicator = root.querySelector<HTMLElement>('[data-mk-indicator]');
+  const scope = createScope();
+  const ctx = gsap.context(() => {});
+  let index = Math.max(0, tabs.findIndex((tab) => tab.getAttribute('aria-selected') === 'true'));
+
+  scope.attr(root, 'role', 'tablist');
+  if (orientation === 'vertical') scope.attr(root, 'aria-orientation', 'vertical');
+
+  const render = (immediate: boolean) => {
+    tabs.forEach((tab, i) => {
+      scope.attr(tab, 'role', 'tab');
+      scope.attr(tab, 'aria-selected', String(i === index));
+      scope.attr(tab, 'tabindex', i === index ? '0' : '-1');
+    });
+    if (indicator) ctx.add(() => slideIndicator(indicator, tabs[index], { immediate, duration, scroller: root, orientation }));
+  };
+
+  const select = (next: number, focus = false) => {
+    const target = Math.min(tabs.length - 1, Math.max(0, next));
+    if (focus) tabs[target].focus();
+    if (target === index) return;
+    index = target;
+    render(false);
+    root.dispatchEvent(new CustomEvent('mk:tab', { detail: { index, tab: tabs[index] }, bubbles: true }));
+    options.onSelect?.(index, tabs[index]);
+  };
+
+  scope.on(root, 'click', (event) => {
+    const tab = (event.target as Element | null)?.closest<HTMLElement>('[data-mk-tab]');
+    const at = tab ? tabs.indexOf(tab) : -1;
+    if (at >= 0) select(at);
+  });
+  scope.on(root, 'keydown', (event) => {
+    const key = (event as KeyboardEvent).key;
+    const back = orientation === 'vertical' ? 'ArrowUp' : 'ArrowLeft';
+    const forward = orientation === 'vertical' ? 'ArrowDown' : 'ArrowRight';
+    const moves: Record<string, number> = { [back]: index - 1, [forward]: index + 1, Home: 0, End: tabs.length - 1 };
+    if (!(key in moves)) return;
+    event.preventDefault();
+    select(moves[key], true);
+  });
+  if (typeof ResizeObserver === 'function') {
+    scope.observe(new ResizeObserver(() => render(true))).observe(root);
+  }
+
+  render(true);
+  root.dataset.mkReady = '';
+
+  return {
+    select: (next: number) => select(next),
+    get index() {
+      return index;
+    },
+    destroy() {
+      scope.dispose();
+      ctx.revert();
+      delete root.dataset.mkReady;
+    },
+  };
+}

package/src/recipes/tabs/tabs.css

@@ -0,0 +1,19 @@
+/* tabs: the indicator sits under the tabs at 0,0 of the list; the recipe sizes and moves it. */
+[data-mk~='tabs'] {
+  position: relative;
+}
+
+[data-mk~='tabs'] [data-mk-tab] {
+  position: relative;
+  z-index: 1;
+}
+
+[data-mk~='tabs'] [data-mk-indicator] {
+  position: absolute;
+  top: 0;
+  left: 0;
+  z-index: 0;
+  pointer-events: none;
+  border-radius: var(--mk-tabs-indicator-radius, var(--mk-radius-full));
+  background: var(--mk-tabs-indicator, var(--mk-accent-soft));
+}

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

@@ -0,0 +1,35 @@
+# text-roll
+
+Un título que gira como una tragaperras: cada letra es un carrete (la letra y una copia debajo) que da entre 9 y 15 vueltas al azar; todas frenan con `expo.out` en 2 s, 40 ms entre letras en orden aleatorio, y se quedan en la misma letra. Puede repetirse cada 6 s mientras se ve y no hay scroll (espera 1 s de calma).
+
+Origen: Siena Film Foundation, títulos de película de la portada (copia `cloneText2`, `L.utils.random(8, 14)` repeticiones).
+
+## HTML / Astro
+
+```html
+<h1 data-mk="text-roll">My Project X</h1>
+<h2 data-mk="text-roll" data-mk-trigger="hover">Explorar</h2>
+<h1 data-mk="text-roll" data-mk-interval="6000">Savoy</h1>
+```
+
+## React
+
+```tsx
+const ref = useRef<HTMLHeadingElement>(null);
+const roll = useTextRoll(ref, { trigger: 'manual' });
+<button onClick={() => roll.current?.play()}>Girar</button>
+```
+
+## API
+
+`createTextRoll(el, { duration, stagger, turns, trigger, delay, interval })` → `{ play(), timelines, destroy }`.
+
+| Opción | Por defecto | |
+|---|---|---|
+| `trigger` | `'load'` | `'scroll'`, `'hover'`, `'manual'` |
+| `interval` | `0` | ms entre repeticiones (Siena: 6000) |
+| `turns` | `[8, 14]` | repeticiones de la vuelta de cada letra |
+
+## Accesibilidad
+
+La raíz recibe `aria-label` y las letras partidas quedan ocultas a lectores. Con movimiento reducido el texto no se parte.