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,100 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file callerMotionValues.test.ts
+ * @input vitest, easedProgress and solveAnimatedPageScroll on a fixed grid of
+ *   easings, durations, moves and retarget velocities
+ * @output Pins each value of those curves, bit for bit, as one hash per set:
+ *   easedProgress's positions and velocities, the pager's positions, and the
+ *   pager's velocities
+ * @position Testing; guards the values that Popover, SegmentedControl and the
+ *   pager read from the progress module
+ */
+
+import {createHash} from 'node:crypto';
+import {describe, expect, it} from 'vitest';
+import {cubicBezier, type BezierPoints} from '../bezier';
+import {solveAnimatedPageScroll} from '../paging';
+import {easedProgress} from '../progress';
+
+/** The first 16 hex digits of the SHA-256 of `values` as float64 bytes. */
+function hashOf(values: ReadonlyArray<number>): string {
+  const bytes = new Uint8Array(new Float64Array(values).buffer);
+  return createHash('sha256').update(bytes).digest('hex').slice(0, 16);
+}
+
+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],
+];
+
+/** 1,005 times, in steps of 1/1000 of `duration`, from 2 steps before it. */
+function sampleTimes(duration: number): number[] {
+  const times: number[] = [];
+  for (let i = 0; i < 1005; i++) {
+    times.push(((i - 2) / 1000) * duration);
+  }
+  return times;
+}
+
+describe('the values Popover, SegmentedControl and the pager read', () => {
+  it('easedProgress keeps each position and velocity', () => {
+    const quarterSteps = (x: number) => Math.floor(4 * x) / 4;
+    const eases = [...EASINGS.map(points => cubicBezier(points)), quarterSteps];
+    const values: number[] = [];
+    for (const ease of eases) {
+      for (const seconds of [0, 0.1, 0.2, 0.3, 0.5]) {
+        for (const jumps of [false, true]) {
+          const curve = easedProgress(seconds, ease, {jumps});
+          for (const t of sampleTimes(seconds)) {
+            values.push(curve.at(t), curve.velocity(t));
+          }
+        }
+      }
+    }
+    expect(values).toHaveLength(140_700);
+    expect(hashOf(values)).toBe('617cb8ab38270e58');
+  });
+
+  // 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 keeps each position, and each velocity but the first from rest', () => {
+    const positions: number[] = [];
+    const velocities: number[] = [];
+    for (const curve of EASINGS) {
+      for (const durationMs of [150, 300]) {
+        for (const [from, to] of [
+          [0, 402],
+          [0, 804],
+          [0, 2010],
+          [804, 402],
+          [100, 100],
+        ]) {
+          for (const velocity of [undefined, 900, -900, 0, 2500]) {
+            const move = solveAnimatedPageScroll({
+              from,
+              to,
+              durationMs,
+              curve,
+              velocity,
+            });
+            for (const t of sampleTimes(move.duration)) {
+              positions.push(move.at(t));
+              if (t > 0 || velocity != null) {
+                velocities.push(move.velocity(t));
+              }
+            }
+          }
+        }
+      }
+    }
+    expect(positions).toHaveLength(301_500);
+    expect(hashOf(positions)).toBe('e1e70cc3826c653d');
+    expect(velocities).toHaveLength(301_320);
+    expect(hashOf(velocities)).toBe('5566f63049f35967');
+  });
+});

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';