@yewdiel21/motion-kit 0.0.0-stage → 0.9.0

package/src/motion/floating.ts

@@ -0,0 +1,389 @@
+import { gsap, EASE, registerMotion } from '../core/gsap';
+import { reduced } from '../core/reduced';
+import { TIMING } from '../core/timing';
+
+/*
+ * Stepbro's floating modal (ported from Kayro): on desktop (≥ 680 px) a handle
+ * lifts a surface into a window that moves on a spring (1100/38, mass by area),
+ * glides when flung (≥ 350 px/s, decays in 0.18 s), stays inside the viewport
+ * (8 px margin), resizes from its corners (min 320 × 240) and remembers where it
+ * was left (localStorage `mk-float.<key>`). A press on the handle without
+ * moving toggles floating.
+ */
+
+const MIN_WIDTH = 320;
+const MIN_HEIGHT = 240;
+const MARGIN = 8;
+const DESKTOP = 680;
+const LIFT = 4;
+const SPRING = { stiffness: 1100, damping: 38 };
+const MASS_AREA = 24_000;
+const MAX_MASS = 1.5;
+const REST_SPEED = 24;
+const FLING_SPEED = 350;
+const POINTER_SMOOTHING = 0.05;
+const SHRINK_FULL = 0.85;
+const FLOAT_SHADOW = 'rgba(0, 0, 0, 0.24) 0px 0px 24px -6px';
+
+export const floatingAvailable = () => typeof innerWidth === 'number' && innerWidth >= DESKTOP;
+
+export interface Rect {
+  top: number;
+  left: number;
+  width: number;
+  height: number;
+}
+
+/** A window kept inside the viewport, at least 320 × 240. */
+export function clampRect(rect: Rect, viewport = { width: innerWidth, height: innerHeight }): Rect {
+  const maxWidth = Math.max(MIN_WIDTH, viewport.width - MARGIN * 2);
+  const maxHeight = Math.max(MIN_HEIGHT, viewport.height - MARGIN * 2);
+  const width = Math.min(maxWidth, Math.max(MIN_WIDTH, rect.width));
+  const height = Math.min(maxHeight, Math.max(MIN_HEIGHT, rect.height));
+  return {
+    top: Math.min(Math.max(MARGIN, viewport.height - height - MARGIN), Math.max(MARGIN, rect.top)),
+    left: Math.min(Math.max(MARGIN, viewport.width - width - MARGIN), Math.max(MARGIN, rect.left)),
+    width,
+    height,
+  };
+}
+
+const rectOf = (element: HTMLElement): Rect => {
+  const box = element.getBoundingClientRect();
+  return { top: box.top, left: box.left, width: box.width, height: box.height };
+};
+
+const place = (element: HTMLElement, rect: Rect) =>
+  Object.assign(element.style, {
+    position: 'fixed',
+    inset: 'auto',
+    margin: '0',
+    top: `${rect.top}px`,
+    left: `${rect.left}px`,
+    width: `${rect.width}px`,
+    height: `${rect.height}px`,
+    maxWidth: 'none',
+    maxHeight: 'none',
+  });
+
+const storageKey = (key: string) => `mk-float.${key}`;
+
+/** Where a floating window was left, if this device remembers it. */
+export function savedFloat(key: string): Rect | null {
+  try {
+    const value = JSON.parse(localStorage.getItem(storageKey(key)) ?? 'null') as Rect | null;
+    return value && (['top', 'left', 'width', 'height'] as const).every((name) => Number.isFinite(value[name])) ? clampRect(value) : null;
+  } catch {
+    return null;
+  }
+}
+
+function saveFloat(key: string, rect: Rect) {
+  try {
+    localStorage.setItem(
+      storageKey(key),
+      JSON.stringify({ top: Math.round(rect.top), left: Math.round(rect.left), width: Math.round(rect.width), height: Math.round(rect.height) }),
+    );
+  } catch {
+    // A convenience only.
+  }
+}
+
+export function forgetFloat(key: string) {
+  try {
+    localStorage.removeItem(storageKey(key));
+  } catch {
+    // A convenience only.
+  }
+}
+
+/** Lift a surface into a window at `rect` (its shadow eases in, 0.45 s). */
+export function liftWindow(surface: HTMLElement, rect: Rect) {
+  registerMotion();
+  place(surface, clampRect(rect));
+  surface.classList.add('is-floating');
+  if (!reduced()) {
+    gsap.fromTo(
+      surface,
+      { boxShadow: 'rgba(0, 0, 0, 0) 0px 0px 0px 0px' },
+      { boxShadow: FLOAT_SHADOW, duration: TIMING.float.shadow, ease: EASE.signature, clearProps: 'boxShadow' },
+    );
+  }
+}
+
+const PLACED = [
+  'position',
+  'inset',
+  'right',
+  'bottom',
+  'margin',
+  'margin-top',
+  'margin-right',
+  'margin-bottom',
+  'margin-left',
+  'top',
+  'left',
+  'width',
+  'height',
+  'max-width',
+  'max-height',
+];
+
+/** Remove what liftWindow wrote (no animation). */
+export function unplaceWindow(surface: HTMLElement) {
+  surface.classList.remove('is-floating');
+  for (const name of PLACED) surface.style.removeProperty(name);
+}
+
+/** Put a floating surface back in its place, travelling from where it floated. */
+export function dockWindow(surface: HTMLElement, from: Rect) {
+  registerMotion();
+  unplaceWindow(surface);
+  if (reduced()) return;
+  const to = rectOf(surface);
+  gsap.from(surface, { x: from.left - to.left, y: from.top - to.top, duration: TIMING.float.shadow, ease: EASE.signature, clearProps: 'transform' });
+}
+
+export interface FloatingOptions {
+  key: string;
+  handle: HTMLElement;
+  corners?: HTMLElement[];
+  isFloating: () => boolean;
+  float: () => void;
+  dock: () => void;
+}
+
+/** Move a floating surface by its handle and resize it from its corners. Returns the detach function. */
+export function attachFloating(surface: HTMLElement, { key, handle, corners = [], isFloating, float, dock }: FloatingOptions) {
+  const cleanups: Array<() => void> = [];
+  const listen = (element: HTMLElement, listener: (event: PointerEvent) => void) => {
+    element.addEventListener('pointerdown', listener);
+    cleanups.push(() => element.removeEventListener('pointerdown', listener));
+  };
+  let active: number | null = null;
+  let release: (() => void) | null = null;
+  /**
+   * Follow one pointer until it is released. Moves and the release are heard on
+   * the window, not only through pointer capture: the window moves under the
+   * pointer, and where capture does not hold the gesture must still end.
+   */
+  const capture = (element: HTMLElement, down: PointerEvent, { onMove, onUp }: { onMove: (event: PointerEvent) => void; onUp: () => void }) => {
+    release?.();
+    active = down.pointerId;
+    try {
+      element.setPointerCapture?.(down.pointerId);
+    } catch {
+      // The window listeners below still follow the pointer.
+    }
+    const move = (event: PointerEvent) => {
+      if (event.pointerId === active) onMove(event);
+    };
+    const up = (event: PointerEvent) => {
+      if (event.pointerId !== active) return;
+      stop();
+      onUp();
+    };
+    const stop = () => {
+      active = null;
+      release = null;
+      window.removeEventListener('pointermove', move);
+      window.removeEventListener('pointerup', up);
+      window.removeEventListener('pointercancel', up);
+    };
+    release = stop;
+    window.addEventListener('pointermove', move);
+    window.addEventListener('pointerup', up);
+    window.addEventListener('pointercancel', up);
+  };
+  cleanups.push(() => release?.());
+
+  type Body = {
+    x: number;
+    y: number;
+    vx: number;
+    vy: number;
+    w: number;
+    h: number;
+    targetX: number;
+    targetY: number;
+    targetW: number;
+    targetH: number;
+    mass: number;
+    time: number;
+    gliding: boolean;
+    fromX: number;
+    fromY: number;
+    pointerVx: number;
+    pointerVy: number;
+    pointerX: number;
+    pointerY: number;
+    pointerTime: number;
+  };
+  let body: Body | null = null;
+  const settle = () => {
+    if (!body) return;
+    gsap.ticker.remove(tick);
+    body = null;
+  };
+  function tick() {
+    if (!body) return;
+    const now = performance.now();
+    const elapsed = Math.min((now - body.time) / 1000, 1 / 30);
+    if (elapsed <= 0) return;
+    body.time = now;
+    if (body.gliding) {
+      const decay = Math.exp(-elapsed / TIMING.float.glideDecay);
+      body.vx *= decay;
+      body.vy *= decay;
+    } else {
+      body.vx += (((body.targetX - body.x) * SPRING.stiffness - body.vx * SPRING.damping) * elapsed) / body.mass;
+      body.vy += (((body.targetY - body.y) * SPRING.stiffness - body.vy * SPRING.damping) * elapsed) / body.mass;
+    }
+    body.x += body.vx * elapsed;
+    body.y += body.vy * elapsed;
+    const smoothing = 1 - Math.exp(-elapsed / TIMING.float.sizeSmoothing);
+    body.w += (body.targetW - body.w) * smoothing;
+    body.h += (body.targetH - body.h) * smoothing;
+    if (Math.abs(body.targetW - body.w) < 0.5) body.w = body.targetW;
+    if (Math.abs(body.targetH - body.h) < 0.5) body.h = body.targetH;
+    const rect = clampRect({ top: body.y, left: body.x, width: body.w, height: body.h });
+    if (rect.left !== body.x) {
+      body.x = rect.left;
+      body.vx = 0;
+    }
+    if (rect.top !== body.y) {
+      body.y = rect.top;
+      body.vy = 0;
+    }
+    place(surface, rect);
+    const resting = Math.hypot(body.vx, body.vy) < REST_SPEED && body.w === body.targetW && body.h === body.targetH;
+    if (body.gliding && resting) {
+      saveFloat(key, rect);
+      settle();
+    }
+  }
+
+  listen(handle, (down) => {
+    if (down.button !== 0 || active !== null || !floatingAvailable()) return;
+    down.preventDefault();
+    settle();
+    let moved = false;
+    capture(handle, down, {
+      onMove(event) {
+        const dx = event.clientX - down.clientX;
+        const dy = event.clientY - down.clientY;
+        if (!moved) {
+          if (Math.abs(dx) < LIFT && Math.abs(dy) < LIFT) return;
+          moved = true;
+          if (!isFloating()) float();
+          const rect = rectOf(surface);
+          const fullWidth = innerWidth - MARGIN * 2;
+          const fullHeight = innerHeight - MARGIN * 2;
+          // A window as large as the screen shrinks so it can be moved.
+          const width = rect.width >= fullWidth - 2 ? Math.max(MIN_WIDTH, Math.round(fullWidth * SHRINK_FULL)) : rect.width;
+          const height = rect.height >= fullHeight - 2 ? Math.max(MIN_HEIGHT, Math.round(fullHeight * SHRINK_FULL)) : rect.height;
+          const grip = rect.width > 0 ? (down.clientX - rect.left) / rect.width : 0;
+          const left = rect.left + (rect.width - width) * grip;
+          const now = performance.now();
+          body = {
+            x: left,
+            y: rect.top,
+            vx: 0,
+            vy: 0,
+            w: rect.width,
+            h: rect.height,
+            targetX: left,
+            targetY: rect.top,
+            targetW: width,
+            targetH: height,
+            mass: Math.min(MAX_MASS, Math.max(1, Math.sqrt((rect.width * rect.height) / MASS_AREA))),
+            time: now,
+            gliding: false,
+            fromX: left,
+            fromY: rect.top,
+            pointerVx: 0,
+            pointerVy: 0,
+            pointerX: event.clientX,
+            pointerY: event.clientY,
+            pointerTime: now,
+          };
+          gsap.ticker.add(tick);
+        }
+        if (!body) return;
+        body.targetX = body.fromX + dx;
+        body.targetY = body.fromY + dy;
+        const now = performance.now();
+        const seconds = Math.max(1, now - body.pointerTime) / 1000;
+        const smoothing = 1 - Math.exp(-seconds / POINTER_SMOOTHING);
+        body.pointerVx += ((event.clientX - body.pointerX) / seconds - body.pointerVx) * smoothing;
+        body.pointerVy += ((event.clientY - body.pointerY) / seconds - body.pointerVy) * smoothing;
+        body.pointerX = event.clientX;
+        body.pointerY = event.clientY;
+        body.pointerTime = now;
+      },
+      onUp() {
+        if (!moved) {
+          if (isFloating()) dock();
+          else float();
+          return;
+        }
+        if (!body) return;
+        // A fling keeps gliding; a gentle release stays where it is.
+        const speed = performance.now() - body.pointerTime > 80 ? 0 : Math.hypot(body.pointerVx, body.pointerVy);
+        if (speed >= FLING_SPEED) {
+          body.vx = body.pointerVx;
+          body.vy = body.pointerVy;
+        } else {
+          body.vx = 0;
+          body.vy = 0;
+          body.targetX = body.x;
+          body.targetY = body.y;
+        }
+        body.gliding = true;
+      },
+    });
+  });
+
+  for (const corner of corners) {
+    listen(corner, (down) => {
+      if (down.button !== 0 || active !== null || !floatingAvailable()) return;
+      down.preventDefault();
+      settle();
+      const side = corner.dataset.mkFloatCorner ?? 'br';
+      const fromLeft = side.endsWith('l');
+      const fromTop = side.startsWith('t');
+      let start: Rect | null = null;
+      capture(corner, down, {
+        onMove(event) {
+          const dx = event.clientX - down.clientX;
+          const dy = event.clientY - down.clientY;
+          if (!start) {
+            if (Math.abs(dx) < LIFT && Math.abs(dy) < LIFT) return;
+            if (!isFloating()) float();
+            start = rectOf(surface);
+          }
+          const width = Math.min(innerWidth - MARGIN * 2, Math.max(MIN_WIDTH, fromLeft ? start.width - dx : start.width + dx));
+          const height = Math.min(innerHeight - MARGIN * 2, Math.max(MIN_HEIGHT, fromTop ? start.height - dy : start.height + dy));
+          place(
+            surface,
+            clampRect({
+              top: fromTop ? start.top + start.height - height : start.top,
+              left: fromLeft ? start.left + start.width - width : start.left,
+              width,
+              height,
+            }),
+          );
+        },
+        onUp() {
+          if (start) saveFloat(key, rectOf(surface));
+        },
+      });
+    });
+  }
+
+  return () => {
+    if (body?.gliding) saveFloat(key, rectOf(surface));
+    settle();
+    for (const cleanup of cleanups) cleanup();
+  };
+}

package/src/motion/flow.ts

@@ -0,0 +1,115 @@
+import { gsap, EASE, registerMotion } from '../core/gsap';
+import { reduced } from '../core/reduced';
+import { TIMING } from '../core/timing';
+import { nextFrame } from '../core/frame';
+import { clearStyles } from '../core/styles';
+
+/*
+ * Stepbro flowIn / flowOut: items drop in from 20 px above out of a 16 px blur,
+ * 0.5 s, 50 ms apart (`flowSoft`), and leave 20 px down into the same blur.
+ * Style 2 grows them from 90 % instead of moving them.
+ */
+
+export interface FlowInOptions {
+  /** Distance travelled (style 1), px. */
+  y?: number;
+  blur?: number;
+  duration?: number;
+  stagger?: number;
+  delay?: number;
+  /** 1: drop from above (default). 2: grow from `startScale`. */
+  style?: 1 | 2;
+  startScale?: number;
+  /** Last item first. */
+  reverse?: boolean;
+  /** With a single container as target, animate its matches instead. */
+  target?: string;
+  ease?: string;
+  /**
+   * Hide with visibility as well as opacity (default). Off for controls that must
+   * take focus while they enter (menu options): a visibility:hidden element cannot.
+   */
+  autoAlpha?: boolean;
+}
+
+export interface FlowOutOptions {
+  y?: number;
+  blur?: number;
+  duration?: number;
+  stagger?: number;
+  delay?: number;
+  reverse?: boolean;
+  target?: string;
+}
+
+const CLEAR = 'transform,filter,opacity,visibility';
+
+function list(targets: gsap.TweenTarget, target?: string, reverse?: boolean): HTMLElement[] {
+  let items: HTMLElement[];
+  if (target && targets instanceof Element) items = [...targets.querySelectorAll<HTMLElement>(target)];
+  else items = gsap.utils.toArray<HTMLElement>(targets);
+  return reverse ? items.reverse() : items;
+}
+
+/** Flow items in. Returns the tween, or null when there is nothing to animate or motion is reduced. */
+export function flowIn(targets: gsap.TweenTarget, options: FlowInOptions = {}): gsap.core.Tween | null {
+  registerMotion();
+  const {
+    y = 20,
+    blur = 16,
+    duration = TIMING.flow,
+    stagger = TIMING.flowStagger,
+    delay = 0,
+    style = 1,
+    startScale = 0.9,
+    reverse = false,
+    target,
+    ease = EASE.flow,
+    autoAlpha = true,
+  } = options;
+  const items = list(targets, target, reverse);
+  if (!items.length) return null;
+  if (reduced()) {
+    // Not gsap.set(clearProps): it would move hidden items around to measure them.
+    clearStyles(items, ['transform', 'translate', 'rotate', 'scale', 'filter', 'opacity', 'visibility']);
+    return null;
+  }
+  const from = style === 2 ? { scale: startScale } : { y: -y };
+  const to = style === 2 ? { scale: 1 } : { y: 0 };
+  const alpha = autoAlpha ? 'autoAlpha' : 'opacity';
+  return gsap.fromTo(
+    items,
+    { ...from, [alpha]: 0, filter: `blur(${blur}px)` },
+    { ...to, [alpha]: 1, filter: 'blur(0px)', duration, stagger, delay, ease, clearProps: CLEAR },
+  );
+}
+
+/** Flow items out (down into a blur). They stay hidden afterwards; flowIn brings them back. */
+export function flowOut(targets: gsap.TweenTarget, options: FlowOutOptions = {}): gsap.core.Tween | null {
+  registerMotion();
+  const { y = 20, blur = 16, duration = TIMING.flow, stagger = TIMING.flowStagger, delay = 0, reverse = false, target } = options;
+  const items = list(targets, target, reverse);
+  if (!items.length) return null;
+  if (reduced()) {
+    gsap.set(items, { autoAlpha: 0 });
+    return null;
+  }
+  return gsap.to(items, { y, autoAlpha: 0, filter: `blur(${blur}px)`, duration, stagger, delay, ease: EASE.flow });
+}
+
+/**
+ * Stepbro's step change: the current children flow out, `mutate` swaps the
+ * content (render the next step there), and after a frame the new children flow in.
+ */
+export async function stepChange(
+  container: HTMLElement,
+  mutate: () => void | Promise<void>,
+  { duration = TIMING.stepChange }: { duration?: number } = {},
+): Promise<void> {
+  const before = [...container.children] as HTMLElement[];
+  const out = flowOut(before, { duration });
+  if (out) await out;
+  await mutate();
+  await nextFrame();
+  flowIn([...container.children] as HTMLElement[], { duration });
+}

package/src/motion/indicator.ts

@@ -0,0 +1,44 @@
+import { gsap, EASE, registerMotion } from '../core/gsap';
+import { reduced } from '../core/reduced';
+import { TIMING } from '../core/timing';
+
+/*
+ * Stepbro's PrettyTabs: the indicator fits the selected option's box in 0.45 s
+ * on the signature curve (Flip.fit in the original; here the same box is
+ * tweened directly). The indicator is an absolutely positioned child at 0,0 of
+ * the group. A scrolling group centres the selected option.
+ */
+
+export interface IndicatorOptions {
+  immediate?: boolean;
+  duration?: number;
+  /** Scroll container to centre the target in (when it overflows). */
+  scroller?: HTMLElement | null;
+  orientation?: 'horizontal' | 'vertical';
+}
+
+export function slideIndicator(indicator: HTMLElement, target: HTMLElement | null, options: IndicatorOptions = {}) {
+  registerMotion();
+  const { immediate = false, duration = TIMING.indicator, scroller, orientation = 'horizontal' } = options;
+  gsap.killTweensOf(indicator);
+  if (!target) {
+    gsap.set(indicator, { opacity: 0 });
+    return null;
+  }
+  const box = { x: target.offsetLeft, y: target.offsetTop, width: target.offsetWidth, height: target.offsetHeight, opacity: 1 };
+  if (scroller) {
+    const horizontal = orientation === 'horizontal';
+    const overflow = horizontal ? scroller.scrollWidth > scroller.clientWidth : scroller.scrollHeight > scroller.clientHeight;
+    if (overflow && typeof scroller.scrollTo === 'function') {
+      const offset = horizontal
+        ? box.x - (scroller.clientWidth - box.width) / 2
+        : box.y - (scroller.clientHeight - box.height) / 2;
+      scroller.scrollTo({ [horizontal ? 'left' : 'top']: offset, behavior: immediate || reduced() ? 'auto' : 'smooth' });
+    }
+  }
+  if (immediate || reduced()) {
+    gsap.set(indicator, box);
+    return null;
+  }
+  return gsap.to(indicator, { ...box, duration, ease: EASE.signature });
+}

package/src/motion/layout.ts

@@ -0,0 +1,39 @@
+import { gsap, Flip, EASE, registerMotion } from '../core/gsap';
+import { reduced } from '../core/reduced';
+import { TIMING } from '../core/timing';
+
+/*
+ * Stepbro's layout reflow: items that changed place travel there on a spring
+ * (0.62 s, ratio .52) and new ones grow in (scale .94, in 60 % of the time).
+ * Capture before the DOM change, reflow after it; items pair by `data-flip-id`.
+ * Don't make the items `position: absolute` — the list would collapse.
+ */
+
+export interface CapturedLayout {
+  state: ReturnType<typeof Flip.getState>;
+  ids: Set<string | undefined>;
+}
+
+export function captureLayout(root: Element, selector: string): CapturedLayout {
+  registerMotion();
+  const items = [...root.querySelectorAll<HTMLElement>(selector)];
+  return { state: Flip.getState(items), ids: new Set(items.map((item) => item.dataset.flipId)) };
+}
+
+export function reflowLayout(root: Element, selector: string, captured: CapturedLayout, { duration = TIMING.layoutTravel }: { duration?: number } = {}) {
+  registerMotion();
+  if (reduced()) return null;
+  const targets = [...root.querySelectorAll<HTMLElement>(selector)];
+  return Flip.from(captured.state, {
+    targets,
+    duration,
+    ease: EASE.layoutReflow,
+    zIndex: 3,
+    onEnter: (elements) =>
+      gsap.fromTo(
+        elements,
+        { opacity: 0, scale: 0.94 },
+        { opacity: 1, scale: 1, duration: duration * TIMING.layoutEnterFactor, ease: EASE.layoutReflow, clearProps: 'opacity,transform' },
+      ),
+  });
+}