An open source design system that's fully customizable and agent ready
TypeScript
chore(lab): Lab's animator hook, over Core's internal touch entry (#9754)
Christopher Chedeauc26fcd543cd4
diff --git a/.changeset/core-internal-touch-entry-lab-animator.md b/.changeset/core-internal-touch-entry-lab-animator.mdnew file mode 100644index 0000000000..75bf478b46--- /dev/null+++ b/.changeset/core-internal-touch-entry-lab-animator.md@@ -0,0 +1,7 @@+---+'@astryxdesign/core': patch+---++[chore] Internal: Core's internal motion engine factory is renamed `createMotionEngine` (from `createMotionAnimator`), with its types `MotionEngine` and `MotionEngineOptions`, at its source and in every internal caller. Core's internal touch entry also re-exports, by name, the UIKit gesture values, the right-to-left check, and the touch-presentation hook and query that Lab components read. Lab's `useMotionEngine` hook wraps the engine, and Lab's refresh control uses it. Apps import nothing new.++@vjeuxdiff --git a/packages/core/src/DateInput/wheelStrip.ts b/packages/core/src/DateInput/wheelStrip.tsindex 8feef24354..506a2f783f 100644--- a/packages/core/src/DateInput/wheelStrip.ts+++ b/packages/core/src/DateInput/wheelStrip.ts@@ -16,7 +16,7 @@*/import {canVibrate, playHaptic} from '../gestures/haptics';-import {createMotionAnimator, type MotionCurve} from '../motion/animator';+import {createMotionEngine, type MotionCurve} from '../motion/animator';import {reducedMotionFade} from '../motion/reducedMotion';import {picker} from '../motion/uikit/picker';import {@@ -132,7 +132,7 @@ function now(): number {* ```*/export function createWheelStrip(initialLayout: WheelLayout): WheelStrip {- const animator = createMotionAnimator(null);+ const animator = createMotionEngine(null);let layout = initialLayout;let running: Running | null = null;let nearestListener: ((position: number) => void) | null = null;diff --git a/packages/core/src/SegmentedControl/useSegmentedSelectionMotion.test.ts b/packages/core/src/SegmentedControl/useSegmentedSelectionMotion.test.tsindex f88dc63b3b..713644d7f9 100644--- a/packages/core/src/SegmentedControl/useSegmentedSelectionMotion.test.ts+++ b/packages/core/src/SegmentedControl/useSegmentedSelectionMotion.test.ts@@ -13,7 +13,7 @@import {afterEach, beforeEach, describe, expect, it, vi} from 'vitest';import {motionRoleOf} from '../motion/roles';-import {createMotionAnimator, type Animator} from '../motion/animator';+import {createMotionEngine, type Animator} from '../motion/animator';import {solveSpring, toSpring} from '../motion/spring';import {cubicBezier} from '../motion/bezier';import {segmentedControl, springs} from '../motion/uikit';@@ -105,12 +105,12 @@ function setup(selected: string, {coarse = true}: {coarse?: boolean} = {}) {document.head.append(style);document.body.append(track);// A finger by default: Reduced Motion fades (design:reduced-motion DR2).- const animator: Animator = createMotionAnimator(null, {+ const animator: Animator = createMotionEngine(null, {now: () => clock,pseudoElement: '::before',});// The ::after: the lifted lens's shadow, or the surface fading out.- const afterAnimator: Animator = createMotionAnimator(null, {+ const afterAnimator: Animator = createMotionEngine(null, {now: () => clock,pseudoElement: '::after',initial: {opacity: 0},diff --git a/packages/core/src/SegmentedControl/useSegmentedSelectionMotion.ts b/packages/core/src/SegmentedControl/useSegmentedSelectionMotion.tsindex 69e10fba73..3fdf9c0af3 100644--- a/packages/core/src/SegmentedControl/useSegmentedSelectionMotion.ts+++ b/packages/core/src/SegmentedControl/useSegmentedSelectionMotion.ts@@ -25,7 +25,7 @@ import {type RefObject,} from 'react';import {- createMotionAnimator,+ createMotionEngine,type AnimateOptions,type Animator,type MotionCurve,@@ -539,7 +539,7 @@ export class SegmentedSelectionMotion {private readonly after: Animator;constructor(- private readonly animator: Animator = createMotionAnimator(null, {+ private readonly animator: Animator = createMotionEngine(null, {pseudoElement: '::before',}),options: SegmentedSelectionMotionOptions = {},@@ -552,7 +552,7 @@ export class SegmentedSelectionMotion {this.now = options.now ?? defaultNow;this.after =options.afterAnimator ??- createMotionAnimator(null, {+ createMotionEngine(null, {pseudoElement: '::after',initial: {opacity: 0},});diff --git a/packages/core/src/Slider/sliderTouchController.ts b/packages/core/src/Slider/sliderTouchController.tsindex 5d90e247e1..916ae87e31 100644--- a/packages/core/src/Slider/sliderTouchController.ts+++ b/packages/core/src/Slider/sliderTouchController.ts@@ -29,7 +29,7 @@ import {TapGestureRecognizer} from '../gestures/TapGestureRecognizer';import type {PointerKind} from '../gestures/types';import {isRtlElement} from '../hooks/isRtlElement';import {- createMotionAnimator,+ createMotionEngine,type Animator,type MotionCurve,type MotionHandle,@@ -1186,7 +1186,7 @@ export class SliderTouchController {private animatorFor(element: HTMLElement): Animator {let animator = this.animators.get(element);if (animator == null) {- animator = createMotionAnimator(element);+ animator = createMotionEngine(element);this.animators.set(element, animator);}return animator;diff --git a/packages/core/src/Switch/useSwitchTouch.test.ts b/packages/core/src/Switch/useSwitchTouch.test.tsindex 63fd79d077..b74e18c849 100644--- a/packages/core/src/Switch/useSwitchTouch.test.ts+++ b/packages/core/src/Switch/useSwitchTouch.test.ts@@ -39,7 +39,7 @@ vi.mock('../motion/animator', async importOriginal => {const actual = await importOriginal<typeof AnimatorModule>();return {...actual,- createMotionAnimator: (+ createMotionEngine: (element: Element,options: {pseudoElement?: string} = {},) => {diff --git a/packages/core/src/Switch/useSwitchTouch.ts b/packages/core/src/Switch/useSwitchTouch.tsindex 2422dc0f47..888f997b53 100644--- a/packages/core/src/Switch/useSwitchTouch.ts+++ b/packages/core/src/Switch/useSwitchTouch.ts@@ -23,7 +23,7 @@ import type {GestureTouch} from '../gestures/types';import {isRtlElement} from '../hooks/isRtlElement';import {useIsomorphicLayoutEffect} from '../hooks/useIsomorphicLayoutEffect';import {- createMotionAnimator,+ createMotionEngine,type Animator,type MotionCurve,} from '../motion/animator';@@ -282,15 +282,15 @@ export class SwitchTouchController {return;}registerSwitchTable();- this.thumb = createMotionAnimator(elements.thumb);+ this.thumb = createMotionEngine(elements.thumb);// The layer rests clear (its class's opacity 0) while the visuals show// the value; from here its opacity is the animator's.- this.fade = createMotionAnimator(elements.track, {+ this.fade = createMotionEngine(elements.track, {pseudoElement: '::after',initial: {opacity: 0},});this.fade.set({opacity: 0});- this.shadow = createMotionAnimator(elements.thumb, {+ this.shadow = createMotionEngine(elements.thumb, {pseudoElement: '::after',initial: {opacity: 0},});diff --git a/packages/core/src/animator/createAnimator.ts b/packages/core/src/animator/createAnimator.tsindex c712bd9467..0fe0663ba4 100644--- a/packages/core/src/animator/createAnimator.ts+++ b/packages/core/src/animator/createAnimator.ts@@ -18,9 +18,9 @@*/import {- createMotionAnimator,+ createMotionEngine,SETTLE_THRESHOLD,- type Animator as MotionAnimator,+ type Animator as MotionEngine,type MotionCurve,type MotionProperty,type MotionValues,@@ -199,7 +199,7 @@ export function createAttachableAnimator(): {readonly animator: Animator;readonly attach: (element: HTMLElement | null) => void;} {- const motion: MotionAnimator = createMotionAnimator(null);+ const motion: MotionEngine = createMotionEngine(null);// Calls do nothing while no element is attached, before the ref attaches// or after it lets go. They also do nothing after destroy, and animate and// decay then resolve at once.diff --git a/packages/core/src/animator/publicSurface.test.ts b/packages/core/src/animator/publicSurface.test.tsindex 00babbcb42..e2196d246e 100644--- a/packages/core/src/animator/publicSurface.test.ts+++ b/packages/core/src/animator/publicSurface.test.ts@@ -21,7 +21,7 @@ const SRC = path.join(__dirname, '..');/** Names of the motion module beneath the public animator. */const INTERNAL = [- 'createMotionAnimator',+ 'createMotionEngine','createAttachableAnimator','animatorFor','coast',@@ -67,6 +67,6 @@ describe('the public animator surface', () => {'utf8',);expect(motion).not.toMatch(/export function createAnimator\b/);- expect(motion).toMatch(/export function createMotionAnimator\b/);+ expect(motion).toMatch(/export function createMotionEngine\b/);});});diff --git a/packages/core/src/gestures/__tests__/browser/presentedFixture.ts b/packages/core/src/gestures/__tests__/browser/presentedFixture.tsindex cc28188bf1..28d360831f 100644--- a/packages/core/src/gestures/__tests__/browser/presentedFixture.ts+++ b/packages/core/src/gestures/__tests__/browser/presentedFixture.ts@@ -22,7 +22,7 @@* @position Browser fixture of presentedHitTesting.interaction.browser.spec.ts; test-only*/-import {createMotionAnimator} from '../../../motion/animator';+import {createMotionEngine} from '../../../motion/animator';import {presentedOffsetOf} from '../../../motion/presentation';import {GestureHost} from '../../GestureHost';import {PanGestureRecognizer} from '../../PanGestureRecognizer';@@ -101,7 +101,7 @@ const TRAVEL = 444;*/const SPRING = {response: 6, dampingRatio: 1} as const;-const animator = createMotionAnimator(sheet);+const animator = createMotionEngine(sheet);const drawn = (target: Element): DOMRect =>Element.prototype.getBoundingClientRect.call(target);diff --git a/packages/core/src/hooks/usePager.test.ts b/packages/core/src/hooks/usePager.test.tsindex 46831b156e..506e985b43 100644--- a/packages/core/src/hooks/usePager.test.ts+++ b/packages/core/src/hooks/usePager.test.ts@@ -17,7 +17,7 @@ import {afterEach, beforeEach, describe, expect, it, vi} from 'vitest';import {GestureHost} from '../gestures/GestureHost';import {PanGestureRecognizer} from '../gestures/PanGestureRecognizer';import {ManualClock} from '../gestures/__tests__/harness';-import {createMotionAnimator, type Animator} from '../motion/animator';+import {createMotionEngine, type Animator} from '../motion/animator';import {solveAnimatedPageScroll, solvePaging} from '../motion/paging';import type * as motionResolution from '../motion/resolveMotion';import {resolveMotion} from '../motion/resolveMotion';@@ -305,7 +305,7 @@ function setup(options: Partial<PagerOptions> = {}, rtl = false): Fixture {value: WIDTH,configurable: true,});- const animator = createMotionAnimator(track, {+ const animator = createMotionEngine(track, {now: () => now,requestFrame: callback => {frameQueue.push(callback);@@ -1259,7 +1259,7 @@ describe('createPager', () => {// (DR3). The drag itself follows the pointer.function reducedPager(f: Fixture, defaultIndex: number, coarse: boolean) {stubMedia(true, coarse);- const reduced = createMotionAnimator(f.track, {+ const reduced = createMotionEngine(f.track, {now: () => now,requestFrame: callback => {frameQueue.push(callback);@@ -1928,7 +1928,7 @@ function setupChildren(value: WIDTH,configurable: true,});- const animator = createMotionAnimator(track, {+ const animator = createMotionEngine(track, {now: () => now,requestFrame: callback => {frameQueue.push(callback);@@ -2461,7 +2461,7 @@ describe('pre-review fixes', () => {configurable: true,});const host = {attach: () => () => {}} as unknown as GestureHost;- const animator = createMotionAnimator(track, {+ const animator = createMotionEngine(track, {now: () => now,requestFrame: callback => {frameQueue.push(callback);diff --git a/packages/core/src/internal/touch.test.ts b/packages/core/src/internal/touch.test.tsindex 0300e71f38..02e63f68e0 100644--- a/packages/core/src/internal/touch.test.ts+++ b/packages/core/src/internal/touch.test.ts@@ -45,7 +45,7 @@ describe('internal/touch', () => {const scroll = await import('../motion/uikit/scroll');expect(entry.PanGestureRecognizer).toBe(pan.PanGestureRecognizer);expect(entry.useGestureRecognizer).toBe(hook.useGestureRecognizer);- expect(entry.createMotionAnimator).toBe(animator.createMotionAnimator);+ expect(entry.createMotionEngine).toBe(animator.createMotionEngine);expect(entry.cubicBezier).toBe(bezier.cubicBezier);expect(entry.mapProgress).toBe(progress.mapProgress);expect(entry.parseCssEasing).toBe(roles.parseCssEasing);@@ -54,8 +54,34 @@ describe('internal/touch', () => {expect(entry.rubberBandInverse).toBe(band.rubberBandInverse);expect(entry.rubberBandSlope).toBe(band.rubberBandSlope);expect(entry.scroll).toBe(scroll.scroll);- // No internal factory shares a public factory's name.- expect(entry).not.toHaveProperty('createAnimator');+ // No internal factory shares a public factory's name, or a planned one's.+ for (const name of [+ 'createAnimator',+ 'createPanGesture',+ 'createDragToSnapPoints',+ ]) {+ expect(entry, name).not.toHaveProperty(name);+ }+ });++ it('re-exports by name what other Lab components read', async () => {+ const entry: Record<string, unknown> = await import('./touch');+ const presentation = await import('../utils/touchPresentation');+ const direction = await import('../hooks/isRtlElement');+ const uikitGestures = await import('../motion/uikit/gestures');+ const touchQueries = await import('../utils/touchQueries');+ expect(entry.useTouchPresentation).toBe(presentation.useTouchPresentation);+ expect(entry.isRtlElement).toBe(direction.isRtlElement);+ expect(entry.UIKIT_GESTURES).toBe(uikitGestures.UIKIT_GESTURES);+ expect(entry.TOUCH_QUERY).toBe(touchQueries.TOUCH_QUERY);+ // An identity check passes when both sides are undefined, so each name+ // must also be defined.+ for (const name of ['useTouchPresentation', 'isRtlElement']) {+ expect(typeof entry[name], name).toBe('function');+ }+ for (const name of ['UIKIT_GESTURES', 'TOUCH_QUERY']) {+ expect(entry[name], name).toBeDefined();+ }});it('attaches no window or document listeners when it loads', async () => {diff --git a/packages/core/src/internal/touch.ts b/packages/core/src/internal/touch.tsindex 560cc95f3e..c46d3d5a83 100644--- a/packages/core/src/internal/touch.ts+++ b/packages/core/src/internal/touch.ts@@ -3,10 +3,11 @@/*** @file touch.ts* @input The gesture core: the arena, the recognizers, and their geometry;- * the pan, the motion animator and the motion math that Lab's- * useRefreshControl reads+ * the pan, the motion engine and math, and the touch-presentation and+ * direction helpers that Lab components read* @output `@astryxdesign/core/internal/touch`: the gesture core's primitives- * for Lab components, re-exported by name+ * and the motion, touch-presentation and direction modules for Lab+ * components, re-exported by name* @position An internal entry reserved for Astryx's own packages:* undocumented, outside the public API and its compatibility promise* (spec:AST-017 FR21), versioned in lockstep with Core, and allowed only in@@ -43,7 +44,7 @@ export {TapGestureRecognizer} from '../gestures/TapGestureRecognizer';export {DEFAULT_ENVIRONMENT} from '../gestures/types';// Lab's useRefreshControl reads these: its pull's pan and the hook that-// starts it. It also reads the motion animator and math, and the scroll+// starts it. It also reads the motion engine and math, and the scroll// view's bounce spring, for its pull, settle and end. Its indicator fades// along the settle's curve, and the motion-role parsers read the theme's// tokens for its end.@@ -55,12 +56,12 @@ export type {PointerKind,} from '../gestures/types';export {useGestureRecognizer} from '../gestures/useGestureRecognizer';-// The animator's internal factory. The public one, `createAnimator`, plays+// The motion engine's factory. The public one, `createAnimator`, plays// only the theme's state-change motion.-export {createMotionAnimator} from '../motion/animator';+export {createMotionEngine} from '../motion/animator';export type {- Animator as MotionAnimator,- AnimatorOptions as MotionAnimatorOptions,+ Animator as MotionEngine,+ AnimatorOptions as MotionEngineOptions,MotionCurve,} from '../motion/animator';export {cubicBezier} from '../motion/bezier';@@ -72,3 +73,10 @@ export {rubberBandSlope,} from '../motion/rubberBand';export {scroll} from '../motion/uikit/scroll';++// Lab components also read the UIKit gesture table, the touch presentation+// and its query, and an element's direction.+export {isRtlElement} from '../hooks/isRtlElement';+export {UIKIT_GESTURES} from '../motion/uikit/gestures';+export {useTouchPresentation} from '../utils/touchPresentation';+export {TOUCH_QUERY} from '../utils/touchQueries';diff --git a/packages/core/src/motion/README.md b/packages/core/src/motion/README.mdindex 352a45bbd9..bb8df901af 100644--- a/packages/core/src/motion/README.md+++ b/packages/core/src/motion/README.md@@ -69,7 +69,7 @@ the timings that decide who gets a touch are not roles.## Animator```-import {createMotionAnimator} from '../motion/animator';+import {createMotionEngine} from '../motion/animator';import {coast} from '../motion/coast';import {solveSpringTowardRamp, toSpring} from '../motion/spring';import {resolveMotion} from '../motion/resolveMotion';@@ -78,7 +78,7 @@ import {registerSpringsTable, springs} from '../motion/uikit';// Once, so the springs are registered as their roles:registerSpringsTable();-const animator = createMotionAnimator(sheet);+const animator = createMotionEngine(sheet);// The animator plays a motion role (spec:AST-094 FR4), its table value, as the// per-role tables stay internal (DEC-15); math on a spring reads the role with// resolveMotion.@@ -175,7 +175,7 @@ await handle.finished; // true if it ran to the end, false if interrupted- `animatorFor(element)` returns the one animator for an element, so codethat animates it from several places (a swipe on x, a removal on y)composes in one `translate` track.-- `createMotionAnimator(dialog, {pseudoElement: '::backdrop'})` drives a+- `createMotionEngine(dialog, {pseudoElement: '::backdrop'})` drives apseudo-element; with no inline style to hold it, a static filling animationholds its end value until the next animation replaces it, while thepseudo-element exists. A dialog's `::backdrop` is made again each time thediff --git a/packages/core/src/motion/__tests__/animator.interaction.browser.spec.ts b/packages/core/src/motion/__tests__/animator.interaction.browser.spec.tsindex 5d69afb906..e8ca643b2a 100644--- a/packages/core/src/motion/__tests__/animator.interaction.browser.spec.ts+++ b/packages/core/src/motion/__tests__/animator.interaction.browser.spec.ts@@ -109,7 +109,7 @@ async function open(page: Page) {</style><div id="box"></div><script>${script}</script>-<script>window.animator = Motion.createMotionAnimator(document.getElementById('box'));</script>`;+<script>window.animator = Motion.createMotionEngine(document.getElementById('box'));</script>`;await page.route('http://motion.test/', async route =>route.fulfill({contentType: 'text/html', body: html}),);@@ -394,7 +394,7 @@ test('a frame painted before the compositor has the curve shows the element wherdocument.body.append(element);return {element,- animator: Motion.createMotionAnimator(element, now ? {now} : {}),+ animator: Motion.createMotionEngine(element, now ? {now} : {}),};};const x = (element: HTMLElement) =>@@ -930,7 +930,7 @@ test('a role variable set on a scope changes nothing while touch motion stays inconst report: Record<string, {worst: number; lowest: number}> = {};for (const id of ['plain', 'themed'] as const) {const element = document.getElementById(id) as HTMLElement;- const animator = Motion.createMotionAnimator(element);+ const animator = Motion.createMotionEngine(element);animator.set({y: 300});const handle = animator.animate({y: 0}, {spring: Motion.springs.settle});await handle.started;@@ -1034,7 +1034,7 @@ test('a fade-in on an element its stylesheet hides stays visible once it retireselement.style.cssText ='position:absolute;top:120px;left:0;width:48px;height:48px;background:#c63';document.body.append(element);- const animator = Motion.createMotionAnimator(element);+ const animator = Motion.createMotionEngine(element);animator.set({opacity: 0});animator.animate({opacity: 1}, {spring});await new Promise<void>(resolve => {@@ -1106,7 +1106,7 @@ test('a dialog\u2019s ::backdrop plays the curve and holds its end state', asyncconst dialog = document.createElement('dialog');document.body.append(dialog);dialog.showModal();- const backdrop = Motion.createMotionAnimator(dialog, {+ const backdrop = Motion.createMotionEngine(dialog, {pseudoElement: '::backdrop',});backdrop.set({opacity: 0});diff --git a/packages/core/src/motion/__tests__/motionBundle.ts b/packages/core/src/motion/__tests__/motionBundle.tsindex 874fb5e2a8..097b83e91a 100644--- a/packages/core/src/motion/__tests__/motionBundle.ts+++ b/packages/core/src/motion/__tests__/motionBundle.ts@@ -8,7 +8,7 @@* (global `Motion`), and the type of that global*/-export {createMotionAnimator} from '../animator';+export {createMotionEngine} from '../animator';export {solveSpring, toSpring} from '../spring';export {registerSpringsTable, springs} from '../uikit/springs';export {motionRoleOf} from '../roles';diff --git a/packages/core/src/motion/animator.test.ts b/packages/core/src/motion/animator.test.tsindex a714bf6414..86c75b2ad3 100644--- a/packages/core/src/motion/animator.test.ts+++ b/packages/core/src/motion/animator.test.ts@@ -19,7 +19,7 @@ import path from 'node:path';import {afterEach, beforeEach, describe, expect, it, vi} from 'vitest';import {animatorFor,- createMotionAnimator,+ createMotionEngine,END_HOLD_MS,PROMOTION_LINGER_MS,type AnimatorOptions,@@ -205,7 +205,7 @@ function setup({}: AnimatorOptions & {reduced?: boolean; coarse?: boolean} = {}) {stubMedia(reduced, coarse);const element = document.createElement('div');- const animator = createMotionAnimator(element, {+ const animator = createMotionEngine(element, {now: () => clock,requestFrame,...options,@@ -2071,11 +2071,11 @@ describe('promotion: a compositing layer while it moves', () => {.mock.calls.filter(([read]) => read === node).length;const removed = document.createElement('div');document.body.append(removed);- createMotionAnimator(removed, {now: () => clock, requestFrame});+ createMotionEngine(removed, {now: () => clock, requestFrame});removed.remove();const kept = document.createElement('div');document.body.append(kept);- createMotionAnimator(kept, {now: () => clock, requestFrame});+ createMotionEngine(kept, {now: () => clock, requestFrame});await vi.advanceTimersByTimeAsync(0);expect(readsOf(removed)).toBe(0);// A node still in the document is read, once, in that task.@@ -2089,7 +2089,7 @@ describe('promotion: a compositing layer while it moves', () => {stylesheet['will-change'] = 'transform, opacity';stubMedia(false, false);const element = document.createElement('div');- const animator = createMotionAnimator(element, {+ const animator = createMotionEngine(element, {now: () => clock,requestFrame,});@@ -2834,7 +2834,7 @@ describe('Reduced Motion (design:reduced-motion)', () => {it('a running dip survives any re-attach, so the move never passes in view', async () => {const halfway = async (- animator: ReturnType<typeof createMotionAnimator>,+ animator: ReturnType<typeof createMotionEngine>,start: number,): Promise<number> => {// The plan lands by timer: step the clock to the landing.@@ -4171,7 +4171,7 @@ describe('pseudoElement: a dialog\u2019s ::backdrop', () => {describe('attach', () => {it('keeps state without an element and resumes the curve on attach', () => {- const animator = createMotionAnimator(null, {+ const animator = createMotionEngine(null, {now: () => clock,});animator.animate({x: 300}, {spring: springs.settle});@@ -4262,7 +4262,7 @@ describe('attach', () => {it('writes nothing for channels at identity', () => {const element = document.createElement('div');- createMotionAnimator(element);+ createMotionEngine(element);expect(element.getAttribute('style')).toBeNull();});});@@ -4367,7 +4367,7 @@ describe("a theme's reduced-motion mark", () => {const element = document.createElement('div');theme.append(element);document.body.append(theme);- const animator = createMotionAnimator(element, {+ const animator = createMotionEngine(element, {now: () => clock,requestFrame,});diff --git a/packages/core/src/motion/animator.ts b/packages/core/src/motion/animator.tsindex d9af6ca317..ba5ec8421a 100644--- a/packages/core/src/motion/animator.ts+++ b/packages/core/src/motion/animator.ts@@ -4,7 +4,7 @@* @file animator.ts* @input An element, target values, and a spring, momentum curves (coast.ts)* or any closed-form curve- * @output Exports `createMotionAnimator`, a compositor animator for+ * @output Exports `createMotionEngine`, a compositor animator for* translate, rotate, scale and opacity, and its option, handle and* transition types. It reads presentation values and velocities from the* analytic curves. It retargets with the velocity kept, freezes in place on@@ -299,9 +299,6 @@ export interface MotionCurve {readonly isTransition?: boolean;}-/**- * Options of `createMotionAnimator`.- *//** How `set` puts values in place. */export interface SetOptions {/**@@ -317,6 +314,9 @@ export interface SetOptions {promote?: boolean;}+/**+ * Options of `createMotionEngine`.+ */export interface AnimatorOptions {/*** Animates a pseudo-element of the element instead (`'::backdrop'` of a@@ -811,7 +811,7 @@ export function animatorFor(const key = options.pseudoElement ?? '';let animator = byPseudo.get(key);if (animator == null) {- animator = createMotionAnimator(element, options);+ animator = createMotionEngine(element, options);byPseudo.set(key, animator);}return animator;@@ -928,7 +928,7 @@ const REDUCED_TRANSITION: SpringTransition = {** @example* ```- * const animator = createMotionAnimator(sheet);+ * const animator = createMotionEngine(sheet);* // finger lifts at 1200 px/s heading for the detent at 0 (a component* // passes the spring of its motion role):* animator.animate({y: 0}, {spring: {response: 0.45, dampingRatio: 0.9}, velocity: {y: 1200}});@@ -937,7 +937,7 @@ const REDUCED_TRANSITION: SpringTransition = {* animator.stop(['y']);* ```*/-export function createMotionAnimator(+export function createMotionEngine(element: HTMLElement | null,options: AnimatorOptions = {},): Animator {diff --git a/packages/core/src/motion/resolveMotion.test.ts b/packages/core/src/motion/resolveMotion.test.tsindex cf5a306761..3045170905 100644--- a/packages/core/src/motion/resolveMotion.test.ts+++ b/packages/core/src/motion/resolveMotion.test.ts@@ -12,7 +12,7 @@*/import {afterEach, beforeEach, describe, expect, it, vi} from 'vitest';-import {createMotionAnimator} from './animator';+import {createMotionEngine} from './animator';import {coast} from './coast';import {resolveMotion} from './resolveMotion';import {solveSpring, toSpring} from './spring';@@ -93,7 +93,7 @@ describe('resolveMotion while the per-role tables stay internal (DEC-15)', () =>describe('the animator', () => {it("plays the table's spring even where a scope sets the role's variable", () => {const child = scoped({'--motion-springs-settle': '0.8s 0.3'});- const animator = createMotionAnimator(child, {now: () => 0});+ const animator = createMotionEngine(child, {now: () => 0});animator.set({y: 300});animator.animate({y: 0}, {spring: springs.settle}, {at: 0});const table = solveSpring(toSpring(springs.settle), {from: 300, to: 0});@@ -104,7 +104,7 @@ describe('the animator', () => {});it('a coast plays the table edge spring whatever a scope sets: scroll.bounce is no role', () => {const child = scoped({'--motion-scroll-bounce': '0.8s 0.3'});- const animator = createMotionAnimator(child, {now: () => 0});+ const animator = createMotionEngine(child, {now: () => 0});animator.set({x: 60});// Released past the edge: straight back on the edge spring.animator.decay(diff --git a/packages/lab/src/RefreshControl/refreshTouchController.ts b/packages/lab/src/RefreshControl/refreshTouchController.tsindex 9fd8d2cd70..e4f66cb91e 100644--- a/packages/lab/src/RefreshControl/refreshTouchController.ts+++ b/packages/lab/src/RefreshControl/refreshTouchController.ts@@ -55,7 +55,7 @@ import {cubicBezier} from '@astryxdesign/core/internal/touch';import {mapProgress} from '@astryxdesign/core/internal/touch';import {scroll} from '@astryxdesign/core/internal/touch';import {observeResize} from '@astryxdesign/core/utils';-import {useMotionAnimator} from './useMotionAnimator';+import {useMotionEngine} from '../internal/useMotionEngine';import {RefreshPullRecognizer,RefreshScrollPullRecognizer,@@ -186,8 +186,8 @@ export function useRefreshTouchController({(event: RefreshEvent) => dispatchRef.current(event),[dispatchRef],);- const content = useMotionAnimator();- const indicator = useMotionAnimator();+ const content = useMotionEngine();+ const indicator = useMotionEngine();const contentElement = useRef<HTMLElement | null>(null);const indicatorElement = useRef<HTMLElement | null>(null);// Whether the content holds the refreshing inset.diff --git a/packages/lab/src/RefreshControl/useMotionAnimator.ts b/packages/lab/src/RefreshControl/useMotionAnimator.tsdeleted file mode 100644index 697641a6e3..0000000000--- a/packages/lab/src/RefreshControl/useMotionAnimator.ts+++ /dev/null@@ -1,35 +0,0 @@-// Copyright (c) Meta Platforms, Inc. and affiliates.--'use client';--/**- * @file useMotionAnimator.ts- * @input Core's internal motion animator (internal/touch)- * @output useMotionAnimator: one motion animator for a component's lifetime,- * and the ref that attaches it to an element- * @position Internal to useRefreshControl; refreshTouchController calls it.- * Core's public `useAnimator` plays only the theme's state-change motion.- */--import {useState} from 'react';-import {- createMotionAnimator,- type MotionAnimator,- type MotionAnimatorOptions,-} from '@astryxdesign/core/internal/touch';--export interface UseMotionAnimatorResult {- readonly ref: (element: HTMLElement | null) => void;- readonly animator: MotionAnimator;-}--/** One motion animator for the component's lifetime, attached through `ref`. */-export function useMotionAnimator(- options?: MotionAnimatorOptions,-): UseMotionAnimatorResult {- const [result] = useState<UseMotionAnimatorResult>(() => {- const animator = createMotionAnimator(null, options);- return {animator, ref: element => animator.attach(element)};- });- return result;-}diff --git a/packages/lab/src/RefreshControl/useRefreshControl.test.tsx b/packages/lab/src/RefreshControl/useRefreshControl.test.tsxindex 062d8d7f25..15695a6a7c 100644--- a/packages/lab/src/RefreshControl/useRefreshControl.test.tsx+++ b/packages/lab/src/RefreshControl/useRefreshControl.test.tsx@@ -17,10 +17,11 @@ import {act, render, screen, waitFor} from '@testing-library/react';import {GestureRecognizer,PanGestureRecognizer,- type MotionAnimator,type MotionCurve,+ type MotionEngine,} from '@astryxdesign/core/internal/touch';import {afterEach, beforeEach, describe, expect, it, vi} from 'vitest';+import type * as MotionEngineModule from '../internal/useMotionEngine';import {revealProgress} from './refreshPull';import {useRefreshControl,@@ -30,14 +31,14 @@ import {// Records the animators that the touch layer creates, the content's first,// so a test can watch the settle and the indicator's fade.const animators = vi.hoisted(() => ({list: [] as unknown[]}));-vi.mock('./useMotionAnimator', async importOriginal => {- const real = await importOriginal<typeof import('./useMotionAnimator')>();+vi.mock('../internal/useMotionEngine', async importOriginal => {+ const real = await importOriginal<typeof MotionEngineModule>();return {...real,- useMotionAnimator: (- ...args: Parameters<typeof real.useMotionAnimator>- ): ReturnType<typeof real.useMotionAnimator> => {- const result = real.useMotionAnimator(...args);+ useMotionEngine: (+ ...args: Parameters<typeof real.useMotionEngine>+ ): ReturnType<typeof real.useMotionEngine> => {+ const result = real.useMotionEngine(...args);if (!animators.list.includes(result.animator)) {animators.list.push(result.animator);}@@ -54,7 +55,7 @@ vi.mock('./useMotionAnimator', async importOriginal => {function watchFade(settleCurve: () => MotionCurve | null) {const [contentAnimator, indicatorAnimator] = animators.list.slice(-2,- ) as MotionAnimator[];+ ) as MotionEngine[];let finishSettle: (done: boolean) => void = () => {};const animate = contentAnimator.animate.bind(contentAnimator);vi.spyOn(contentAnimator, 'animate').mockImplementation(@@ -504,14 +505,14 @@ describe('useRefreshControl', () => {<p>Inbox</p></Refreshable>,);- const [, indicatorAnimator] = animators.list.slice(-2) as MotionAnimator[];+ const [, indicatorAnimator] = animators.list.slice(-2) as MotionEngine[];const play = vi.spyOn(indicatorAnimator, 'play');// Released below the trigger: the settle back and the fade start.pull(content(), [20, 20, 20, 10]);const fadeAt = play.mock.calls.findIndex(([curves]) => 'opacity' in curves);expect(fadeAt).toBeGreaterThanOrEqual(0);const fade = play.mock.results[fadeAt].value as ReturnType<- MotionAnimator['play']+ MotionEngine['play']>;const shown = Number(reveal());expect(shown).toBeGreaterThan(0);@@ -1263,7 +1264,7 @@ describe('useRefreshControl', () => {);const [contentAnimator, indicatorAnimator] = animators.list.slice(-2,- ) as MotionAnimator[];+ ) as MotionEngine[];const contentAnimate = vi.spyOn(contentAnimator, 'animate');const indicatorAnimate = vi.spyOn(indicatorAnimator, 'animate');scrollVelocity.mockClear();diff --git a/packages/lab/src/internal/useMotionEngine.test.tsx b/packages/lab/src/internal/useMotionEngine.test.tsxnew file mode 100644index 0000000000..73b76673ab--- /dev/null+++ b/packages/lab/src/internal/useMotionEngine.test.tsx@@ -0,0 +1,108 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/**+ * @file useMotionEngine.test.tsx+ * @input vitest (jsdom), React Testing Library, the hook+ * @output Checks that the animator is stable, attaches through the ref, and+ * never re-renders its component while animating, retargeting or tracking+ * @position Testing; validates useMotionEngine.ts+ */++import {act, render} from '@testing-library/react';+import {useEffect} from 'react';+import {afterEach, beforeEach, describe, expect, it, vi} from 'vitest';+import type {MotionEngine} from '@astryxdesign/core/internal/touch';+import {useMotionEngine} from './useMotionEngine';++/** A critically damped half-second spring (SwiftUI's default). */+const SETTLE = {duration: 0.5, bounce: 0} as const;+/** A stiff, heavy spring (UIKit's sheet presentation). */+const SHEET = {mass: 3, stiffness: 1000, damping: 500} as const;++beforeEach(() => {+ HTMLElement.prototype.animate = function () {+ return {startTime: null, cancel: vi.fn()} as unknown as Animation;+ };+});++afterEach(() => {+ Reflect.deleteProperty(HTMLElement.prototype, 'animate');+});++/** A component that hands its animator out, for the unmount test. */+function UnmountProbe({box}: {box: {current: MotionEngine | null}}) {+ const {ref, animator} = useMotionEngine();+ box.current = animator;+ return <div ref={ref} />;+}++describe('useMotionEngine', () => {+ it('keeps one animator and ref, and never re-renders while animating', () => {+ let renders = 0;+ const seen = new Set<MotionEngine>();+ const refs = new Set<unknown>();+ let api: MotionEngine | null = null;+ function Probe() {+ renders++;+ const {ref, animator} = useMotionEngine();+ seen.add(animator);+ refs.add(ref);+ useEffect(() => {+ api = animator;+ });+ return <div ref={ref} data-testid="probe" />;+ }+ const {rerender, getByTestId} = render(<Probe />);+ const before = renders;+ act(() => {+ api?.animate({x: 100}, {spring: SETTLE});+ for (let x = 0; x < 50; x++) {+ api?.set({y: x});+ }+ api?.animate({x: 10}, {spring: SETTLE});+ api?.stop();+ });+ expect(renders).toBe(before);+ expect(getByTestId('probe').style.translate).not.toBe('');+ rerender(<Probe />);+ expect(seen.size).toBe(1);+ expect(refs.size).toBe(1);+ });++ it('attaches on mount and detaches on unmount', () => {+ const box: {current: MotionEngine | null} = {current: null};+ function Probe() {+ const {ref, animator} = useMotionEngine({initial: {opacity: 0.5}});+ box.current = animator;+ return <div ref={ref} data-testid="probe" />;+ }+ const {getByTestId, unmount} = render(<Probe />);+ const element = getByTestId('probe');+ expect(box.current?.element).toBe(element);+ expect(element.style.opacity).toBe('0.5');+ unmount();+ expect(box.current?.element).toBeNull();+ });++ it('ends its callers waits on unmount and keeps no timer for them', async () => {+ vi.useFakeTimers();+ try {+ const box: {current: MotionEngine | null} = {current: null};+ const {unmount} = render(<UnmountProbe box={box} />);+ const animator = box.current!;+ const handle = animator.animate({x: 100}, {spring: SHEET});+ let rested = false;+ void animator.atRest().then(() => {+ rested = true;+ });+ expect(vi.getTimerCount()).toBeGreaterThan(0);+ unmount();+ // Without advancing time: the curve has not ended.+ await expect(handle.finished).resolves.toBe(false);+ expect(rested).toBe(true);+ expect(vi.getTimerCount()).toBe(0);+ } finally {+ vi.useRealTimers();+ }+ });+});diff --git a/packages/lab/src/internal/useMotionEngine.ts b/packages/lab/src/internal/useMotionEngine.tsnew file mode 100644index 0000000000..5f0e9c7f00--- /dev/null+++ b/packages/lab/src/internal/useMotionEngine.ts@@ -0,0 +1,54 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++'use client';++/**+ * @file useMotionEngine.ts+ * @input React and Core's motion engine (`createMotionEngine`)+ * @output useMotionEngine: a stable motion engine and the callback ref that+ * attaches it to an element+ * @position Lab's React binding of Core's motion engine, for Lab components.+ * Lab's entry point does not export it.+ *+ * SYNC: When modified, update useMotionEngine.test.tsx+ */++import {useState} from 'react';+import {+ createMotionEngine,+ type MotionEngine,+ type MotionEngineOptions,+} from '@astryxdesign/core/internal/touch';++export interface UseMotionEngineResult {+ /** Callback ref for the animated element; stable. */+ readonly ref: (element: HTMLElement | null) => void;+ /** The animator; stable for the component's lifetime. */+ readonly animator: MotionEngine;+}++/**+ * A compositor animator bound to an element through a callback ref. The+ * animator never sets state, so a move never re-renders the component. When+ * the element unmounts, the ref detaches the animator: its moves stop and its+ * values stay, so a remount resumes from them. `options` are read on the+ * first render only.+ *+ * @example+ * ```+ * const {ref, animator} = useMotionEngine();+ * // `spring` is the motion role for this move, or the component's own+ * // measured spring.+ * const open = () => animator.animate({y: 0}, {spring});+ * return <div ref={ref} />;+ * ```+ */+export function useMotionEngine(+ options?: MotionEngineOptions,+): UseMotionEngineResult {+ const [result] = useState<UseMotionEngineResult>(() => {+ const animator = createMotionEngine(null, options);+ return {animator, ref: element => animator.attach(element)};+ });+ return result;+}diff --git a/scripts/motion-node-load.test.mjs b/scripts/motion-node-load.test.mjsindex 093ea9eab1..14fb54553f 100644--- a/scripts/motion-node-load.test.mjs+++ b/scripts/motion-node-load.test.mjs@@ -28,7 +28,7 @@ const coreSrc = path.join(root, 'packages/core/src');* the press paint's styles).*/const ENTRY = `-export {createMotionAnimator, animatorFor, SETTLE_THRESHOLD} from './motion/animator';+export {createMotionEngine, animatorFor, SETTLE_THRESHOLD} from './motion/animator';export {reducedMotionFade} from './motion/reducedMotion';export {resolveMotion} from './motion/resolveMotion';export {solveSpring, toSpring} from './motion/spring';@@ -105,10 +105,10 @@ describe('the touch motion foundation in plain Node', () => {'-e',`const m = await import(${JSON.stringify(pathToFileURL(file).href)});m.registerSpringsTable();- const animator = m.createMotionAnimator(null);+ const animator = m.createMotionEngine(null);const pan = new m.PanGestureRecognizer({});console.log(JSON.stringify({- createMotionAnimator: typeof m.createMotionAnimator,+ createMotionEngine: typeof m.createMotionEngine,set: typeof animator.set,sheet: m.springs.sheetPresent != null,pan: typeof pan.state,@@ -117,7 +117,7 @@ describe('the touch motion foundation in plain Node', () => {{encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe']},);expect(JSON.parse(out.trim().split('\n').at(-1))).toEqual({- createMotionAnimator: 'function',+ createMotionEngine: 'function',set: 'function',sheet: true,pan: 'string',diff --git a/scripts/touch-support-bundle.test.mjs b/scripts/touch-support-bundle.test.mjsindex 76ebf5bc5b..83963a7269 100644--- a/scripts/touch-support-bundle.test.mjs+++ b/scripts/touch-support-bundle.test.mjs@@ -110,14 +110,16 @@ function exportsOf(entry) {}/**- * What the internal entry gives Lab's refresh pull: the pan, its hook, the- * motion animator, its motion math and companion curves, the scroll view's- * spring and the motion-role parsers. None is public API.+ * What the internal entry gives Lab components, none of it public API. Lab's+ * refresh pull reads the pan, its hook, the motion engine, its motion math and+ * companion curves, the scroll view's spring and the motion-role parsers.+ * Other Lab components read the UIKit gesture table, the touch presentation+ * and its query, and an element's direction.*/const LAB_ONLY_NAMES = ['PanGestureRecognizer','useGestureRecognizer',- 'createMotionAnimator',+ 'createMotionEngine','cubicBezier','mapProgress','parseCssEasing',@@ -126,6 +128,10 @@ const LAB_ONLY_NAMES = ['rubberBandInverse','rubberBandSlope','scroll',+ 'isRtlElement',+ 'UIKIT_GESTURES',+ 'useTouchPresentation',+ 'TOUCH_QUERY',];/** The inputs matching `pattern` that put bytes in `bytes`. */