tensum 0.1.0

package/src/support/inertia.ts

@@ -0,0 +1,367 @@
+import { resolveSettlingOptions } from '../settling.js';
+import { createSpring } from '../spring.js';
+import { validateSpringParameters } from '../solver.js';
+import type {
+  SettlingResult,
+  SpringParameters,
+  SpringSettleInput,
+  SpringSolution,
+  SpringState,
+} from '../types.js';
+
+const DEFAULT_BOUNDARY_SPRING: Readonly<SpringParameters> = Object.freeze({
+  mass: 1,
+  stiffness: 500,
+  damping: 40,
+});
+
+export interface InertiaOptions {
+  from: number;
+  velocity: number;
+  timeConstant?: number;
+  min?: number;
+  max?: number;
+  modifyTarget?: (naturalTarget: number) => number;
+  boundarySpring?: SpringParameters;
+  settle?: SpringSettleInput;
+}
+
+export interface InertiaBoundaryTransition {
+  readonly time: number;
+  readonly bound: number;
+  readonly incomingVelocity: number;
+  readonly spring: SpringSolution;
+}
+
+export type InertiaPhase = 'decay' | 'spring' | 'complete';
+
+export interface InertiaSolution {
+  readonly initialState: Readonly<SpringState>;
+  readonly naturalTarget: number;
+  readonly target: number;
+  readonly duration: number;
+  readonly settled: boolean;
+  readonly boundary?: Readonly<InertiaBoundaryTransition>;
+  stateAt(time: number): SpringState;
+  positionAt(time: number): number;
+  velocityAt(time: number): number;
+  phaseAt(time: number): InertiaPhase;
+  getSettlingResult(): SettlingResult;
+}
+
+function assertFinite(name: string, value: number): void {
+  if (!Number.isFinite(value)) {
+    throw new RangeError(`${name} must be a finite number`);
+  }
+}
+
+function assertPositive(name: string, value: number): void {
+  assertFinite(name, value);
+  if (value <= 0) throw new RangeError(`${name} must be greater than 0`);
+}
+
+function finiteState(
+  position: number,
+  velocity: number,
+  suffix = '',
+): SpringState {
+  assertFinite(`position${suffix}`, position);
+  assertFinite(`velocity${suffix}`, velocity);
+  return { position, velocity };
+}
+
+export function snapToGrid(size: number, origin = 0): (target: number) => number {
+  assertPositive('grid size', size);
+  assertFinite('grid origin', origin);
+  return (target: number): number => {
+    assertFinite('target', target);
+    const result = origin + Math.round((target - origin) / size) * size;
+    assertFinite('snapped target', result);
+    return result;
+  };
+}
+
+export function createInertia(options: InertiaOptions): InertiaSolution {
+  assertFinite('from', options.from);
+  assertFinite('velocity', options.velocity);
+  const timeConstant =
+    options.timeConstant === undefined ? 0.7 : options.timeConstant;
+  assertPositive('timeConstant', timeConstant);
+  if (options.min !== undefined) assertFinite('min', options.min);
+  if (options.max !== undefined) assertFinite('max', options.max);
+  if (
+    options.min !== undefined &&
+    options.max !== undefined &&
+    options.min > options.max
+  ) {
+    throw new RangeError('min must be less than or equal to max');
+  }
+
+  const settling = resolveSettlingOptions(options.settle);
+  if (options.boundarySpring !== undefined) {
+    validateSpringParameters(options.boundarySpring);
+  }
+  const naturalTarget = options.from + options.velocity * timeConstant;
+  assertFinite('naturalTarget', naturalTarget);
+  const target =
+    options.modifyTarget === undefined
+      ? naturalTarget
+      : options.modifyTarget(naturalTarget);
+  assertFinite('modified target', target);
+  const displacement = options.from - target;
+  assertFinite('displacement', displacement);
+  const linearCoefficient = options.velocity + displacement / timeConstant;
+  assertFinite('linear coefficient', linearCoefficient);
+
+  const decayStateAt = (time: number): SpringState => {
+    if (time === 0) return { position: options.from, velocity: options.velocity };
+    const decay = Math.exp(-time / timeConstant);
+    if (decay === 0) return { position: target, velocity: 0 };
+    const timeDecay = time * decay;
+    return finiteState(
+      target + decay * displacement + timeDecay * linearCoefficient,
+      decay * options.velocity -
+        (timeDecay / timeConstant) * linearCoefficient,
+    );
+  };
+
+  const decayBoundsAt = (time: number): SpringState => {
+    const decay = Math.exp(-time / timeConstant);
+    if (decay === 0) return { position: 0, velocity: 0 };
+    const timeDecay = time * decay;
+    return finiteState(
+      decay * Math.abs(displacement) +
+        timeDecay * Math.abs(linearCoefficient),
+      decay * Math.abs(options.velocity) +
+        (timeDecay / timeConstant) * Math.abs(linearCoefficient),
+      ' bound',
+    );
+  };
+
+  const boundsMeet = (time: number): boolean => {
+    const bounds = decayBoundsAt(time);
+    return (
+      bounds.position <= settling.positionEpsilon &&
+      bounds.velocity <= settling.velocityEpsilon
+    );
+  };
+
+  let decayIterations = 0;
+  let decayResult: SettlingResult;
+  if (displacement === 0 && options.velocity === 0) {
+    decayResult = { duration: 0, iterations: 0, settled: true };
+  } else {
+    const absoluteLinearCoefficient = Math.abs(linearCoefficient);
+    const positionMonotonicAfter =
+      absoluteLinearCoefficient === 0
+        ? 0
+        : Math.max(
+            0,
+            timeConstant - Math.abs(displacement) / absoluteLinearCoefficient,
+          );
+    const velocityMonotonicAfter =
+      absoluteLinearCoefficient === 0
+        ? 0
+        : Math.max(
+            0,
+            timeConstant -
+              (Math.abs(options.velocity) * timeConstant) /
+                absoluteLinearCoefficient,
+          );
+    const boundsMonotonicAfter = Math.max(
+      positionMonotonicAfter,
+      velocityMonotonicAfter,
+    );
+    if (boundsMonotonicAfter > settling.maxDuration) {
+      decayResult = {
+        duration: settling.maxDuration,
+        iterations: 0,
+        settled: false,
+      };
+    } else if (boundsMeet(0) && boundsMonotonicAfter === 0) {
+      decayResult = { duration: 0, iterations: 0, settled: true };
+    } else {
+      let lower = boundsMonotonicAfter;
+      let upper = Math.max(lower, Math.min(settling.maxDuration, 1 / 120));
+      if (boundsMeet(lower)) {
+        decayResult = { duration: lower, iterations: 0, settled: true };
+      } else {
+        while (upper < settling.maxDuration && !boundsMeet(upper)) {
+          lower = upper;
+          upper = Math.min(settling.maxDuration, upper * 2);
+          decayIterations += 1;
+        }
+        if (!boundsMeet(upper)) {
+          decayResult = {
+            duration: settling.maxDuration,
+            iterations: decayIterations,
+            settled: false,
+          };
+        } else {
+          for (
+            let iteration = 0;
+            iteration < settling.refinementIterations;
+            iteration += 1
+          ) {
+            const midpoint = lower + (upper - lower) / 2;
+            if (midpoint === lower || midpoint === upper) break;
+            if (boundsMeet(midpoint)) upper = midpoint;
+            else lower = midpoint;
+            decayIterations += 1;
+          }
+          decayResult = {
+            duration: upper,
+            iterations: decayIterations,
+            settled: true,
+          };
+        }
+      }
+    }
+  }
+
+  const outsideAtStart =
+    options.min !== undefined && options.from < options.min
+      ? options.min
+      : options.max !== undefined && options.from > options.max
+        ? options.max
+        : options.min !== undefined &&
+            options.from === options.min &&
+            options.velocity < 0
+          ? options.min
+          : options.max !== undefined &&
+              options.from === options.max &&
+              options.velocity > 0
+            ? options.max
+            : undefined;
+
+  const findBoundary = (): { time: number; bound: number } | undefined => {
+    if (outsideAtStart !== undefined) return { time: 0, bound: outsideAtStart };
+    if (options.min === undefined && options.max === undefined) return undefined;
+    const extremumTime =
+      linearCoefficient === 0
+        ? undefined
+        : (options.velocity * timeConstant) / linearCoefficient;
+    const boundaries = [
+      0,
+      ...(extremumTime !== undefined &&
+      extremumTime > 0 &&
+      extremumTime < decayResult.duration
+        ? [extremumTime]
+        : []),
+      decayResult.duration,
+    ];
+
+    for (let index = 1; index < boundaries.length; index += 1) {
+      const startTime = boundaries[index - 1]!;
+      const endTime = boundaries[index]!;
+      const startPosition = decayStateAt(startTime).position;
+      const endPosition = decayStateAt(endTime).position;
+      const increasing = endPosition >= startPosition;
+      const bound = increasing
+        ? options.max !== undefined &&
+          startPosition <= options.max &&
+          endPosition >= options.max
+          ? options.max
+          : undefined
+        : options.min !== undefined &&
+            startPosition >= options.min &&
+            endPosition <= options.min
+          ? options.min
+          : undefined;
+      if (bound === undefined) continue;
+
+      let lower = startTime;
+      let upper = endTime;
+      for (let iteration = 0; iteration < 48; iteration += 1) {
+        const midpoint = lower + (upper - lower) / 2;
+        const position = decayStateAt(midpoint).position;
+        const crossed = increasing ? position >= bound : position <= bound;
+        if (crossed) upper = midpoint;
+        else lower = midpoint;
+      }
+      return { time: upper, bound };
+    }
+    return undefined;
+  };
+
+  const hit = findBoundary();
+  let boundary: Readonly<InertiaBoundaryTransition> | undefined;
+  let duration = decayResult.duration;
+  let settled = decayResult.settled;
+  let iterations = decayResult.iterations;
+
+  if (hit) {
+    const hitState =
+      hit.time === 0
+        ? { position: options.from, velocity: options.velocity }
+        : decayStateAt(hit.time);
+    const spring = createSpring({
+      from: hitState.position,
+      to: hit.bound,
+      velocity: hitState.velocity,
+      ...(options.boundarySpring ?? DEFAULT_BOUNDARY_SPRING),
+      settle: {
+        position: settling.positionEpsilon,
+        velocity: settling.velocityEpsilon,
+        maxDuration: settling.maxDuration,
+        refinementIterations: settling.refinementIterations,
+      },
+    });
+    const springResult = spring.getSettlingResult();
+    boundary = Object.freeze({
+      time: hit.time,
+      bound: hit.bound,
+      incomingVelocity: hitState.velocity,
+      spring,
+    });
+    duration = hit.time + springResult.duration;
+    assertFinite('duration', duration);
+    settled = springResult.settled;
+    iterations += springResult.iterations;
+  }
+
+  const stateAt = (time: number): SpringState => {
+    assertFinite('time', time);
+    if (time < 0) throw new RangeError('time must be greater than or equal to 0');
+    if (settled && time >= duration) {
+      return { position: boundary?.bound ?? target, velocity: 0 };
+    }
+    if (boundary && time >= boundary.time) {
+      return boundary.spring.stateAt(
+        Math.min(time - boundary.time, boundary.spring.getSettlingDuration()),
+      );
+    }
+    return decayStateAt(Math.min(time, decayResult.duration));
+  };
+
+  const phaseAt = (time: number): InertiaPhase => {
+    assertFinite('time', time);
+    if (time < 0) throw new RangeError('time must be greater than or equal to 0');
+    if (settled && time >= duration) return 'complete';
+    if (boundary && time >= boundary.time) return 'spring';
+    return 'decay';
+  };
+
+  return Object.freeze({
+    initialState: Object.freeze({
+      position: options.from,
+      velocity: options.velocity,
+    }),
+    naturalTarget,
+    target: boundary?.bound ?? target,
+    duration,
+    settled,
+    ...(boundary === undefined ? {} : { boundary }),
+    stateAt,
+    positionAt(time: number): number {
+      return stateAt(time).position;
+    },
+    velocityAt(time: number): number {
+      return stateAt(time).velocity;
+    },
+    phaseAt,
+    getSettlingResult(): SettlingResult {
+      return { duration, iterations, settled };
+    },
+  });
+}

package/src/support/keyframes.ts

@@ -0,0 +1,188 @@
+import { createSpring } from '../spring.js';
+import type {
+  SettlingResult,
+  SpringParameters,
+  SpringSettleInput,
+  SpringSolution,
+  SpringState,
+  SpringTiming,
+  SpringTimingInput,
+} from '../types.js';
+
+export interface SpringKeyframe {
+  value: number;
+  startVelocity?: number;
+  parameters?: Partial<SpringParameters>;
+  settle?: SpringSettleInput;
+  timing?: SpringTimingInput;
+}
+
+export interface SpringKeyframesOptions {
+  from: number;
+  keyframes: readonly SpringKeyframe[];
+  parameters: SpringParameters;
+  velocity?: number;
+  settle?: SpringSettleInput;
+  timing?: SpringTimingInput;
+}
+
+export interface SpringKeyframeSegment {
+  readonly index: number;
+  readonly startTime: number;
+  readonly endTime: number;
+  readonly solution: SpringSolution;
+}
+
+export interface SpringKeyframeSequence {
+  readonly duration: number;
+  readonly settled: boolean;
+  readonly timing: Readonly<SpringTiming>;
+  readonly segments: readonly Readonly<SpringKeyframeSegment>[];
+  positionAt(time: number): number;
+  velocityAt(time: number): number;
+  stateAt(time: number): SpringState;
+  getSettlingResult(): SettlingResult;
+}
+
+function assertFinite(name: string, value: number): void {
+  if (!Number.isFinite(value)) {
+    throw new RangeError(`${name} must be a finite number`);
+  }
+}
+
+function assertOptionalObject(name: string, value: unknown): void {
+  if (
+    value !== undefined &&
+    (typeof value !== 'object' || value === null || Array.isArray(value))
+  ) {
+    throw new TypeError(`${name} must be an object when provided`);
+  }
+}
+
+export function createSpringKeyframes(
+  options: SpringKeyframesOptions,
+): SpringKeyframeSequence {
+  assertFinite('from', options.from);
+  if (options.keyframes.length === 0) {
+    throw new RangeError('spring keyframes require at least one destination');
+  }
+
+  const segments: SpringKeyframeSegment[] = [];
+  let from = options.from;
+  let startTime = 0;
+  let perceptualDuration = 0;
+
+  if (options.velocity !== undefined) {
+    assertFinite('velocity', options.velocity);
+  }
+  assertOptionalObject('settle', options.settle);
+  assertOptionalObject('timing', options.timing);
+
+  for (let index = 0; index < options.keyframes.length; index += 1) {
+    const keyframe = options.keyframes[index]!;
+    assertFinite(`keyframes[${index}].value`, keyframe.value);
+    assertOptionalObject(`keyframes[${index}].parameters`, keyframe.parameters);
+    assertOptionalObject(`keyframes[${index}].settle`, keyframe.settle);
+    assertOptionalObject(`keyframes[${index}].timing`, keyframe.timing);
+    const frameVelocity =
+      keyframe.startVelocity === undefined
+        ? index === 0
+          ? options.velocity === undefined
+            ? 0
+            : options.velocity
+          : 0
+        : keyframe.startVelocity;
+    assertFinite(`keyframes[${index}].startVelocity`, frameVelocity);
+    const parameters: SpringParameters = {
+      mass:
+        keyframe.parameters?.mass === undefined
+          ? options.parameters.mass
+          : keyframe.parameters.mass,
+      stiffness:
+        keyframe.parameters?.stiffness === undefined
+          ? options.parameters.stiffness
+          : keyframe.parameters.stiffness,
+      damping:
+        keyframe.parameters?.damping === undefined
+          ? options.parameters.damping
+          : keyframe.parameters.damping,
+    };
+    const settle =
+      options.settle || keyframe.settle
+        ? { ...options.settle, ...keyframe.settle }
+        : undefined;
+    const timing =
+      keyframe.timing === undefined ? options.timing : keyframe.timing;
+    const solution = createSpring({
+      from,
+      to: keyframe.value,
+      velocity: frameVelocity,
+      ...parameters,
+      ...(settle === undefined ? {} : { settle }),
+      ...(timing === undefined ? {} : { timing }),
+    });
+    const result = solution.getSettlingResult();
+    if (!result.settled && index < options.keyframes.length - 1) {
+      throw new RangeError(
+        `keyframes[${index}] is unsettled and cannot define the next segment start`,
+      );
+    }
+    const endTime = startTime + result.duration;
+    assertFinite('duration', endTime);
+    segments.push(Object.freeze({ index, startTime, endTime, solution }));
+    perceptualDuration += solution.timing.perceptualDuration;
+    assertFinite('perceptualDuration', perceptualDuration);
+    startTime = endTime;
+    from = keyframe.value;
+  }
+
+  const frozenSegments = Object.freeze(segments);
+  const duration = frozenSegments.at(-1)!.endTime;
+  const settled = frozenSegments.every((segment) => segment.solution.timing.settled);
+  const timing: Readonly<SpringTiming> = Object.freeze({
+    perceptualDuration,
+    settlingDuration: duration,
+    settled,
+  });
+
+  const stateAt = (time: number): SpringState => {
+    assertFinite('time', time);
+    if (time < 0) throw new RangeError('time must be greater than or equal to 0');
+    const segment =
+      frozenSegments.find((candidate) => time < candidate.endTime) ??
+      frozenSegments.at(-1)!;
+    const localTime = Math.min(
+      Math.max(0, time - segment.startTime),
+      segment.solution.getSettlingDuration(),
+    );
+    if (time >= duration && segment.solution.timing.settled) {
+      return { position: segment.solution.initialState.target, velocity: 0 };
+    }
+    return segment.solution.stateAt(localTime);
+  };
+
+  return Object.freeze({
+    duration,
+    settled,
+    timing,
+    segments: frozenSegments,
+    positionAt(time: number): number {
+      return stateAt(time).position;
+    },
+    velocityAt(time: number): number {
+      return stateAt(time).velocity;
+    },
+    stateAt,
+    getSettlingResult(): SettlingResult {
+      return {
+        duration,
+        iterations: frozenSegments.reduce(
+          (total, segment) =>
+            total + segment.solution.getSettlingResult().iterations,
+          0,
+        ),
+        settled,
+      };
+    },
+  });
+}