@sweberdev/lagrangian 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,382 @@
+/** Position and velocity of a motion at one moment. */
+interface MotionState {
+    value: number;
+    velocity: number;
+    done: boolean;
+}
+/** A motion maps elapsed seconds to a state. Springs, decay and your own functions fit this. */
+type Motion = (t: number) => MotionState;
+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;
+}
+interface SpringParams {
+    stiffness: number;
+    damping: number;
+    mass: number;
+}
+/** Resolves stiffness, damping and mass, also from `duration` and `bounce`. */
+declare function springParams(options?: SpringOptions): SpringParams;
+/** Damping ratio: below 1 the spring overshoots, 1 is critical, above 1 it creeps. */
+declare function dampingRatio(options?: SpringOptions): number;
+/**
+ * A spring from `from` to `to`, starting with `velocity` (units per second).
+ * Returns the exact state for any elapsed time.
+ */
+declare function spring(from: number, to: number, velocity?: number, options?: SpringOptions): Motion;
+/**
+ * Seconds until a motion settles, sampled at 1 ms. Returns Infinity when it does not settle
+ * within `limit` seconds (an undamped spring never does).
+ */
+declare function settleTime(motion: Motion, limit?: number): number;
+/** The value a motion comes to rest at, or its value after `limit` seconds. */
+declare function restValue(motion: Motion, limit?: number): number;
+
+type Snap = readonly number[] | ((restingPoint: number) => number);
+interface DecayOptions {
+    /** Starting velocity in units per second. Defaults to the value's current velocity. */
+    velocity?: number;
+    /**
+     * Fraction of speed kept per millisecond. 0.998 is the iOS "normal" scroll feel (default),
+     * 0.99 is "fast" and stops much sooner.
+     */
+    deceleration?: number;
+    /** Lower bound. Crossing it hands over to a spring that settles on the edge. */
+    min?: number;
+    /** Upper bound. */
+    max?: number;
+    /** Snap points, or a function that maps the natural resting point to a snapped one. */
+    snap?: Snap;
+    /** Spring used at the edges and when a snap point needs a spring. */
+    bounce?: SpringOptions;
+    /** The motion ends once it is this close to its resting point. Default 0.5. */
+    restDelta?: number;
+}
+declare function timeConstant(deceleration?: number): number;
+/** Where a throw with this velocity comes to rest without bounds or snap points. */
+declare function projectRest(from: number, velocity: number, deceleration?: number): number;
+/** Nearest snap point to `value`. */
+declare function nearest(points: readonly number[], value: number): number;
+/** A throw with friction from `from`, optionally with bounds and snap points. */
+declare function decay(from: number, options?: DecayOptions): Motion;
+/**
+ * Elastic overscroll, as on iOS: the further past the edge, the harder it pulls back.
+ * `distance` is how far past the edge, `dimension` the size of the visible area.
+ */
+declare function rubberband(distance: number, dimension: number, constant?: number): number;
+/** Applies `rubberband` to a value outside [min, max]. Values inside stay unchanged. */
+declare function rubberClamp(value: number, min: number, max: number, dimension: number, constant?: number): number;
+
+/** A running animation. Await `finished` to know whether it completed. */
+interface Animation {
+    /** Resolves with true when the motion came to rest, false when it was interrupted. */
+    readonly finished: Promise<boolean>;
+    stop(): void;
+}
+type Listener = (value: number, velocity: number) => void;
+declare class PhysicsValue {
+    #private;
+    constructor(initial?: number);
+    get(): number;
+    /** Units per second, from the running motion or from recent `set` calls. */
+    get velocity(): number;
+    get animating(): boolean;
+    /** Sets the value directly (e.g. while dragging). Stops any motion and tracks the velocity. */
+    set(value: number): void;
+    /** Sets the value and drops all momentum. */
+    jump(value: number): void;
+    /** Springs to `target`, starting from the current position and velocity. */
+    to(target: number, options?: SpringOptions & {
+        velocity?: number;
+    }): Animation;
+    /** Throws the value with friction, optionally into bounds or onto snap points. */
+    throw(options?: DecayOptions): Animation;
+    /** Runs any motion. Elapsed time starts at 0 on the next frame. */
+    start(motion: Motion): Animation;
+    /** Stops where it is. The velocity is kept, so a following `to` or `throw` continues it. */
+    stop(): void;
+    /** Calls `listener` on every change. Returns the unsubscribe function. */
+    on(listener: Listener): () => void;
+}
+/** Creates a value with momentum. */
+declare function value(initial?: number): PhysicsValue;
+
+type TransformProp = "x" | "y" | "z" | "scale" | "scaleX" | "scaleY" | "rotate";
+type Prop = TransformProp | "opacity" | `--${string}`;
+type Props = Partial<Record<Prop, number>>;
+interface AnimateOptions extends SpringOptions {
+    /** Starting velocity per property, e.g. from a gesture. */
+    velocity?: Props;
+    /** Seconds to wait before starting. */
+    delay?: number;
+    /** Extra delay per element when animating several, in seconds. */
+    stagger?: number;
+}
+type Target = Element | Iterable<Element> | ArrayLike<Element> | string;
+/**
+ * The physical value behind one property of an element. Use it to read the live velocity,
+ * to drive the element from a gesture with `set`, or to listen to changes.
+ */
+declare function getValue(element: Element, prop: Prop): PhysicsValue;
+/**
+ * Springs one or more elements to the given values.
+ *
+ * ```ts
+ * animate(".card", { x: 120, rotate: 4, opacity: 1 }, { duration: 0.6, bounce: 0.3 })
+ * ```
+ */
+declare function animate(target: Target, props: Props, options?: AnimateOptions): Animation;
+/** Sets values immediately, without animation, and drops their momentum. */
+declare function set(target: Target, props: Props): void;
+
+interface Bounds {
+    left?: number;
+    right?: number;
+    top?: number;
+    bottom?: number;
+}
+interface DragInfo {
+    x: number;
+    y: number;
+    velocityX: number;
+    velocityY: number;
+}
+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;
+}
+interface Draggable {
+    readonly x: PhysicsValue;
+    readonly y: PhysicsValue;
+    readonly dragging: boolean;
+    destroy(): void;
+}
+/** Makes an element draggable and throwable. */
+declare function draggable(element: HTMLElement, options?: DraggableOptions): Draggable;
+
+/** Returns d(state)/dt for a state at time t. */
+type Derivatives = (state: readonly number[], t: number) => number[];
+/** One classic fourth-order Runge-Kutta step of size `dt`. */
+declare function rk4(state: readonly number[], t: number, dt: number, f: Derivatives): number[];
+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). */
+declare function system(f: Derivatives, initial: readonly number[], step?: number): System;
+
+type Task = (dt: number, now: number) => void;
+/** Current time in milliseconds, from the manual clock while the loop is in manual mode. */
+declare function now(): number;
+declare const loop: {
+    /** Runs `task` on every frame until the returned function is called. */
+    add(task: Task): () => void;
+    /**
+     * Switches to manual stepping (for tests, server rendering or video export) or back to
+     * requestAnimationFrame.
+     */
+    manual(on?: boolean): void;
+    /** Advances the manual clock by `ms` and runs one frame. Only has an effect in manual mode. */
+    step(ms?: number): void;
+    /** Number of running tasks. */
+    readonly size: number;
+};
+
+type ReducedMotion = "user" | "always" | "never";
+/**
+ * "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.
+ */
+declare function setReducedMotion(value: ReducedMotion): void;
+declare function reducedMotion(): boolean;
+
+declare class VelocityTracker {
+    #private;
+    /** Adds a sample: `time` in milliseconds, `value` in any unit. */
+    add(time: number, value: number): void;
+    /** Velocity in units per second at `time` (ms). 0 when the pointer has been resting. */
+    velocity(time?: number): number;
+    reset(): void;
+}
+
+interface Vector {
+    x: number;
+    y: number;
+}
+interface Rect {
+    left: number;
+    top: number;
+    right: number;
+    bottom: number;
+}
+interface BodyOptions {
+    /** Centre in pixels. */
+    x: number;
+    y: number;
+    radius: number;
+    /** Mass in kg. Defaults to the area times `density`. */
+    mass?: number;
+    /** kg per square meter, used when `mass` is not given. Default 1. */
+    density?: number;
+    /** Bounciness, 0 (clay) to 1 (perfectly elastic). Default 0.5. */
+    restitution?: number;
+    /** Coulomb friction coefficient. Default 0.4. */
+    friction?: number;
+    /** Fixed bodies never move but others collide with them. */
+    fixed?: boolean;
+    /** Initial velocity in pixels per second. */
+    vx?: number;
+    vy?: number;
+    /** Angle in radians and angular velocity in radians per second. */
+    angle?: number;
+    spin?: number;
+    /** An element positioned at the top left of the world that follows this body. */
+    element?: HTMLElement | SVGElement | null;
+}
+interface Body {
+    x: number;
+    y: number;
+    vx: number;
+    vy: number;
+    angle: number;
+    spin: number;
+    readonly radius: number;
+    readonly mass: number;
+    restitution: number;
+    friction: number;
+    readonly fixed: boolean;
+    element: HTMLElement | SVGElement | null;
+    /** @internal */ invMass: number;
+    /** @internal */ invInertia: number;
+}
+interface LinkOptions {
+    /** Rest length in pixels. Defaults to the current distance. */
+    length?: number;
+    /** Oscillation frequency in Hz. Higher is stiffer. Default 4. */
+    frequency?: number;
+    /** Damping ratio, 0 to 1. Default 0.3. */
+    damping?: number;
+}
+interface Link {
+    a: Body;
+    b: Body;
+    length: number;
+    frequency: number;
+    damping: number;
+}
+interface WorldOptions {
+    /** Gravity in m/s². Default { x: 0, y: 9.81 }. */
+    gravity?: Vector;
+    /** Scale between the simulation (meters) and the screen. Default 500 pixels per meter. */
+    pixelsPerMeter?: number;
+    /** Linear air drag per second. Default 0.05. */
+    airDrag?: number;
+    /**
+     * Rolling resistance coefficient: a braking torque proportional to the contact force that
+     * makes rolling bodies come to a stop and keeps resting piles still. Default 0.05.
+     */
+    rollingResistance?: number;
+    /** Walls in pixels, or an element whose content box becomes the walls. */
+    bounds?: Rect | HTMLElement | null;
+    /** Simulation steps per second. Default 240. */
+    rate?: number;
+    /** Collision solver passes per step. More gives steadier stacks. Default 4. */
+    iterations?: number;
+    /** Called after every frame, e.g. to draw on a canvas. */
+    onFrame?: (world: World) => void;
+    /** Called when two bodies (or a body and a wall) hit with an impact speed in px/s. */
+    onCollide?: (a: Body, b: Body | null, speed: number) => void;
+}
+interface Grab {
+    move(x: number, y: number): void;
+    release(): void;
+}
+declare class World {
+    #private;
+    readonly bodies: Body[];
+    readonly links: Link[];
+    gravity: Vector;
+    pixelsPerMeter: number;
+    airDrag: number;
+    rollingResistance: number;
+    iterations: number;
+    bounds: Rect | null;
+    constructor(options?: WorldOptions);
+    /** Sets the walls. With an element, they follow its size. */
+    setBounds(bounds: Rect | HTMLElement | null): void;
+    add(options: BodyOptions): Body;
+    remove(body: Body): void;
+    /** Connects two bodies with a damped spring. */
+    link(a: Body, b: Body, options?: LinkOptions): Link;
+    unlink(link: Link): void;
+    /** Body under a point, if any. */
+    bodyAt(x: number, y: number): Body | null;
+    /** Pulls a body towards a moving point with a stiff spring. Released bodies keep their speed. */
+    grab(body: Body, x: number, y: number): Grab;
+    /** Adds an impulse in kg·px/s at the centre (or `at` a point on the body for spin). */
+    push(body: Body, impulse: Vector, at?: Vector): void;
+    /**
+     * Lets the pointer grab and throw bodies inside `element` (default: the bounds element).
+     * Returns a function that removes the listeners.
+     */
+    bindPointer(element?: HTMLElement | null): () => void;
+    /** Starts the simulation on the shared frame loop. */
+    start(): this;
+    /** Pauses the simulation. */
+    stop(): this;
+    /** True while the world runs and something moves. A resting world uses no CPU. */
+    get awake(): boolean;
+    /** Resumes a resting world, e.g. after you changed bodies by hand. */
+    wake(): void;
+    destroy(): void;
+    /** Advances the simulation by `dt` seconds. Called for you while the world runs. */
+    step(dt: number): void;
+}
+/** Creates a world. Call `start()` to run it on the frame loop, or `step()` it yourself. */
+declare function world(options?: WorldOptions): World;
+
+export { type AnimateOptions, type Animation, type Body, type BodyOptions, type Bounds, type DecayOptions, type Derivatives, type DragInfo, type Draggable, type DraggableOptions, type Grab, type Link, type LinkOptions, type Listener, type Motion, type MotionState, PhysicsValue, type Prop, type Props, type Rect, type ReducedMotion, type Snap, type SpringOptions, type SpringParams, type System, type Task, type TransformProp, type Vector, VelocityTracker, World, type WorldOptions, animate, dampingRatio, decay, draggable, getValue, loop, nearest, now, projectRest, reducedMotion, restValue, rk4, rubberClamp, rubberband, set, setReducedMotion, settleTime, spring, springParams, system, timeConstant, value, world };