@astryxdesign/lab 0.7.9-canary.35bbaee → 0.7.9-canary.3731ec3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -45,7 +45,7 @@ import { cubicBezier } from '@astryxdesign/core/internal/touch';
45
45
  import { mapProgress } from '@astryxdesign/core/internal/touch';
46
46
  import { scroll } from '@astryxdesign/core/internal/touch';
47
47
  import { observeResize } from '@astryxdesign/core/utils';
48
- import { useMotionAnimator } from "./useMotionAnimator.js";
48
+ import { useMotionEngine } from "../internal/useMotionEngine.js";
49
49
  import { RefreshPullRecognizer, RefreshScrollPullRecognizer } from "./RefreshPullRecognizer.js";
50
50
  import { REFRESH_REVEAL_VAR } from "./refreshIndicator.js";
51
51
  import { endMotion, endTiming, modeAfterTrigger, pullOverscroll, pullSlope, pullTravel, REFRESH_HEIGHT, releaseTarget, revealProgress, triggerDistance } from "./refreshPull.js";
@@ -116,8 +116,8 @@ export function useRefreshTouchController({
116
116
  dispatchRef
117
117
  }) {
118
118
  const dispatch = useCallback(event => dispatchRef.current(event), [dispatchRef]);
119
- const content = useMotionAnimator();
120
- const indicator = useMotionAnimator();
119
+ const content = useMotionEngine();
120
+ const indicator = useMotionEngine();
121
121
  const contentElement = useRef(null);
122
122
  const indicatorElement = useRef(null);
123
123
  // Whether the content holds the refreshing inset.
@@ -0,0 +1,25 @@
1
+ import { type MotionEngine, type MotionEngineOptions } from '@astryxdesign/core/internal/touch';
2
+ export interface UseMotionEngineResult {
3
+ /** Callback ref for the animated element; stable. */
4
+ readonly ref: (element: HTMLElement | null) => void;
5
+ /** The animator; stable for the component's lifetime. */
6
+ readonly animator: MotionEngine;
7
+ }
8
+ /**
9
+ * A compositor animator bound to an element through a callback ref. The
10
+ * animator never sets state, so a move never re-renders the component. When
11
+ * the element unmounts, the ref detaches the animator: its moves stop and its
12
+ * values stay, so a remount resumes from them. `options` are read on the
13
+ * first render only.
14
+ *
15
+ * @example
16
+ * ```
17
+ * const {ref, animator} = useMotionEngine();
18
+ * // `spring` is the motion role for this move, or the component's own
19
+ * // measured spring.
20
+ * const open = () => animator.animate({y: 0}, {spring});
21
+ * return <div ref={ref} />;
22
+ * ```
23
+ */
24
+ export declare function useMotionEngine(options?: MotionEngineOptions): UseMotionEngineResult;
25
+ //# sourceMappingURL=useMotionEngine.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"useMotionEngine.d.ts","sourceRoot":"","sources":["../../src/internal/useMotionEngine.ts"],"names":[],"mappings":"AAgBA,OAAO,EAEL,KAAK,YAAY,EACjB,KAAK,mBAAmB,EACzB,MAAM,mCAAmC,CAAC;AAE3C,MAAM,WAAW,qBAAqB;IACpC,qDAAqD;IACrD,QAAQ,CAAC,GAAG,EAAE,CAAC,OAAO,EAAE,WAAW,GAAG,IAAI,KAAK,IAAI,CAAC;IACpD,yDAAyD;IACzD,QAAQ,CAAC,QAAQ,EAAE,YAAY,CAAC;CACjC;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,eAAe,CAC7B,OAAO,CAAC,EAAE,mBAAmB,GAC5B,qBAAqB,CAMvB"}
@@ -0,0 +1,42 @@
1
+ // Copyright (c) Meta Platforms, Inc. and affiliates.
2
+
3
+ 'use client';
4
+
5
+ /**
6
+ * @file useMotionEngine.ts
7
+ * @input React and Core's motion engine (`createMotionEngine`)
8
+ * @output useMotionEngine: a stable motion engine and the callback ref that
9
+ * attaches it to an element
10
+ * @position Lab's React binding of Core's motion engine, for Lab components.
11
+ * Lab's entry point does not export it.
12
+ *
13
+ * SYNC: When modified, update useMotionEngine.test.tsx
14
+ */
15
+ import { useState } from 'react';
16
+ import { createMotionEngine } from '@astryxdesign/core/internal/touch';
17
+ /**
18
+ * A compositor animator bound to an element through a callback ref. The
19
+ * animator never sets state, so a move never re-renders the component. When
20
+ * the element unmounts, the ref detaches the animator: its moves stop and its
21
+ * values stay, so a remount resumes from them. `options` are read on the
22
+ * first render only.
23
+ *
24
+ * @example
25
+ * ```
26
+ * const {ref, animator} = useMotionEngine();
27
+ * // `spring` is the motion role for this move, or the component's own
28
+ * // measured spring.
29
+ * const open = () => animator.animate({y: 0}, {spring});
30
+ * return <div ref={ref} />;
31
+ * ```
32
+ */
33
+ export function useMotionEngine(options) {
34
+ const [result] = useState(() => {
35
+ const animator = createMotionEngine(null, options);
36
+ return {
37
+ animator,
38
+ ref: element => animator.attach(element)
39
+ };
40
+ });
41
+ return result;
42
+ }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@astryxdesign/lab",
3
- "version": "0.7.9-canary.35bbaee",
3
+ "version": "0.7.9-canary.3731ec3",
4
4
  "description": "Experimental Astryx components — published to npm only under the @canary dist-tag for early testing; never released as a stable (latest) version.",
5
5
  "author": "Meta Open Source",
6
6
  "license": "MIT",
@@ -49,7 +49,7 @@
49
49
  },
50
50
  "peerDependencies": {
51
51
  "@stylexjs/stylex": ">=0.10.0",
52
- "@astryxdesign/core": "0.7.9-canary.35bbaee",
52
+ "@astryxdesign/core": "0.7.9-canary.3731ec3",
53
53
  "react": ">=19.0.0",
54
54
  "react-dom": ">=19.0.0"
55
55
  },
@@ -59,9 +59,9 @@
59
59
  "d3-shape": "^3.2.0"
60
60
  },
61
61
  "devDependencies": {
62
- "@astryxdesign/a11y-spec": "0.7.9-canary.35bbaee",
63
- "@astryxdesign/cli": "0.7.9-canary.35bbaee",
64
- "@astryxdesign/interaction-harness": "0.7.9-canary.35bbaee",
62
+ "@astryxdesign/a11y-spec": "0.7.9-canary.3731ec3",
63
+ "@astryxdesign/cli": "0.7.9-canary.3731ec3",
64
+ "@astryxdesign/interaction-harness": "0.7.9-canary.3731ec3",
65
65
  "@babel/cli": "^7.29.7",
66
66
  "@babel/core": "^7.29.7",
67
67
  "@babel/preset-react": "^7.29.7",
@@ -55,7 +55,7 @@ import {cubicBezier} from '@astryxdesign/core/internal/touch';
55
55
  import {mapProgress} from '@astryxdesign/core/internal/touch';
56
56
  import {scroll} from '@astryxdesign/core/internal/touch';
57
57
  import {observeResize} from '@astryxdesign/core/utils';
58
- import {useMotionAnimator} from './useMotionAnimator';
58
+ import {useMotionEngine} from '../internal/useMotionEngine';
59
59
  import {
60
60
  RefreshPullRecognizer,
61
61
  RefreshScrollPullRecognizer,
@@ -186,8 +186,8 @@ export function useRefreshTouchController({
186
186
  (event: RefreshEvent) => dispatchRef.current(event),
187
187
  [dispatchRef],
188
188
  );
189
- const content = useMotionAnimator();
190
- const indicator = useMotionAnimator();
189
+ const content = useMotionEngine();
190
+ const indicator = useMotionEngine();
191
191
  const contentElement = useRef<HTMLElement | null>(null);
192
192
  const indicatorElement = useRef<HTMLElement | null>(null);
193
193
  // Whether the content holds the refreshing inset.
@@ -17,10 +17,11 @@ import {act, render, screen, waitFor} from '@testing-library/react';
17
17
  import {
18
18
  GestureRecognizer,
19
19
  PanGestureRecognizer,
20
- type MotionAnimator,
21
20
  type MotionCurve,
21
+ type MotionEngine,
22
22
  } from '@astryxdesign/core/internal/touch';
23
23
  import {afterEach, beforeEach, describe, expect, it, vi} from 'vitest';
24
+ import type * as MotionEngineModule from '../internal/useMotionEngine';
24
25
  import {revealProgress} from './refreshPull';
25
26
  import {
26
27
  useRefreshControl,
@@ -30,14 +31,14 @@ import {
30
31
  // Records the animators that the touch layer creates, the content's first,
31
32
  // so a test can watch the settle and the indicator's fade.
32
33
  const animators = vi.hoisted(() => ({list: [] as unknown[]}));
33
- vi.mock('./useMotionAnimator', async importOriginal => {
34
- const real = await importOriginal<typeof import('./useMotionAnimator')>();
34
+ vi.mock('../internal/useMotionEngine', async importOriginal => {
35
+ const real = await importOriginal<typeof MotionEngineModule>();
35
36
  return {
36
37
  ...real,
37
- useMotionAnimator: (
38
- ...args: Parameters<typeof real.useMotionAnimator>
39
- ): ReturnType<typeof real.useMotionAnimator> => {
40
- const result = real.useMotionAnimator(...args);
38
+ useMotionEngine: (
39
+ ...args: Parameters<typeof real.useMotionEngine>
40
+ ): ReturnType<typeof real.useMotionEngine> => {
41
+ const result = real.useMotionEngine(...args);
41
42
  if (!animators.list.includes(result.animator)) {
42
43
  animators.list.push(result.animator);
43
44
  }
@@ -54,7 +55,7 @@ vi.mock('./useMotionAnimator', async importOriginal => {
54
55
  function watchFade(settleCurve: () => MotionCurve | null) {
55
56
  const [contentAnimator, indicatorAnimator] = animators.list.slice(
56
57
  -2,
57
- ) as MotionAnimator[];
58
+ ) as MotionEngine[];
58
59
  let finishSettle: (done: boolean) => void = () => {};
59
60
  const animate = contentAnimator.animate.bind(contentAnimator);
60
61
  vi.spyOn(contentAnimator, 'animate').mockImplementation(
@@ -504,14 +505,14 @@ describe('useRefreshControl', () => {
504
505
  <p>Inbox</p>
505
506
  </Refreshable>,
506
507
  );
507
- const [, indicatorAnimator] = animators.list.slice(-2) as MotionAnimator[];
508
+ const [, indicatorAnimator] = animators.list.slice(-2) as MotionEngine[];
508
509
  const play = vi.spyOn(indicatorAnimator, 'play');
509
510
  // Released below the trigger: the settle back and the fade start.
510
511
  pull(content(), [20, 20, 20, 10]);
511
512
  const fadeAt = play.mock.calls.findIndex(([curves]) => 'opacity' in curves);
512
513
  expect(fadeAt).toBeGreaterThanOrEqual(0);
513
514
  const fade = play.mock.results[fadeAt].value as ReturnType<
514
- MotionAnimator['play']
515
+ MotionEngine['play']
515
516
  >;
516
517
  const shown = Number(reveal());
517
518
  expect(shown).toBeGreaterThan(0);
@@ -1263,7 +1264,7 @@ describe('useRefreshControl', () => {
1263
1264
  );
1264
1265
  const [contentAnimator, indicatorAnimator] = animators.list.slice(
1265
1266
  -2,
1266
- ) as MotionAnimator[];
1267
+ ) as MotionEngine[];
1267
1268
  const contentAnimate = vi.spyOn(contentAnimator, 'animate');
1268
1269
  const indicatorAnimate = vi.spyOn(indicatorAnimator, 'animate');
1269
1270
  scrollVelocity.mockClear();
@@ -0,0 +1,108 @@
1
+ // Copyright (c) Meta Platforms, Inc. and affiliates.
2
+
3
+ /**
4
+ * @file useMotionEngine.test.tsx
5
+ * @input vitest (jsdom), React Testing Library, the hook
6
+ * @output Checks that the animator is stable, attaches through the ref, and
7
+ * never re-renders its component while animating, retargeting or tracking
8
+ * @position Testing; validates useMotionEngine.ts
9
+ */
10
+
11
+ import {act, render} from '@testing-library/react';
12
+ import {useEffect} from 'react';
13
+ import {afterEach, beforeEach, describe, expect, it, vi} from 'vitest';
14
+ import type {MotionEngine} from '@astryxdesign/core/internal/touch';
15
+ import {useMotionEngine} from './useMotionEngine';
16
+
17
+ /** A critically damped half-second spring (SwiftUI's default). */
18
+ const SETTLE = {duration: 0.5, bounce: 0} as const;
19
+ /** A stiff, heavy spring (UIKit's sheet presentation). */
20
+ const SHEET = {mass: 3, stiffness: 1000, damping: 500} as const;
21
+
22
+ beforeEach(() => {
23
+ HTMLElement.prototype.animate = function () {
24
+ return {startTime: null, cancel: vi.fn()} as unknown as Animation;
25
+ };
26
+ });
27
+
28
+ afterEach(() => {
29
+ Reflect.deleteProperty(HTMLElement.prototype, 'animate');
30
+ });
31
+
32
+ /** A component that hands its animator out, for the unmount test. */
33
+ function UnmountProbe({box}: {box: {current: MotionEngine | null}}) {
34
+ const {ref, animator} = useMotionEngine();
35
+ box.current = animator;
36
+ return <div ref={ref} />;
37
+ }
38
+
39
+ describe('useMotionEngine', () => {
40
+ it('keeps one animator and ref, and never re-renders while animating', () => {
41
+ let renders = 0;
42
+ const seen = new Set<MotionEngine>();
43
+ const refs = new Set<unknown>();
44
+ let api: MotionEngine | null = null;
45
+ function Probe() {
46
+ renders++;
47
+ const {ref, animator} = useMotionEngine();
48
+ seen.add(animator);
49
+ refs.add(ref);
50
+ useEffect(() => {
51
+ api = animator;
52
+ });
53
+ return <div ref={ref} data-testid="probe" />;
54
+ }
55
+ const {rerender, getByTestId} = render(<Probe />);
56
+ const before = renders;
57
+ act(() => {
58
+ api?.animate({x: 100}, {spring: SETTLE});
59
+ for (let x = 0; x < 50; x++) {
60
+ api?.set({y: x});
61
+ }
62
+ api?.animate({x: 10}, {spring: SETTLE});
63
+ api?.stop();
64
+ });
65
+ expect(renders).toBe(before);
66
+ expect(getByTestId('probe').style.translate).not.toBe('');
67
+ rerender(<Probe />);
68
+ expect(seen.size).toBe(1);
69
+ expect(refs.size).toBe(1);
70
+ });
71
+
72
+ it('attaches on mount and detaches on unmount', () => {
73
+ const box: {current: MotionEngine | null} = {current: null};
74
+ function Probe() {
75
+ const {ref, animator} = useMotionEngine({initial: {opacity: 0.5}});
76
+ box.current = animator;
77
+ return <div ref={ref} data-testid="probe" />;
78
+ }
79
+ const {getByTestId, unmount} = render(<Probe />);
80
+ const element = getByTestId('probe');
81
+ expect(box.current?.element).toBe(element);
82
+ expect(element.style.opacity).toBe('0.5');
83
+ unmount();
84
+ expect(box.current?.element).toBeNull();
85
+ });
86
+
87
+ it('ends its callers waits on unmount and keeps no timer for them', async () => {
88
+ vi.useFakeTimers();
89
+ try {
90
+ const box: {current: MotionEngine | null} = {current: null};
91
+ const {unmount} = render(<UnmountProbe box={box} />);
92
+ const animator = box.current!;
93
+ const handle = animator.animate({x: 100}, {spring: SHEET});
94
+ let rested = false;
95
+ void animator.atRest().then(() => {
96
+ rested = true;
97
+ });
98
+ expect(vi.getTimerCount()).toBeGreaterThan(0);
99
+ unmount();
100
+ // Without advancing time: the curve has not ended.
101
+ await expect(handle.finished).resolves.toBe(false);
102
+ expect(rested).toBe(true);
103
+ expect(vi.getTimerCount()).toBe(0);
104
+ } finally {
105
+ vi.useRealTimers();
106
+ }
107
+ });
108
+ });
@@ -0,0 +1,54 @@
1
+ // Copyright (c) Meta Platforms, Inc. and affiliates.
2
+
3
+ 'use client';
4
+
5
+ /**
6
+ * @file useMotionEngine.ts
7
+ * @input React and Core's motion engine (`createMotionEngine`)
8
+ * @output useMotionEngine: a stable motion engine and the callback ref that
9
+ * attaches it to an element
10
+ * @position Lab's React binding of Core's motion engine, for Lab components.
11
+ * Lab's entry point does not export it.
12
+ *
13
+ * SYNC: When modified, update useMotionEngine.test.tsx
14
+ */
15
+
16
+ import {useState} from 'react';
17
+ import {
18
+ createMotionEngine,
19
+ type MotionEngine,
20
+ type MotionEngineOptions,
21
+ } from '@astryxdesign/core/internal/touch';
22
+
23
+ export interface UseMotionEngineResult {
24
+ /** Callback ref for the animated element; stable. */
25
+ readonly ref: (element: HTMLElement | null) => void;
26
+ /** The animator; stable for the component's lifetime. */
27
+ readonly animator: MotionEngine;
28
+ }
29
+
30
+ /**
31
+ * A compositor animator bound to an element through a callback ref. The
32
+ * animator never sets state, so a move never re-renders the component. When
33
+ * the element unmounts, the ref detaches the animator: its moves stop and its
34
+ * values stay, so a remount resumes from them. `options` are read on the
35
+ * first render only.
36
+ *
37
+ * @example
38
+ * ```
39
+ * const {ref, animator} = useMotionEngine();
40
+ * // `spring` is the motion role for this move, or the component's own
41
+ * // measured spring.
42
+ * const open = () => animator.animate({y: 0}, {spring});
43
+ * return <div ref={ref} />;
44
+ * ```
45
+ */
46
+ export function useMotionEngine(
47
+ options?: MotionEngineOptions,
48
+ ): UseMotionEngineResult {
49
+ const [result] = useState<UseMotionEngineResult>(() => {
50
+ const animator = createMotionEngine(null, options);
51
+ return {animator, ref: element => animator.attach(element)};
52
+ });
53
+ return result;
54
+ }
@@ -1,8 +0,0 @@
1
- import { type MotionAnimator, type MotionAnimatorOptions } from '@astryxdesign/core/internal/touch';
2
- export interface UseMotionAnimatorResult {
3
- readonly ref: (element: HTMLElement | null) => void;
4
- readonly animator: MotionAnimator;
5
- }
6
- /** One motion animator for the component's lifetime, attached through `ref`. */
7
- export declare function useMotionAnimator(options?: MotionAnimatorOptions): UseMotionAnimatorResult;
8
- //# sourceMappingURL=useMotionAnimator.d.ts.map
@@ -1 +0,0 @@
1
- {"version":3,"file":"useMotionAnimator.d.ts","sourceRoot":"","sources":["../../src/RefreshControl/useMotionAnimator.ts"],"names":[],"mappings":"AAcA,OAAO,EAEL,KAAK,cAAc,EACnB,KAAK,qBAAqB,EAC3B,MAAM,mCAAmC,CAAC;AAE3C,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,GAAG,EAAE,CAAC,OAAO,EAAE,WAAW,GAAG,IAAI,KAAK,IAAI,CAAC;IACpD,QAAQ,CAAC,QAAQ,EAAE,cAAc,CAAC;CACnC;AAED,gFAAgF;AAChF,wBAAgB,iBAAiB,CAC/B,OAAO,CAAC,EAAE,qBAAqB,GAC9B,uBAAuB,CAMzB"}
@@ -1,25 +0,0 @@
1
- // Copyright (c) Meta Platforms, Inc. and affiliates.
2
-
3
- 'use client';
4
-
5
- /**
6
- * @file useMotionAnimator.ts
7
- * @input Core's internal motion animator (internal/touch)
8
- * @output useMotionAnimator: one motion animator for a component's lifetime,
9
- * and the ref that attaches it to an element
10
- * @position Internal to useRefreshControl; refreshTouchController calls it.
11
- * Core's public `useAnimator` plays only the theme's state-change motion.
12
- */
13
- import { useState } from 'react';
14
- import { createMotionAnimator } from '@astryxdesign/core/internal/touch';
15
- /** One motion animator for the component's lifetime, attached through `ref`. */
16
- export function useMotionAnimator(options) {
17
- const [result] = useState(() => {
18
- const animator = createMotionAnimator(null, options);
19
- return {
20
- animator,
21
- ref: element => animator.attach(element)
22
- };
23
- });
24
- return result;
25
- }
@@ -1,35 +0,0 @@
1
- // Copyright (c) Meta Platforms, Inc. and affiliates.
2
-
3
- 'use client';
4
-
5
- /**
6
- * @file useMotionAnimator.ts
7
- * @input Core's internal motion animator (internal/touch)
8
- * @output useMotionAnimator: one motion animator for a component's lifetime,
9
- * and the ref that attaches it to an element
10
- * @position Internal to useRefreshControl; refreshTouchController calls it.
11
- * Core's public `useAnimator` plays only the theme's state-change motion.
12
- */
13
-
14
- import {useState} from 'react';
15
- import {
16
- createMotionAnimator,
17
- type MotionAnimator,
18
- type MotionAnimatorOptions,
19
- } from '@astryxdesign/core/internal/touch';
20
-
21
- export interface UseMotionAnimatorResult {
22
- readonly ref: (element: HTMLElement | null) => void;
23
- readonly animator: MotionAnimator;
24
- }
25
-
26
- /** One motion animator for the component's lifetime, attached through `ref`. */
27
- export function useMotionAnimator(
28
- options?: MotionAnimatorOptions,
29
- ): UseMotionAnimatorResult {
30
- const [result] = useState<UseMotionAnimatorResult>(() => {
31
- const animator = createMotionAnimator(null, options);
32
- return {animator, ref: element => animator.attach(element)};
33
- });
34
- return result;
35
- }