@astryxdesign/core 0.7.5-canary.fccd771 → 0.7.5

package/src/motion/bezier.test.ts

@@ -0,0 +1,52 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file bezier.test.ts
+ * @input vitest, the cubic-bézier timing function
+ * @output Checks the solver against the curve's own parametric form and the
+ *   properties every CSS / Core Animation timing curve has
+ * @position Testing; validates bezier.ts without a browser
+ */
+
+import {describe, expect, it} from 'vitest';
+import {cubicBezier, type BezierPoints} from './bezier';
+import {timing} from './uikit/timing';
+
+const CURVES: BezierPoints[] = [
+  timing.curves.viewChange,
+  timing.curves.move,
+  timing.curves.exit,
+  timing.curves.entrance,
+  [0.24, 1, 0.4, 1],
+  [0.3, 0, 0.6, 0.6],
+];
+
+describe('cubicBezier', () => {
+  it.each(CURVES)('matches the parametric curve (%s)', (...points) => {
+    const [x1, y1, x2, y2] = points;
+    const ease = cubicBezier(points);
+    const axis = (a: number, b: number, t: number) =>
+      3 * a * t * (1 - t) ** 2 + 3 * b * t * t * (1 - t) + t ** 3;
+    for (let t = 0; t <= 1; t += 1 / 256) {
+      expect(ease(axis(x1, x2, t))).toBeCloseTo(axis(y1, y2, t), 5);
+    }
+  });
+
+  it('runs from 0 to 1 and clamps outside', () => {
+    for (const points of CURVES) {
+      const ease = cubicBezier(points);
+      expect(ease(0)).toBe(0);
+      expect(ease(1)).toBe(1);
+      expect(ease(-0.5)).toBe(0);
+      expect(ease(1.5)).toBe(1);
+    }
+  });
+
+  it('ease-in-out is symmetric about its midpoint', () => {
+    const ease = cubicBezier(timing.curves.move);
+    expect(ease(0.5)).toBeCloseTo(0.5, 9);
+    for (let x = 0; x <= 0.5; x += 0.05) {
+      expect(ease(x) + ease(1 - x)).toBeCloseTo(1, 6);
+    }
+  });
+});

package/src/motion/bezier.ts

@@ -0,0 +1,64 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file bezier.ts
+ * @input Cubic-bézier control points [x1, y1, x2, y2]
+ * @output Exports `cubicBezier`, the timing function CSS and Core Animation
+ *   define by those points (progress → eased progress)
+ * @position Pure math under the animator (the Reduced Motion cross-fade runs
+ *   on Core Animation's named curves); no DOM, no React
+ *
+ * The curve runs from (0, 0) to (1, 1) with the two given control points;
+ * x is time, y is progress. Solved for x by Newton's method with a bisection
+ * fallback, the approach browser engines use for CSS `cubic-bezier()`.
+ *
+ * SYNC: When modified, update /packages/core/src/motion/bezier.test.ts
+ */
+
+export type BezierPoints = readonly [number, number, number, number];
+
+/** The timing function for `points`: maps time progress to eased progress. */
+export function cubicBezier([x1, y1, x2, y2]: BezierPoints): (
+  x: number,
+) => number {
+  const cx = 3 * x1;
+  const bx = 3 * (x2 - x1) - cx;
+  const ax = 1 - cx - bx;
+  const cy = 3 * y1;
+  const by = 3 * (y2 - y1) - cy;
+  const ay = 1 - cy - by;
+  const sampleX = (t: number) => ((ax * t + bx) * t + cx) * t;
+  const sampleY = (t: number) => ((ay * t + by) * t + cy) * t;
+  const slopeX = (t: number) => (3 * ax * t + 2 * bx) * t + cx;
+  const solveT = (x: number) => {
+    let t = x;
+    for (let i = 0; i < 8; i++) {
+      const error = sampleX(t) - x;
+      if (Math.abs(error) < 1e-7) {
+        return t;
+      }
+      const slope = slopeX(t);
+      if (Math.abs(slope) < 1e-6) {
+        break;
+      }
+      t -= error / slope;
+    }
+    let lo = 0;
+    let hi = 1;
+    t = x;
+    for (let i = 0; i < 60; i++) {
+      const value = sampleX(t);
+      if (Math.abs(value - x) < 1e-7) {
+        break;
+      }
+      if (value < x) {
+        lo = t;
+      } else {
+        hi = t;
+      }
+      t = (lo + hi) / 2;
+    }
+    return t;
+  };
+  return x => (x <= 0 ? 0 : x >= 1 ? 1 : sampleY(solveT(x)));
+}

package/src/motion/coast.test.ts

@@ -0,0 +1,99 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file coast.test.ts
+ * @input vitest, coast.ts, and the decay and spring math it composes
+ * @output Checks each momentum curve `coast` builds against the closed-form
+ *   coast and edge spring: inside the bounds, through an edge, released past
+ *   an edge, at rest, from the presentation value at the release time
+ * @position Testing; pure, with a stand-in for the animator's `get`
+ */
+
+import {describe, expect, it} from 'vitest';
+import type {Animator, MotionProperty} from './animator';
+import {coast} from './coast';
+import {solveDecay} from './decay';
+import {solveSpring, toSpring} from './spring';
+import {scroll} from './uikit/scroll';
+
+/** An animator whose presentation values are fixed, recording `get` times. */
+function at(values: Partial<Record<MotionProperty, number>>) {
+  const reads: (number | undefined)[] = [];
+  const animator = {
+    get(property: MotionProperty, time?: number) {
+      reads.push(time);
+      return values[property] ?? 0;
+    },
+  } as unknown as Animator;
+  return {animator, reads};
+}
+
+describe('coast', () => {
+  it('follows the coast from the presentation value and ends where it projects', () => {
+    const {animator} = at({y: 40});
+    const {y} = coast(animator, {y: -2400});
+    const glide = solveDecay({from: 40, velocity: -2400});
+    expect(y).toBeDefined();
+    for (const t of [0, 0.016, 0.1, 0.4, 1.2]) {
+      expect(y!.at(t)).toBeCloseTo(glide.value(t), 9);
+      expect(y!.velocity(t)).toBeCloseTo(glide.velocity(t), 9);
+    }
+    expect(y!.at(y!.duration)).toBe(glide.rest);
+  });
+
+  it('hands the coast\u2019s velocity to the edge spring where it reaches an edge', () => {
+    const {animator} = at({y: -100});
+    const {y} = coast(animator, {y: 3000}, {bounds: {y: {min: -2000, max: 0}}});
+    const glide = solveDecay({from: -100, velocity: 3000});
+    const hit = glide.timeToReach(0) as number;
+    expect(y!.at(hit)).toBeCloseTo(0, 6);
+    expect(y!.velocity(hit - 1e-9)).toBeCloseTo(y!.velocity(hit + 1e-9), 2);
+    // It overshoots past the edge, then comes back to it.
+    expect(y!.at(hit + 0.06)).toBeGreaterThan(0);
+    expect(y!.at(y!.duration)).toBe(0);
+  });
+
+  it('springs straight back with the release velocity when released past an edge', () => {
+    const {animator} = at({x: 60});
+    const {x} = coast(animator, {x: 400}, {bounds: {x: {min: -500, max: 0}}});
+    const back = solveSpring(toSpring(scroll.bounce), {
+      from: 60,
+      to: 0,
+      velocity: 400,
+    });
+    expect(x!.velocity(0)).toBeCloseTo(400, 6);
+    expect(x!.at(0.1)).toBeCloseTo(back.value(0.1), 9);
+    expect(x!.at(x!.duration)).toBe(0);
+  });
+
+  it('rests where it is at zero velocity inside its bounds', () => {
+    const {animator} = at({x: -30});
+    const {x} = coast(animator, {x: 0}, {bounds: {x: {min: -100, max: 0}}});
+    expect(x!.duration).toBe(0);
+    expect(x!.at(0)).toBe(-30);
+  });
+
+  it('reads the presentation value at the release time, on the translate axes only', () => {
+    const {animator, reads} = at({x: 0, y: 0});
+    const curves = coast(animator, {x: 500, y: 200}, {at: 1234});
+    expect(Object.keys(curves).sort()).toEqual(['x', 'y']);
+    expect(curves.x!.velocity(0)).toBeCloseTo(500, 9);
+    expect(curves.y!.velocity(0)).toBeCloseTo(200, 9);
+    expect(reads).toEqual([1234, 1234]);
+  });
+
+  it('coasts at the given rate', () => {
+    const {animator} = at({x: 0});
+    const {x} = coast(
+      animator,
+      {x: 1000},
+      {rate: scroll.decelerationRate.fast},
+    );
+    const glide = solveDecay({
+      from: 0,
+      velocity: 1000,
+      rate: scroll.decelerationRate.fast,
+    });
+    expect(x!.at(x!.duration)).toBe(glide.rest);
+  });
+});

package/src/motion/coast.ts

@@ -0,0 +1,150 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file coast.ts
+ * @input An animator, release velocities, and optional edges, deceleration
+ *   rate and edge spring
+ * @output Exports `coast`: the momentum curves of a released scroll view
+ *   (UIScrollView's coast, handing its velocity to an edge spring at a bound)
+ *   for `Animator.decay` to play; and its `CoastOptions`
+ * @position Motion foundation, pure math over an animator's presentation
+ *   values. Only a surface that coasts imports it, so the coast math and the
+ *   scroll table stay out of every other caller of the animator.
+ *
+ * Each property starts at its presentation value (`animator.get`), so a coast
+ * continues whatever was running without a jump:
+ * - inside its bounds, it coasts at `rate` (decay.ts) and comes to rest where
+ *   it projects;
+ * - a coast that reaches an edge hands its velocity at the contact to the
+ *   edge spring, which settles on the edge;
+ * - released past an edge, it springs straight back with the release
+ *   velocity: a transition, not momentum, so under Reduce Motion `decay`
+ *   plays it as `animate` does, a cross-fade on a coarse pointer or after a
+ *   touch release (`touchRelease`) and at once on any other
+ *   (`design:reduced-motion` DR2, DR3);
+ * - at zero velocity inside its bounds, it rests where it is.
+ *
+ * SYNC: When modified, update coast.test.ts.
+ */
+
+import {SETTLE_THRESHOLD, type Animator, type MotionCurve} from './animator';
+import {solveDecay} from './decay';
+import {solveSpring, toSpring, type SpringDescription} from './spring';
+import {scroll} from './uikit/scroll';
+
+export interface CoastOptions {
+  /** Per-millisecond velocity factor; UIScrollView's normal rate by default. */
+  rate?: number;
+  /** Edges: a coast crossing one hands its velocity to `bounce`. */
+  bounds?: Partial<Record<'x' | 'y', {min: number; max: number}>>;
+  /** The edge spring; `scroll.bounce` by default. */
+  bounce?: SpringDescription;
+  /**
+   * The release time on the document timeline (ms, `performance.now()`
+   * clock); now by default. Pass the same `at` to `decay`.
+   */
+  at?: number;
+}
+
+/** A curve that holds `end` from `duration` on. */
+function settling(
+  duration: number,
+  end: number,
+  at: (t: number) => number,
+  velocity: (t: number) => number,
+): MotionCurve {
+  return {
+    duration,
+    at: t => (t >= duration ? end : at(t)),
+    velocity: t => (t >= duration ? 0 : velocity(t)),
+  };
+}
+
+/**
+ * The momentum curves of a release with `velocity` (px per second on each
+ * translate axis), for `animator.decay`, which moves only `x` and `y`:
+ * momentum continues a finger's throw (design:reduced-motion DR2).
+ *
+ * @example
+ * ```
+ * animator.decay(
+ *   coast(animator, {x: velocityX}, {bounds: {x: {min: -maxScroll, max: 0}}}),
+ * );
+ * ```
+ */
+export function coast(
+  animator: Animator,
+  velocity: {readonly x?: number; readonly y?: number},
+  options: CoastOptions = {},
+): Partial<Record<'x' | 'y', MotionCurve>> {
+  const velocities: Partial<Record<'x' | 'y', number>> = {};
+  for (const key of ['x', 'y'] as const) {
+    const value = velocity[key];
+    if (value != null && Number.isFinite(value)) {
+      velocities[key] = value;
+    }
+  }
+  const rate = options.rate ?? scroll.decelerationRate.normal;
+  const bounce = toSpring(options.bounce ?? scroll.bounce);
+  const curves: Partial<Record<'x' | 'y', MotionCurve>> = {};
+  for (const [key, v0] of Object.entries(velocities) as ['x' | 'y', number][]) {
+    const from = animator.get(key, options.at);
+    const bounds = options.bounds?.[key];
+    const threshold = SETTLE_THRESHOLD[key];
+    if (bounds != null && (from < bounds.min || from > bounds.max)) {
+      // Released past an edge: straight back with the release velocity.
+      const edge = from < bounds.min ? bounds.min : bounds.max;
+      const back = solveSpring(bounce, {from, to: edge, velocity: v0});
+      curves[key] = {
+        ...settling(
+          back.settleTime(threshold),
+          edge,
+          t => back.value(t),
+          t => back.velocity(t),
+        ),
+        // A spring the release starts, not momentum (Reduce Motion: DR2).
+        isTransition: true,
+      };
+      continue;
+    }
+    const glide = solveDecay({from, velocity: v0, rate});
+    const edge =
+      bounds == null
+        ? null
+        : glide.rest < bounds.min
+          ? bounds.min
+          : glide.rest > bounds.max
+            ? bounds.max
+            : null;
+    const hit = edge == null ? null : glide.timeToReach(edge);
+    if (edge != null && hit != null) {
+      // The coast reaches the edge: the edge spring takes its velocity.
+      const spring = solveSpring(bounce, {
+        from: edge,
+        to: edge,
+        velocity: glide.velocity(hit),
+      });
+      curves[key] = settling(
+        hit + spring.settleTime(threshold),
+        edge,
+        t => (t < hit ? glide.value(t) : spring.value(t - hit)),
+        t => (t < hit ? glide.velocity(t) : spring.velocity(t - hit)),
+      );
+    } else if (v0 === 0) {
+      curves[key] = settling(
+        0,
+        from,
+        () => from,
+        () => 0,
+      );
+    } else {
+      curves[key] = settling(
+        glide.settleTime(threshold * 2),
+        edge ?? glide.rest,
+        t => glide.value(t),
+        t => glide.velocity(t),
+      );
+    }
+  }
+  return curves;
+}

package/src/motion/decay.test.ts

@@ -0,0 +1,120 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file decay.test.ts
+ * @input vitest, the decay model
+ * @output Checks the continuous coast against an independent per-millisecond
+ *   simulation of UIScrollView's deceleration, against WWDC18's projection,
+ *   and every derived time (settle, speed, reach)
+ * @position Testing; validates decay.ts without a browser
+ */
+
+import {describe, expect, it} from 'vitest';
+import {decayRestDistance, solveDecay} from './decay';
+import {projectDistance} from './projection';
+import {scroll} from './uikit/scroll';
+
+/**
+ * Independent reference: the deceleration rate applied literally, the
+ * velocity multiplied by the rate once per millisecond and integrated
+ * exactly over each millisecond step.
+ */
+function perMillisecond(
+  from: number,
+  velocity: number,
+  rate: number,
+  ms: number,
+) {
+  let x = from;
+  let v = velocity / 1000; // units per ms
+  const k = -Math.log(rate);
+  for (let i = 0; i < ms; i++) {
+    // Within one ms the speed falls from v to v·rate exponentially.
+    x += (v * (1 - rate)) / k;
+    v *= rate;
+  }
+  return {value: x, velocity: v * 1000};
+}
+
+describe('solveDecay', () => {
+  for (const rate of [
+    scroll.decelerationRate.normal,
+    scroll.decelerationRate.fast,
+  ]) {
+    for (const velocity of [-3000, -400, 150, 2500, 8000]) {
+      it(`matches a per-millisecond simulation (rate ${rate}, ${velocity} units/s)`, () => {
+        const coast = solveDecay({from: 100, velocity, rate});
+        for (const ms of [0, 1, 16, 100, 250, 600, 1500, 4000]) {
+          const reference = perMillisecond(100, velocity, rate, ms);
+          expect(coast.value(ms / 1000)).toBeCloseTo(reference.value, 6);
+          expect(coast.velocity(ms / 1000)).toBeCloseTo(reference.velocity, 6);
+        }
+      });
+    }
+  }
+
+  it('rests where the coast ends, 0.1 % past WWDC18\u2019s geometric projection', () => {
+    const coast = solveDecay({from: 0, velocity: 2000});
+    expect(coast.rest).toBeCloseTo(2000 / (-1000 * Math.log(0.998)), 9);
+    expect(coast.value(60)).toBeCloseTo(coast.rest, 6);
+    // −1 ÷ ln(0.998) = 499.5 ms against 0.998 ÷ 0.002 = 499 ms.
+    expect(coast.rest / projectDistance(2000)).toBeCloseTo(499.5 / 499, 3);
+    expect(decayRestDistance(2000)).toBeCloseTo(coast.rest, 9);
+  });
+
+  it('a fast rate stops sooner and shorter', () => {
+    const normal = solveDecay({from: 0, velocity: 2000});
+    const fast = solveDecay({
+      from: 0,
+      velocity: 2000,
+      rate: scroll.decelerationRate.fast,
+    });
+    expect(fast.rest).toBeLessThan(normal.rest);
+    expect(fast.settleTime(0.5)).toBeLessThan(normal.settleTime(0.5));
+  });
+
+  it('settleTime bounds every later distance to rest', () => {
+    const coast = solveDecay({from: 0, velocity: -5000});
+    for (const threshold of [5, 0.5, 0.01]) {
+      const settle = coast.settleTime(threshold);
+      expect(Math.abs(coast.value(settle) - coast.rest)).toBeCloseTo(
+        threshold,
+        9,
+      );
+      expect(Math.abs(coast.value(settle + 0.5) - coast.rest)).toBeLessThan(
+        threshold,
+      );
+    }
+    expect(solveDecay({from: 0, velocity: 0.1}).settleTime(0.5)).toBe(0);
+  });
+
+  it('timeToSpeed lands on the asked speed', () => {
+    const coast = solveDecay({from: 0, velocity: 3000});
+    const t = coast.timeToSpeed(100);
+    expect(coast.velocity(t)).toBeCloseTo(100, 9);
+    expect(coast.timeToSpeed(5000)).toBe(0);
+    expect(coast.timeToSpeed(0)).toBe(Infinity);
+  });
+
+  it('timeToReach finds the crossing, or null when the coast never gets there', () => {
+    const coast = solveDecay({from: 0, velocity: 2000});
+    const t = coast.timeToReach(400);
+    expect(t).not.toBeNull();
+    expect(coast.value(t ?? 0)).toBeCloseTo(400, 9);
+    expect(coast.timeToReach(-10)).toBeNull();
+    expect(coast.timeToReach(coast.rest)).toBeNull();
+    expect(coast.timeToReach(coast.rest + 1)).toBeNull();
+    const back = solveDecay({from: 0, velocity: -2000});
+    expect(back.value(back.timeToReach(-400) ?? 0)).toBeCloseTo(-400, 9);
+    expect(solveDecay({from: 3, velocity: 0}).timeToReach(3)).toBe(0);
+  });
+
+  it('rejects a rate outside (0, 1)', () => {
+    expect(() => solveDecay({from: 0, velocity: 1, rate: 1})).toThrow(
+      RangeError,
+    );
+    expect(() => solveDecay({from: 0, velocity: 1, rate: 0})).toThrow(
+      RangeError,
+    );
+  });
+});

package/src/motion/decay.ts

@@ -0,0 +1,126 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file decay.ts
+ * @input A release value, velocity and a UIScrollView deceleration rate
+ * @output Exports `solveDecay`, the closed-form momentum coast of a scroll
+ *   view after the finger lifts (value, velocity, rest point, settle time,
+ *   time to reach a value), and `decayRestDistance`
+ * @position Pure math under the motion animator; no DOM, no React
+ *
+ * UIScrollView's deceleration rate is a per-millisecond velocity factor: the
+ * speed is multiplied by the rate every millisecond (0.998 normal, 0.99 fast;
+ * see uikit/scroll.ts). As a continuous decay that is
+ *   v(t) = v₀·e^(−λt),  x(t) = x₀ + v₀·(1 − e^(−λt)) ÷ λ,  λ = −1000·ln(rate) /s
+ * and the coast ends at x₀ + v₀ ÷ λ. WWDC18 "Designing Fluid Interfaces"
+ * projects the same rest point with the geometric series v₀·rate ÷ (1 − rate)
+ * per millisecond (projection.ts), 0.1 % shorter at the normal rate (499.0
+ * against 499.5 ms of the release speed); the continuous form is the one
+ * that also gives the position and velocity at every instant, which the
+ * animator needs to grab a coasting surface mid-flight.
+ *
+ * Units: time in seconds, velocity in units per second.
+ *
+ * SYNC: When modified, update:
+ * - /packages/core/src/motion/decay.test.ts
+ * - /packages/core/src/motion/README.md
+ */
+
+import {scroll} from './uikit/scroll';
+
+/** A coast released at `from` with `initialVelocity`. */
+export interface DecayCurve {
+  readonly from: number;
+  /** Units per second. */
+  readonly initialVelocity: number;
+  /** Per-millisecond velocity factor. */
+  readonly rate: number;
+  /** Where the coast comes to rest. */
+  readonly rest: number;
+  /** Value `t` seconds after release. */
+  value(t: number): number;
+  /** Velocity `t` seconds after release, units/s. */
+  velocity(t: number): number;
+  /** Seconds until the value is within `threshold` of `rest` for good. */
+  settleTime(threshold: number): number;
+  /** Seconds until the speed falls to `speed` units/s (0 if already slower). */
+  timeToSpeed(speed: number): number;
+  /**
+   * Seconds until the coast reaches `target`, or null when it never gets
+   * there (behind the release point, or at or past the rest point).
+   */
+  timeToReach(target: number): number | null;
+}
+
+function decayConstant(rate: number): number {
+  if (!(rate > 0 && rate < 1)) {
+    throw new RangeError(`decay: rate must be in (0, 1), got ${rate}`);
+  }
+  return -1000 * Math.log(rate);
+}
+
+/** How far a coast at `velocity` units/s travels before it stops. */
+export function decayRestDistance(
+  velocity: number,
+  rate: number = scroll.decelerationRate.normal,
+): number {
+  return velocity / decayConstant(rate);
+}
+
+/**
+ * The momentum coast UIScrollView performs after the finger lifts.
+ *
+ * @example
+ * ```
+ * const coast = solveDecay({from: 0, velocity: 2000});
+ * coast.rest; // ≈ 999 px
+ * coast.value(0.2); // px after 200 ms
+ * ```
+ */
+export function solveDecay({
+  from,
+  velocity: initialVelocity,
+  rate = scroll.decelerationRate.normal,
+}: {
+  from: number;
+  velocity: number;
+  rate?: number;
+}): DecayCurve {
+  const lambda = decayConstant(rate);
+  const rest = from + initialVelocity / lambda;
+  const speed0 = Math.abs(initialVelocity);
+  return {
+    from,
+    initialVelocity,
+    rate,
+    rest,
+    value: t => from + (initialVelocity * -Math.expm1(-lambda * t)) / lambda,
+    velocity: t => initialVelocity * Math.exp(-lambda * t),
+    settleTime: threshold => {
+      const remaining = speed0 / lambda;
+      if (!(threshold > 0)) {
+        return Infinity;
+      }
+      return remaining <= threshold
+        ? 0
+        : Math.log(remaining / threshold) / lambda;
+    },
+    timeToSpeed: speed =>
+      speed0 <= speed
+        ? 0
+        : speed > 0
+          ? Math.log(speed0 / speed) / lambda
+          : Infinity,
+    timeToReach: target => {
+      if (initialVelocity === 0) {
+        return target === from ? 0 : null;
+      }
+      // 1 − e^(−λt) = λ·(target − from) ÷ v₀
+      const fraction = (lambda * (target - from)) / initialVelocity;
+      if (fraction < 0 || fraction >= 1) {
+        return null;
+      }
+      return -Math.log1p(-fraction) / lambda;
+    },
+  };
+}