feat(core): one rect morph for touch presentations that grow out of a source rect

.changeset/motion-morph-path.md

@@ -0,0 +1,7 @@
+---
+'@astryxdesign/core': patch
+---
+
+[chore] Internal: the rect morph's paths, the geometry touch presentations share when they grow out of a source rect and shrink back into it. `lerpPath` (a straight line between two rects) and `edgeGrowPath` (UIKit's popover, growing out of a point on its edge) name the rect an element shows at each progress, and say how an interrupted motion continues in their own law; `morphCurves` turns a path into compositor curves (`translate`, `scale` and a companion `opacity`). Not exported from the package entry point; no component uses them yet.
+
+@vjeux

.changeset/motion-rect-morph.md

@@ -0,0 +1,7 @@
+---
+'@astryxdesign/core': patch
+---
+
+[chore] Internal: the rect morph, one way for a touch presentation to grow out of a source rect and shrink back into it. `createRectMorph` presents an element along a path (`lerpPath`, `edgeGrowPath`) and dismisses it back on a copy or on itself, each continuing the other from the rect on screen. Each play takes the timing the component's motion record names (AST-094 FR45): a duration and easing, or a spring, starting from the velocity it is given. Reduced Motion is left to the animator. `easedProgress` moves to the progress helpers with the same values. `timedCurve` joins them: a timed motion that keeps a retargeted velocity, for the pager and the rect morph. Not exported from the package entry point; no component uses it yet.
+
+@vjeux

docs/architecture/react-component-runtime.md

@@ -226,7 +226,9 @@
   change and moves shifted content with a compositor-only translate played
   through the shared rectangle morph (`architecture:layer-runtime` INV15;
   `spec:AST-094` FR5) once Core has that morph; until then, the module plays
-  its own compositor translate. It never animates height. Its walk visits only
+  its own compositor translate. (Implementation gap: Core has the shared
+  rectangle morph, but the size-change glide still plays its own compositor
+  translate.) It never animates height. Its walk visits only
   the changed element's ancestors up to the area and the element siblings on
   either side at each of their levels, through `parentElement`,
   `nextElementSibling` and `previousElementSibling`, descending only into an
@@ -301,7 +303,7 @@
   (`design:reduced-motion` DR1–DR3); the touch hit-area expansion; and List's
   reorder session, for a collection that adapts the reorderable object to its
   own values or whose rows are not `ListItem`s (`createReorderable`'s
   plain-element `attach`, `spec:AST-103` FR4b, is not built).
   Components import
   them statically, and the bundler
   keeps one copy per page however many components use them. A surface

docs/specs/AST-094-touch-presentations/spec.md

@@ -35,6 +35,7 @@ verified_by:
     "packages/core/src/Layer/holdEntranceInput.ts",
     "packages/core/src/Layer/inputHold.ts",
     "packages/core/src/hooks/usePager.ts",
+    "packages/core/src/motion/rectMorph.ts",
     "packages/core/src/motion/uikit/segmented.ts",
     "packages/core/src/motion/uikit/slider.ts"
   ]

packages/core/src/Popover/popoverSurfaceMotion.ts

@@ -28,12 +28,8 @@ import {
 } from '../motion/animator';
 import {holdInput} from '../Layer/inputHold';
 import {ENTRANCE_OPACITY_FLOOR} from '../motion/opacityFloor';
-import {mapProgress, mapRange} from '../motion/progress';
-import {
-  easedProgress,
-  readThemeTiming,
-  type ThemeTimingTokens,
-} from '../motion/themeTiming';
+import {easedProgress, mapProgress, mapRange} from '../motion/progress';
+import {readThemeTiming, type ThemeTimingTokens} from '../motion/themeTiming';
 import {placePopoverExitCopy} from '../privateAttributes/popoverExit.stylex';
 import {
   frameOf,
@@ -57,8 +53,11 @@ export type {
 /**
  * The curves from `from` to `to` as `progress` moves from 0 to 1. The scale
  * and the length move together, so the scale along the axis is their product.
+ *
+ * @internal Read by the rect morph's popover proofs; not exported from the
+ *   package.
  */
-function surfaceCurves(
+export function surfaceCurves(
   from: SurfaceState,
   to: SurfaceState,
   axis: 'x' | 'y',
@@ -85,8 +84,16 @@ function timingOn(element: Element, tokens: ThemeTimingTokens): MotionCurve {
   return readThemeTiming(element, tokens) ?? easedProgress(0, x => x);
 }
 
-/** What `animator` shows now, split back into scale and length. */
-function readState(animator: Animator, axis: 'x' | 'y'): SurfaceState {
+/**
+ * What `animator` shows now, split back into scale and length.
+ *
+ * @internal Read by the rect morph's popover proofs; not exported from the
+ *   package.
+ */
+export function readState(
+  animator: Pick<Animator, 'get'>,
+  axis: 'x' | 'y',
+): SurfaceState {
   const across = animator.get(axis === 'x' ? 'scaleY' : 'scaleX');
   const along = animator.get(axis === 'x' ? 'scaleX' : 'scaleY');
   return {

packages/core/src/SegmentedControl/useSegmentedSelectionMotion.ts

@@ -41,7 +41,8 @@ import {useIsomorphicLayoutEffect} from '../hooks/useIsomorphicLayoutEffect';
 import {observeResize} from '../utils/sharedResizeObserver';
 import {titleOfSegment} from '../privateAttributes/segmentTitle.stylex';
 import {mapProgress, mapRange} from '../motion/progress';
-import {easedProgress, readThemeTiming} from '../motion/themeTiming';
+import {easedProgress} from '../motion/progress';
+import {readThemeTiming} from '../motion/themeTiming';
 import {useSegmentedTouchTracking} from './useSegmentedTouchTracking';
 
 /** The segments, in DOM order. */

packages/core/src/motion/README.md

@@ -45,6 +45,8 @@ roles through `resolveMotion`.
 | `resolveSnapPoint.ts`                            | Release policy: the snap point a release lands on (flick, back-out cancel, step limit), on `selectSnapPoint`. Internal.                                              |
 | `bezier.ts`                                      | Cubic-bézier timing functions (Core Animation's named curves).                                                                                                       |
 | `animator.ts`                                    | Compositor animator: springs, coasts and any closed-form curve compiled to Web Animations, read back analytically.                                                   |
+| `morphPath.ts`                                   | The rect an element shows at each progress of a grow-out presentation: a straight line, a popover’s edge growth, and the curves that put it there.                   |
+| `rectMorph.ts`                                   | Grow out of a source rect and shrink back into it along a path: present and dismiss, each continuing the other from the rect on screen.                              |
 | `progress.ts`                                    | A spring's progress, one curve mapped from another (companions, clamped ranges), the velocity that continues a motion.                                               |
 | `presentation.ts`                                | Where each moving element is drawn relative to where the engine hit-tests it, reported by the animator while translate runs; read by the gesture host at touch-down. |
 | `reducedMotionPlan.ts`                           | The animator's Reduce Motion planner: what one call becomes, a cross-fade whose travel lands while transparent or at once.                                           |

packages/core/src/motion/__tests__/callerMotionValues.test.ts

@@ -0,0 +1,220 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file callerMotionValues.test.ts
+ * @input vitest, easedProgress and solveAnimatedPageScroll, and copies of
+ *   their earlier versions, on a fixed grid of easings, durations, moves and
+ *   retarget velocities
+ * @output Checks that each position and velocity is the same number, bit for
+ *   bit, as the earlier version gives on the same platform
+ * @position Testing; guards the values that Popover, SegmentedControl and the
+ *   pager read from the progress module
+ */
+
+import {describe, expect, it} from 'vitest';
+import type {MotionCurve} from '../animator';
+import {cubicBezier, type BezierPoints} from '../bezier';
+import {solveAnimatedPageScroll} from '../paging';
+import {easedProgress} from '../progress';
+import {paging} from '../uikit/paging';
+
+// The two reference functions below are copies of main at ebb9ddec. Their
+// float results can change with the platform's math library, so the test
+// compares them with the shipped functions on one platform, not with a
+// stored hash.
+
+/** easedProgress, copied from themeTiming.ts. */
+function referenceEasedProgress(
+  seconds: number,
+  ease: (x: number) => number,
+  {jumps = false}: {readonly jumps?: boolean} = {},
+): MotionCurve {
+  const at = (t: number) =>
+    seconds <= 0 || t >= seconds ? 1 : ease(Math.max(0, t) / seconds);
+  // A central difference, one step inside the curve at either end.
+  const step = Math.min(1e-3, seconds / 100);
+  return {
+    duration: seconds,
+    at,
+    velocity: t => {
+      if (seconds <= 0 || t >= seconds) {
+        return 0;
+      }
+      const before = Math.max(0, t - step);
+      const after = Math.min(seconds, t + step);
+      if (!jumps) {
+        return (at(after) - at(before)) / (after - before);
+      }
+      const here = at(t);
+      const slopes: number[] = [];
+      if (t > before) {
+        slopes.push((here - at(before)) / (t - before));
+      }
+      if (after > t) {
+        slopes.push((at(after) - here) / (after - t));
+      }
+      return slopes.reduce((a, b) => (Math.abs(b) < Math.abs(a) ? b : a));
+    },
+  };
+}
+
+/** solveAnimatedPageScroll, copied from paging.ts. */
+function referenceAnimatedPageScroll({
+  from,
+  to,
+  durationMs = paging.animatedScroll.durationMs,
+  curve = paging.animatedScroll.curve,
+  velocity,
+}: {
+  from: number;
+  to: number;
+  durationMs?: number;
+  curve?: BezierPoints;
+  velocity?: number;
+}): MotionCurve {
+  const duration = durationMs / 1000;
+  const distance = to - from;
+  const ease = cubicBezier(curve);
+  const progress = (u: number) => ease(Math.min(1, Math.max(0, u)));
+  // The carry, in px: the retargeted velocity over the whole duration, less
+  // what the curve's own starting slope already gives.
+  const startSlope = progress(1e-4) / 1e-4;
+  const carry =
+    velocity == null ? 0 : velocity * duration - distance * startSlope;
+  const at = (t: number) => {
+    const u = Math.min(1, Math.max(0, t / duration));
+    return from + distance * progress(u) + carry * u * (1 - u) * (1 - u);
+  };
+  return {
+    duration,
+    at,
+    velocity: t => {
+      if (t <= 0) {
+        return velocity ?? 0;
+      }
+      if (t >= duration) {
+        return 0;
+      }
+      const h = Math.min(1e-4, t / 2, (duration - t) / 2);
+      return (at(t + h) - at(t - h)) / (2 * h);
+    },
+  };
+}
+
+const EASINGS: ReadonlyArray<BezierPoints> = [
+  [0, 0, 1, 1],
+  [0.25, 0.1, 0.25, 1],
+  [0.42, 0, 1, 1],
+  [0, 0, 0.58, 1],
+  [0.42, 0, 0.58, 1],
+  [0.2, 0, 0, 1],
+  [0.24, 1, 0.4, 1],
+];
+
+/**
+ * 1,005 times, in steps of 1/1000 of `duration`, from 2 steps before it, and
+ * 10 µs, 0.1 ms and 1 ms in from each end.
+ */
+function sampleTimes(duration: number): number[] {
+  const times: number[] = [];
+  for (let i = 0; i < 1005; i++) {
+    times.push(((i - 2) / 1000) * duration);
+  }
+  for (const inset of [1e-5, 1e-4, 1e-3]) {
+    times.push(inset, duration - inset);
+  }
+  return times;
+}
+
+/** Collects each sample whose shipped value is not the reference's. */
+function differences() {
+  let compared = 0;
+  const found: string[] = [];
+  return {
+    compare(label: string, shipped: number, reference: number) {
+      compared++;
+      if (!Object.is(shipped, reference) && found.length < 5) {
+        found.push(`${label}: ${shipped} is not ${reference}`);
+      }
+    },
+    get compared() {
+      return compared;
+    },
+    found,
+  };
+}
+
+describe('the values Popover, SegmentedControl and the pager read', () => {
+  it('easedProgress gives the same positions and velocities as before', () => {
+    const quarterSteps = (x: number) => Math.floor(4 * x) / 4;
+    const eases = [
+      ...EASINGS.map(points => ({
+        name: points.join(','),
+        ease: cubicBezier(points),
+      })),
+      {name: 'steps(4)', ease: quarterSteps},
+      {name: 'linear', ease: (x: number) => x},
+    ];
+    const positions = differences();
+    const velocities = differences();
+    for (const {name, ease} of eases) {
+      for (const seconds of [0, 0.001, 0.1, 0.15, 0.2, 0.3, 0.5]) {
+        for (const jumps of [false, true]) {
+          const shipped = easedProgress(seconds, ease, {jumps});
+          const reference = referenceEasedProgress(seconds, ease, {jumps});
+          for (const t of sampleTimes(seconds)) {
+            const label = `${name} ${seconds} s jumps=${jumps} t=${t}`;
+            positions.compare(label, shipped.at(t), reference.at(t));
+            velocities.compare(
+              label,
+              shipped.velocity(t),
+              reference.velocity(t),
+            );
+          }
+        }
+      }
+    }
+    expect(positions.compared).toBe(9 * 7 * 2 * 1011);
+    expect(positions.found).toEqual([]);
+    expect(velocities.found).toEqual([]);
+  });
+
+  // From rest, the velocity at t <= 0 is the one value that changes:
+  // paging.test.ts holds it to the curve's starting slope.
+  it('the pager gives the same positions, and each velocity but the first from rest', () => {
+    const positions = differences();
+    const velocities = differences();
+    for (const curve of [undefined, ...EASINGS]) {
+      for (const durationMs of [150, 300, 350]) {
+        for (const [from, to] of [
+          [0, 402],
+          [0, 804],
+          [0, 2010],
+          [804, 402],
+          [100, -200],
+          [100, 100],
+        ]) {
+          for (const velocity of [undefined, 900, -900, 0, 2500]) {
+            const move = {from, to, durationMs, curve, velocity};
+            const shipped = solveAnimatedPageScroll(move);
+            const reference = referenceAnimatedPageScroll(move);
+            for (const t of sampleTimes(reference.duration)) {
+              const label = `${JSON.stringify(move)} t=${t}`;
+              positions.compare(label, shipped.at(t), reference.at(t));
+              if (t > 0 || velocity != null) {
+                velocities.compare(
+                  label,
+                  shipped.velocity(t),
+                  reference.velocity(t),
+                );
+              }
+            }
+          }
+        }
+      }
+    }
+    expect(positions.compared).toBe(8 * 3 * 6 * 5 * 1011);
+    expect(positions.found).toEqual([]);
+    expect(velocities.found).toEqual([]);
+  });
+});

packages/core/src/motion/__tests__/motionBundle.ts

@@ -9,6 +9,8 @@
  */
 
 export {createMotionEngine} from '../animator';
+export {progressCurve} from '../progress';
+export {createRectMorph, edgeGrowPath, lerpPath} from '../rectMorph';
 export {solveSpring, toSpring} from '../spring';
 export {registerSpringsTable, springs} from '../uikit/springs';
 export {motionRoleOf} from '../roles';