An open source design system that's fully customizable and agent ready
TypeScript
// Copyright (c) Meta Platforms, Inc. and affiliates.
/**
* @file useRefreshControl.test.tsx
* @input vitest (jsdom), useRefreshControl in a minimal app scroll
* container, input events on its content, and stand-ins for a touch screen
* and a non-iOS WebKit
* @output Covers the pull, the end, controlled and programmatic refreshes, and
* the announcement. Also covers the inputs that pull and those that do not,
* the disabled state and the scroll container's top-edge overscroll policy
* @position Testing; colocated with useRefreshControl.ts. A real browser
* checks the motion itself (the interaction spec and its storyboards)
*/
import {Suspense, startTransition, use, useState, type ReactNode} from 'react';
import {act, render, screen, waitFor} from '@testing-library/react';
import {
GestureRecognizer,
PanGestureRecognizer,
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,
type UseRefreshControlOptions,
} from './useRefreshControl';
// 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('../internal/useMotionEngine', async importOriginal => {
const real = await importOriginal<typeof MotionEngineModule>();
return {
...real,
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);
}
return result;
},
};
});
/**
* Gives the content's settle back to the top the curve from `settleCurve`
* and an end that the test controls. Records the curves that the indicator
* plays on its opacity.
*/
function watchFade(settleCurve: () => MotionCurve | null) {
const [contentAnimator, indicatorAnimator] = animators.list.slice(
-2,
) as MotionEngine[];
let finishSettle: (done: boolean) => void = () => {};
const animate = contentAnimator.animate.bind(contentAnimator);
vi.spyOn(contentAnimator, 'animate').mockImplementation(
(to, transition, options) => {
const handle = animate(to, transition, options);
if (to.y !== 0) {
return handle;
}
const curve = settleCurve();
const finished = new Promise<boolean>(resolve => {
finishSettle = resolve;
});
return {...handle, finished, curve: () => curve};
},
);
const play = vi.spyOn(indicatorAnimator, 'play');
return {
fades: () =>
play.mock.calls
.map(([curves]) => curves.opacity)
.filter((curve): curve is MotionCurve => curve != null),
finishSettle: (done: boolean) => finishSettle(done),
};
}
/**
* Gives a scroll container the height of the scroll view that UIKit's frames
* were measured on, and content that overflows it. The trigger distance is
* then UIKit's floor, 73 px of overscroll. jsdom lays nothing out.
*/
function measured(element: HTMLElement | null): void {
if (element != null) {
sized(element, {client: 334, scroll: 1000});
}
}
/** Gives an element a height and a content height. */
function sized(
element: HTMLElement,
{client, scroll}: {client: number; scroll: number},
): void {
Object.defineProperty(element, 'clientHeight', {
value: client,
configurable: true,
});
Object.defineProperty(element, 'scrollHeight', {
value: scroll,
configurable: true,
});
}
/**
* The structure the hook drives: the app's scroll container, the pulled
* content and an indicator. With `isBare`, the test supplies the container.
*/
function Refreshable({
children,
'data-testid': testId,
isBare = false,
announce = 'Refreshing',
...options
}: UseRefreshControlOptions & {
children: ReactNode;
'data-testid'?: string;
isBare?: boolean;
}) {
const control = useRefreshControl({announce, ...options});
const pulled = (
<div
data-testid={testId}
ref={control.contentRef}
aria-busy={control.isRefreshing || undefined}>
<div ref={control.indicatorRef} aria-hidden />
{children}
</div>
);
return isBare ? (
pulled
) : (
<div data-testid="list" ref={measured} style={{overflowY: 'auto'}}>
{pulled}
</div>
);
}
const COARSE = /\(\s*pointer\s*:\s*coarse\s*\)/;
let originalMatchMedia: typeof window.matchMedia;
let originalInnerHeight: number;
const originalCss = Object.getOwnPropertyDescriptor(window, 'CSS');
/** Whether the engine answers iOS WebKit's `CSS.supports` query. */
function useIos(isIos: boolean): void {
Object.defineProperty(window, 'CSS', {
configurable: true,
writable: true,
value: {
escape: (value: string) => value,
supports: (query: string) =>
isIos && query === '(-webkit-touch-callout: none)',
},
});
}
function useTouchScreen(isTouch: boolean): void {
window.matchMedia = (query: string) =>
({
matches: isTouch && COARSE.test(query),
media: query,
onchange: null,
addListener: () => {},
removeListener: () => {},
addEventListener: () => {},
removeEventListener: () => {},
dispatchEvent: () => false,
}) as MediaQueryList;
}
let clock = 0;
function touch(
type: string,
target: EventTarget,
y: number,
isLift = false,
): void {
clock += 16;
const event = new Event(type, {bubbles: true, cancelable: true});
const entry = {identifier: 1, clientX: 100, clientY: y, target};
Object.defineProperty(event, 'changedTouches', {value: [entry]});
Object.defineProperty(event, 'touches', {value: isLift ? [] : [entry]});
Object.defineProperty(event, 'timeStamp', {value: clock});
act(() => {
target.dispatchEvent(event);
});
}
/** A one-finger drag from y 100 down by each step in turn. */
function pull(target: EventTarget, steps: number[], lift = true): void {
let y = 100;
touch('touchstart', target, y);
for (const step of steps) {
y += step;
touch('touchmove', target, y);
}
if (lift) {
touch('touchend', target, y, true);
}
}
/**
* A drag with a mouse or a pen from y 100. `move` goes down by a step with the
* button held, and `lift` releases the button.
*/
function pointerDrag(target: EventTarget, pointerType: 'mouse' | 'pen') {
let y = 100;
const send = (type: string, buttons: number) => {
clock += 16;
const event = new PointerEvent(type, {
bubbles: true,
cancelable: true,
composed: true,
pointerId: 7,
pointerType,
isPrimary: true,
clientX: 100,
clientY: y,
button: 0,
buttons,
});
Object.defineProperty(event, 'timeStamp', {value: clock});
act(() => {
target.dispatchEvent(event);
});
};
send('pointerdown', 1);
return {
move(step: number) {
y += step;
send('pointermove', 1);
},
lift() {
send('pointerup', 0);
},
};
}
/**
* Wheel steps of `dy` px each. `trackpad` adds the legacy `wheelDeltaY` that
* Chromium and WebKit report for a trackpad, three times each delta against
* the content. Without it, the gesture host reads a mouse wheel.
*/
function wheel(
target: EventTarget,
steps: number[],
{trackpad}: {trackpad: boolean},
): void {
for (const dy of steps) {
clock += 16;
const event = new WheelEvent('wheel', {
bubbles: true,
cancelable: true,
composed: true,
clientX: 100,
clientY: 100,
deltaY: dy,
deltaMode: 0,
});
Object.defineProperty(event, 'timeStamp', {value: clock});
if (trackpad) {
Object.defineProperty(event, 'wheelDeltaX', {value: 0});
Object.defineProperty(event, 'wheelDeltaY', {value: -3 * dy});
}
act(() => {
target.dispatchEvent(event);
});
}
}
function translateY(element: HTMLElement): number {
const value = element.style.getPropertyValue('translate');
if (value === '' || value === 'none') {
return 0;
}
const parts = value.trim().split(/\s+/);
return parseFloat(parts[1] ?? '0');
}
/** The app's indicator. */
function indicator(): HTMLElement {
return content().firstElementChild as HTMLElement;
}
/** How much of the indicator the touch layer reveals, 0 to 1. */
function reveal(): string {
return indicator().style.getPropertyValue('--astryx-refresh-reveal');
}
function content(): HTMLElement {
return screen.getByTestId('refresh');
}
describe('useRefreshControl', () => {
beforeEach(() => {
originalMatchMedia = window.matchMedia;
originalInnerHeight = window.innerHeight;
useTouchScreen(true);
// The page as tall as the scroll container, for anything that reads it.
Object.defineProperty(window, 'innerHeight', {
value: 334,
configurable: true,
});
clock = 0;
});
afterEach(() => {
vi.unstubAllGlobals();
vi.useRealTimers();
Reflect.deleteProperty(HTMLElement.prototype, 'animate');
window.matchMedia = originalMatchMedia;
if (originalCss) {
Object.defineProperty(window, 'CSS', originalCss);
} else {
Reflect.deleteProperty(window, 'CSS');
}
Object.defineProperty(window, 'innerHeight', {
value: originalInnerHeight,
configurable: true,
});
document.documentElement.style.overscrollBehaviorY = '';
});
it('pulls the content as UIKit does: one to one past the hysteresis, up to the height', () => {
render(
<Refreshable data-testid="refresh" onRefresh={() => {}}>
<p>Inbox</p>
</Refreshable>,
);
pull(content(), [12, 8, 20], false);
// 40 px of finger travel, 10 of them the pan's hysteresis.
expect(translateY(content())).toBeCloseTo(30, 5);
touch('touchmove', content(), 170);
expect(translateY(content())).toBeCloseTo(60, 5);
touch('touchend', content(), 170, true);
});
it('triggers with the finger still down, then settles onto the refreshing inset', async () => {
const onRefresh = vi.fn(() => new Promise<void>(() => {}));
render(
<Refreshable data-testid="refresh" onRefresh={onRefresh}>
<p>Inbox</p>
</Refreshable>,
);
pull(content(), [20, 20, 20, 20], false);
expect(onRefresh).not.toHaveBeenCalled();
// 105 px of travel: past the trigger (73 px of overscroll).
touch('touchmove', content(), 205);
expect(onRefresh).toHaveBeenCalledTimes(1);
expect(content()).toHaveAttribute('aria-busy', 'true');
expect(translateY(content())).toBeGreaterThan(74);
expect(translateY(content())).toBeLessThan(95);
// The next frame snaps to one to one with the finger, as UIKit does.
touch('touchmove', content(), 210);
expect(translateY(content())).toBeCloseTo(100, 5);
touch('touchend', content(), 210, true);
// The settle starts in the next frame; jsdom has no compositor, so it
// lands on its target at once.
await waitFor(() => expect(translateY(content())).toBeCloseTo(60, 5));
await waitFor(() => expect(document.body).toHaveTextContent('Refreshing'));
});
it('pulls from the move that crosses the hysteresis, even one that lands on it exactly', () => {
render(
<Refreshable data-testid="refresh" onRefresh={() => {}}>
<p>Inbox</p>
</Refreshable>,
);
// 5 px steps: the second lands on the 10 px hysteresis, where the pan
// begins at a translation of zero. The two after it pull 10 px.
pull(content(), [5, 5, 5, 5], false);
expect(translateY(content())).toBe(10);
});
it('keeps the indicator at the top of the scroll view while the content is pulled, settles and ends', async () => {
let resolve: () => void = () => {};
render(
<Refreshable
data-testid="refresh"
onRefresh={() =>
new Promise<void>(done => {
resolve = done;
})
}>
<p>Inbox</p>
</Refreshable>,
);
const indicator = content().firstElementChild as HTMLElement;
pull(content(), [30, 30, 30, 30], false);
// UIRefreshControl stays where it is while the content moves away from it.
// The indicator rides on the content's edge, so it moves back by what the
// content moved past the inset.
const pulled = translateY(content());
expect(pulled).toBeGreaterThan(60);
expect(translateY(indicator)).toBeCloseTo(60 - pulled, 5);
touch('touchend', content(), 220, true);
await waitFor(() => expect(translateY(content())).toBeCloseTo(60, 5));
expect(translateY(indicator)).toBeCloseTo(0, 5);
await act(async () => {
resolve();
});
await waitFor(() => expect(translateY(content())).toBe(0));
// Back at the top, the content's edge covers it.
expect(translateY(indicator)).toBeCloseTo(60, 5);
});
it('leaves the content’s compositor layer to the animator: promoted once while it moves, given back at rest', async () => {
let resolve: () => void = () => {};
render(
<Refreshable
data-testid="refresh"
onRefresh={() =>
new Promise<void>(done => {
resolve = done;
})
}>
<p>Inbox</p>
</Refreshable>,
);
const willChange = () => content().style.willChange;
// A tap at the top moves nothing, so nothing is promoted.
touch('touchstart', content(), 100);
touch('touchend', content(), 100, true);
expect(willChange()).toBe('');
// A pull is promoted from its first move, once, and keeps the layer
// through the refresh until the end has run.
pull(content(), [30, 30, 30, 30]);
expect(willChange()).toBe('translate');
await act(async () => {
resolve();
});
await waitFor(() => expect(willChange()).toBe(''), {timeout: 3000});
});
it('settles back to the top without refreshing below the trigger', async () => {
const onRefresh = vi.fn();
render(
<Refreshable data-testid="refresh" onRefresh={onRefresh}>
<p>Inbox</p>
</Refreshable>,
);
pull(content(), [20, 20, 20, 10]);
expect(onRefresh).not.toHaveBeenCalled();
await waitFor(() => expect(translateY(content())).toBe(0));
expect(content()).not.toHaveAttribute('aria-busy');
});
it('fades the indicator along the content settle curve when a pull ends below the trigger', () => {
animators.list.length = 0;
render(
<Refreshable data-testid="refresh" onRefresh={() => {}}>
<p>Inbox</p>
</Refreshable>,
);
// A curve that no spring makes: the fade follows the settle's own curve.
let from = 0;
const settle: MotionCurve = {
duration: 0.8,
at: t => from * Math.max(0, 1 - t / 0.8),
velocity: t => (t < 0.8 ? -from / 0.8 : 0),
};
const fade = watchFade(() => settle);
pull(content(), [20, 20, 20, 10], false);
from = translateY(content());
expect(from).toBeGreaterThan(0);
touch('touchend', content(), 170, true);
const fades = fade.fades();
expect(fades).toHaveLength(1);
expect(fades[0].duration).toBe(0.8);
const start = revealProgress(from, 334);
for (const time of [0, 0.2, 0.4, 0.6, 0.8]) {
expect(fades[0].at(time)).toBeCloseTo(
revealProgress(settle.at(time), 334) / start,
6,
);
}
});
it('holds the indicator under Reduce Motion, where the settle has no curve, and resets it once the content settles', async () => {
animators.list.length = 0;
render(
<Refreshable data-testid="refresh" onRefresh={() => {}}>
<p>Inbox</p>
</Refreshable>,
);
const fade = watchFade(() => null);
pull(content(), [20, 20, 20, 10]);
expect(Number(reveal())).toBeGreaterThan(0);
expect(fade.fades()).toEqual([]);
await act(async () => {
fade.finishSettle(true);
});
await waitFor(() => expect(reveal()).toBe('0'));
});
it('keeps what the indicator shows when a finger catches its fade, and the fade no longer resets it under the finger', async () => {
animators.list.length = 0;
render(
<Refreshable data-testid="refresh" onRefresh={() => {}}>
<p>Inbox</p>
</Refreshable>,
);
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<
MotionEngine['play']
>;
const shown = Number(reveal());
expect(shown).toBeGreaterThan(0);
// A finger catches the settle halfway through the fade.
const presentedGet = indicatorAnimator.get.bind(indicatorAnimator);
const presented = vi
.spyOn(indicatorAnimator, 'get')
.mockImplementation(property =>
property === 'opacity' ? 0.5 : presentedGet(property),
);
const set = vi.spyOn(indicatorAnimator, 'set');
touch('touchstart', content(), 100);
presented.mockRestore();
expect(Number(reveal())).toBeCloseTo(shown * 0.5, 6);
expect(set).toHaveBeenCalledWith({opacity: 1});
// The finger pulls on. The fade ends stopped, so it never resets the
// indicator under the finger.
touch('touchmove', content(), 110);
touch('touchmove', content(), 120);
let isFadeDone: boolean | undefined;
await act(async () => {
isFadeDone = await fade.finished;
});
expect(isFadeDone).toBe(false);
expect(Number(reveal())).toBeGreaterThan(0);
});
it('ends when the promise from onRefresh settles, and removes the inset', async () => {
let resolve: () => void = () => {};
const onRefresh = vi.fn(
() =>
new Promise<void>(done => {
resolve = done;
}),
);
render(
<Refreshable data-testid="refresh" onRefresh={onRefresh}>
<p>Inbox</p>
</Refreshable>,
);
pull(content(), [30, 30, 30, 30]);
expect(content()).toHaveAttribute('aria-busy', 'true');
await act(async () => {
resolve();
});
expect(content()).not.toHaveAttribute('aria-busy');
// The slide starts in the frame after the end has rendered.
await waitFor(() => expect(translateY(content())).toBe(0));
});
it('ends after a rejected refresh as well', async () => {
let reject: () => void = () => {};
render(
<Refreshable
data-testid="refresh"
onRefresh={() =>
new Promise<void>((_, fail) => {
reject = () => fail(new Error('offline'));
})
}>
<p>Inbox</p>
</Refreshable>,
);
pull(content(), [30, 30, 30, 30]);
await act(async () => {
reject();
});
expect(content()).not.toHaveAttribute('aria-busy');
});
it('follows a controlled isRefreshing without calling onRefresh for it', () => {
const onRefresh = vi.fn();
const {rerender} = render(
<Refreshable
data-testid="refresh"
onRefresh={onRefresh}
isRefreshing={false}>
<p>Inbox</p>
</Refreshable>,
);
rerender(
<Refreshable data-testid="refresh" onRefresh={onRefresh} isRefreshing>
<p>Inbox</p>
</Refreshable>,
);
expect(content()).toHaveAttribute('aria-busy', 'true');
expect(onRefresh).not.toHaveBeenCalled();
rerender(
<Refreshable
data-testid="refresh"
onRefresh={onRefresh}
isRefreshing={false}>
<p>Inbox</p>
</Refreshable>,
);
expect(content()).not.toHaveAttribute('aria-busy');
});
it('keeps a pulled refresh running while a controlled parent holds it, until the parent ends it', async () => {
let end: () => void = () => {};
function Parent() {
const [refreshing, setRefreshing] = useState(false);
end = () => setRefreshing(false);
return (
<Refreshable
data-testid="refresh"
onRefresh={() => setRefreshing(true)}
isRefreshing={refreshing}>
<p>Inbox</p>
</Refreshable>
);
}
render(<Parent />);
pull(content(), [30, 30, 30, 30]);
await waitFor(() => expect(content()).toHaveAttribute('aria-busy', 'true'));
await act(async () => {
await new Promise(resolve => setTimeout(resolve, 50));
});
expect(content()).toHaveAttribute('aria-busy', 'true');
act(() => {
end();
});
await waitFor(() => expect(content()).not.toHaveAttribute('aria-busy'));
});
it.each(['pen', 'mouse'] as const)(
'never pulls under a %s drag: it stays the browser’s, for text selection',
pointerType => {
useTouchScreen(false);
const onRefresh = vi.fn();
render(
<Refreshable data-testid="refresh" onRefresh={onRefresh}>
<p>Inbox</p>
</Refreshable>,
);
const drag = pointerDrag(content(), pointerType);
// 105 px of travel: past the trigger, were it a finger.
for (const step of [12, 8, 20, 20, 20, 25]) {
drag.move(step);
}
expect(translateY(content())).toBe(0);
drag.lift();
expect(onRefresh).not.toHaveBeenCalled();
expect(content()).not.toHaveAttribute('aria-busy');
},
);
it('takes a scroll only through a pan that claims it: the touch pull is a watcher and takes none, and the content’s only blocking listener is the scroll pull’s `wheel` (spec:AST-094 FR20)', () => {
useTouchScreen(false);
const enabled = vi.spyOn(GestureRecognizer.prototype, 'setEnabled');
const added = vi.spyOn(HTMLElement.prototype, 'addEventListener');
try {
render(
<Refreshable data-testid="refresh" onRefresh={() => {}}>
<p>Inbox</p>
</Refreshable>,
);
const pans = [...new Set(enabled.mock.contexts as GestureRecognizer[])];
expect(pans).toHaveLength(2);
for (const pan of pans) {
// A watcher registers only passive listeners. A pan that takes a
// scroll gets a blocking `wheel` listener, so only a claimer may take a
// scroll.
expect(pan.allowedScrollTypes.size > 0).toBe(pan.claimsTouches);
}
const blocking = added.mock.calls
.filter(
(call, index) =>
added.mock.contexts[index] === content() &&
typeof call[2] === 'object' &&
call[2] != null &&
call[2].passive === false,
)
.map(call => call[0]);
expect(blocking).toEqual(['wheel']);
} finally {
enabled.mockRestore();
added.mockRestore();
}
});
it('pulls under a trackpad’s two-finger scroll at the top as under a finger: the same mapping, a trigger, the settle onto the inset once the scroll ends (spec:AST-094 FR43)', async () => {
useTouchScreen(false);
const onRefresh = vi.fn(() => new Promise<void>(() => {}));
render(
<Refreshable data-testid="refresh" onRefresh={onRefresh}>
<p>Inbox</p>
</Refreshable>,
);
wheel(content(), [-12, -8, -20], {trackpad: true});
// 40 px of scroll toward the top, 10 of them the pan's hysteresis, as
// under a finger.
expect(translateY(content())).toBeCloseTo(30, 5);
wheel(content(), [-20, -20, -25], {trackpad: true});
// 105 px: past the trigger (73 px of overscroll), mid-scroll.
expect(onRefresh).toHaveBeenCalledTimes(1);
expect(content()).toHaveAttribute('aria-busy', 'true');
// The scroll ends 100 ms after its last step: the content settles onto
// the inset.
await waitFor(() => expect(translateY(content())).toBeCloseTo(60, 5));
});
it('keeps the page’s text selection through a trackpad pull: a scroll selects nothing (spec:AST-094 FR43)', async () => {
useTouchScreen(false);
render(
<Refreshable data-testid="refresh" onRefresh={() => {}}>
<p>Inbox</p>
</Refreshable>,
);
act(() => {
document.getSelection()?.selectAllChildren(content());
});
wheel(content(), [-12, -8, -20], {trackpad: true});
expect(translateY(content())).toBeGreaterThan(0);
expect(document.getSelection()?.isCollapsed).toBe(false);
await waitFor(() => expect(translateY(content())).toBe(0));
expect(document.getSelection()?.isCollapsed).toBe(false);
});
it('never pulls under a mouse wheel’s notches: they scroll what is under the pointer (spec:AST-094 FR43)', () => {
useTouchScreen(false);
const onRefresh = vi.fn();
render(
<Refreshable data-testid="refresh" onRefresh={onRefresh}>
<p>Inbox</p>
</Refreshable>,
);
wheel(content(), [-100, -100], {trackpad: false});
expect(translateY(content())).toBe(0);
expect(onRefresh).not.toHaveBeenCalled();
});
it('pulls on any touch screen, an Android phone’s included: one touch model, no iOS check', async () => {
useIos(false);
const onRefresh = vi.fn();
const {unmount} = render(
<Refreshable data-testid="refresh" onRefresh={onRefresh}>
<p>Inbox</p>
</Refreshable>,
);
// The pull owns its container's top edge, so the browser draws no
// overscroll of its own there.
expect(screen.getByTestId('list').style.overscrollBehaviorY).toBe('none');
pull(content(), [30, 30, 30, 30]);
expect(onRefresh).toHaveBeenCalledTimes(1);
await waitFor(() => expect(content()).not.toHaveAttribute('aria-busy'));
await waitFor(() => expect(translateY(content())).toBe(0));
unmount();
render(<p data-testid="refresh">Gone</p>);
});
it('ends a pulled refresh on the next commit when a controlled isRefreshing stays false', async () => {
// The parent never takes the refresh (or sets true then false in one
// handler): the prop is the source, so the refresh ends.
const onRefresh = vi.fn();
render(
<Refreshable
data-testid="refresh"
onRefresh={onRefresh}
isRefreshing={false}>
<p>Inbox</p>
</Refreshable>,
);
pull(content(), [30, 30, 30, 30]);
expect(onRefresh).toHaveBeenCalledTimes(1);
await waitFor(() => expect(content()).not.toHaveAttribute('aria-busy'));
await waitFor(() => expect(translateY(content())).toBe(0));
});
it('renders a controlled isRefreshing from its first render', () => {
const seen: boolean[] = [];
function Probe({isRefreshing}: {isRefreshing: boolean}) {
const control = useRefreshControl({isRefreshing});
seen.push(control.isRefreshing);
return <div ref={control.contentRef} />;
}
render(<Probe isRefreshing />);
// No first render with the refresh off.
expect(seen[0]).toBe(true);
});
it('leaves no inline translate on the content at rest, so its fixed children stay fixed', async () => {
let resolve: () => void = () => {};
render(
<Refreshable
data-testid="refresh"
onRefresh={() =>
new Promise<void>(done => {
resolve = done;
})
}>
<p>Inbox</p>
</Refreshable>,
);
// Any translate, 0 included, makes the content the containing block of
// its `position: fixed` children.
pull(content(), [20, 20, 20, 10]);
await waitFor(() =>
expect(content().style.getPropertyValue('translate')).toBe(''),
);
pull(content(), [30, 30, 30, 30]);
await waitFor(() => expect(translateY(content())).toBeCloseTo(60, 5));
await act(async () => {
resolve();
});
await waitFor(() =>
expect(content().style.getPropertyValue('translate')).toBe(''),
);
});
it('holds one scroll listener, on its scroll container, only while enabled, and no resize listener (spec:AST-094 FR24)', () => {
// Optional behavior holds its resources only while enabled. Other parts,
// such as the gesture host, keep their own, so the test compares a
// disabled pull with an enabled one.
const listenersFor = (isDisabled: boolean) => {
const onDocument = vi.spyOn(document, 'addEventListener');
const onElements = vi.spyOn(HTMLElement.prototype, 'addEventListener');
const onWindow = vi.spyOn(window, 'addEventListener');
const {unmount} = render(
<Refreshable
data-testid="refresh"
onRefresh={() => {}}
isDisabled={isDisabled}>
<p>Inbox</p>
</Refreshable>,
);
const list = screen.getByTestId('list');
const counts = {
documentScroll: onDocument.mock.calls.filter(
call => call[0] === 'scroll',
).length,
listScroll: onElements.mock.instances.filter(
(element, index) =>
element === list && onElements.mock.calls[index][0] === 'scroll',
).length,
resize: onWindow.mock.calls.filter(call => call[0] === 'resize').length,
};
unmount();
onDocument.mockRestore();
onElements.mockRestore();
onWindow.mockRestore();
return counts;
};
const disabled = listenersFor(true);
const enabled = listenersFor(false);
expect(enabled.documentScroll).toBe(0);
expect(enabled.listScroll - disabled.listScroll).toBe(1);
expect(enabled.resize - disabled.resize).toBe(0);
render(<p data-testid="refresh">Gone</p>);
});
it('keeps the edge claimed when React discards a render that disables the pull', async () => {
// A transition that suspends for good: React renders the new props, then
// keeps the committed tree and never commits that render.
const pending = new Promise<never>(() => {});
function Pending(): null {
use(pending);
return null;
}
function List({isDisabled}: {isDisabled: boolean}) {
const control = useRefreshControl({
onRefresh: () => {},
announce: 'Refreshing',
isDisabled,
});
return (
<div data-testid="list" ref={measured} style={{overflowY: 'auto'}}>
<div data-testid="refresh" ref={control.contentRef}>
<div ref={control.indicatorRef} aria-hidden />
<p>Inbox</p>
</div>
</div>
);
}
function Screen({
isDisabled,
isPending,
}: {
isDisabled: boolean;
isPending: boolean;
}) {
return (
<Suspense fallback={null}>
<List isDisabled={isDisabled} />
{isPending ? <Pending /> : null}
</Suspense>
);
}
const {rerender} = render(<Screen isDisabled={false} isPending={false} />);
await act(async () => {
for (let frame = 0; frame < 3; frame += 1) {
await new Promise<void>(resolve => {
requestAnimationFrame(() => resolve());
});
}
});
const list = screen.getByTestId('list');
expect(list.style.overscrollBehaviorY).toBe('none');
await act(async () => {
startTransition(() => {
rerender(<Screen isDisabled isPending />);
});
});
act(() => {
list.dispatchEvent(new Event('scroll'));
});
expect(list.style.overscrollBehaviorY).toBe('none');
});
it('sets up the edge for content that mounts after the hook: its container is claimed near the top, given back when scrolled away, and given back when the content leaves', async () => {
function Late({isShown}: {isShown: boolean}) {
const control = useRefreshControl({
onRefresh: () => {},
announce: 'Refreshing',
});
return (
<div data-testid="list" ref={measured} style={{overflowY: 'auto'}}>
{isShown ? (
<div data-testid="refresh" ref={control.contentRef}>
<div ref={control.indicatorRef} aria-hidden />
<p>Inbox</p>
</div>
) : null}
</div>
);
}
const {rerender} = render(<Late isShown={false} />);
// The hook's own setup, two frames after it mounts, finds no content.
await act(async () => {
for (let frame = 0; frame < 3; frame += 1) {
await new Promise<void>(resolve => {
requestAnimationFrame(() => resolve());
});
}
});
const list = screen.getByTestId('list');
const onList = vi.spyOn(list, 'addEventListener');
const offList = vi.spyOn(list, 'removeEventListener');
rerender(<Late isShown />);
expect(list.style.overscrollBehaviorY).toBe('none');
expect(onList.mock.calls.filter(call => call[0] === 'scroll')).toHaveLength(
1,
);
// Scrolled away from the top, the container's edge is the browser's
// again; back at the top, the pull claims it again.
const scrollTo = (top: number) => {
list.scrollTop = top;
act(() => {
list.dispatchEvent(new Event('scroll'));
});
};
scrollTo(500);
expect(list.style.overscrollBehaviorY).toBe('');
scrollTo(0);
expect(list.style.overscrollBehaviorY).toBe('none');
rerender(<Late isShown={false} />);
expect(list.style.overscrollBehaviorY).toBe('');
expect(
offList.mock.calls.filter(call => call[0] === 'scroll'),
).toHaveLength(1);
onList.mockRestore();
offList.mockRestore();
});
it('ends a refresh that begins and ends before React renders: refresh() from a timer, with an onRefresh that settles at once', async () => {
let refresh: () => void = () => {};
function Probe() {
const control = useRefreshControl({onRefresh: () => {}});
refresh = control.refresh;
return (
<div
data-testid="refresh"
ref={control.contentRef}
aria-busy={control.isRefreshing || undefined}>
<div ref={control.indicatorRef} aria-hidden />
<p>Inbox</p>
</div>
);
}
render(<Probe />);
// Outside any React event, so the begin and the end land in one render
// and the rendered `isRefreshing` never changes.
await new Promise<void>(resolve =>
setTimeout(() => {
refresh();
resolve();
}, 0),
);
// The inset went on with no visible motion; the end slides it off.
await waitFor(() => expect(translateY(content())).toBe(0), {
timeout: 3000,
});
expect(content()).not.toHaveAttribute('aria-busy');
});
it('does not pull while disabled', () => {
const onRefresh = vi.fn();
render(
<Refreshable data-testid="refresh" onRefresh={onRefresh} isDisabled>
<p>Inbox</p>
</Refreshable>,
);
pull(content(), [30, 30, 30, 30]);
expect(onRefresh).not.toHaveBeenCalled();
expect(translateY(content())).toBe(0);
});
it('owns the top edge of the scroll container it sits in, not the page’s', () => {
const {unmount} = render(
<div
data-testid="scroller"
ref={measured}
style={{overflowY: 'auto', overscrollBehaviorY: 'contain'}}>
<Refreshable data-testid="refresh" isBare onRefresh={() => {}}>
<p>Inbox</p>
</Refreshable>
</div>,
);
const scroller = screen.getByTestId('scroller');
expect(scroller.style.overscrollBehaviorY).toBe('none');
expect(document.documentElement.style.overscrollBehaviorY).toBe('');
unmount();
});
it('finds a scroll container that starts scrolling only after mount, as ScrollableArea does once it has measured', async () => {
const {unmount} = render(
<div
data-testid="scroller"
ref={measured}
style={{overflowY: 'clip', overscrollBehaviorY: 'auto'}}>
<Refreshable data-testid="refresh" isBare onRefresh={() => {}}>
<p>Inbox</p>
</Refreshable>
</div>,
);
const scroller = screen.getByTestId('scroller');
// Not scrolling yet: no element scrolls, and the page's own top edge
// stays the browser's.
expect(scroller.style.overscrollBehaviorY).toBe('auto');
expect(document.documentElement.style.overscrollBehaviorY).toBe('');
// The container's next render makes it scroll.
scroller.style.overflowY = 'auto';
await waitFor(() =>
expect(scroller.style.overscrollBehaviorY).toBe('none'),
);
expect(document.documentElement.style.overscrollBehaviorY).toBe('');
unmount();
expect(scroller.style.overscrollBehaviorY).toBe('auto');
});
it('follows its scroll container’s scrolls: the top edge is the pull’s only near the top', () => {
render(
<div data-testid="scroller" ref={measured} style={{overflowY: 'auto'}}>
<Refreshable data-testid="refresh" isBare onRefresh={() => {}}>
<p>Inbox</p>
</Refreshable>
</div>,
);
const scroller = screen.getByTestId('scroller');
expect(scroller.style.overscrollBehaviorY).toBe('none');
const scrollTo = (top: number) => {
Object.defineProperty(scroller, 'scrollTop', {
value: top,
configurable: true,
});
act(() => {
scroller.dispatchEvent(new Event('scroll'));
});
};
// Far from the top the browser keeps its own overscroll (the bottom
// bounce), and near the top the pull takes it back.
scrollTo(500);
expect(scroller.style.overscrollBehaviorY).toBe('');
scrollTo(0);
expect(scroller.style.overscrollBehaviorY).toBe('none');
});
it('restores the scroll container’s own value when it unmounts', () => {
function Host({hasControl}: {hasControl: boolean}) {
return (
<div data-testid="scroller" ref={measured} style={{overflowY: 'auto'}}>
{hasControl ? (
<Refreshable data-testid="refresh" isBare onRefresh={() => {}}>
<p>Inbox</p>
</Refreshable>
) : (
<p>Inbox</p>
)}
</div>
);
}
const {rerender} = render(<Host hasControl />);
const scroller = screen.getByTestId('scroller');
expect(scroller.style.overscrollBehaviorY).toBe('none');
rerender(<Host hasControl={false} />);
expect(scroller.style.overscrollBehaviorY).toBe('');
});
it('shows the indicator in full for a refresh begun without a pull', () => {
function WithButton() {
const control = useRefreshControl({
onRefresh: () => new Promise<void>(() => {}),
});
return (
<div data-testid="list" ref={measured} style={{overflowY: 'auto'}}>
<div data-testid="refresh" ref={control.contentRef}>
<div ref={control.indicatorRef} aria-hidden />
<button type="button" onClick={control.refresh}>
Refresh
</button>
</div>
</div>
);
}
render(<WithButton />);
expect(reveal()).toBe('');
act(() => {
screen.getByRole('button', {name: 'Refresh'}).click();
});
expect(reveal()).toBe('1');
});
it('reveals the indicator with the pull, and hides it again when a refresh ends under the finger', async () => {
function Controlled({isRefreshing}: {isRefreshing: boolean}) {
return (
<Refreshable
data-testid="refresh"
isRefreshing={isRefreshing}
onRefresh={() => {}}>
<p>Inbox</p>
</Refreshable>
);
}
const {rerender} = render(<Controlled isRefreshing={false} />);
// Part of the way to the trigger: part of the indicator.
pull(content(), [20, 20], false);
const partway = Number(reveal());
expect(partway).toBeGreaterThan(0);
expect(partway).toBeLessThan(1);
// Past the trigger, the finger still down: all of it.
for (const step of [30, 30]) {
touch('touchmove', content(), 140 + step);
}
rerender(<Controlled isRefreshing />);
expect(reveal()).toBe('1');
rerender(<Controlled isRefreshing={false} />);
touch('touchend', content(), 200, true);
await waitFor(() => expect(reveal()).toBe('0'));
});
it('pulls only in an element that scrolls: on the page itself the browser keeps its own top edge', () => {
document.documentElement.style.overscrollBehaviorY = 'auto';
const onRefresh = vi.fn();
render(
<Refreshable data-testid="refresh" isBare onRefresh={onRefresh}>
<p>Inbox</p>
</Refreshable>,
);
expect(document.documentElement.style.overscrollBehaviorY).toBe('auto');
pull(content(), [30, 30, 30, 30]);
expect(onRefresh).not.toHaveBeenCalled();
expect(translateY(content())).toBe(0);
document.documentElement.style.overscrollBehaviorY = '';
});
it('leaves a scroll container that fits to the browser: no top-edge claim and no pull (spec:AST-025 FR14, FR18)', () => {
const onRefresh = vi.fn();
render(
<div
data-testid="scroller"
ref={element => {
if (element != null) {
sized(element, {client: 334, scroll: 334});
}
}}
style={{overflowY: 'auto'}}>
<Refreshable data-testid="refresh" isBare onRefresh={onRefresh}>
<p>Inbox</p>
</Refreshable>
</div>,
);
// A scroll that starts here belongs to the page around the list. So the
// list keeps no containment, and the pull takes nothing.
expect(screen.getByTestId('scroller').style.overscrollBehaviorY).toBe('');
pull(content(), [30, 30, 30, 30]);
expect(onRefresh).not.toHaveBeenCalled();
expect(translateY(content())).toBe(0);
});
it('claims the top edge once its container overflows, and gives it back when the content fits again (spec:AST-025 FR14)', () => {
type Dispatch = (entries: ResizeObserverEntry[]) => void;
const observers: {callback: Dispatch; isConnected: boolean}[] = [];
vi.stubGlobal(
'ResizeObserver',
class {
state: {callback: Dispatch; isConnected: boolean};
constructor(callback: Dispatch) {
this.state = {callback, isConnected: true};
observers.push(this.state);
}
observe() {
this.state.isConnected = true;
}
unobserve() {}
disconnect() {
this.state.isConnected = false;
}
},
);
const {unmount} = render(
<div
data-testid="scroller"
ref={element => {
if (element != null) {
sized(element, {client: 334, scroll: 334});
}
}}
style={{overflowY: 'auto'}}>
<Refreshable data-testid="refresh" isBare onRefresh={() => {}}>
<p>Inbox</p>
</Refreshable>
</div>,
);
const scroller = screen.getByTestId('scroller');
const resize = (scroll: number) => {
sized(scroller, {client: 334, scroll});
act(() => {
for (const observer of observers) {
observer.callback([
{target: scroller} as unknown as ResizeObserverEntry,
]);
}
});
};
expect(scroller.style.overscrollBehaviorY).toBe('');
resize(1000);
expect(scroller.style.overscrollBehaviorY).toBe('none');
resize(334);
expect(scroller.style.overscrollBehaviorY).toBe('');
unmount();
expect(observers.length).toBeGreaterThan(0);
expect(observers.some(observer => observer.isConnected)).toBe(false);
});
it('never scrolls the page: a refresh begun with no container that overflows moves no scroll', () => {
const scrollTo = vi.fn();
vi.stubGlobal('scrollTo', scrollTo);
function OnThePage() {
const control = useRefreshControl({
onRefresh: () => new Promise<void>(() => {}),
});
return (
<div data-testid="refresh" ref={control.contentRef}>
<div ref={control.indicatorRef} aria-hidden />
<button type="button" onClick={control.refresh}>
Refresh
</button>
</div>
);
}
render(<OnThePage />);
act(() => {
screen.getByRole('button', {name: 'Refresh'}).click();
});
expect(scrollTo).not.toHaveBeenCalled();
});
it('calls onRefresh once: a pull while refreshing only stretches', async () => {
const onRefresh = vi.fn(() => new Promise<void>(() => {}));
render(
<Refreshable data-testid="refresh" onRefresh={onRefresh}>
<p>Inbox</p>
</Refreshable>,
);
pull(content(), [30, 30, 30, 30]);
expect(onRefresh).toHaveBeenCalledTimes(1);
await waitFor(() => expect(translateY(content())).toBeCloseTo(60, 5));
// Far past the trigger again, beyond the inset too.
pull(content(), [30, 30, 30, 30, 30, 30]);
expect(onRefresh).toHaveBeenCalledTimes(1);
expect(content()).toHaveAttribute('aria-busy', 'true');
});
it("starts each release's settle at the content's speed as the finger lifts: the finger's speed where it tracks one to one, less in the rubber band, and the same onto the refreshing inset", () => {
// The gesture arena keeps one clock for the page across tests. The
// events start past it, and the browser's clock follows them, so real
// time between two events never reads as a pause before a lift. Both
// clocks are put back afterwards.
const eventClock = clock;
clock = performance.now() + 100_000;
const browserNow = vi
.spyOn(performance, 'now')
.mockImplementation(() => clock);
const scrollVelocity = vi.spyOn(
PanGestureRecognizer.prototype,
'scrollVelocity',
);
try {
const release = (
steps: number[],
onRefresh: UseRefreshControlOptions['onRefresh'] = () => {},
) => {
animators.list.length = 0;
const {unmount} = render(
<Refreshable data-testid="refresh" onRefresh={onRefresh}>
<p>Inbox</p>
</Refreshable>,
);
const [contentAnimator, indicatorAnimator] = animators.list.slice(
-2,
) as MotionEngine[];
const contentAnimate = vi.spyOn(contentAnimator, 'animate');
const indicatorAnimate = vi.spyOn(indicatorAnimator, 'animate');
scrollVelocity.mockClear();
pull(content(), steps);
const [to, transition] = contentAnimate.mock.calls.at(-1) ?? [];
const result = {
to: to?.y,
content: transition?.velocity?.y,
indicator: indicatorAnimate.mock.calls.at(-1)?.[1].velocity?.y,
scroll: scrollVelocity.mock.results.at(-1)?.value?.y as
number | undefined,
isBusy: content().getAttribute('aria-busy') === 'true',
};
unmount();
return result;
};
// 10 px a frame of 16 ms is 625 px/s.
const tracked = release([10, 10, 10, 10, 10]);
expect(tracked.to).toBe(0);
expect(tracked.content).toBeCloseTo(625, 6);
expect(tracked.indicator).toBeCloseTo(-625, 6);
// Past the one-to-one stretch the content moves slower than the finger.
const banded = release([10, 10, 10, 10, 10, 10, 10, 10]);
expect(banded.content).toBeGreaterThan(0);
expect(banded.content).toBeLessThan(625);
expect(banded.indicator).toBeCloseTo(-(banded.content ?? 0), 6);
// An accelerating flick hands the scroll view's release velocity, the
// blend of the pan's last two values, below its last frame's speed.
const flick = release([5, 5, 5, 10, 15]);
expect(flick.scroll).toBeGreaterThan(0);
expect(flick.content).toBeCloseTo(flick.scroll ?? Number.NaN, 6);
expect(flick.content).toBeLessThan(15 / 0.016);
// A finger that held still before it lifted hands no speed.
expect(release([10, 10, 10, 10, 0, 0, 0, 0, 0, 0]).content).toBe(0);
// A pull that triggers carries its speed onto the refreshing inset.
const inset = release(
[20, 20, 20, 20, 20, 20, 20, 20],
() => new Promise<void>(() => {}),
);
expect(inset.isBusy).toBe(true);
expect(inset.to).toBe(60);
expect(inset.content).toBeGreaterThan(600);
} finally {
scrollVelocity.mockRestore();
browserNow.mockRestore();
clock = eventClock;
}
});
});