@sweberdev/lagrangian 0.1.0

package/src/drag.ts

@@ -0,0 +1,174 @@
+// Drag an element with the pointer and throw it: rubber-band past the bounds, glide with
+// friction on release, settle on snap points. The element moves via its x/y physical values,
+// so `animate()` and a drag can hand over to each other at any moment.
+
+import { getValue } from "./animate";
+import { rubberClamp, type Snap } from "./decay";
+import type { SpringOptions } from "./spring";
+import type { PhysicsValue } from "./value";
+
+export interface Bounds {
+  left?: number;
+  right?: number;
+  top?: number;
+  bottom?: number;
+}
+
+export interface DragInfo {
+  x: number;
+  y: number;
+  velocityX: number;
+  velocityY: number;
+}
+
+export interface DraggableOptions {
+  /** Restrict movement to one axis. Default "both". */
+  axis?: "x" | "y" | "both";
+  /**
+   * Movement limits in pixels relative to the start position, or an element the dragged
+   * element has to stay inside.
+   */
+  bounds?: Bounds | Element | (() => Bounds | Element);
+  /** Resistance past the bounds, 0 to 1 (0.55 like iOS), or false to stop hard at the edge. */
+  rubberband?: number | false;
+  /** Keep moving with friction after release. Default true. */
+  inertia?: boolean;
+  /** Fraction of speed kept per millisecond during the throw. Default 0.998. */
+  deceleration?: number;
+  /** Snap points per axis, in pixels relative to the start position. */
+  snap?: { x?: Snap; y?: Snap };
+  /** Spring for snapping and for bouncing off the bounds. */
+  spring?: SpringOptions;
+  onStart?: (info: DragInfo) => void;
+  onMove?: (info: DragInfo) => void;
+  /** Called on release with the throw velocity. */
+  onEnd?: (info: DragInfo) => void;
+}
+
+export interface Draggable {
+  readonly x: PhysicsValue;
+  readonly y: PhysicsValue;
+  readonly dragging: boolean;
+  destroy(): void;
+}
+
+type Range = [number, number];
+const FREE: Range = [Number.NEGATIVE_INFINITY, Number.POSITIVE_INFINITY];
+
+function ranges(element: Element, x: number, y: number, bounds: DraggableOptions["bounds"]) {
+  const b = typeof bounds === "function" ? bounds() : bounds;
+  if (!b) return { x: FREE, y: FREE };
+  if (typeof Element !== "undefined" && b instanceof Element) {
+    const outer = b.getBoundingClientRect();
+    const inner = element.getBoundingClientRect();
+    // Origin of the element without its current translation.
+    const left = inner.left - x;
+    const top = inner.top - y;
+    return {
+      x: [outer.left - left, outer.right - left - inner.width] as Range,
+      y: [outer.top - top, outer.bottom - top - inner.height] as Range,
+    };
+  }
+  const box = b as Bounds;
+  return {
+    x: [box.left ?? FREE[0], box.right ?? FREE[1]] as Range,
+    y: [box.top ?? FREE[0], box.bottom ?? FREE[1]] as Range,
+  };
+}
+
+/** Makes an element draggable and throwable. */
+export function draggable(element: HTMLElement, options: DraggableOptions = {}): Draggable {
+  const axis = options.axis ?? "both";
+  const x = getValue(element, "x");
+  const y = getValue(element, "y");
+  const moveX = axis !== "y";
+  const moveY = axis !== "x";
+  let pointer: number | null = null;
+  let start = { px: 0, py: 0, x: 0, y: 0 };
+  let range = { x: FREE, y: FREE };
+
+  const info = (): DragInfo => ({
+    x: x.get(),
+    y: y.get(),
+    velocityX: x.velocity,
+    velocityY: y.velocity,
+  });
+
+  const previousTouchAction = element.style.touchAction;
+  element.style.touchAction = axis === "x" ? "pan-y" : axis === "y" ? "pan-x" : "none";
+
+  const place = (value: number, [min, max]: Range, dimension: number) => {
+    if (options.rubberband === false) return Math.min(Math.max(value, min), max);
+    return rubberClamp(value, min, max, dimension, options.rubberband ?? 0.55);
+  };
+
+  const down = (event: PointerEvent) => {
+    if (pointer !== null || (event.pointerType === "mouse" && event.button !== 0)) return;
+    pointer = event.pointerId;
+    element.setPointerCapture?.(event.pointerId);
+    x.stop();
+    y.stop();
+    start = { px: event.clientX, py: event.clientY, x: x.get(), y: y.get() };
+    range = ranges(element, start.x, start.y, options.bounds);
+    // Grabbing stops the momentum; the samples from here on give the throw velocity.
+    x.jump(start.x);
+    y.jump(start.y);
+    if (moveX) x.set(start.x);
+    if (moveY) y.set(start.y);
+    options.onStart?.(info());
+  };
+
+  const move = (event: PointerEvent) => {
+    if (event.pointerId !== pointer) return;
+    const viewport =
+      typeof window !== "undefined" ? window : { innerWidth: 1000, innerHeight: 1000 };
+    if (moveX) x.set(place(start.x + event.clientX - start.px, range.x, viewport.innerWidth));
+    if (moveY) y.set(place(start.y + event.clientY - start.py, range.y, viewport.innerHeight));
+    options.onMove?.(info());
+  };
+
+  const release = (value: PhysicsValue, [min, max]: Range, snap: Snap | undefined) => {
+    const throwOptions = {
+      min,
+      max,
+      bounce: options.spring,
+      ...(options.deceleration !== undefined ? { deceleration: options.deceleration } : {}),
+      ...(snap !== undefined ? { snap } : {}),
+    };
+    if (options.inertia !== false) {
+      value.throw(throwOptions);
+      return;
+    }
+    // Without inertia only snap points and bounds move the element after release.
+    value.throw({ ...throwOptions, velocity: 0 });
+  };
+
+  const up = (event: PointerEvent) => {
+    if (event.pointerId !== pointer) return;
+    pointer = null;
+    element.releasePointerCapture?.(event.pointerId);
+    options.onEnd?.(info());
+    if (moveX) release(x, range.x, options.snap?.x);
+    if (moveY) release(y, range.y, options.snap?.y);
+  };
+
+  element.addEventListener("pointerdown", down);
+  element.addEventListener("pointermove", move);
+  element.addEventListener("pointerup", up);
+  element.addEventListener("pointercancel", up);
+
+  return {
+    x,
+    y,
+    get dragging() {
+      return pointer !== null;
+    },
+    destroy() {
+      element.removeEventListener("pointerdown", down);
+      element.removeEventListener("pointermove", move);
+      element.removeEventListener("pointerup", up);
+      element.removeEventListener("pointercancel", up);
+      element.style.touchAction = previousTouchAction;
+    },
+  };
+}

package/src/index.ts

@@ -0,0 +1,54 @@
+export {
+  type AnimateOptions,
+  animate,
+  getValue,
+  type Prop,
+  type Props,
+  set,
+  type TransformProp,
+} from "./animate";
+export {
+  type DecayOptions,
+  decay,
+  nearest,
+  projectRest,
+  rubberband,
+  rubberClamp,
+  type Snap,
+  timeConstant,
+} from "./decay";
+export {
+  type Bounds,
+  type Draggable,
+  type DraggableOptions,
+  type DragInfo,
+  draggable,
+} from "./drag";
+export { type Derivatives, rk4, type System, system } from "./integrate";
+export { loop, now, type Task } from "./loop";
+export { type ReducedMotion, reducedMotion, setReducedMotion } from "./reduced-motion";
+export {
+  dampingRatio,
+  type Motion,
+  type MotionState,
+  restValue,
+  type SpringOptions,
+  type SpringParams,
+  settleTime,
+  spring,
+  springParams,
+} from "./spring";
+export { type Animation, type Listener, PhysicsValue, value } from "./value";
+export { VelocityTracker } from "./velocity";
+export {
+  type Body,
+  type BodyOptions,
+  type Grab,
+  type Link,
+  type LinkOptions,
+  type Rect,
+  type Vector,
+  World,
+  type WorldOptions,
+  world,
+} from "./world";

package/src/integrate.ts

@@ -0,0 +1,61 @@
+// Runge-Kutta 4 for your own equations of motion, e.g. derived from a Lagrangian.
+// Write the system as first-order derivatives of a state vector and step it.
+
+/** Returns d(state)/dt for a state at time t. */
+export type Derivatives = (state: readonly number[], t: number) => number[];
+
+/** One classic fourth-order Runge-Kutta step of size `dt`. */
+export function rk4(state: readonly number[], t: number, dt: number, f: Derivatives): number[] {
+  const n = state.length;
+  const add = (k: readonly number[], h: number) => state.map((s, i) => s + (k[i] ?? 0) * h);
+  const k1 = f(state, t);
+  const k2 = f(add(k1, dt / 2), t + dt / 2);
+  const k3 = f(add(k2, dt / 2), t + dt / 2);
+  const k4 = f(add(k3, dt), t + dt);
+  const next = new Array<number>(n);
+  for (let i = 0; i < n; i++) {
+    next[i] =
+      (state[i] ?? 0) +
+      (dt / 6) * ((k1[i] ?? 0) + 2 * (k2[i] ?? 0) + 2 * (k3[i] ?? 0) + (k4[i] ?? 0));
+  }
+  return next;
+}
+
+export interface System {
+  /** Current state vector. */
+  readonly state: readonly number[];
+  /** Simulated time in seconds. */
+  readonly time: number;
+  /** Advances by `seconds` in fixed steps, so results do not depend on the frame rate. */
+  advance(seconds: number): readonly number[];
+  /** Replaces the state, e.g. after the user grabbed something. */
+  reset(state: readonly number[]): void;
+}
+
+/** A system of ODEs stepped with RK4 at a fixed step (default 1/240 s). */
+export function system(f: Derivatives, initial: readonly number[], step = 1 / 240): System {
+  let state = [...initial];
+  let time = 0;
+  let pending = 0;
+  return {
+    get state() {
+      return state;
+    },
+    get time() {
+      return time;
+    },
+    advance(seconds) {
+      pending += seconds;
+      while (pending >= step) {
+        state = rk4(state, time, step, f);
+        time += step;
+        pending -= step;
+      }
+      return state;
+    },
+    reset(next) {
+      state = [...next];
+      pending = 0;
+    },
+  };
+}

package/src/loop.ts

@@ -0,0 +1,73 @@
+// One shared frame loop for every running value and world.
+// Tasks get the frame time step in seconds. A long pause (hidden tab, debugger) is clamped so a
+// simulation never takes one giant step and objects never fly through walls.
+
+export type Task = (dt: number, now: number) => void;
+
+const MAX_DT = 1 / 20;
+const tasks = new Set<Task>();
+let scheduled = false;
+let manual = false;
+let last = -1;
+let clock = 0;
+
+const hasRaf = () => typeof requestAnimationFrame === "function";
+
+function schedule(): void {
+  if (scheduled || manual || tasks.size === 0) return;
+  scheduled = true;
+  if (hasRaf()) requestAnimationFrame(frame);
+  else setTimeout(() => frame(now()), 16);
+}
+
+function frame(time: number): void {
+  scheduled = false;
+  if (manual) return;
+  const dt = last < 0 ? 1 / 60 : Math.min(Math.max((time - last) / 1000, 0), MAX_DT);
+  last = time;
+  run(dt, time);
+  if (tasks.size > 0) schedule();
+  else last = -1;
+}
+
+function run(dt: number, time: number): void {
+  for (const task of [...tasks]) {
+    if (tasks.has(task)) task(dt, time);
+  }
+}
+
+/** Current time in milliseconds, from the manual clock while the loop is in manual mode. */
+export function now(): number {
+  if (manual) return clock;
+  return typeof performance !== "undefined" ? performance.now() : Date.now();
+}
+
+export const loop = {
+  /** Runs `task` on every frame until the returned function is called. */
+  add(task: Task): () => void {
+    tasks.add(task);
+    schedule();
+    return () => {
+      tasks.delete(task);
+    };
+  },
+  /**
+   * Switches to manual stepping (for tests, server rendering or video export) or back to
+   * requestAnimationFrame.
+   */
+  manual(on = true): void {
+    manual = on;
+    last = -1;
+    if (!on) schedule();
+  },
+  /** Advances the manual clock by `ms` and runs one frame. Only has an effect in manual mode. */
+  step(ms = 1000 / 60): void {
+    if (!manual) return;
+    clock += ms;
+    run(Math.min(ms / 1000, MAX_DT), clock);
+  },
+  /** Number of running tasks. */
+  get size(): number {
+    return tasks.size;
+  },
+};

package/src/reduced-motion.ts

@@ -0,0 +1,17 @@
+export type ReducedMotion = "user" | "always" | "never";
+
+let mode: ReducedMotion = "user";
+
+/**
+ * "user" (default) follows the prefers-reduced-motion setting, "always" skips animated
+ * transitions everywhere, "never" ignores the setting. Direct manipulation (dragging, the
+ * world simulation) always follows the pointer; only automatic motion is skipped.
+ */
+export function setReducedMotion(value: ReducedMotion): void {
+  mode = value;
+}
+
+export function reducedMotion(): boolean {
+  if (mode !== "user") return mode === "always";
+  return typeof matchMedia === "function" && matchMedia("(prefers-reduced-motion: reduce)").matches;
+}

package/src/spring.ts

@@ -0,0 +1,140 @@
+// Damped harmonic oscillator, solved in closed form: m·x'' + c·x' + k·(x − target) = 0.
+// The exact solution means there is no integration error, no frame-rate dependence, and the
+// position and velocity at any moment are known, which is what makes interruptions seamless.
+
+/** Position and velocity of a motion at one moment. */
+export interface MotionState {
+  value: number;
+  velocity: number;
+  done: boolean;
+}
+
+/** A motion maps elapsed seconds to a state. Springs, decay and your own functions fit this. */
+export type Motion = (t: number) => MotionState;
+
+export interface SpringOptions {
+  /** Spring constant k. Higher is snappier. Default 170. */
+  stiffness?: number;
+  /** Damping coefficient c. Lower bounces more. Default 26. */
+  damping?: number;
+  /** Mass m. Heavier is slower and carries more momentum. Default 1. */
+  mass?: number;
+  /**
+   * Perceptual duration in seconds, used together with `bounce` instead of
+   * stiffness and damping (as in SwiftUI). It is the period of the undamped spring.
+   */
+  duration?: number;
+  /** -1 to 1. 0 is critically damped, 0.3 is a gentle bounce, negative values are overdamped. */
+  bounce?: number;
+  /** The motion counts as finished once it is this close to the target... */
+  restDelta?: number;
+  /** ...and slower than this (units per second). */
+  restSpeed?: number;
+}
+
+export interface SpringParams {
+  stiffness: number;
+  damping: number;
+  mass: number;
+}
+
+/** Resolves stiffness, damping and mass, also from `duration` and `bounce`. */
+export function springParams(options: SpringOptions = {}): SpringParams {
+  const mass = options.mass ?? 1;
+  if (options.duration !== undefined || options.bounce !== undefined) {
+    const duration = Math.max(options.duration ?? 0.5, 0.01);
+    const bounce = Math.min(Math.max(options.bounce ?? 0, -0.99), 1);
+    const omega = (2 * Math.PI) / duration;
+    const zeta = bounce >= 0 ? 1 - bounce : 1 / (1 + bounce);
+    return { stiffness: mass * omega * omega, damping: 2 * mass * zeta * omega, mass };
+  }
+  return { stiffness: options.stiffness ?? 170, damping: options.damping ?? 26, mass };
+}
+
+/** Damping ratio: below 1 the spring overshoots, 1 is critical, above 1 it creeps. */
+export function dampingRatio(options: SpringOptions = {}): number {
+  const { stiffness, damping, mass } = springParams(options);
+  return damping / (2 * Math.sqrt(stiffness * mass));
+}
+
+export function restThresholds(from: number, to: number, options: SpringOptions = {}) {
+  const span = Math.max(Math.abs(to - from), Math.abs(to) * 0.01, 1e-3);
+  const restDelta = options.restDelta ?? Math.min(Math.max(span * 1e-3, 1e-4), 0.5);
+  return { restDelta, restSpeed: options.restSpeed ?? restDelta * 10 };
+}
+
+/**
+ * A spring from `from` to `to`, starting with `velocity` (units per second).
+ * Returns the exact state for any elapsed time.
+ */
+export function spring(
+  from: number,
+  to: number,
+  velocity = 0,
+  options: SpringOptions = {},
+): Motion {
+  const { stiffness: k, damping: c, mass: m } = springParams(options);
+  const { restDelta, restSpeed } = restThresholds(from, to, options);
+  const d0 = from - to;
+  const v0 = velocity;
+  const w0 = Math.sqrt(k / m);
+  const zeta = c / (2 * Math.sqrt(k * m));
+
+  let displacement: (t: number) => [number, number];
+  if (zeta < 1 - 1e-6) {
+    const a = zeta * w0;
+    const wd = w0 * Math.sqrt(1 - zeta * zeta);
+    const B = (v0 + a * d0) / wd;
+    displacement = (t) => {
+      const e = Math.exp(-a * t);
+      const cos = Math.cos(wd * t);
+      const sin = Math.sin(wd * t);
+      return [e * (d0 * cos + B * sin), e * ((B * wd - a * d0) * cos - (a * B + d0 * wd) * sin)];
+    };
+  } else if (zeta <= 1 + 1e-6) {
+    const B = v0 + w0 * d0;
+    displacement = (t) => {
+      const e = Math.exp(-w0 * t);
+      return [e * (d0 + B * t), e * (v0 - w0 * B * t)];
+    };
+  } else {
+    const s = Math.sqrt(zeta * zeta - 1);
+    const r1 = -w0 * (zeta - s);
+    const r2 = -w0 * (zeta + s);
+    const c1 = (v0 - r2 * d0) / (r1 - r2);
+    const c2 = d0 - c1;
+    displacement = (t) => {
+      const e1 = Math.exp(r1 * t);
+      const e2 = Math.exp(r2 * t);
+      return [c1 * e1 + c2 * e2, c1 * r1 * e1 + c2 * r2 * e2];
+    };
+  }
+
+  return (t) => {
+    const [x, v] = displacement(Math.max(t, 0));
+    if (Math.abs(x) <= restDelta && Math.abs(v) <= restSpeed) {
+      return { value: to, velocity: 0, done: true };
+    }
+    return { value: to + x, velocity: v, done: false };
+  };
+}
+
+/**
+ * Seconds until a motion settles, sampled at 1 ms. Returns Infinity when it does not settle
+ * within `limit` seconds (an undamped spring never does).
+ */
+export function settleTime(motion: Motion, limit = 30): number {
+  for (let t = 0; t <= limit; t += 1 / 1000) {
+    if (motion(t).done) return t;
+  }
+  return Number.POSITIVE_INFINITY;
+}
+
+/** The value a motion comes to rest at, or its value after `limit` seconds. */
+export function restValue(motion: Motion, limit = 30): number {
+  for (let t = 0; t <= limit; t += 1 / 60) {
+    const state = motion(t);
+    if (state.done) return state.value;
+  }
+  return motion(limit).value;
+}

package/src/value.ts

@@ -0,0 +1,147 @@
+// A number with momentum. It always knows its velocity, so a new animation, a throw or a drag
+// can take over mid-flight without a jolt: the physics continues from the current state.
+
+import { type DecayOptions, decay } from "./decay";
+import { loop, now } from "./loop";
+import { reducedMotion } from "./reduced-motion";
+import { type Motion, restValue, type SpringOptions, spring } from "./spring";
+import { VelocityTracker } from "./velocity";
+
+/** A running animation. Await `finished` to know whether it completed. */
+export interface Animation {
+  /** Resolves with true when the motion came to rest, false when it was interrupted. */
+  readonly finished: Promise<boolean>;
+  stop(): void;
+}
+
+export type Listener = (value: number, velocity: number) => void;
+
+export function settled(value: boolean): Animation {
+  const finished = Promise.resolve(value);
+  return { finished, stop() {} };
+}
+
+export class PhysicsValue {
+  #value: number;
+  #velocity = 0;
+  #tracked = false;
+  #listeners = new Set<Listener>();
+  #tracker = new VelocityTracker();
+  #cancel: (() => void) | null = null;
+  #resolve: ((completed: boolean) => void) | null = null;
+
+  constructor(initial = 0) {
+    this.#value = initial;
+  }
+
+  get(): number {
+    return this.#value;
+  }
+
+  /** Units per second, from the running motion or from recent `set` calls. */
+  get velocity(): number {
+    return this.#tracked ? this.#tracker.velocity(now()) : this.#velocity;
+  }
+
+  get animating(): boolean {
+    return this.#cancel !== null;
+  }
+
+  /** Sets the value directly (e.g. while dragging). Stops any motion and tracks the velocity. */
+  set(value: number): void {
+    this.#halt(false);
+    this.#tracked = true;
+    this.#tracker.add(now(), value);
+    this.#velocity = this.#tracker.velocity();
+    this.#emit(value);
+  }
+
+  /** Sets the value and drops all momentum. */
+  jump(value: number): void {
+    this.#halt(false);
+    this.#tracker.reset();
+    this.#tracked = false;
+    this.#velocity = 0;
+    this.#emit(value);
+  }
+
+  /** Springs to `target`, starting from the current position and velocity. */
+  to(target: number, options: SpringOptions & { velocity?: number } = {}): Animation {
+    const from = this.#value;
+    return this.start(spring(from, target, options.velocity ?? this.velocity, options));
+  }
+
+  /** Throws the value with friction, optionally into bounds or onto snap points. */
+  throw(options: DecayOptions = {}): Animation {
+    return this.start(
+      decay(this.#value, { ...options, velocity: options.velocity ?? this.velocity }),
+    );
+  }
+
+  /** Runs any motion. Elapsed time starts at 0 on the next frame. */
+  start(motion: Motion): Animation {
+    this.#halt(false);
+    if (reducedMotion()) {
+      this.jump(restValue(motion));
+      return settled(true);
+    }
+    let elapsed = 0;
+    let resolve!: (completed: boolean) => void;
+    const finished = new Promise<boolean>((r) => {
+      resolve = r;
+    });
+    this.#resolve = resolve;
+    const remove = loop.add((dt) => {
+      elapsed += dt;
+      const state = motion(elapsed);
+      this.#velocity = state.velocity;
+      this.#emit(state.value);
+      if (state.done) this.#halt(true);
+    });
+    this.#cancel = remove;
+    this.#tracked = false;
+    this.#tracker.reset();
+    return {
+      finished,
+      stop: () => {
+        if (this.#resolve === resolve) this.#halt(false);
+      },
+    };
+  }
+
+  /** Stops where it is. The velocity is kept, so a following `to` or `throw` continues it. */
+  stop(): void {
+    this.#halt(false);
+  }
+
+  /** Calls `listener` on every change. Returns the unsubscribe function. */
+  on(listener: Listener): () => void {
+    this.#listeners.add(listener);
+    return () => {
+      this.#listeners.delete(listener);
+    };
+  }
+
+  #emit(value: number): void {
+    this.#value = value;
+    for (const listener of [...this.#listeners]) listener(value, this.#velocity);
+  }
+
+  #halt(completed: boolean): void {
+    const cancel = this.#cancel;
+    const resolve = this.#resolve;
+    this.#cancel = null;
+    this.#resolve = null;
+    if (cancel) {
+      cancel();
+      // Interrupted motions keep their momentum for whatever comes next.
+      if (completed) this.#velocity = 0;
+    }
+    resolve?.(completed);
+  }
+}
+
+/** Creates a value with momentum. */
+export function value(initial = 0): PhysicsValue {
+  return new PhysicsValue(initial);
+}