@yewdiel21/motion-kit 0.0.0-stage → 0.9.0

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

@@ -0,0 +1,111 @@
+import { gsap, registerMotion } from '../../core/gsap';
+import { entrances } from '../../core/reduced';
+import { clearStyles } from '../../core/styles';
+import { TIMING } from '../../core/timing';
+import { inert, warnOnce, type Instance } from '../../core/types';
+import { shows, thresholds } from '../../core/visible';
+
+/*
+ * Siena's reveal group: when the block shows (30 %), its marked children enter
+ * one after another, 30 ms apart, 1.2 s expo.out — rules grow from alternating
+ * sides (scaleX 0 → 1), fades appear (OFFFICE's alpha), rises come up from 200 %
+ * inside their clip. When it leaves, every child goes back to its start state
+ * so the block enters again next time (unless once).
+ * Children: [data-mk-cascade="rule|fade|rise"].
+ */
+
+export interface CascadeOptions {
+  /** Seconds before the first child (also data-mk-delay). */
+  delay?: number;
+  duration?: number;
+  /** Seconds between children. */
+  step?: number;
+  once?: boolean;
+  trigger?: 'scroll' | 'load' | 'manual';
+}
+
+export interface CascadeInstance extends Instance {
+  play(): void;
+  /** Every child back to its start state (what Siena does when the block leaves). */
+  reset(): void;
+}
+
+type Kind = 'rule' | 'fade' | 'rise';
+const STYLES = ['transform', 'translate', 'rotate', 'scale', 'transform-origin', 'opacity', 'visibility'];
+
+export function createCascade(root: HTMLElement | null, options: CascadeOptions = {}): CascadeInstance {
+  if (!root) {
+    warnOnce('cascade: missing element');
+    return inert({ play() {}, reset() {} });
+  }
+  const t = TIMING.cascade;
+  const { duration = t.duration, step = t.step, once = false, trigger = 'scroll' } = options;
+  const delay = options.delay ?? (Number(root.dataset.mkDelay) || 0);
+  const items = [...root.querySelectorAll<HTMLElement>('[data-mk-cascade]')].map((el, index) => ({
+    el,
+    index,
+    kind: (el.dataset.mkCascade as Kind) || 'fade',
+  }));
+  if (!entrances() || !items.length) {
+    root.dataset.mkReady = '';
+    return {
+      play() {},
+      reset() {},
+      destroy() {
+        delete root.dataset.mkReady;
+      },
+    };
+  }
+  registerMotion();
+  let observer: IntersectionObserver | null = null;
+
+  const setOut = ({ el, index, kind }: (typeof items)[number]) => {
+    gsap.killTweensOf(el);
+    if (kind === 'rule') gsap.set(el, { scaleX: 0, transformOrigin: index % 2 === 0 ? 'left center' : 'right center' });
+    else if (kind === 'rise') gsap.set(el, { yPercent: t.rise });
+    else gsap.set(el, { autoAlpha: 0 });
+  };
+  items.forEach(setOut);
+
+  let shown = false;
+  const play = () => {
+    shown = true;
+    for (const { el, index, kind } of items) {
+      const to = kind === 'rule' ? { scaleX: 1 } : kind === 'rise' ? { yPercent: 0 } : { autoAlpha: 1 };
+      gsap.to(el, { ...to, duration, ease: 'expo.out', delay: delay + index * step, overwrite: 'auto' });
+    }
+  };
+  const reset = () => {
+    shown = false;
+    items.forEach(setOut);
+  };
+
+  if (trigger === 'load') play();
+  else if (trigger === 'scroll' && typeof IntersectionObserver === 'function') {
+    observer = new IntersectionObserver(
+      (entries) => {
+        for (const entry of entries) {
+          if (shows(entry, t.threshold)) {
+            if (!shown) play();
+            if (once) observer?.disconnect();
+          } else if (!entry.isIntersecting && shown && !once) reset();
+        }
+      },
+      { threshold: thresholds(t.threshold) },
+    );
+    observer.observe(root);
+  }
+  root.dataset.mkReady = '';
+
+  return {
+    play,
+    reset,
+    destroy() {
+      observer?.disconnect();
+      const elements = items.map((item) => item.el);
+      gsap.killTweensOf(elements);
+      clearStyles(elements, STYLES);
+      delete root.dataset.mkReady;
+    },
+  };
+}

package/src/recipes/contrast/README.md

@@ -0,0 +1,29 @@
+# contrast
+
+La cabecera cambia de tono según la sección que tiene debajo: las secciones dicen si son claras u oscuras (`data-mk-tone="light"` / `"dark"`) y la que cruza el 10 % superior de la pantalla escribe su tono en la cabecera (`data-mk-on`). Tu CSS decide los colores.
+
+Origen: Siena Film Foundation, logo que pasa a negro sobre secciones claras (`rootMargin: 0% 0% -90% 0%`).
+
+## HTML / Astro
+
+```html
+<header data-mk="contrast" class="site-header">…</header>
+<section data-mk-tone="dark">…</section>
+<section data-mk-tone="light">…</section>
+
+<style>
+  .site-header { color: white; transition: color 0.3s; }
+  .site-header[data-mk-on='light'] { color: black; }
+</style>
+```
+
+## React
+
+```tsx
+const ref = useRef<HTMLElement>(null);
+useContrast(ref);
+```
+
+## API
+
+`createContrast(target, { sections, attribute })` → `{ tone, destroy }`. `sections` por defecto `[data-mk-tone]`; `attribute` por defecto `data-mk-on`.

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

@@ -0,0 +1,68 @@
+import { createScope } from '../../core/scope';
+import { inert, warnOnce, type Instance } from '../../core/types';
+
+/*
+ * Siena's header contrast: sections say what they are (data-mk-tone="light" or
+ * "dark"); the section crossing the top 10 % of the screen gives its tone to
+ * the header (data-mk-on), and the page's CSS turns the logo and links dark on
+ * light sections and light on dark ones.
+ */
+
+export interface ContrastOptions {
+  /** Sections to watch (default [data-mk-tone]). */
+  sections?: string;
+  /** Attribute written on the target (default data-mk-on). */
+  attribute?: string;
+}
+
+export interface ContrastInstance extends Instance {
+  readonly tone: string | null;
+}
+
+export function createContrast(target: HTMLElement | null, options: ContrastOptions = {}): ContrastInstance {
+  if (!target) {
+    warnOnce('contrast: missing element');
+    return inert({ tone: null });
+  }
+  const { sections = '[data-mk-tone]', attribute = 'data-mk-on' } = options;
+  const scope = createScope();
+  const watched = [...document.querySelectorAll<HTMLElement>(sections)];
+  // Under the band, in the order they came in: the newest wins.
+  const under = new Set<HTMLElement>();
+  let tone: string | null = target.getAttribute(attribute);
+
+  const apply = () => {
+    const current = [...under].at(-1);
+    if (!current) return;
+    tone = current.dataset.mkTone ?? null;
+    scope.attr(target, attribute, tone);
+  };
+
+  if (typeof IntersectionObserver === 'function' && watched.length) {
+    const observer = scope.observe(
+      new IntersectionObserver(
+        (entries) => {
+          for (const entry of entries) {
+            const section = entry.target as HTMLElement;
+            under.delete(section);
+            if (entry.isIntersecting) under.add(section);
+          }
+          apply();
+        },
+        { rootMargin: '0% 0% -90% 0%', threshold: 0 },
+      ),
+    );
+    for (const section of watched) observer.observe(section);
+  }
+  target.dataset.mkReady = '';
+
+  return {
+    get tone() {
+      return tone;
+    },
+    destroy() {
+      scope.dispose();
+      delete target.dataset.mkReady;
+    },
+  };
+}

package/src/recipes/counter/README.md

@@ -0,0 +1,42 @@
+# counter
+
+Un número cuenta hasta su valor con la curva `numberSoft` (0.6 s), partiendo del valor que muestra.
+
+Origen: Stepbro — animated number (`numeric-counter` en el kit: 0.6 s, 0.7 s en precios, `M0,0 C0.25,0.1 0.25,1 1,1`).
+
+## Vanilla / Astro
+
+```html
+<span data-mk="counter" data-mk-to="1280" data-mk-prefix="$">0</span>
+```
+
+Sin `autoInit`: `createCounter(el, opciones)`.
+
+## React
+
+```tsx
+const ref = useRef<HTMLSpanElement>(null);
+const counter = useCounter(ref, { to: total, trigger: 'load' });
+// después: counter.current?.set(nuevoTotal)
+```
+
+Para un número que cambia con el estado, `<AnimatedNumber value={total} />` es más cómodo.
+
+## Opciones
+
+| Opción | Por defecto | Qué hace |
+|---|---|---|
+| `to` | número del texto | Valor final |
+| `from` | `0` | Valor inicial |
+| `duration` | `.6` | Segundos |
+| `decimals` | `0` | Decimales mostrados |
+| `locale` | del navegador | Agrupación y separador decimal (`Intl`) |
+| `prefix`, `suffix` | `''` | Texto antes y después |
+| `trigger` | `'scroll'` | `'scroll'`, `'load'` o `'manual'` |
+| `start` | `'top 90%'` | Inicio del ScrollTrigger |
+
+## Controles
+
+`play()`, `set(valor)`, `destroy()` (devuelve el texto original)
+
+Con movimiento reducido muestra el valor final directamente.

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

@@ -0,0 +1,84 @@
+import { gsap, ScrollTrigger, registerMotion } from '../../core/gsap';
+import { entrances } from '../../core/reduced';
+import { inert, warnOnce, type Instance } from '../../core/types';
+import { TIMING } from '../../core/timing';
+import { countTo } from '../../motion/count';
+
+/* Stepbro's animated number: counts to its value with `numberSoft` (0.6 s), from the value shown. */
+
+export interface CounterOptions {
+  /** Final value. Default: the number written in the element. */
+  to?: number;
+  from?: number;
+  duration?: number;
+  decimals?: number;
+  /** Intl locale for grouping and decimals. Default: the browser's. */
+  locale?: string;
+  prefix?: string;
+  suffix?: string;
+  trigger?: 'scroll' | 'load' | 'manual';
+  start?: string;
+}
+
+export interface CounterInstance extends Instance {
+  /** Count from the start value to `to`. */
+  play(): void;
+  /** Count from the value shown to `value`. */
+  set(value: number): void;
+}
+
+export function createCounter(el: HTMLElement | null, options: CounterOptions = {}): CounterInstance {
+  if (!el) {
+    warnOnce('counter: missing element');
+    return inert({ play() {}, set() {} });
+  }
+  registerMotion();
+  const original = el.textContent ?? '';
+  const parsed = Number(original.replace(/[^\d.-]/g, ''));
+  const {
+    to = Number.isFinite(parsed) ? parsed : 0,
+    from = 0,
+    duration = TIMING.number,
+    decimals = 0,
+    locale,
+    prefix = '',
+    suffix = '',
+    trigger = 'scroll',
+    start = 'top 90%',
+  } = options;
+  const format = (value: number) =>
+    prefix + value.toLocaleString(locale, { minimumFractionDigits: decimals, maximumFractionDigits: decimals }) + suffix;
+  const ctx = gsap.context(() => {});
+  let played = false;
+
+  const play = () => {
+    if (played) return;
+    played = true;
+    ctx.add(() => countTo(el, to, { from, duration, format }));
+  };
+
+  if (entrances()) {
+    el.textContent = format(from);
+    ctx.add(() => {
+      if (trigger === 'load') play();
+      else if (trigger !== 'manual') ScrollTrigger.create({ trigger: el, start, end: 'max', once: true, onEnter: play });
+    });
+  } else {
+    played = true;
+    el.textContent = format(to);
+  }
+  el.dataset.mkReady = '';
+
+  return {
+    play,
+    set(value: number) {
+      played = true;
+      ctx.add(() => countTo(el, value, { duration, format }));
+    },
+    destroy() {
+      ctx.revert();
+      el.textContent = original;
+      delete el.dataset.mkReady;
+    },
+  };
+}

package/src/recipes/curved-carousel/README.md

@@ -0,0 +1,50 @@
+# curved-carousel
+
+Carrusel en arco: se arrastra con inercia (fricción .85), se centra solo en la slide más cercana, da la vuelta infinita y responde a la rueda horizontal, las flechas y el foco.
+
+Origen: spencergabor.com — Carousel.global.vue.
+
+## Vanilla / Astro
+
+```html
+<div data-mk="curved-carousel" tabindex="0" aria-roledescription="carousel" aria-label="Proyectos">
+  <button data-mk-slide>
+    <span class="mk-carousel__media"><img src="a.jpg" alt=""></span>
+    <span class="mk-carousel__title">Proyecto A</span>
+  </button>
+  …
+</div>
+<script>el.addEventListener('mk:select', (e) => open(e.detail.index))</script>
+```
+
+Con `autoInit()` (de `@yewdiel21/motion-kit/auto`) las opciones van como `data-mk-<opción>` en kebab-case. Sin `autoInit`: `createCurvedCarousel(el, opciones)`.
+
+## React
+
+```tsx
+const ref = useRef<HTMLDivElement>(null);
+const carousel = useCurvedCarousel(ref, { onSelect: (i) => setOpen(i) });
+// carousel.current?.next()
+```
+
+## Opciones
+
+| Opción | Por defecto | Qué hace |
+|---|---|---|
+| `slideSelector` | `'[data-mk-slide]'` | Slides dentro del root |
+| `friction` | `.85` | Decaimiento por frame de la velocidad |
+| `throwBoost` | `2` | Multiplicador de la velocidad al soltar |
+| `wheel` | `.2` | Factor de la rueda horizontal |
+| `tapDistance` | `6` | px por debajo de los cuales es un clic |
+| `startIndex` | `0` | Slide centrada al inicio |
+| `onSelect(index, slide)` | — | Clic/Enter en una slide (en `autoInit`: evento `mk:select`) |
+
+## Controles
+
+`next()`, `prev()`, `goTo(i)`, `index`, `destroy()`
+
+## CSS
+
+Mientras corre, el root lleva `data-mk-carousel` y las slides se posicionan en absoluto con `--mk-x` y giran según `--mk-t` (distancia al centro). Sin JS el root conserva tu estilo (por ejemplo, una fila con scroll). Ajusta `--mk-slide-w`, `--mk-gap` y `--mk-carousel-h` en el root.
+
+Con `prefers-reduced-motion: reduce` la receta deja el contenido en su estado final, sin animar.

package/src/recipes/curved-carousel/carousel-math.ts

@@ -0,0 +1,20 @@
+import { wrap } from '../../core/math';
+
+export const FRICTION = 0.85;
+
+/** X of slide k relative to the viewport's left edge, wrapped so the track loops. */
+export function slideX(k: number, offset: number, step: number, length: number) {
+  return wrap(k * step - offset + step, length) - step;
+}
+
+/** Where the offset ends if velocity v (px/frame, applied as offset -= v) decays by f each frame. */
+export const restingOffset = (offset: number, v: number, f = FRICTION) => offset - (v * f) / (1 - f);
+
+/** Velocity that makes restingOffset(offset, v) === target. */
+export const velocityFor = (target: number, offset: number, f = FRICTION) => -((target - offset) * (1 - f)) / f;
+
+/** Offset that centres the slide nearest to the projected rest; `dir` forces ±1 slide from the current one. */
+export function snapOffset(offset: number, v: number, step: number, center: number, f = FRICTION, dir = 0) {
+  const base = dir === 0 ? restingOffset(offset, v, f) : offset;
+  return (Math.round((base + center) / step) + dir) * step - center;
+}

package/src/recipes/curved-carousel/create-curved-carousel.ts

@@ -0,0 +1,257 @@
+import { registerMotion } from '../../core/gsap';
+import { reduced } from '../../core/reduced';
+import { whileVisible } from '../../core/loop';
+import { createScope } from '../../core/scope';
+import { inert, warnOnce, type Instance } from '../../core/types';
+import { shows, thresholds } from '../../core/visible';
+import { wrap } from '../../core/math';
+import { FRICTION, slideX, snapOffset } from './carousel-math';
+
+/*
+ * spencergabor.com carousel: offset with friction .85, drag follows the pointer,
+ * release multiplies the velocity and snaps to the slide nearest the projected
+ * rest. Slides loop by wrapping their x; CSS turns the distance from the centre
+ * (`--mk-t`) into the arc (see curved-carousel.css).
+ */
+
+export interface CurvedCarouselOptions {
+  /** Slides inside the root. */
+  slideSelector?: string;
+  /** Per-frame velocity decay (0–1). */
+  friction?: number;
+  /** Multiplier applied to the release velocity before snapping. */
+  throwBoost?: number;
+  /** Horizontal wheel / trackpad factor. */
+  wheel?: number;
+  /** Movement below this many px counts as a tap (click), not a drag. */
+  tapDistance?: number;
+  startIndex?: number;
+  /** Tap/click or Enter on a slide. */
+  onSelect?: (index: number, slide: HTMLElement) => void;
+}
+
+export interface CurvedCarouselInstance extends Instance {
+  next(): void;
+  prev(): void;
+  goTo(index: number): void;
+  /** Index of the slide closest to the centre. */
+  readonly index: number;
+}
+
+export function createCurvedCarousel(root: HTMLElement | null, options: CurvedCarouselOptions = {}): CurvedCarouselInstance {
+  const o = {
+    slideSelector: '[data-mk-slide]',
+    friction: FRICTION,
+    throwBoost: 2,
+    wheel: 0.2,
+    tapDistance: 6,
+    startIndex: 0,
+    ...options,
+  };
+  o.friction = Math.min(0.99, Math.max(0.5, o.friction));
+  const slides = root ? [...root.querySelectorAll<HTMLElement>(o.slideSelector)] : [];
+  const count = slides.length;
+  if (!root || !count) {
+    warnOnce(`curved-carousel: no "${o.slideSelector}" inside the root`);
+    return inert({ next() {}, prev() {}, goTo() {}, index: 0 });
+  }
+
+  registerMotion();
+  const scope = createScope();
+  root.dataset.mkCarousel = '';
+  slides.forEach((slide, k) => slide.style.setProperty('--mk-k', String(k)));
+  scope.add(() => {
+    delete root.dataset.mkCarousel;
+    delete root.dataset.mkReady;
+    delete root.dataset.mkInview;
+    slides.forEach((slide) => ['--mk-k', '--mk-x', '--mk-t'].forEach((name) => slide.style.removeProperty(name)));
+  });
+
+  let rootW = 0;
+  let slideW = 0;
+  let step = 1;
+  let length = count;
+  let center = 0;
+  let offset = 0;
+  let v = 0;
+  let target: number | null = null;
+  let measured = false;
+
+  let down = false;
+  let dragDelta = 0;
+  let lastX = 0;
+  let travelled = 0;
+  let suppressClick = false;
+  let wheelTimer: ReturnType<typeof setTimeout> | undefined;
+  scope.add(() => clearTimeout(wheelTimer));
+
+  const render = () => {
+    for (let k = 0; k < count; k++) {
+      const x = slideX(k, offset, step, length);
+      const style = slides[k]!.style;
+      style.setProperty('--mk-x', x.toFixed(2));
+      style.setProperty('--mk-t', (x + slideW / 2 - rootW / 2).toFixed(2));
+    }
+  };
+
+  /** Offset that centres slide k, picking the loop copy nearest to the current offset. */
+  const centred = (k: number) => {
+    const base = k * step - center;
+    return base + Math.round((offset - base) / length) * length;
+  };
+
+  const settleTo = (next: number) => {
+    target = next;
+    if (!reduced()) return;
+    offset = next;
+    target = null;
+    v = 0;
+    render();
+  };
+
+  const measure = () => {
+    const previousCenter = center;
+    rootW = root.clientWidth;
+    slideW = slides[0]!.offsetWidth;
+    const gap = parseFloat(getComputedStyle(root).columnGap) || 16;
+    const index = measured ? (offset + previousCenter) / step : o.startIndex;
+    step = slideW + gap || 1;
+    length = count * step;
+    center = (rootW - slideW) / 2;
+    offset = index * step - center;
+    if (target !== null) target = Math.round((target + previousCenter) / step) * step - center;
+    measured = true;
+    render();
+  };
+
+  const tick = (dt: number) => {
+    if (down) {
+      v = dragDelta;
+      dragDelta = 0;
+      offset -= v;
+    } else if (target !== null) {
+      // Geometric approach to the snap point: the same path as Spencer's computed velocity.
+      const next = offset + (target - offset) * (1 - Math.pow(o.friction, dt));
+      v = offset - next;
+      offset = next;
+      if (Math.abs(target - offset) < 0.1) {
+        offset = target;
+        target = null;
+        v = 0;
+      }
+    } else if (Math.abs(v) > 0.01) {
+      v *= Math.pow(o.friction, dt);
+      offset -= v * dt;
+    } else {
+      return;
+    }
+    render();
+  };
+
+  // Drag (window listeners so the drag survives leaving the carousel)
+  scope.on(root, 'pointerdown', (e: PointerEvent) => {
+    if (e.button !== 0) return;
+    if (e.pointerType === 'mouse') e.preventDefault();
+    down = true;
+    target = null;
+    dragDelta = 0;
+    travelled = 0;
+    lastX = e.clientX;
+  });
+  scope.on(
+    window,
+    'pointermove',
+    (e: PointerEvent) => {
+      if (!down) return;
+      const dx = e.clientX - lastX;
+      lastX = e.clientX;
+      dragDelta += dx;
+      travelled += Math.abs(dx);
+    },
+    { passive: true },
+  );
+  const release = (cancelled: boolean) => {
+    if (!down) return;
+    down = false;
+    suppressClick = travelled > o.tapDistance;
+    const throwV = cancelled || reduced() ? 0 : v * o.throwBoost;
+    settleTo(snapOffset(offset, throwV, step, center, o.friction));
+  };
+  scope.on(window, 'pointerup', () => release(false));
+  scope.on(window, 'pointercancel', () => release(true));
+
+  // A drag must not count as a click on the slide under the pointer.
+  scope.on(
+    root,
+    'click',
+    (e: MouseEvent) => {
+      if (!suppressClick) return;
+      suppressClick = false;
+      e.preventDefault();
+      e.stopPropagation();
+    },
+    true,
+  );
+  scope.on(root, 'click', (e: MouseEvent) => {
+    const slide = (e.target as Element).closest<HTMLElement>(o.slideSelector);
+    if (slide && root.contains(slide)) o.onSelect?.(slides.indexOf(slide), slide);
+  });
+
+  // Horizontal wheel / trackpad
+  scope.on(
+    root,
+    'wheel',
+    (e: WheelEvent) => {
+      if (Math.abs(e.deltaX) <= Math.abs(e.deltaY)) return;
+      e.preventDefault();
+      target = null;
+      if (reduced()) {
+        offset += e.deltaX;
+        render();
+      } else {
+        v -= e.deltaX * o.wheel;
+      }
+      clearTimeout(wheelTimer);
+      wheelTimer = setTimeout(() => settleTo(snapOffset(offset, v, step, center, o.friction)), 150);
+    },
+    { passive: false },
+  );
+
+  // Keyboard: arrows step one slide; focusing a slide centres it.
+  const stepBy = (dir: 1 | -1) => settleTo(snapOffset(target ?? offset, 0, step, center, o.friction, dir));
+  scope.on(root, 'keydown', (e: KeyboardEvent) => {
+    if (e.key !== 'ArrowLeft' && e.key !== 'ArrowRight') return;
+    e.preventDefault();
+    stepBy(e.key === 'ArrowLeft' ? -1 : 1);
+  });
+  scope.on(root, 'focusin', (e: FocusEvent) => {
+    const slide = (e.target as Element).closest<HTMLElement>(o.slideSelector);
+    if (!slide || down) return;
+    settleTo(centred(slides.indexOf(slide)));
+  });
+
+  scope.observe(new ResizeObserver(measure)).observe(root);
+  scope
+    .observe(
+      new IntersectionObserver(
+        ([entry]) => {
+          if (entry && shows(entry, 0.2)) root.dataset.mkInview = '';
+        },
+        { threshold: thresholds(0.2) },
+      ),
+    )
+    .observe(root);
+  scope.add(whileVisible(root, tick));
+  measure();
+  root.dataset.mkReady = '';
+
+  return {
+    destroy: () => scope.dispose(),
+    next: () => stepBy(1),
+    prev: () => stepBy(-1),
+    goTo: (index: number) => settleTo(centred(wrap(Math.round(index), count))),
+    get index() {
+      return wrap(Math.round(((target ?? offset) + center) / step), count);
+    },
+  };
+}