An open source design system that's fully customizable and agent ready
TypeScript
// Copyright (c) Meta Platforms, Inc. and affiliates.
/**
* @file useDragToSnapPoints.test.tsx
* @input vitest (jsdom, fake clock), React Testing Library, the hook
* @output Checks `spec:AST-107` FR2 and FR6 for the hook. `settleTo` from a
* key settles and calls the latest `onSettle`, and `settleTo` is stable.
* A render that React throws away leaves the committed `onSettle` in place.
* An unmount stops reporting, and an empty list stays empty. The hook
* module holds no behavior of its own.
* @position Testing; validates useDragToSnapPoints.ts
*/
import fs from 'node:fs';
import path from 'node:path';
import {act, render} from '@testing-library/react';
import {Suspense, startTransition, use, useRef} from 'react';
import {afterEach, beforeEach, describe, expect, it, vi} from 'vitest';
import {coarsePrimaryPointer} from '../gestures/__tests__/harness';
import {useDragToSnapPoints} from './useDragToSnapPoints';
beforeEach(() => {
vi.useFakeTimers({
toFake: [
'setTimeout',
'clearTimeout',
'performance',
'requestAnimationFrame',
'cancelAnimationFrame',
],
});
HTMLElement.prototype.animate = function (
keyframes: Keyframe[] | PropertyIndexedKeyframes | null,
) {
played.push(keyframes);
let start: number | null = null;
const animation = {
get startTime() {
return start;
},
set startTime(value: number | null) {
start = value;
},
playState: 'running',
ready: new Promise(() => {}),
finish() {},
cancel() {},
};
requestAnimationFrame(() => {
start ??= performance.now();
});
return animation as unknown as Animation;
};
});
afterEach(() => {
Reflect.deleteProperty(HTMLElement.prototype, 'animate');
vi.useRealTimers();
});
const POINTS = [0, 240, 480];
function touch(
type: string,
target: EventTarget,
contact: {x: number; y: number},
time: number,
isLift = false,
): void {
const event = new Event(type, {bubbles: true, cancelable: true});
const entry = {identifier: 1, clientX: contact.x, clientY: contact.y, target};
Object.defineProperty(event, 'changedTouches', {value: [entry]});
Object.defineProperty(event, 'touches', {value: isLift ? [] : [entry]});
Object.defineProperty(event, 'timeStamp', {value: time});
target.dispatchEvent(event);
}
// The document's host outlives a test, so event times only move forward.
let clock = 2_000_000;
/** The keyframes of every animation the element played, in order. */
const played: (Keyframe[] | PropertyIndexedKeyframes | null)[] = [];
function Drawer({
onSettle,
settlers,
snapPoints = POINTS,
}: {
onSettle: (index: number) => void;
settlers: Set<(index: number) => void>;
snapPoints?: ReadonlyArray<number>;
}) {
const ref = useRef<HTMLDivElement>(null);
const {settleTo} = useDragToSnapPoints(ref, {
axis: 'y',
snapPoints,
onSettle,
});
settlers.add(settleTo);
return <div ref={ref} />;
}
describe('useDragToSnapPoints', () => {
it('settleTo settles from a key and calls the latest onSettle; settleTo is stable', async () => {
const settlers = new Set<(index: number) => void>();
const first = vi.fn();
const latest = vi.fn();
const {rerender} = render(<Drawer onSettle={first} settlers={settlers} />);
rerender(<Drawer onSettle={latest} settlers={settlers} />);
expect(settlers.size).toBe(1);
const [settleTo] = settlers;
act(() => settleTo(2));
await act(async () => {
await vi.advanceTimersByTimeAsync(3000);
});
expect(first).not.toHaveBeenCalled();
expect(latest).toHaveBeenCalledWith(2);
});
it('a render that React throws away leaves the committed onSettle in place', async () => {
const settlers = new Set<(index: number) => void>();
const committed = vi.fn();
const discarded = vi.fn();
const never = new Promise<never>(() => {});
function Pending({
onSettle,
isPending,
}: {
onSettle: (index: number) => void;
isPending: boolean;
}) {
const ref = useRef<HTMLDivElement>(null);
const {settleTo} = useDragToSnapPoints(ref, {
axis: 'y',
snapPoints: POINTS,
onSettle,
});
settlers.add(settleTo);
if (isPending) {
use(never);
}
return <div ref={ref} />;
}
const {rerender} = render(
<Suspense fallback={null}>
<Pending onSettle={committed} isPending={false} />
</Suspense>,
);
// A transition that suspends keeps the committed screen, and React throws
// its render away.
act(() => {
startTransition(() => {
rerender(
<Suspense fallback={null}>
<Pending onSettle={discarded} isPending />
</Suspense>,
);
});
});
const [settleTo] = settlers;
act(() => settleTo(2));
await act(async () => {
await vi.advanceTimersByTimeAsync(3000);
});
expect(discarded).not.toHaveBeenCalled();
expect(committed).toHaveBeenCalledWith(2);
});
it('after an unmount nothing reports', async () => {
const settlers = new Set<(index: number) => void>();
const onSettle = vi.fn();
const {unmount} = render(
<Drawer onSettle={onSettle} settlers={settlers} />,
);
const [settleTo] = settlers;
act(() => settleTo(1));
unmount();
await vi.advanceTimersByTimeAsync(3000);
expect(onSettle).not.toHaveBeenCalled();
expect(() => settleTo(2)).not.toThrow();
});
it('an empty list stays empty: settleTo does nothing', async () => {
const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
const settlers = new Set<(index: number) => void>();
const onSettle = vi.fn();
render(<Drawer onSettle={onSettle} settlers={settlers} snapPoints={[]} />);
const [settleTo] = settlers;
act(() => settleTo(0));
await act(async () => {
await vi.advanceTimersByTimeAsync(3000);
});
expect(onSettle).not.toHaveBeenCalled();
expect(warn).toHaveBeenCalled();
warn.mockRestore();
});
it('drives an element mounted after the hook first ran, and follows the one that replaces it (INV6)', async () => {
const settlers = new Set<(index: number) => void>();
const onSettle = vi.fn();
function Late({shown, version}: {shown: boolean; version: number}) {
const ref = useRef<HTMLDivElement>(null);
const {settleTo} = useDragToSnapPoints(ref, {
axis: 'y',
snapPoints: POINTS,
onSettle,
});
settlers.add(settleTo);
return shown ? <div key={version} ref={ref} data-testid="late" /> : null;
}
const {rerender, getByTestId} = render(<Late shown={false} version={0} />);
rerender(<Late shown version={0} />);
const [settleTo] = settlers;
act(() => settleTo(1));
await act(async () => {
await vi.advanceTimersByTimeAsync(3000);
});
expect(onSettle).toHaveBeenLastCalledWith(1);
// A new node behind the ref: the drag moves to it.
rerender(<Late shown version={1} />);
const replaced = getByTestId('late');
act(() => settleTo(2));
await act(async () => {
await vi.advanceTimersByTimeAsync(3000);
});
expect(onSettle).toHaveBeenLastCalledWith(2);
expect(replaced.style.translate).toContain('480px');
});
it('an option changed mid-use leaves the element where it is, and the next settle starts there', async () => {
const settlers = new Set<(index: number) => void>();
const onSettle = vi.fn();
function Sheet({flickThreshold}: {flickThreshold: number}) {
const ref = useRef<HTMLDivElement>(null);
const {settleTo} = useDragToSnapPoints(ref, {
axis: 'y',
snapPoints: POINTS,
flickThreshold,
onSettle,
});
settlers.add(settleTo);
return <div ref={ref} data-testid="sheet" />;
}
const {rerender, getByTestId} = render(<Sheet flickThreshold={1008} />);
const element = getByTestId('sheet');
const [settleTo] = settlers;
act(() => settleTo(1));
await act(async () => {
await vi.advanceTimersByTimeAsync(3000);
});
const settled = element.style.translate;
expect(settled).toContain('240px');
rerender(<Sheet flickThreshold={600} />);
expect(element.style.translate).toBe(settled);
// The next settle moves on from 240, not from the resting position.
played.length = 0;
act(() => settleTo(2));
expect(JSON.stringify(played[0])).toContain('240px');
await act(async () => {
await vi.advanceTimersByTimeAsync(3000);
});
expect(onSettle).toHaveBeenLastCalledWith(2);
});
it('an option changed during a settle stops it where it is, and the next settle starts there', async () => {
const settlers = new Set<(index: number) => void>();
const onSettle = vi.fn();
function Sheet({flickThreshold}: {flickThreshold: number}) {
const ref = useRef<HTMLDivElement>(null);
const {settleTo} = useDragToSnapPoints(ref, {
axis: 'y',
snapPoints: POINTS,
flickThreshold,
onSettle,
});
settlers.add(settleTo);
return <div ref={ref} />;
}
const {rerender} = render(<Sheet flickThreshold={1008} />);
const [settleTo] = settlers;
act(() => settleTo(2));
await act(async () => {
await vi.advanceTimersByTimeAsync(150);
});
played.length = 0;
rerender(<Sheet flickThreshold={600} />);
// The drag is created again with the new option and nothing more: the
// settle stops where the element is, and nothing reports.
await act(async () => {
await vi.advanceTimersByTimeAsync(3000);
});
expect(played).toHaveLength(0);
expect(onSettle).not.toHaveBeenCalled();
// The next settle starts from there: never from 0, never a jump.
const [next] = [...settlers].slice(-1);
act(() => next(2));
const frames = played[0] as Keyframe[];
const yOf = (frame: Keyframe | undefined) =>
Number.parseFloat(String(frame?.translate ?? '').split(' ')[1] ?? '');
expect(yOf(frames[0])).toBeGreaterThan(0);
expect(yOf(frames[0])).toBeLessThan(480);
expect(yOf(frames.at(-1))).toBeCloseTo(480, 0);
await act(async () => {
await vi.advanceTimersByTimeAsync(3000);
});
expect(onSettle).toHaveBeenLastCalledWith(2);
});
it('new snap points leave a resting element where it is, and the next settle starts there', async () => {
const settlers = new Set<(index: number) => void>();
const onSettle = vi.fn();
function Sheet({snapPoints}: {snapPoints: number[]}) {
const ref = useRef<HTMLDivElement>(null);
const {settleTo} = useDragToSnapPoints(ref, {
axis: 'y',
snapPoints,
onSettle,
});
settlers.add(settleTo);
return <div ref={ref} />;
}
const {rerender} = render(<Sheet snapPoints={POINTS} />);
const [settleTo] = settlers;
act(() => settleTo(1));
await act(async () => {
await vi.advanceTimersByTimeAsync(3000);
});
// 240 is still a snap point, now the third: nothing moves.
played.length = 0;
rerender(<Sheet snapPoints={[0, 120, 240, 480]} />);
expect(played).toHaveLength(0);
// 240 is gone: still nothing moves, and nothing reports.
onSettle.mockClear();
rerender(<Sheet snapPoints={[0, 300, 600]} />);
await act(async () => {
await vi.advanceTimersByTimeAsync(3000);
});
expect(played).toHaveLength(0);
expect(onSettle).not.toHaveBeenCalled();
// The next settle, to 300, starts from 240.
act(() => settleTo(1));
expect(JSON.stringify(played[0])).toContain('240px');
await act(async () => {
await vi.advanceTimersByTimeAsync(3000);
});
expect(onSettle).toHaveBeenLastCalledWith(1);
});
it('an option changed during a release\u2019s settle leaves it where it is: the hook only creates the drag again', async () => {
// A flick from 260 toward 480, stopped about 330 by a new option. Creating
// the drag again is all the hook does (spec:AST-107 FR6), so nothing aims
// it at 240 or reports a point it never reached.
const restore = coarsePrimaryPointer();
try {
const settlers = new Set<(index: number) => void>();
const onSettle = vi.fn();
function Sheet({flickThreshold}: {flickThreshold: number}) {
const ref = useRef<HTMLDivElement>(null);
const {settleTo} = useDragToSnapPoints(ref, {
axis: 'y',
snapPoints: POINTS,
flickThreshold,
onSettle,
});
settlers.add(settleTo);
return <div ref={ref} />;
}
const {rerender, container} = render(<Sheet flickThreshold={1008} />);
const element = container.firstElementChild as HTMLElement;
const [settleTo] = settlers;
act(() => settleTo(1));
await act(async () => {
await vi.advanceTimersByTimeAsync(3000);
});
onSettle.mockClear();
// From 240: 20 px down slowly, to 260, then 30 px in 20 ms (1500 px/s),
// a flick toward 480.
clock += 10_000;
const start = clock;
act(() => {
touch('touchstart', element, {x: 10, y: 10}, start);
touch('touchmove', element, {x: 10, y: 20}, start + 200);
touch('touchmove', element, {x: 10, y: 30}, start + 400);
touch('touchmove', element, {x: 10, y: 45}, start + 410);
touch('touchmove', element, {x: 10, y: 60}, start + 420);
touch('touchend', element, {x: 10, y: 60}, start + 424, true);
});
await act(async () => {
await vi.advanceTimersByTimeAsync(40);
});
played.length = 0;
rerender(<Sheet flickThreshold={600} />);
await act(async () => {
await vi.advanceTimersByTimeAsync(3000);
});
expect(played).toHaveLength(0);
expect(onSettle).not.toHaveBeenCalled();
} finally {
restore();
}
});
it('delegates entirely to the factory: the hook module holds no behavior of its own', () => {
const source = fs.readFileSync(
path.join(__dirname, 'useDragToSnapPoints.ts'),
'utf8',
);
const imports = [...source.matchAll(/from '([^']+)'/g)].map(m => m[1]);
expect([...new Set(imports)].sort()).toEqual([
'../dragToSnapPoints/createDragToSnapPoints',
'./useAttachment',
'./useIsomorphicLayoutEffect',
'react',
]);
expect(source).toContain('createDragToSnapPoints(element');
expect(source).toContain('useAttachment(');
expect(source).not.toMatch(/\b(motion|gestures)\//);
});
});