@astryxdesign/core 0.7.5-canary.fccd771 → 0.7.5

package/src/motion/reducedMotionPlan.ts

@@ -0,0 +1,263 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file reducedMotionPlan.ts
+ * @input A call's targets and a read-only view of the animator's opacity
+ *   state
+ * @output planReducedMotion, TRAVEL_PROPERTIES and the plan's types
+ * @position The animator's Reduce Motion planner (packages/core/src/motion):
+ *   what one call becomes under Reduce Motion. animator.ts applies the plan;
+ *   the policy itself is described in its header (design:reduced-motion
+ *   DR1–DR4).
+ *
+ * With `fade` (a coarse primary pointer, or a touch drag's release), a call
+ * becomes an opacity-only cross-fade whose travel lands while the element is
+ * transparent: an entrance from 0 lands at once and fades in, an exit to 0
+ * fades out in place and then lands, and any other call that moves dips
+ * (fades out, lands, fades back in). Without `fade`, everything lands at once. When no call owns
+ * the opacity, a dip or a fade by role starts from and returns to the
+ * element's own (stylesheet) opacity, which the plan reports as `borrowed`.
+ * The planner is pure: it reads the animator only through
+ * `ReducedMotionView` and returns what to write.
+ *
+ * SYNC: When modified, update animator.ts (its header's Reduce Motion
+ * section, and `reducedMotion`, which applies the plan) and animator.test.ts.
+ */
+
+import type {MotionProperty} from './animator';
+import {reducedMotionCrossFade} from './uikit/timing';
+
+/** The properties that move an element rather than fade it. */
+export const TRAVEL_PROPERTIES: ReadonlyArray<MotionProperty> = [
+  'x',
+  'y',
+  'rotate',
+  'scaleX',
+  'scaleY',
+];
+
+/** A point of the opacity fade: ms after the call's start, and the value. */
+export interface FadePoint {
+  readonly at: number;
+  readonly value: number;
+}
+
+/** The travel a plan writes later, while the element is transparent. */
+export interface PlannedLanding {
+  /** ms after the call's start. */
+  readonly at: number;
+  readonly values: Map<MotionProperty, number>;
+  /**
+   * The fade back in that follows the landing (a dip); `isBorrowed` when it
+   * returns to the stylesheet's opacity, which owns it again once it ends.
+   */
+  fadeIn: {
+    readonly to: number;
+    readonly ms: number;
+    readonly isBorrowed?: boolean;
+  } | null;
+  /** The opacity written with the landing (an exit by role). */
+  restore: number | null;
+  /**
+   * The restore returns to the stylesheet's opacity (an exit by role on a
+   * surface no call owns opacity on): the stylesheet owns it again.
+   */
+  restoreIsBorrowed?: boolean;
+}
+
+/** What the planner reads of the animator, at the call's time. */
+export interface ReducedMotionView {
+  valueAt(property: MotionProperty, time: number): number;
+  /** Where the opacity is heading (a running fade's end, else its value). */
+  opacityHeading(): number;
+  /** The element's own (stylesheet) opacity. */
+  ownOpacity(): number;
+  /** Whether the animator writes the element's opacity itself. */
+  writesOwnOpacity(): boolean;
+  /** The stylesheet opacity a running dip borrowed, if any. */
+  readonly borrowedOpacity: number | null;
+  readonly hasOpacityCurve: boolean;
+  readonly restingOpacity: number;
+  /** Whether a move of an earlier call still waits to land. */
+  readonly hasPendingLanding: boolean;
+}
+
+/** What Reduce Motion makes of a call. */
+export interface ReducedMotionPlan {
+  /** Properties written at once, with no curve. */
+  readonly atOnce: MotionProperty[];
+  /** The opacity fade, when the call fades. */
+  readonly opacityFade: FadePoint[] | null;
+  /** Values that stay where they are until the landing writes them. */
+  readonly holds: Partial<Record<MotionProperty, number>>;
+  readonly landing: PlannedLanding | null;
+  /** The stylesheet opacity a dip borrowed (no call owns opacity). */
+  readonly borrowed?: number | null;
+}
+
+/** The opacity no call has changed. */
+const IDENTITY_OPACITY = 1;
+
+/**
+ * Plans one call under Reduce Motion: with `fade`, an opacity-only
+ * cross-fade whose travel lands while the element is transparent; without,
+ * everything at once. `role` gives a call that names no opacity its
+ * direction (`crossfadeAs`).
+ */
+export function planReducedMotion(
+  view: ReducedMotionView,
+  time: number,
+  targets: Partial<Record<MotionProperty, number>>,
+  properties: ReadonlyArray<MotionProperty>,
+  fade: boolean,
+  role?: 'entrance' | 'exit',
+): ReducedMotionPlan {
+  const holds: Partial<Record<MotionProperty, number>> = {};
+  if (!fade) {
+    return {atOnce: [...properties], opacityFade: null, holds, landing: null};
+  }
+  const atOnce = properties.filter(property =>
+    TRAVEL_PROPERTIES.includes(property),
+  );
+  const opacityNow = view.valueAt('opacity', time);
+  // A fade the call does not name keeps going where it was heading.
+  const opacityTo = targets.opacity ?? view.opacityHeading();
+  const travel = properties.filter(
+    property =>
+      TRAVEL_PROPERTIES.includes(property) &&
+      Math.abs((targets[property] as number) - view.valueAt(property, time)) >
+        1e-9,
+  );
+  // Only the call's own opacity (or its role) makes it an entrance or an
+  // exit: a fade it does not name, such as a dip still running, does not.
+  const named = targets.opacity != null;
+  let entering = named && opacityTo > opacityNow + 1e-6;
+  let leaving = named && opacityTo < opacityNow - 1e-6;
+  let fadeFrom = opacityNow;
+  let fadeTo = opacityTo;
+  let restore: number | null = null;
+  // A fade by role on a surface no call owns opacity on starts from, or
+  // returns to, the element's own (stylesheet) opacity, as a dip does.
+  const roleBorrow =
+    role != null &&
+    !named &&
+    view.borrowedOpacity == null &&
+    !view.hasOpacityCurve &&
+    view.restingOpacity === IDENTITY_OPACITY &&
+    !view.writesOwnOpacity()
+      ? view.ownOpacity()
+      : null;
+  if (!entering && !leaving && role === 'entrance') {
+    entering = true;
+    // From transparent, or from where a running fade (an exit caught
+    // midway) has it.
+    fadeFrom = view.hasOpacityCurve ? opacityNow : 0;
+    fadeTo = roleBorrow ?? opacityTo;
+  } else if (!entering && !leaving && role === 'exit') {
+    leaving = true;
+    fadeFrom = roleBorrow ?? opacityNow;
+    fadeTo = 0;
+    restore = roleBorrow ?? opacityTo;
+  }
+  // A move still waiting to land (an earlier dip's) lands at this call's
+  // invisible moment, never while the element shows.
+  const pending = view.hasPendingLanding;
+  // Not a theme role: no theme lengthens it (design:reduced-motion DR4).
+  const ms = reducedMotionCrossFade.durationMs;
+  const landsLater = (
+    at: number,
+    fadeIn: PlannedLanding['fadeIn'],
+  ): PlannedLanding => {
+    const values = new Map<MotionProperty, number>();
+    for (const property of travel) {
+      holds[property] = view.valueAt(property, time);
+      values.set(property, targets[property] as number);
+    }
+    return {
+      at,
+      values,
+      fadeIn,
+      restore,
+      ...(roleBorrow != null && restore != null
+        ? {restoreIsBorrowed: true}
+        : {}),
+    };
+  };
+  // Travel lands only while the element is transparent (DR1, DR2): an
+  // entrance that starts visible, or an exit that ends visible, dips instead
+  // when it has travel or a waiting landing to carry.
+  const carries = travel.length > 0 || pending;
+  if (entering && !pending && (!carries || fadeFrom <= 1e-6)) {
+    // Lands at once (the travel is written at once) and fades in.
+    return {
+      atOnce,
+      opacityFade: [
+        {at: 0, value: fadeFrom},
+        {at: ms, value: fadeTo},
+      ],
+      holds,
+      landing: null,
+      borrowed: roleBorrow,
+    };
+  }
+  if (leaving && (!carries || fadeTo <= 1e-6)) {
+    // Fades out in place, then lands.
+    const opacityFade = [
+      {at: 0, value: fadeFrom},
+      {at: ms, value: fadeTo},
+    ];
+    return {
+      atOnce,
+      opacityFade,
+      holds,
+      landing:
+        travel.length > 0 || restore != null || pending
+          ? landsLater(ms, null)
+          : null,
+    };
+  }
+  if (carries) {
+    // A dip: fades out, lands while transparent, fades back in. When no
+    // call owns opacity it starts from and returns to the element's own
+    // (stylesheet) opacity, not the model's 1.
+    // A dip still running on borrowed opacity (its fade out or back in)
+    // lends the same borrow to the next one: overlapping dips never pin
+    // the stylesheet's value inline.
+    const priorBorrow = view.borrowedOpacity;
+    // An opacity the animator left inline (a `set` over a stylesheet that
+    // hides or dims the element) is owned too: a dip returns to it.
+    const ownsOpacity =
+      named ||
+      (priorBorrow == null &&
+        (view.hasOpacityCurve ||
+          view.restingOpacity !== IDENTITY_OPACITY ||
+          view.writesOwnOpacity()));
+    const borrowed = ownsOpacity ? null : (priorBorrow ?? view.ownOpacity());
+    if (borrowed != null && borrowed <= 1e-6) {
+      // A stylesheet that hides the element lends nothing: invisible, the
+      // move lands at once, with no dip.
+      return {atOnce, opacityFade: null, holds, landing: null};
+    }
+    // It opens at the opacity on screen: an earlier dip's, when one is
+    // still running, else the borrowed stylesheet value.
+    const opacityFade = [
+      {
+        at: 0,
+        value: view.hasOpacityCurve ? opacityNow : (borrowed ?? opacityNow),
+      },
+      {at: ms / 2, value: 0},
+    ];
+    const landing = landsLater(ms / 2, {
+      to: borrowed ?? opacityTo,
+      ms: ms / 2,
+      isBorrowed: borrowed != null,
+    });
+    return {atOnce, opacityFade, holds, landing, borrowed};
+  }
+  return {
+    atOnce: 'opacity' in targets ? [...atOnce, 'opacity'] : atOnce,
+    opacityFade: null,
+    holds,
+    landing: null,
+  };
+}

package/src/motion/resolveSnapPoint.test.ts

@@ -0,0 +1,189 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import {fileURLToPath} from 'node:url';
+import {describe, expect, it} from 'vitest';
+import * as core from '../index';
+import {resolveSnapPoint} from './resolveSnapPoint';
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+
+const SHEET = {
+  flickThreshold: 1008,
+  tolerance: 1,
+  projection: {seconds: 0.1, minSpeed: 250},
+} as const;
+
+describe('resolveSnapPoint', () => {
+  it('lands a slow release on the snap point nearest where it was let go', () => {
+    expect(
+      resolveSnapPoint({
+        points: [0, 300, 640],
+        position: 140,
+        velocity: 0,
+        flickThreshold: 48,
+      }),
+    ).toEqual({index: 0, projected: 140});
+    expect(
+      resolveSnapPoint({
+        points: [0, 300, 640],
+        position: 160,
+        velocity: 20,
+        flickThreshold: 48,
+      }).index,
+    ).toBe(1);
+  });
+
+  it('projects nothing below the projection speed, and judges a faster slow release where it coasts to', () => {
+    // 240 px/s is below 250: judged at 140, nearer 0.
+    expect(
+      resolveSnapPoint({
+        ...SHEET,
+        points: [0, 300, 640],
+        position: 140,
+        velocity: 240,
+      }),
+    ).toEqual({index: 0, projected: 140});
+    // 600 px/s projects 0.1 s ahead: 140 + 60 = 200, nearer 300.
+    const projected = resolveSnapPoint({
+      ...SHEET,
+      points: [0, 300, 640],
+      position: 140,
+      velocity: 600,
+    });
+    expect(projected.index).toBe(1);
+    expect(projected.projected).toBeCloseTo(200, 6);
+  });
+
+  it('takes a flick at least to the next snap point beyond, or to its projection if that is farther', () => {
+    // At 300 moving 1200 px/s: projected 420 (nearer 300), but a flick goes on.
+    const flick = resolveSnapPoint({
+      ...SHEET,
+      points: [0, 300, 640],
+      position: 300,
+      velocity: 1200,
+    });
+    expect(flick.index).toBe(2);
+    expect(flick.projected).toBeCloseTo(420, 6);
+    // Without projection, from just past the first snap point.
+    expect(
+      resolveSnapPoint({
+        points: [0, 300],
+        position: 2,
+        velocity: 60,
+        flickThreshold: 48,
+      }).index,
+    ).toBe(1);
+    // Moving down the axis, to the next snap point below.
+    expect(
+      resolveSnapPoint({
+        ...SHEET,
+        points: [0, 300, 640],
+        position: 620,
+        velocity: -1100,
+      }).index,
+    ).toBe(1);
+  });
+
+  it('counts a snap point within the tolerance as reached, so a flick goes on to the one after it', () => {
+    expect(
+      resolveSnapPoint({
+        points: [0, 300, 640],
+        position: 300.5,
+        velocity: 2000,
+        flickThreshold: 1008,
+        tolerance: 1,
+      }).index,
+    ).toBe(2);
+    // Past the last snap point there is nothing beyond: the nearest stays.
+    expect(
+      resolveSnapPoint({
+        points: [0, 300],
+        position: 310,
+        velocity: 2000,
+        flickThreshold: 1008,
+        tolerance: 1,
+      }).index,
+    ).toBe(1);
+  });
+
+  it('cancels a release moving back toward where the drag began, whatever its travel or speed', () => {
+    // Dragged from 0 to 280, released slowly moving back up: back to 0.
+    expect(
+      resolveSnapPoint({
+        ...SHEET,
+        points: [0, 300, 640],
+        position: 280,
+        velocity: -10,
+        start: 0,
+      }).index,
+    ).toBe(0);
+    // A flick back toward the start cancels too.
+    expect(
+      resolveSnapPoint({
+        ...SHEET,
+        points: [0, 300, 640],
+        position: 500,
+        velocity: -1500,
+        start: 300,
+      }).index,
+    ).toBe(1);
+    // Moving away from the start does not cancel.
+    expect(
+      resolveSnapPoint({
+        ...SHEET,
+        points: [0, 300, 640],
+        position: 280,
+        velocity: 10,
+        start: 0,
+      }).index,
+    ).toBe(1);
+  });
+
+  it('sends a tie the way a projected release moves, and otherwise to the earlier snap point', () => {
+    const at = (velocity: number, projection?: typeof SHEET.projection) =>
+      resolveSnapPoint({
+        points: [0, 300],
+        // Released where its projection lands on the midpoint.
+        position: 150 - velocity * 0.1 * (projection == null ? 0 : 1),
+        velocity,
+        flickThreshold: 1008,
+        projection,
+      }).index;
+    expect(at(0)).toBe(0);
+    expect(at(10)).toBe(0);
+    expect(at(-10)).toBe(0);
+    expect(at(400, SHEET.projection)).toBe(1);
+    expect(at(-400, SHEET.projection)).toBe(0);
+  });
+
+  it('needs at least one snap point', () => {
+    expect(() =>
+      resolveSnapPoint({
+        points: [],
+        position: 0,
+        velocity: 0,
+        flickThreshold: 1,
+      }),
+    ).toThrow(RangeError);
+  });
+
+  it('stays internal: not exported from the package or any barrel', () => {
+    expect(core).not.toHaveProperty('resolveSnapPoint');
+    const pkg = JSON.parse(
+      fs.readFileSync(path.join(here, '../../package.json'), 'utf8'),
+    ) as {exports: Record<string, unknown>};
+    expect(
+      Object.keys(pkg.exports).filter(key => key.includes('motion')),
+    ).toEqual([]);
+    const barrels = fs
+      .readdirSync(here)
+      .filter(name => /^index\.(ts|tsx|js|mjs)$/.test(name));
+    for (const barrel of barrels) {
+      expect(fs.readFileSync(path.join(here, barrel), 'utf8')).not.toMatch(
+        /resolveSnapPoint/,
+      );
+    }
+  });
+});

package/src/motion/resolveSnapPoint.ts

@@ -0,0 +1,169 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file resolveSnapPoint.ts
+ * @input A release (position and velocity on one axis), the points it can
+ *   land on, and the release policy's thresholds
+ * @output Exports resolveSnapPoint: the index of the snap point a release lands on,
+ *   and the projected rest position it was judged from
+ * @position The release policy of the motion foundation, on
+ *   `selectSnapPoint` (projection.ts), which stays the math primitive
+ *   (projection + nearest). Pure: no DOM, no React. Internal to core: not
+ *   exported from the package or any barrel (resolveSnapPoint.test.ts locks
+ *   that). A component's release rule calls it with its own points and
+ *   thresholds; this is the one "where does a release land" helper, so a
+ *   second one should not be added beside it.
+ *
+ * - A slow release lands on the snap point nearest where it would come to rest:
+ *   its position, or, with `projection`, its position plus the distance it
+ *   would coast at its velocity (projection.ts). Below
+ *   `projection.minSpeed` nothing is projected, so it lands on the snap point
+ *   nearest where it was let go. A tie goes the way a projected release
+ *   moves, and otherwise to the earlier snap point (`selectSnapPoint`).
+ * - A flick (`flickThreshold` or faster) lands at least on the next snap point
+ *   beyond its position in the direction it moves, or on the nearest
+ *   snap point to its projection if that is farther. A snap point within
+ *   `tolerance` of the position counts as reached, so the flick goes on to
+ *   the one after it.
+ * - With `start` (where the drag began), a release moving back toward it
+ *   cancels to the snap point nearest `start`, whatever its travel so far or its
+ *   speed.
+ * - With `fromIndex` and `maxSteps`, a release lands at most `maxSteps`
+ *   points away from the one at `fromIndex` (a pager's one page per
+ *   release).
+ *
+ * Snap points are ascending positions on the axis; velocities are in the same
+ * units per second, positive toward larger positions.
+ *
+ * SYNC: When modified, update resolveSnapPoint.test.ts.
+ */
+
+import {selectSnapPoint} from './projection';
+
+/** Where a release lands. */
+export interface SnapPointRelease {
+  /** Index into the points passed in. */
+  readonly index: number;
+  /** The rest position the choice was judged from (the position without a projection). */
+  readonly projected: number;
+}
+
+/** A release's projection: how far ahead it is judged, and from what speed. */
+export interface SnapPointProjection {
+  /** Seconds of the release velocity the projection reaches. */
+  readonly seconds: number;
+  /** Below this speed (units/s), nothing is projected (default 0). */
+  readonly minSpeed?: number;
+}
+
+/** The deceleration rate whose projection reaches `seconds` of the velocity. */
+function rateForProjection(seconds: number): number {
+  // WWDC18's projection coasts (v / 1000) · r / (1 − r): r / (1 − r) = 1000·τ.
+  const ms = seconds * 1000;
+  return ms / (1 + ms);
+}
+
+/** The index of the snap point nearest `position` (the first on a tie). */
+function nearestIndex(points: ReadonlyArray<number>, position: number): number {
+  let best = 0;
+  for (let i = 1; i < points.length; i += 1) {
+    if (Math.abs(points[i] - position) < Math.abs(points[best] - position)) {
+      best = i;
+    }
+  }
+  return best;
+}
+
+/**
+ * The snap point a release lands on.
+ *
+ * @example
+ * ```
+ * // Snap points at 0, 300 and 640 px. Released at 300 px moving toward 640 at
+ * // 1200 px/s, a flick: on to 640, although its projection (420 px) is
+ * // nearer 300.
+ * resolveSnapPoint({
+ *   points: [0, 300, 640],
+ *   position: 300,
+ *   velocity: 1200,
+ *   flickThreshold: 1008,
+ *   tolerance: 1,
+ *   projection: {seconds: 0.1, minSpeed: 250},
+ *   start: 0,
+ * }); // {index: 2, projected: 420}
+ * ```
+ */
+export function resolveSnapPoint({
+  points,
+  position,
+  velocity,
+  flickThreshold,
+  tolerance = 0,
+  projection,
+  start,
+  fromIndex,
+  maxSteps,
+}: {
+  /** Snap point positions, ascending. */
+  points: ReadonlyArray<number>;
+  position: number;
+  velocity: number;
+  /** From this speed (units/s) on, a release is a flick. */
+  flickThreshold: number;
+  /** A snap point this close to the position counts as reached by a flick. */
+  tolerance?: number;
+  /** Judge a slow release where it would coast to; absent, where it was let go. */
+  projection?: SnapPointProjection;
+  /** Where the drag began: a release moving back toward it cancels to it. */
+  start?: number;
+  /** The snap point the release starts from, for `maxSteps`. */
+  fromIndex?: number;
+  /** At most this many points away from `fromIndex`. */
+  maxSteps?: number;
+}): SnapPointRelease {
+  if (points.length === 0) {
+    throw new RangeError('resolveSnapPoint needs at least one snap point');
+  }
+  const projectedVelocity =
+    projection == null || Math.abs(velocity) < (projection.minSpeed ?? 0)
+      ? 0
+      : velocity;
+  const choice = selectSnapPoint(points, {
+    position,
+    velocity: projectedVelocity,
+    rate:
+      projection == null ? undefined : rateForProjection(projection.seconds),
+    fromIndex,
+    maxSteps,
+  });
+  let index = choice.index;
+  if (Math.abs(velocity) >= flickThreshold) {
+    // A flick goes at least to the next snap point beyond where it is.
+    let next = -1;
+    if (velocity > 0) {
+      next = points.findIndex(d => d > position + tolerance);
+    } else {
+      for (let i = points.length - 1; i >= 0 && next === -1; i -= 1) {
+        if (points[i] < position - tolerance) {
+          next = i;
+        }
+      }
+    }
+    if (next !== -1 && (velocity > 0 ? next > index : next < index)) {
+      index = next;
+    }
+  }
+  if (
+    start != null &&
+    velocity !== 0 &&
+    Math.sign(velocity) === Math.sign(start - position)
+  ) {
+    index = nearestIndex(points, start);
+  }
+  if (fromIndex != null && maxSteps != null) {
+    // A stale index past either end counts from the nearest real snap point.
+    const from = Math.min(Math.max(fromIndex, 0), points.length - 1);
+    index = Math.min(Math.max(index, from - maxSteps), from + maxSteps);
+  }
+  return {index, projected: choice.projected};
+}