An open source design system that's fully customizable and agent ready
TypeScript
feat(lab): useRefreshControl, UIKit's pull to refresh for an app's scroll container (#9865)
Christopher Chedeau9d068fc89dc7
diff --git a/apps/storybook/stories/PullToRefresh.stories.tsx b/apps/storybook/stories/PullToRefresh.stories.tsxnew file mode 100644index 0000000000..0dbb6e0302--- /dev/null+++ b/apps/storybook/stories/PullToRefresh.stories.tsx@@ -0,0 +1,234 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++import {useCallback, useState, type ReactNode} from 'react';+import type {Meta, StoryObj} from '@storybook/react';+import {REFRESH_REVEAL_VAR, useRefreshControl} from '@astryxdesign/lab';+import {Button} from '@astryxdesign/core/Button';+import {List, ListItem} from '@astryxdesign/core/List';+import {Spinner} from '@astryxdesign/core/Spinner';++interface StoryArgs {+ /**+ * How long a refresh takes, in ms. Below 0, it lasts until the page+ * dispatches `refreshcontrol-story-end` on `window`, so a test ends it.+ */+ refreshMs: number;+ /** Rows in the list. */+ rows: number;+}++const meta: Meta<StoryArgs> = {+ title: 'Lab/Pull to refresh',+ parameters: {+ layout: 'fullscreen',+ },+ args: {+ refreshMs: 1500,+ rows: 40,+ },+ argTypes: {+ refreshMs: {control: {type: 'number', min: 0, step: 100}},+ rows: {control: {type: 'number', min: 1, step: 1}},+ },+};++export default meta;++type Story = StoryObj<StoryArgs>;++const wait = (ms: number) =>+ new Promise<void>(resolve => {+ setTimeout(resolve, ms);+ });++/** One refresh: `ms`, or until the page ends it when `ms` is below 0. */+function refreshFor(ms: number): Promise<void> {+ if (Number(ms) >= 0) {+ return wait(ms);+ }+ return new Promise<void>(resolve => {+ window.addEventListener('refreshcontrol-story-end', () => resolve(), {+ once: true,+ });+ });+}++function Messages({rows, count}: {rows: number; count: number}) {+ return (+ <List header={`Inbox (refreshed ${count} times)`}>+ {Array.from({length: rows}, (_, index) => (+ <ListItem+ key={index}+ label={`Message ${index + 1}`}+ description={+ index === 0 ? `Refresh ${count}` : 'Pull down at the top to refresh'+ }+ />+ ))}+ </List>+ );+}++/** The app's indicator shows as much of itself as the pull reveals. */+const revealed = {opacity: `var(${REFRESH_REVEAL_VAR}, 0)`};++/**+ * What an app writes: its own scroll container, the content the hook pulls,+ * and its own indicator, here Core's Spinner. The indicator band sits at the+ * bottom of an overflow-hidden box on the content's top edge, after the+ * content.+ */+function PullToRefresh({+ onRefresh,+ isRefreshing,+ text,+ count,+ isAlwaysScrollable = false,+ children,+}: {+ onRefresh: () => unknown;+ isRefreshing?: boolean;+ text: string;+ count: number;+ /**+ * Makes the content 1 px taller than the container. The pull applies only+ * in a container that overflows, so a short list pulls only with this.+ */+ isAlwaysScrollable?: boolean;+ children: ReactNode;+}) {+ const control = useRefreshControl({+ onRefresh,+ isRefreshing,+ announce: 'Refreshing',+ });+ return (+ <div+ data-refresh-scroller=""+ data-refresh-count={count}+ style={{height: '100%', overflowY: 'auto'}}>+ <div+ ref={control.contentRef}+ data-refresh-content=""+ aria-busy={control.isRefreshing || undefined}+ style={{+ position: 'relative',+ minHeight: isAlwaysScrollable ? 'calc(100% + 1px)' : undefined,+ }}>+ {children}+ <div+ style={{+ position: 'absolute',+ insetInline: 0,+ bottom: '100%',+ height: '100lvh',+ overflow: 'hidden',+ pointerEvents: 'none',+ }}>+ <div+ ref={control.indicatorRef}+ aria-hidden+ style={{+ position: 'absolute',+ insetInline: 0,+ bottom: 0,+ height: 60,+ display: 'flex',+ alignItems: 'center',+ justifyContent: 'center',+ }}>+ <span style={revealed}>+ <Spinner size="lg" shade="subtle" label={text} />+ </span>+ </div>+ </div>+ </div>+ </div>+ );+}++function useInbox(refreshMs: number) {+ const [count, setCount] = useState(0);+ const onRefresh = useCallback(async () => {+ await refreshFor(refreshMs);+ setCount(value => value + 1);+ }, [refreshMs]);+ return {count, onRefresh};+}++/**+ * A list in the app's own scroll container. Pull it down past the top on a+ * touch screen, or with a trackpad's two-finger scroll. Past the trigger, the+ * refresh starts with the finger down.+ */+export const InAScrollContainer: Story = {+ render: function InAScrollContainerStory({refreshMs, rows}) {+ const {count, onRefresh} = useInbox(refreshMs);+ return (+ <div style={{height: '100dvh'}}>+ <PullToRefresh+ onRefresh={onRefresh}+ count={count}+ text={`Updated ${count} times`}>+ <Messages rows={rows} count={count} />+ </PullToRefresh>+ </div>+ );+ },+};++/**+ * Controlled: the button refreshes too (the pull has no keyboard or+ * screen-reader equivalent), and the app sets `isRefreshing` itself.+ */+export const Controlled: Story = {+ render: function ControlledStory({refreshMs, rows}) {+ const [isRefreshing, setIsRefreshing] = useState(false);+ const [count, setCount] = useState(0);+ const refresh = useCallback(() => {+ setIsRefreshing(true);+ void refreshFor(refreshMs).then(() => {+ setCount(value => value + 1);+ setIsRefreshing(false);+ });+ }, [refreshMs]);+ return (+ <div style={{height: '100dvh', display: 'flex', flexDirection: 'column'}}>+ <div style={{padding: 8}}>+ <Button label="Refresh" onClick={refresh} isDisabled={isRefreshing} />+ </div>+ <div style={{flex: 1, minHeight: 0}}>+ <PullToRefresh+ onRefresh={refresh}+ isRefreshing={isRefreshing}+ count={count}+ text={`Updated ${count} times`}>+ <Messages rows={rows} count={count} />+ </PullToRefresh>+ </div>+ </div>+ );+ },+};++/**+ * A list shorter than the screen still pulls: the app makes its content 1 px+ * taller than the container, so the container overflows.+ */+export const ShortList: Story = {+ args: {rows: 3},+ render: function ShortListStory({refreshMs, rows}) {+ const {count, onRefresh} = useInbox(refreshMs);+ return (+ <div style={{height: '100dvh'}}>+ <PullToRefresh+ onRefresh={onRefresh}+ count={count}+ isAlwaysScrollable+ text="Pull to refresh">+ <Messages rows={rows} count={count} />+ </PullToRefresh>+ </div>+ );+ },+};diff --git a/packages/lab/src/RefreshControl/RefreshPullRecognizer.ts b/packages/lab/src/RefreshControl/RefreshPullRecognizer.tsnew file mode 100644index 0000000000..242465436c--- /dev/null+++ b/packages/lab/src/RefreshControl/RefreshPullRecognizer.ts@@ -0,0 +1,104 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/**+ * @file RefreshPullRecognizer.ts+ * @input Touches from the gesture arena (Core's internal touch entry)+ * @output Exports RefreshPullRecognizer, the vertical pan that reads a pull+ * to refresh without taking the touch, and RefreshScrollPullRecognizer+ * @position The gesture of useRefreshControl, on the foundation's+ * PanGestureRecognizer+ *+ * SYNC: When modified, update:+ * - /packages/lab/src/RefreshControl/useRefreshControl.ts+ */++// UIKit's refresh pull is the scroll view's own drag, not a second gesture.+// One touch can scroll, pull past the top, and scroll the same content again.+// So this pan never claims its touch, and only watches it. The browser keeps+// the finger for native scrolling, so nothing changes hands midway. The pan+// reads the finger to draw the overscroll, because the scroll owner's+// `overscroll-behavior-y` is `none` near the top.+//+// The pan begins on vertical travel past its hysteresis. The touch layer+// starts the pull where the content is at its top and the finger moves down.+// When the browser takes the touch to scroll, the pan keeps reading it to the+// lift. A second finger is the browser's, for pinch-zoom.+//+// A trackpad's scroll pulls through RefreshScrollPullRecognizer. A pen's or+// a mouse's drag stays the browser's, for text selection: the pan takes only+// a finger. `pointerType` and `scrollType` record the first contact's input.+// `onTouchDown` reports that contact landing, so a settle in flight can stop+// where it is, as UIScrollView brakes on touch-down.++import {+ PanGestureRecognizer,+ type PanGestureRecognizerOptions,+} from '@astryxdesign/core/internal/touch';+import type {+ GestureEventContext,+ GestureTouch,+ PointerKind,+} from '@astryxdesign/core/internal/touch';++export class RefreshPullRecognizer extends PanGestureRecognizer {+ /** Called when the first contact of a gesture lands, with its timestamp. */+ onTouchDown: ((time: number) => void) | null = null;+ /** The pointer of the gesture's first contact. */+ pointerType: PointerKind = 'touch';+ /** Set when the gesture is a trackpad's scroll rather than a contact. */+ scrollType: GestureTouch['scrollType'] | null = null;++ constructor(options: PanGestureRecognizerOptions = {}) {+ super({+ name: 'RefreshPull',+ direction: 'vertical',+ maximumNumberOfTouches: 1,+ allowedPointerTypes: ['touch'],+ ...options,+ });+ }++ /** Native scrolling keeps the finger: the pull only reads it. */+ override get claimsTouches(): boolean {+ return false;+ }++ protected override touchesBegan(+ touches: ReadonlyArray<GestureTouch>,+ event: GestureEventContext,+ ): void {+ if (this.numberOfTouches === touches.length) {+ const touch = touches[0];+ this.pointerType = touch?.pointerType ?? 'touch';+ this.scrollType = touch?.scrollType ?? null;+ this.onTouchDown?.(event.time);+ }+ super.touchesBegan(touches, event);+ }+}++/**+ * The scroll pull: a trackpad's two-finger scroll at the top. It is a+ * scroll-edge pan that takes a trackpad's scroll and no pointer. So it takes a+ * scroll only where nothing under the pointer could scroll: the owner at its+ * top and the content moving down. The host cancels each wheel event of a+ * gesture that it takes, so its element gets a blocking `wheel` listener. Only+ * a recognizer that claims may register one. It takes no pointer, so it adds+ * no `touchmove` listener.+ */+export class RefreshScrollPullRecognizer extends RefreshPullRecognizer {+ constructor(options: PanGestureRecognizerOptions = {}) {+ super({+ name: 'RefreshScrollPull',+ scrollEdge: true,+ allowedPointerTypes: [],+ allowedScrollTypes: ['continuous'],+ ...options,+ });+ }++ /** The scroll it takes is its own: the host cancels its wheel events. */+ override get claimsTouches(): boolean {+ return true;+ }+}diff --git a/packages/lab/src/RefreshControl/__tests__/RefreshControl.interaction.browser.spec.ts b/packages/lab/src/RefreshControl/__tests__/RefreshControl.interaction.browser.spec.tsnew file mode 100644index 0000000000..5eb67caa51--- /dev/null+++ b/packages/lab/src/RefreshControl/__tests__/RefreshControl.interaction.browser.spec.ts@@ -0,0 +1,1454 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/**+ * @file RefreshControl.interaction.browser.spec.ts+ * @input The built pull-to-refresh stories (useRefreshControl in an app's+ * scroll container), real touch input (Chromium CDP and WebKit's input+ * command) and the interaction harness+ * @output Interaction and animation proofs for the pull to refresh+ * @position Interaction tests of packages/lab/src/RefreshControl+ * (useRefreshControl), on the shape of the BottomSheetDetent exemplar+ */++// The proofs: the pull follows UIKit's measured mapping and settles back below+// the trigger. Past the trigger, the refresh starts with the finger down, and+// the content settles onto the 60 px inset. The settle follows the scroll+// view's bounce spring. The end plays the theme's duration token nearest+// UIKit's 0.3 s, on the move easing. The settle keeps moving through a+// blocked main thread, with no Layout or Paint per frame. A list that fits+// its container keeps the browser's scroll. Under Reduce Motion, a release+// and the end only fade, within 200 ms. A trackpad's scroll at the top+// pulls. A mouse's or a pen's drag stays the browser's, and a mouse wheel's+// notches never pull.+//+// The harness's touch contexts report a coarse pointer in both engines, so+// every proof runs as a phone. The desktop proofs report a fine one.+//+// The oracles are UIKit's numbers, written here apart from the code under+// test. The pan's hysteresis is 10 px, and 60 px follow one to one. Then+// UIScrollView's rubber band applies to the excess (c = 0.55, d = the+// scroller's height). The trigger is at max(73, 0.198 × d) px of overscroll.+// The settle uses response 0.5 s and damping 1. UIKit's end takes 300 ms,+// and the page's own tokens give the end's duration and easing.++import {+ expect,+ test,+ type Browser,+ type Locator,+ type Page,+} from '@astryxdesign/a11y-spec/playwright';+import {+ blockMainThread,+ busyWindowProof,+ compareCurve,+ countBetween,+ cubicBezier,+ drag,+ frames,+ markElement,+ openStory,+ path,+ releaseAnimations,+ rubberBand,+ springStep,+ startBusyControl,+ startCompositorTrace,+ startScreencast,+ timeline,+ trackControl,+ touchDriver,+ toTouchEvents,+ traceRendering,+ trackMarker,+ withStorybook,+ writeEvidence,+ type TouchDriver,+ PEN_SKIP,+ webInputDriver,+} from '@astryxdesign/interaction-harness';++import {refreshControl} from '../refreshValues';++const storybook = withStorybook(test);++/** UIKit's end, measured: `endRefreshing()` moves the content over 0.3 s. */+const UIKIT_END_MS = 300;++/** A CSS time in ms, for the page's duration tokens. */+function timeMs(value: string): number {+ const match = /^\s*(\d*\.?\d+)(ms|s)\s*$/.exec(value);+ if (match == null) {+ throw new Error(`timeMs: not a CSS time: "${value}"`);+ }+ return Number(match[1]) * (match[2] === 's' ? 1000 : 1);+}++/** The control points of a CSS cubic-bezier easing, for the page's tokens. */+function bezierPoints(value: string): [number, number, number, number] {+ const match = /^\s*cubic-bezier\(([^)]*)\)\s*$/.exec(value);+ const points = match?.[1].split(',').map(Number) ?? [];+ if (points.length !== 4 || points.some(n => !Number.isFinite(n))) {+ throw new Error(`bezierPoints: not a cubic-bezier: "${value}"`);+ }+ return points as [number, number, number, number];+}++/** The theme tokens at the content, as the page computes them. */+const tokensAt = (content: Locator, names: readonly string[]) =>+ content.evaluate(+ (element, list) =>+ Object.fromEntries(+ list.map(name => [+ name,+ getComputedStyle(element).getPropertyValue(name).trim(),+ ]),+ ),+ [...names],+ );++const HYSTERESIS = 10;+const HEIGHT = 60;+/**+ * Three frames at 60 Hz. A Web Animation's start resolves to the time of the+ * frame that started it. On a loaded machine, that frame can lie a frame or+ * two before the task that made it. A start dated before a busy task that it+ * waited on lies a whole block earlier.+ */+const START_SLACK_MS = 50;++/** UIKit's trigger distance for a scroll view `dimension` tall. */+const triggerFor = (dimension: number) => Math.max(73, 0.198 * dimension);++/** UIKit's refresh pull: overscroll shown for `travel` px of finger travel. */+function uikitPull(travel: number, dimension: number): number {+ const u = travel - HYSTERESIS;+ if (u <= 0) {+ return 0;+ }+ return u <= HEIGHT ? u : HEIGHT + rubberBand(u - HEIGHT, dimension);+}++interface Opened {+ driver: TouchDriver;+ /** The pulled content (the element under the hook's `contentRef`). */+ content: Locator;+ /** Where the finger lands: on the list, near the top of the screen. */+ start: {x: number; y: number};+ /** The scroll owner's height: the rubber band's dimension. */+ dimension: number;+}++async function openRefresh(+ page: Page,+ story = 'lab-pull-to-refresh--in-a-scroll-container',+ args: Record<string, string> = {},+): Promise<Opened> {+ await openStory(page, storybook(), story, args);+ const driver = await touchDriver(page);+ const content = page.locator('[data-refresh-content]').first();+ await expect(content).toBeVisible();+ const dimension = await content.evaluate(element => {+ for (let node = element.parentElement; node; node = node.parentElement) {+ const overflow = getComputedStyle(node).overflowY;+ if (overflow === 'auto' || overflow === 'scroll') {+ return node.clientHeight;+ }+ }+ return window.innerHeight;+ });+ return {driver, content, start: {x: 200, y: 160}, dimension};+}++/** The content's presented translation, px (works while animations are held). */+const shownPull = (content: Locator) =>+ content.evaluate(element => {+ const value = getComputedStyle(element).translate;+ if (value === 'none' || value === '') {+ return 0;+ }+ return parseFloat(value.split(/\s+/)[1] ?? '0');+ });++const isBusy = (content: Locator) =>+ content.evaluate(element => element.getAttribute('aria-busy') === 'true');++/**+ * Ends the story's refresh, which `refreshMs: '-1'` holds until now. A test+ * that times the end starts it on cue, so a slow pull cannot outrun a clock.+ */+const endRefresh = (page: Page) =>+ page.evaluate(() => {+ window.dispatchEvent(new Event('refreshcontrol-story-end'));+ });++/**+ * Waits for an animation of the content itself (not an indicator's endless+ * spin inside it) and returns its active interval on the page clock. With+ * `afterRefresh`, only once the refresh has ended (the end of a refresh);+ * with `hold`, it is paused where it was found, ready for sampling.+ */+async function waitForSettle(+ content: Locator,+ {+ minProgressMs = 1,+ afterRefresh = false,+ hold = false,+ timeout = 6000,+ }: {+ minProgressMs?: number;+ afterRefresh?: boolean;+ hold?: boolean;+ timeout?: number;+ } = {},+): Promise<{from: number; to: number}> {+ return content.evaluate(+ (element, options) =>+ new Promise<{from: number; to: number}>((resolve, reject) => {+ const deadline = performance.now() + options.timeout;+ const tick = () => {+ const running = element+ .getAnimations()+ .filter(+ a =>+ a.playState === 'running' &&+ a.startTime != null &&+ Number(a.currentTime ?? 0) >= options.minProgressMs,+ );+ const ready =+ running.length > 0 &&+ (!options.afterRefresh ||+ element.getAttribute('aria-busy') !== 'true');+ if (ready) {+ if (options.hold) {+ for (const animation of running) {+ animation.pause();+ }+ (+ window as unknown as {__harnessHeld?: Animation[]}+ ).__harnessHeld = running;+ }+ const timing = running[0].effect?.getComputedTiming();+ const from =+ performance.timeOrigin ++ Number(running[0].startTime) ++ Number(timing?.delay ?? 0);+ resolve({from, to: from + Number(timing?.activeDuration ?? 0)});+ return;+ }+ if (performance.now() > deadline) {+ reject(new Error('waitForSettle: no animation on the content'));+ return;+ }+ requestAnimationFrame(tick);+ };+ tick();+ }),+ {minProgressMs, afterRefresh, hold, timeout},+ );+}++/** Resolves once the content itself holds still (an indicator may spin on). */+async function waitForContentRest(+ content: Locator,+ timeout = 6000,+): Promise<void> {+ await content.evaluate(+ (element, ms) =>+ new Promise<void>((resolve, reject) => {+ const deadline = performance.now() + ms;+ let last = '';+ let still = 0;+ const tick = () => {+ const translate = getComputedStyle(element).translate;+ const moving = element+ .getAnimations()+ .some(a => a.playState === 'running');+ still = !moving && translate === last ? still + 1 : 0;+ last = translate;+ if (still >= 2) {+ resolve();+ return;+ }+ if (performance.now() > deadline) {+ reject(+ new Error(`waitForContentRest: still moving (${translate})`),+ );+ return;+ }+ requestAnimationFrame(tick);+ };+ tick();+ }),+ timeout,+ );+}++/** A slow pull that rests before the lift (release velocity 0). */+function slowPull(from: {x: number; y: number}, dy: number, restMs = 150) {+ return drag(+ from,+ {x: from.x, y: from.y + dy},+ {durationMs: Math.max(200, dy * 5), hz: 60, restMs},+ );+}++/** Samples a held animation's presented translation at each time. */+async function sampleTranslate(+ content: Locator,+ times: readonly number[],+): Promise<{t: number; value: number}[]> {+ return content.evaluate(+ (element, ts) => {+ const held =+ (window as unknown as {__harnessHeld?: Animation[]}).__harnessHeld ??+ [];+ return ts.map(t => {+ for (const animation of held) {+ const end = Number(+ animation.effect?.getComputedTiming().endTime ?? Infinity,+ );+ animation.currentTime = Math.min(t, end - 0.5);+ }+ const value = getComputedStyle(element).translate;+ return {+ t,+ value:+ value === 'none' || value === ''+ ? 0+ : parseFloat(value.split(/\s+/)[1] ?? '0'),+ };+ });+ },+ [...times],+ );+}++/** Reads the shown pull after every move of a script, while the finger is down. */+async function playReading(+ page: Page,+ driver: TouchDriver,+ content: Locator,+ script: ReturnType<typeof drag>,+ onLastMove?: () => Promise<void>,+): Promise<{travel: number; shown: number}[]> {+ const startY = script[0].fingers[0].y;+ const moves = toTouchEvents(script).filter(e => e.type === 'touchMove');+ const readings: {travel: number; shown: number}[] = [];+ let index = 0;+ await driver.play(script, {+ onEvent: async step => {+ if (step.type !== 'touchMove') {+ return;+ }+ await frames(page, 1);+ const y = step.changed[0]?.y ?? step.fingers[0]?.y ?? startY;+ readings.push({travel: y - startY, shown: await shownPull(content)});+ if (index === moves.length - 1) {+ await onLastMove?.();+ }+ index++;+ },+ });+ return readings;+}++test('a pull follows UIKit’s mapping and settles back below the trigger', async ({+ page,+}) => {+ const {driver, content, start, dimension} = await openRefresh(page);+ const readings = await playReading(+ page,+ driver,+ content,+ slowPull(start, 76),+ );+ // Every reading sits on UIKit's curve for its finger travel (the page may+ // lag the finger by a frame: compare with the travel's neighbours).+ const last = readings.at(-1);+ expect(last?.shown ?? NaN).toBeCloseTo(uikitPull(76, dimension), 0);+ for (const {travel, shown} of readings) {+ expect(shown).toBeLessThanOrEqual(uikitPull(travel, dimension) + 1);+ }+ expect(Math.max(...readings.map(r => r.shown))).toBeLessThan(+ triggerFor(dimension),+ );+ await waitForContentRest(content);+ expect(await shownPull(content)).toBeCloseTo(0, 1);+ expect(await isBusy(content)).toBe(false);+});++test('past the trigger the refresh starts with the finger down, then settles onto the inset', async ({+ page,+}) => {+ const {driver, content, start} = await openRefresh(page, undefined, {+ refreshMs: '6000',+ });+ let busyWhileDown = false;+ await playReading(+ page,+ driver,+ content,+ slowPull(start, 300, 200),+ async () => {+ busyWhileDown = await isBusy(content);+ },+ );+ expect(busyWhileDown).toBe(true);+ await waitForContentRest(content);+ expect(await shownPull(content)).toBeCloseTo(HEIGHT, 0);+ expect(await isBusy(content)).toBe(true);+});++test('the settle onto the inset follows the scroll view’s bounce spring', async ({+ page,+}, testInfo) => {+ const {driver, content, start} = await openRefresh(page, undefined, {+ refreshMs: '6000',+ });+ await driver.play(slowPull(start, 300, 200));+ await waitForSettle(content, {hold: true});+ const times = timeline(700);+ const samples = await sampleTranslate(content, times);+ await releaseAnimations(page);+ const from = samples[0].value;+ // scroll.bounce: {duration 0.5, bounce 0} = response 0.5 s, damping 1.+ const oracle = (t: number) =>+ from + (HEIGHT - from) * springStep({response: 0.5, dampingFraction: 1}, t);+ const result = compareCurve(samples, oracle, 1);+ await writeEvidence(+ 'curves/refresh-settle',+ {+ [`${testInfo.project.name}.json`]: JSON.stringify(+ {samples, result},+ null,+ 1,+ ),+ },+ testInfo,+ );+ expect(result.maxError, JSON.stringify(result.worst)).toBeLessThanOrEqual(1);+ expect(samples.at(-1)?.value).toBeCloseTo(HEIGHT, 0);+});++test('the end slides the content up on the theme’s duration and move easing tokens (spec:AST-094 FR45)', async ({+ page,+}, testInfo) => {+ const {driver, content, start} = await openRefresh(page, undefined, {+ refreshMs: '-1',+ });+ const tokens = await tokensAt(content, ['--duration-medium', '--ease-move']);+ const ms = timeMs(tokens['--duration-medium']);+ await driver.play(slowPull(start, 300, 200));+ await waitForContentRest(content);+ expect(await shownPull(content)).toBeCloseTo(HEIGHT, 0);+ await endRefresh(page);+ await waitForSettle(content, {afterRefresh: true, hold: true});+ const samples = await sampleTranslate(content, timeline(ms));+ await releaseAnimations(page);+ const ease = cubicBezier(...bezierPoints(tokens['--ease-move']));+ const oracle = (t: number) => HEIGHT * (1 - ease(Math.min(1, t / ms)));+ const result = compareCurve(samples, oracle, 0.75);+ await writeEvidence(+ 'curves/refresh-end',+ {+ [`${testInfo.project.name}.json`]: JSON.stringify(+ {samples, result},+ null,+ 1,+ ),+ },+ testInfo,+ );+ expect(result.maxError, JSON.stringify(result.worst)).toBeLessThanOrEqual(+ 0.75,+ );+ await waitForContentRest(content);+ expect(await shownPull(content)).toBeCloseTo(0, 1);+});++test('the settle keeps moving every frame while the main thread is blocked', async ({+ page,+ browserName,+}, testInfo) => {+ test.skip(+ browserName !== 'chromium',+ 'screencast frame evidence is Chromium-only in Playwright (WebKit: the iOS simulator rig)',+ );+ const {driver, content, start} = await openRefresh(page, undefined, {+ refreshMs: '6000',+ });+ await markElement(content);+ // The harness's busy-window control: a box the compositor moves along the+ // top edge, in the same screencast. The settle is judged against what the+ // compositor presented, not against a frame rate.+ const control = await startBusyControl(page);+ const cast = await startScreencast(page);+ // The compositor's own frames: a loaded machine's screencast skips frames+ // the compositor still presents, and the verdict measures those gaps+ // between the compositor's frames instead.+ const compositor = await startCompositorTrace(page);+ await driver.play(slowPull(start, 300, 200));+ // The settle must be running (and composited) before the block: an+ // animation cannot start while the main thread is held.+ const settle = await waitForSettle(content, {minProgressMs: 16});+ const block = await blockMainThread(page, 400);+ await page.waitForTimeout(150);+ const castFrames = await cast.stop();+ const presented = await compositor.stop();+ await control.remove();+ const tracked = await trackMarker(page, castFrames);+ const controlFrames = await trackControl(+ page,+ castFrames.filter(f => f.t >= block.from - 300 && f.t <= block.to + 100),+ );+ const proof = busyWindowProof(+ tracked,+ {from: block.from, to: Math.min(block.to, settle.to)},+ {settledWithin: 3, presented, control: controlFrames},+ );+ await writeEvidence(+ 'busy-main-thread/refresh-settle',+ {+ [`${testInfo.project.name}.json`]: JSON.stringify(+ {+ block,+ settle,+ proof,+ frames: tracked.map(f => ({+ t: +(f.t - settle.from).toFixed(1),+ y: f.box?.y ?? null,+ })),+ },+ null,+ 1,+ ),+ },+ testInfo,+ );+ // The screencast resolves whole CSS pixels, so the proof judges until 3 px+ // from rest. The settle moves on every frame the control moves on, and it+ // stalls no longer than the control.+ expect(proof.verdict.failures, proof.summary).toEqual([]);+});++test('the settle does no Layout or Paint per frame', async ({+ page,+ browserName,+}) => {+ test.skip(browserName !== 'chromium', 'rendering traces are Chromium-only');+ const {driver, content, start} = await openRefresh(page, undefined, {+ refreshMs: '6000',+ });+ // The indicator is the app's: Core's Spinner here. Its turn does style work+ // every few frames, and that paints inside the moving band. With the turn+ // paused, the settle paints nothing. So the proof pauses the turn, and the+ // Spinner stays in place, laid out and painted.+ const spinner = await content.evaluate(element => {+ const band = element.querySelector(':scope > :last-child > div');+ for (const node of band?.querySelectorAll<HTMLElement>('*') ?? []) {+ if (getComputedStyle(node).animationName !== 'none') {+ node.style.animationPlayState = 'paused';+ }+ }+ const box = band?.querySelector('svg')?.getBoundingClientRect();+ return {width: box?.width ?? 0, height: box?.height ?? 0};+ });+ expect(spinner.width).toBeGreaterThan(0);+ expect(spinner.height).toBeGreaterThan(0);+ let settle = {from: 0, to: 0};+ let steadyFrom = 0;+ const trace = await traceRendering(page, async () => {+ await driver.play(slowPull(start, 300, 200));+ settle = await waitForSettle(content);+ // The release commits over the settle's first frames. The steady part+ // starts once the page renders three more frames. They are counted in+ // frames, not ms, so a loaded machine that draws them late is judged the+ // same.+ steadyFrom = await page.evaluate(+ () =>+ new Promise<number>(resolve => {+ let left = 3;+ const tick = () => {+ left -= 1;+ if (left > 0) {+ requestAnimationFrame(tick);+ return;+ }+ // A task after this frame has rendered.+ setTimeout(() =>+ resolve(performance.timeOrigin + performance.now()),+ );+ };+ requestAnimationFrame(tick);+ }),+ );+ // A fixed wait: polling the content's style every frame would itself+ // recalculate style.+ await page.waitForTimeout(900);+ });+ // The steady part of the settle, until it is within a pixel of rest.+ const from = Math.max(settle.from + 50, steadyFrom);+ const to = settle.from + 600;+ const judged = `judged ${(from - settle.from).toFixed(0)}–600 ms into the settle`;+ // Too little left to judge fails rather than passes.+ expect(to - from, judged).toBeGreaterThan(200);+ const during = countBetween(trace, from, to);+ expect(during.Layout ?? 0, `${judged}: ${JSON.stringify(during)}`).toBe(0);+ expect(during.Paint ?? 0, `${judged}: ${JSON.stringify(during)}`).toBe(0);+ // Main-thread work during that part; the pull's trigger and the release's+ // render are not the settle's.+ const blocking = trace.longTasks.filter(+ task => task.start < to && task.start + task.durationMs > from,+ );+ expect(+ blocking,+ `${judged}; long tasks, ms into the settle: ${JSON.stringify(+ trace.longTasks.map(task => [+ +(task.start - settle.from).toFixed(1),+ +task.durationMs.toFixed(1),+ ]),+ )}`,+ ).toEqual([]);+});++test('a list shorter than the screen still pulls and refreshes', async ({+ page,+}) => {+ // The story's content is 1 px taller than its container, so the container+ // overflows.+ const {driver, content, start} = await openRefresh(+ page,+ 'lab-pull-to-refresh--short-list',+ {refreshMs: '6000'},+ );+ await driver.play(slowPull(start, 300, 200));+ await waitForContentRest(content);+ expect(await isBusy(content)).toBe(true);+ expect(await shownPull(content)).toBeCloseTo(HEIGHT, 0);+});++test('a list that fits its container leaves the scroll to the browser: no containment and no pull (spec:AST-025 FR14)', async ({+ page,+}) => {+ const {driver, content, start} = await openRefresh(+ page,+ 'lab-pull-to-refresh--short-list',+ {refreshMs: '6000'},+ );+ const scroller = page.locator('[data-refresh-scroller]').first();+ const containment = () =>+ scroller.evaluate(element => getComputedStyle(element).overscrollBehaviorY);+ // With the extra pixel, the container overflows and the pull holds its top.+ await expect.poll(containment).toBe('none');+ // Without it, the list fits.+ await content.evaluate(element => {+ element.style.minHeight = '0px';+ });+ await expect.poll(containment).toBe('auto');+ await driver.play(slowPull(start, 300, 200));+ await page.waitForTimeout(250);+ expect(await isBusy(content)).toBe(false);+ expect(await shownPull(content)).toBe(0);+});++test('a pull pushed back past its start hands the finger to native scrolling', async ({+ page,+ browserName,+}) => {+ test.skip(+ browserName !== 'chromium',+ 'native scrolling from injected touches is Chromium-only (WebKit: the iOS simulator rig)',+ );+ const {driver, content, start} = await openRefresh(page);+ const scrollTop = () =>+ page+ .locator('[data-refresh-scroller]')+ .first()+ .evaluate(el => el.scrollTop);+ // Down 50 px, then up 250 px, in one touch.+ const at = (progress: number) =>+ progress < 0.25+ ? {x: start.x, y: start.y + 50 * (progress / 0.25)}+ : {x: start.x, y: start.y + 50 - 250 * ((progress - 0.25) / 0.75)};+ await driver.play(path(at, {durationMs: 900, hz: 60, restMs: 150}));+ await waitForContentRest(content);+ expect(await shownPull(content)).toBeCloseTo(0, 1);+ expect(await isBusy(content)).toBe(false);+ expect(await scrollTop()).toBeGreaterThan(50);+});++test('a drag that began as a scroll pulls once the content reaches the top, in the same touch', async ({+ page,+ browserName,+}) => {+ test.skip(+ browserName !== 'chromium',+ 'native scrolling from injected touches is Chromium-only (WebKit: the iOS simulator rig)',+ );+ const {driver, content, start} = await openRefresh(page, undefined, {+ refreshMs: '6000',+ });+ const scroller = page.locator('[data-refresh-scroller]').first();+ const scrollTop = () => scroller.evaluate(el => el.scrollTop);+ await scroller.evaluate(el => {+ el.scrollTop = 80;+ });+ await expect.poll(scrollTop).toBe(80);+ // Down 450 px in one touch: the first 80 px scroll the content to its top+ // natively, and the rest pulls past the trigger.+ await driver.play(slowPull(start, 450, 200));+ await waitForContentRest(content);+ expect(await scrollTop()).toBe(0);+ expect(await isBusy(content)).toBe(true);+ expect(await shownPull(content)).toBeCloseTo(HEIGHT, 0);+});++test('a pull while refreshing stretches from the inset and settles back onto it', async ({+ page,+}) => {+ const {driver, content, start} = await openRefresh(page, undefined, {+ refreshMs: '6000',+ });+ await driver.play(slowPull(start, 300, 200));+ await waitForContentRest(content);+ expect(await shownPull(content)).toBeCloseTo(HEIGHT, 0);+ let deepest = 0;+ await playReading(+ page,+ driver,+ content,+ slowPull(start, 200, 200),+ async () => {+ deepest = await shownPull(content);+ },+ );+ // The second pull starts from the inset, not from the top.+ expect(deepest).toBeGreaterThan(HEIGHT + 60);+ await waitForContentRest(content);+ expect(await shownPull(content)).toBeCloseTo(HEIGHT, 0);+ expect(await isBusy(content)).toBe(true);+});++test('a finger catching the settle holds it where it is, then pulls on from there', async ({+ page,+}) => {+ const {driver, content, start} = await openRefresh(page);+ await driver.play(slowPull(start, 76, 150));+ // The settle back to the top is running: catch it 100 ms in.+ await waitForSettle(content);+ await page.waitForTimeout(100);+ // Where the settle stood as the finger landed. A listener reads it before+ // anything handles the touch. A reading taken earlier misses how far the+ // settle moved before the touch arrived.+ await content.evaluate(element => {+ window.addEventListener(+ 'touchstart',+ () => {+ const value = getComputedStyle(element).translate;+ element.dataset.caughtAt = String(+ value === 'none' || value === ''+ ? 0+ : parseFloat(value.split(/\s+/)[1] ?? '0'),+ );+ },+ {capture: true, once: true},+ );+ });+ const readings = await playReading(+ page,+ driver,+ content,+ drag(+ start,+ {x: start.x, y: start.y + 30},+ {durationMs: 300, hz: 60, restMs: 100},+ ),+ );+ const caught = Number(+ await content.evaluate(element => element.dataset.caughtAt),+ );+ expect(caught).toBeGreaterThan(5);+ // No jump at the catch: the first reading is where the settle stood, and+ // the pull goes on from there.+ expect(Math.abs(readings[0].shown - caught)).toBeLessThan(6);+ expect(readings.at(-1)?.shown ?? 0).toBeGreaterThan(caught);+ await waitForContentRest(content);+ expect(await shownPull(content)).toBeCloseTo(0, 1);+});++/** The primary pointer the page reports: coarse (a touch screen) or fine. */+async function primaryPointer(page: Page, kind: 'coarse' | 'fine') {+ await page.addInitScript(coarse => {+ const native = window.matchMedia.bind(window);+ window.matchMedia = (query: string) => {+ const pointer = /^\(\s*pointer\s*:\s*(coarse|fine|none)\s*\)$/.exec(+ query.trim(),+ );+ if (pointer == null) {+ return native(query);+ }+ // A static list: the primary pointer never changes in a test.+ const list = {+ matches: (pointer[1] === 'coarse') === coarse,+ media: query,+ onchange: null,+ addEventListener() {},+ removeEventListener() {},+ addListener() {},+ removeListener() {},+ dispatchEvent: () => false,+ };+ return list as unknown as MediaQueryList;+ };+ }, kind === 'coarse');+}++interface RecordedAnimation {+ part: 'content' | 'band' | 'other';+ properties: string[];+ /** How long the animated values change, ms (the held end excluded). */+ movingMs: number;+ /**+ * Whether anything but opacity passes through values in between (travel);+ * a value that lands at once (two keyframes at one offset) does not.+ */+ travels: boolean;+ /** Repeats forever (an indicator's own spin, outside the record). */+ endless: boolean;+ /** When it was created (`performance.now()`). */+ at: number;+}++/**+ * Records every animation the page creates from now on, and when the+ * refresh's busy state clears.+ */+async function recordAnimations(page: Page) {+ await page.evaluate(() => {+ const log: unknown[] = [];+ const record = window as unknown as {+ __animations: unknown[];+ __endedAt: number | null;+ };+ record.__animations = log;+ record.__endedAt = null;+ const content = document.querySelector('[data-refresh-content]');+ if (content != null) {+ new MutationObserver(() => {+ if (!content.hasAttribute('aria-busy') && record.__endedAt == null) {+ record.__endedAt = performance.now();+ }+ }).observe(content, {attributes: true, attributeFilter: ['aria-busy']});+ }+ const native = Element.prototype.animate;+ Element.prototype.animate = function (keyframes, options) {+ const animation = native.call(this, keyframes, options);+ const content = document.querySelector('[data-refresh-content]');+ const band = content?.querySelector(':scope > :last-child > div');+ const part =+ this === content ? 'content' : this === band ? 'band' : 'other';+ const effect = animation.effect as KeyframeEffect | null;+ const frames = effect?.getKeyframes() ?? [];+ const skip = new Set(['offset', 'computedOffset', 'easing', 'composite']);+ const properties = [+ ...new Set(+ frames.flatMap(f => Object.keys(f).filter(k => !skip.has(k))),+ ),+ ];+ const timing = effect?.getComputedTiming();+ const duration = Number(timing?.duration ?? 0);+ const last = frames.at(-1);+ let movingMs = 0;+ for (let i = frames.length - 1; i > 0; i--) {+ if (properties.some(p => frames[i - 1][p] !== last?.[p])) {+ movingMs = Number(frames[i].computedOffset) * duration;+ break;+ }+ }+ const travels = properties+ .filter(p => p !== 'opacity')+ .some(p =>+ frames.some((frame, i) => {+ const next = frames[i + 1];+ return (+ next != null &&+ frame[p] !== next[p] &&+ Number(next.computedOffset) > Number(frame.computedOffset) &&+ !/^step/.test(String(frame.easing ?? 'linear'))+ );+ }),+ );+ log.push({+ part,+ properties,+ movingMs,+ travels,+ endless: timing?.iterations === Infinity,+ at: performance.now(),+ });+ return animation;+ };+ });+}++const recordedAnimations = (page: Page) =>+ page.evaluate(+ () =>+ (window as unknown as {__animations: RecordedAnimation[]}).__animations,+ );++/** The animations created once the refresh's busy state cleared: the end's. */+const recordedEnd = (page: Page) =>+ page.evaluate(() => {+ const record = window as unknown as {+ __animations: RecordedAnimation[];+ __endedAt: number | null;+ };+ const endedAt = record.__endedAt ?? Infinity;+ return record.__animations.filter(a => a.at >= endedAt);+ });++/**+ * The record's failures among recorded transitions (spins excluded): travel,+ * or values still changing after 200 ms.+ */+function reducedMotionFailures(log: readonly RecordedAnimation[]) {+ return log.filter(+ a => a.part !== 'other' && !a.endless && (a.travels || a.movingMs > 200),+ );+}++test('under Reduce Motion a release cross-fades onto the inset: opacity only, within 200 ms', async ({+ page,+}) => {+ // Under Reduce Motion, a transition that a touch release starts only fades+ // its opacity, in 200 ms or less. Nothing moves.+ await page.emulateMedia({reducedMotion: 'reduce'});+ await primaryPointer(page, 'coarse');+ const {driver, content, start} = await openRefresh(page, undefined, {+ refreshMs: '6000',+ });+ await recordAnimations(page);+ await driver.play(slowPull(start, 300, 200));+ await waitForContentRest(content);+ expect(await shownPull(content)).toBeCloseTo(HEIGHT, 1);+ const log = await recordedAnimations(page);+ expect(reducedMotionFailures(log), JSON.stringify(log)).toEqual([]);+ // A change with no cross-fade fails too.+ expect(+ log.some(a => a.part === 'content' && a.properties.includes('opacity')),+ JSON.stringify(log),+ ).toBe(true);+});++test('under Reduce Motion the end cross-fades on a touch screen, and a `--motion-…` variable changes nothing', async ({+ page,+}) => {+ // The refresh control's values are internal constants. So no `--motion-…`+ // variable restores travel or a longer animation under Reduce Motion.+ await page.emulateMedia({reducedMotion: 'reduce'});+ await primaryPointer(page, 'coarse');+ const {driver, content, start} = await openRefresh(page, undefined, {+ refreshMs: '-1',+ });+ await page.evaluate(() => {+ const root = document.documentElement.style;+ root.setProperty('--motion-refresh-control-end-ms', '2000ms');+ root.setProperty('--motion-refresh-control-exit-ms', '2000ms');+ });+ await recordAnimations(page);+ await driver.play(slowPull(start, 300, 200));+ await waitForContentRest(content);+ await endRefresh(page);+ await expect.poll(() => isBusy(content), {timeout: 8000}).toBe(false);+ await page.waitForTimeout(100);+ await waitForContentRest(content);+ expect(await shownPull(content)).toBeCloseTo(0, 1);+ const log = await recordedEnd(page);+ expect(reducedMotionFailures(log), JSON.stringify(log)).toEqual([]);+ expect(+ log.some(a => a.part === 'content' && a.properties.includes('opacity')),+ JSON.stringify(log),+ ).toBe(true);+});++test('the end plays the neutral theme’s duration token nearest UIKit’s measured end (spec:AST-094 FR45)', async ({+ page,+}) => {+ const {content} = await openRefresh(page, undefined, {refreshMs: '-1'});+ const steps = ['fast', 'medium', 'slow'].flatMap(band => [+ `--duration-${band}-min`,+ `--duration-${band}`,+ `--duration-${band}-max`,+ ]);+ const tokens = await tokensAt(content, steps);+ // The Storybook theme is neutral: its fast, medium and slow bases.+ expect(+ ['--duration-fast', '--duration-medium', '--duration-slow'].map(name =>+ timeMs(tokens[name]),+ ),+ JSON.stringify(tokens),+ ).toEqual([125, 300, 700]);+ const nearest = steps.reduce((best, name) =>+ Math.abs(timeMs(tokens[name]) - UIKIT_END_MS) <+ Math.abs(timeMs(tokens[best]) - UIKIT_END_MS)+ ? name+ : best,+ );+ // The measurement stays in the motion table as the reference.+ expect(refreshControl.endMs).toBe(UIKIT_END_MS);+ expect(refreshControl.endDurationToken, JSON.stringify(tokens)).toBe(nearest);+});++test('a theme’s duration token retimes the end, and a `--motion-…` variable does not (spec:AST-094 FR45)', async ({+ page,+}) => {+ // The end reads the theme's duration token at its start. The refresh+ // control's own values are internal constants, so no variable retunes them.+ const {driver, content, start} = await openRefresh(page, undefined, {+ refreshMs: '-1',+ });+ await content.evaluate(element => {+ element.style.setProperty('--duration-medium', '600ms');+ document.documentElement.style.setProperty(+ '--motion-refresh-control-end-ms',+ '2000ms',+ );+ });+ await recordAnimations(page);+ await driver.play(slowPull(start, 300, 200));+ await waitForContentRest(content);+ await endRefresh(page);+ await expect.poll(() => isBusy(content), {timeout: 8000}).toBe(false);+ await page.waitForTimeout(100);+ await waitForContentRest(content);+ const log = await recordedEnd(page);+ const slide = log.find(+ a => a.part === 'content' && a.properties.includes('translate'),+ );+ expect(slide, JSON.stringify(log)).toBeDefined();+ expect(Math.abs((slide?.movingMs ?? 0) - 600)).toBeLessThan(20);+});++/** A desktop context: no touch screen, so CSS and script read a fine pointer. */+async function desktopPage(+ browser: Browser,+ options: {reducedMotion?: 'reduce'} = {},+) {+ const context = await browser.newContext({+ viewport: {width: 402, height: 714},+ hasTouch: false,+ isMobile: false,+ ...options,+ });+ const page = await context.newPage();+ await openStory(+ page,+ storybook(),+ 'lab-pull-to-refresh--in-a-scroll-container',+ {+ refreshMs: '6000',+ },+ );+ const pointer = await page.evaluate(() => ({+ coarse: matchMedia('(pointer: coarse)').matches,+ fine: matchMedia('(pointer: fine)').matches,+ }));+ expect(pointer).toEqual({coarse: false, fine: true});+ const content = page.locator('[data-refresh-content]').first();+ await expect(content).toBeVisible();+ return {context, page, content};+}++/** A mouse drag down from the top of the page, 15 px a step. */+async function mousePull(page: Page, content: Locator, steps: number) {+ await page.mouse.move(200, 160);+ await page.mouse.down();+ const shown: number[] = [];+ for (let step = 1; step <= steps; step++) {+ await page.mouse.move(200, 160 + step * 15);+ shown.push(await shownPull(content));+ }+ await page.mouse.up();+ return shown;+}++/** A pen stroke down from the top of the page: 300 px, 15 px every 16 ms. */+async function penPull(page: Page) {+ const driver = await webInputDriver(page);+ await driver.pen(+ Array.from({length: 21}, (_, step) => ({+ x: 200,+ y: 160 + step * 15,+ t: step * 16,+ })),+ );+}++/**+ * Resolves once the content's settle starts: the release of a pull that+ * ended without a lift (a trackpad's scroll ends when its gesture does).+ */+async function waitForSettleStart(content: Locator, timeout = 3000) {+ await content.evaluate(+ (element, ms) =>+ new Promise<void>((resolve, reject) => {+ const deadline = performance.now() + ms;+ const tick = () => {+ if (element.getAnimations().some(a => a.playState === 'running')) {+ resolve();+ return;+ }+ if (performance.now() > deadline) {+ reject(+ new Error('waitForSettleStart: the pull was never released'),+ );+ return;+ }+ requestAnimationFrame(tick);+ };+ tick();+ }),+ timeout,+ );+}++/** The list's scroll position once it has stopped moving (a smooth scroll ends). */+async function listScrollRest(page: Page, timeout = 3000): Promise<number> {+ return page.evaluate(+ ms =>+ new Promise<number>((resolve, reject) => {+ const deadline = performance.now() + ms;+ const scroller = document.querySelector('[data-refresh-scroller]');+ let last = Number.NaN;+ let still = 0;+ const tick = () => {+ const y = scroller?.scrollTop ?? Number.NaN;+ still = y === last ? still + 1 : 0;+ last = y;+ if (still >= 3) {+ resolve(y);+ return;+ }+ if (performance.now() > deadline) {+ reject(new Error(`listScrollRest: still scrolling (${y})`));+ return;+ }+ requestAnimationFrame(tick);+ };+ tick();+ }),+ timeout,+ );+}++/** Why the trackpad proofs run in WebKit only. */+const TRACKPAD_SKIP =+ "Chromium's driver sends each wheel step as a mouse wheel's notch; WebKit's sends a trackpad's precise deltas";+/** Why the mouse wheel proof runs in Chromium only. */+const MOUSE_WHEEL_SKIP =+ "WebKit's driver sends a trackpad's precise deltas; Chromium's sends each wheel step as a mouse wheel's notch";++/**+ * Wheel steps of `dy` CSS px over the content. Chromium's driver sends each+ * step as a mouse wheel's notch, and WebKit's as a trackpad's precise deltas.+ */+async function scrollWheel(page: Page, steps: number, dy: number) {+ const driver = await webInputDriver(page);+ for (let step = 0; step < steps; step++) {+ await driver.wheel({x: 200, y: 300, dy});+ }+}++test('with a trackpad, a two-finger scroll at the top pulls and refreshes as a finger does (spec:AST-094 FR43)', async ({+ browser,+ browserName,+}) => {+ test.skip(browserName === 'chromium', TRACKPAD_SKIP);+ const {context, page, content} = await desktopPage(browser);+ try {+ // 300 px of scroll toward the top: past the trigger.+ await scrollWheel(page, 30, -10);+ // The scroll's gesture ends after its last step. The pull's release+ // starts the settle, and the content comes to rest on the inset.+ await waitForSettleStart(content);+ await waitForContentRest(content);+ expect(await isBusy(content)).toBe(true);+ expect(await shownPull(content)).toBeCloseTo(HEIGHT, 0);+ } finally {+ await context.close();+ }+});++test('a scroll down the list and back up short of its top stays the list’s and pulls nothing (spec:AST-094 FR43)', async ({+ browser,+}) => {+ const {context, page, content} = await desktopPage(browser);+ try {+ // A scroll down from the top is the list's, not the pull's.+ await scrollWheel(page, 20, 10);+ const scrolled = await listScrollRest(page);+ expect(scrolled).toBeGreaterThan(100);+ // Back up, short of the top: still the list's.+ await scrollWheel(page, 5, -10);+ const back = await listScrollRest(page);+ expect(back).toBeLessThan(scrolled);+ expect(back).toBeGreaterThan(0);+ expect(await shownPull(content)).toBe(0);+ expect(await isBusy(content)).toBe(false);+ } finally {+ await context.close();+ }+});++test('a mouse wheel’s notches at the top never pull: they scroll what is under the pointer (spec:AST-094 FR43)', async ({+ browser,+ browserName,+}) => {+ test.skip(browserName !== 'chromium', MOUSE_WHEEL_SKIP);+ const {context, page, content} = await desktopPage(browser);+ try {+ await scrollWheel(page, 3, -100);+ await page.waitForTimeout(250);+ expect(await shownPull(content)).toBe(0);+ expect(await isBusy(content)).toBe(false);+ } finally {+ await context.close();+ }+});++test('with a mouse, a drag at the top stays the browser’s and never pulls', async ({+ browser,+}) => {+ const {context, page, content} = await desktopPage(browser);+ try {+ const shown = await mousePull(page, content, 20);+ expect(shown, JSON.stringify(shown)).toEqual(shown.map(() => 0));+ expect(await isBusy(content)).toBe(false);+ } finally {+ await context.close();+ }+});++test('with a pen, a drag at the top stays the browser’s and never pulls', async ({+ browser,+ browserName,+}) => {+ // A pen exists only in Chromium's input.+ test.skip(browserName !== 'chromium', PEN_SKIP);+ const {context, page, content} = await desktopPage(browser);+ try {+ await penPull(page);+ await page.waitForTimeout(250);+ expect(await shownPull(content)).toBe(0);+ expect(await isBusy(content)).toBe(false);+ } finally {+ await context.close();+ }+});++/** The top of the indicator band, in px below the scroll view's top. */+const indicatorTop = (content: Locator) =>+ content.evaluate(element => {+ const band = element.querySelector(':scope > :last-child > div');+ let scroller = element.parentElement;+ while (+ scroller != null &&+ !/auto|scroll/.test(getComputedStyle(scroller).overflowY)+ ) {+ scroller = scroller.parentElement;+ }+ const top = scroller?.getBoundingClientRect().top ?? 0;+ return (band?.getBoundingClientRect().top ?? NaN) - top;+ });++test('the indicator stays at the top of the scroll view while the content is pulled and settles, as UIRefreshControl’s does', async ({+ page,+}) => {+ const {driver, content, start} = await openRefresh(page, undefined, {+ refreshMs: '6000',+ });+ const readings: {shown: number; indicator: number}[] = [];+ await driver.play(slowPull(start, 300, 150), {+ onEvent: async step => {+ if (step.type !== 'touchMove') {+ return;+ }+ await frames(page, 1);+ readings.push({+ shown: await shownPull(content),+ indicator: await indicatorTop(content),+ });+ },+ });+ await waitForContentRest(content);+ const revealed = readings.filter(r => r.shown >= HEIGHT + 10);+ const shown = revealed.map(r => r.shown);+ const indicator = revealed.map(r => r.indicator);+ // The content travelled while the indicator held still.+ expect(Math.max(...shown) - Math.min(...shown)).toBeGreaterThan(40);+ expect(Math.max(...indicator) - Math.min(...indicator)).toBeLessThanOrEqual(+ 1,+ );+ // Settled onto the inset, it is where it was during the pull.+ expect(await shownPull(content)).toBeCloseTo(HEIGHT, 0);+ expect(+ Math.abs((await indicatorTop(content)) - indicator[0]),+ ).toBeLessThanOrEqual(1);+});++/**+ * Watches the content's animations every frame from `from`: the finger's lift+ * or the refresh's end. Right after it, the watcher blocks the main thread for+ * `blockMs`, as a busy app would, and records when the block ends. After the+ * lift, the block runs in its own task, and on a loaded machine the next frame+ * can come first. After the end, it runs in the commit that ends the busy+ * state. For each animation on the content, the watcher records when the main+ * thread first saw it, and when its curve starts on the document timeline.+ */+async function sampleAfter(+ content: Locator,+ from: 'lift' | 'end',+ blockMs: number,+): Promise<void> {+ await content.evaluate(+ (element, {from, blockMs}) => {+ let frames = 0;+ const tracked: {+ animation: Animation;+ seen: number;+ start: number | null;+ }[] = [];+ (window as unknown as {__tracked: typeof tracked}).__tracked = tracked;+ const track = () => {+ const now = performance.now();+ for (const animation of element.getAnimations()) {+ let entry = tracked.find(item => item.animation === animation);+ if (entry == null) {+ entry = {animation, seen: now, start: null};+ tracked.push(entry);+ }+ if (entry.start == null && animation.startTime != null) {+ entry.start = Number(animation.startTime);+ }+ }+ };+ const block = () => {+ const until = performance.now() + blockMs;+ while (performance.now() < until) {+ // A busy app.+ }+ (window as unknown as {__blockEnd: number}).__blockEnd =+ performance.now();+ };+ const watch = () => {+ track();+ frames += 1;+ if (frames < 90) {+ requestAnimationFrame(watch);+ }+ };+ const begin = () => {+ track();+ requestAnimationFrame(watch);+ };+ if (from === 'lift') {+ addEventListener(+ 'touchend',+ () => {+ begin();+ setTimeout(block, 0);+ },+ {once: true},+ );+ } else {+ const observer = new MutationObserver(() => {+ if (element.getAttribute('aria-busy') !== 'true') {+ observer.disconnect();+ begin();+ block();+ }+ });+ observer.observe(element, {+ attributes: true,+ attributeFilter: ['aria-busy'],+ });+ }+ },+ {from, blockMs},+ );+}++/**+ * The first animation the content ran after `sampleAfter`'s moment: when the+ * main thread first saw it, and when its curve starts on the document+ * timeline.+ */+async function firstAnimation(+ page: Page,+): Promise<{seen: number; start: number | null} | null> {+ return page.evaluate(() => {+ const [first] = (+ window as unknown as {+ __tracked: {seen: number; start: number | null}[];+ }+ ).__tracked;+ return first == null ? null : {seen: first.seen, start: first.start};+ });+}++test('the settle starts where its curve starts, even when the page is busy right after the lift', async ({+ page,+}) => {+ const {driver, content, start} = await openRefresh(page, undefined, {+ refreshMs: '6000',+ });+ await sampleAfter(content, 'lift', 250);+ await driver.play(slowPull(start, 300, 150));+ await page.waitForTimeout(1200);+ // The settle is made in the lift's own task. It starts at the next frame+ // that the main thread commits, before or after the busy task. Before it,+ // the compositor plays the settle through the block. Either way, its curve+ // starts at the frame it was made for, so its first frames show. A start+ // dated before a block that it waited on would skip them. The content's+ // place in the first frame after the block tells the cases apart only by+ // luck. That frame carries the time it was due, or the current time on a+ // loaded machine. So the proof reads the animation's own start.+ const settle = await firstAnimation(page);+ expect(settle).not.toBeNull();+ expect(settle?.start).not.toBeNull();+ expect(settle?.start ?? 0).toBeGreaterThanOrEqual(+ (settle?.seen ?? 0) - START_SLACK_MS,+ );+ expect(await shownPull(content)).toBeCloseTo(HEIGHT, 0);+});++test('the end slides from its start, even when the page is busy as the refresh ends', async ({+ page,+}) => {+ const {driver, content, start} = await openRefresh(page, undefined, {+ refreshMs: '-1',+ });+ await sampleAfter(content, 'end', 250);+ await driver.play(slowPull(start, 300, 150));+ await waitForContentRest(content);+ await endRefresh(page);+ await waitForSettle(content, {afterRefresh: true});+ await page.waitForTimeout(800);+ // The block runs in the commit that ends the refresh, and the slide is+ // made two frames later. A start dated before the block would skip the+ // slide's first frames. The content's place in the first frame after the+ // block tells this apart only by luck on a loaded machine. So the proof+ // reads the animation's own start, as the settle's proof does.+ const end = await firstAnimation(page);+ const blockEnd = await page.evaluate(+ () => (window as unknown as {__blockEnd: number}).__blockEnd,+ );+ // The end animation and the block's end are both present first, so a+ // missing one fails by name.+ expect(end, JSON.stringify({end, blockEnd})).not.toBeNull();+ expect(typeof end?.start).toBe('number');+ expect(typeof blockEnd).toBe('number');+ expect(end?.start ?? 0).toBeGreaterThanOrEqual(blockEnd - START_SLACK_MS);+});diff --git a/packages/lab/src/RefreshControl/index.ts b/packages/lab/src/RefreshControl/index.tsnew file mode 100644index 0000000000..f20c32be64--- /dev/null+++ b/packages/lab/src/RefreshControl/index.ts@@ -0,0 +1,18 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++'use client';++/**+ * @file index.ts+ * @input Imports from useRefreshControl+ * @output Exports useRefreshControl, its types and the reveal's custom+ * property+ * @position Entry point for Lab's pull to refresh; re-exported by+ * /packages/lab/src/index.ts+ */++export {REFRESH_REVEAL_VAR, useRefreshControl} from './useRefreshControl';+export type {+ UseRefreshControlOptions,+ UseRefreshControlResult,+} from './useRefreshControl';diff --git a/packages/lab/src/RefreshControl/refreshIndicator.ts b/packages/lab/src/RefreshControl/refreshIndicator.tsnew file mode 100644index 0000000000..9523c00970--- /dev/null+++ b/packages/lab/src/RefreshControl/refreshIndicator.ts@@ -0,0 +1,12 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/**+ * @file refreshIndicator.ts+ * @output The name of the custom property the touch layer writes and the+ * app's indicator styles may read+ * @position Internal to useRefreshControl; re-exported for the app's+ * indicator styles+ */++/** CSS custom property the indicator reads: how much of it is revealed (0–1). */+export const REFRESH_REVEAL_VAR = '--astryx-refresh-reveal';diff --git a/packages/lab/src/RefreshControl/refreshModel.test.ts b/packages/lab/src/RefreshControl/refreshModel.test.tsnew file mode 100644index 0000000000..0a718622e7--- /dev/null+++ b/packages/lab/src/RefreshControl/refreshModel.test.ts@@ -0,0 +1,174 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/**+ * @file refreshModel.test.ts+ * @input vitest, refreshModel+ * @output Walks UIRefreshControl's state machine: trigger once with the+ * finger down, settle targets, cancel, programmatic begin and end, a pull+ * while refreshing, and no-ops+ * @position Testing; colocated with refreshModel.ts+ */++import {describe, expect, it} from 'vitest';+import {+ INITIAL_REFRESH_STATE,+ reduceRefresh,+ type RefreshEffect,+ type RefreshEvent,+ type RefreshState,+} from './refreshModel';++function run(+ events: ReadonlyArray<RefreshEvent>,+ from: RefreshState = INITIAL_REFRESH_STATE,+): {state: RefreshState; effects: RefreshEffect[]} {+ let state = from;+ const effects: RefreshEffect[] = [];+ for (const event of events) {+ const next = reduceRefresh(state, event);+ state = next.state;+ effects.push(...next.effects);+ }+ return {state, effects};+}++describe('reduceRefresh', () => {+ it('triggers once, with the finger down, when the pull reaches the trigger distance', () => {+ const {state, effects} = run([+ {type: 'pullStart'},+ {type: 'pullMove', overscroll: 40, trigger: 74},+ {type: 'pullMove', overscroll: 73.33, trigger: 74},+ {type: 'pullMove', overscroll: 74, trigger: 74},+ {type: 'pullMove', overscroll: 95, trigger: 74},+ ]);+ expect(effects).toEqual([{type: 'trigger'}]);+ expect(state).toEqual({+ isRefreshing: true,+ isPulling: true,+ hasTriggered: true,+ });+ });++ it('settles onto the inset when released while refreshing', () => {+ const {state, effects} = run([+ {type: 'pullStart'},+ {type: 'pullMove', overscroll: 80, trigger: 74},+ {type: 'pullEnd'},+ ]);+ expect(effects).toEqual([{type: 'trigger'}, {type: 'settle', to: 'inset'}]);+ expect(state.isPulling).toBe(false);+ expect(state.isRefreshing).toBe(true);+ });++ it('settles back to the top when released below the trigger', () => {+ const {state, effects} = run([+ {type: 'pullStart'},+ {type: 'pullMove', overscroll: 50, trigger: 74},+ {type: 'pullEnd'},+ ]);+ expect(effects).toEqual([{type: 'settle', to: 'top'}]);+ expect(state.isRefreshing).toBe(false);+ });++ it('keeps refreshing when a pull that triggered is pushed back before the lift', () => {+ const {state, effects} = run([+ {type: 'pullStart'},+ {type: 'pullMove', overscroll: 90, trigger: 74},+ {type: 'pullMove', overscroll: 10, trigger: 74},+ {type: 'pullEnd'},+ ]);+ expect(effects).toEqual([{type: 'trigger'}, {type: 'settle', to: 'inset'}]);+ expect(state.isRefreshing).toBe(true);+ });++ it('settles a cancelled pull like a release', () => {+ expect(+ run([+ {type: 'pullStart'},+ {type: 'pullMove', overscroll: 30, trigger: 74},+ {type: 'pullCancel'},+ ]).effects,+ ).toEqual([{type: 'settle', to: 'top'}]);+ expect(+ run([+ {type: 'pullStart'},+ {type: 'pullMove', overscroll: 99, trigger: 74},+ {type: 'pullCancel'},+ ]).effects,+ ).toEqual([{type: 'trigger'}, {type: 'settle', to: 'inset'}]);+ });++ it('never triggers from movement that no finger is pulling (a momentum overshoot)', () => {+ expect(+ run([{type: 'pullMove', overscroll: 120, trigger: 74}]).effects,+ ).toEqual([]);+ });++ it('never triggers again on a pull while refreshing: one refresh runs at a time', () => {+ const refreshing = run([+ {type: 'pullStart'},+ {type: 'pullMove', overscroll: 80, trigger: 74},+ {type: 'pullEnd'},+ ]).state;+ // Far past the trigger, and past it beyond the inset too.+ const far = run(+ [+ {type: 'pullStart'},+ {type: 'pullMove', overscroll: 134, trigger: 74},+ {type: 'pullMove', overscroll: 200, trigger: 74},+ {type: 'pullEnd'},+ ],+ refreshing,+ );+ expect(far.effects).toEqual([{type: 'settle', to: 'inset'}]);+ expect(far.state.isRefreshing).toBe(true);+ });++ it('begins programmatically, calling the handler only for the user’s request', () => {+ expect(run([{type: 'begin', source: 'user'}]).effects).toEqual([+ {type: 'begin', callHandler: true},+ ]);+ expect(run([{type: 'begin', source: 'program'}]).effects).toEqual([+ {type: 'begin', callHandler: false},+ ]);+ // Already refreshing: nothing new starts.+ expect(+ run([+ {type: 'begin', source: 'program'},+ {type: 'begin', source: 'user'},+ ]).effects,+ ).toEqual([{type: 'begin', callHandler: false}]);+ });++ it('ends a running refresh once, and ignores an end with nothing running', () => {+ expect(run([{type: 'end'}]).effects).toEqual([]);+ const {state, effects} = run([+ {type: 'begin', source: 'program'},+ {type: 'end'},+ {type: 'end'},+ ]);+ expect(effects).toEqual([+ {type: 'begin', callHandler: false},+ {type: 'end'},+ ]);+ expect(state.isRefreshing).toBe(false);+ });++ it('ends a refresh under the finger without settling; the lift then settles to the top', () => {+ const {effects} = run([+ {type: 'pullStart'},+ {type: 'pullMove', overscroll: 80, trigger: 74},+ {type: 'end'},+ {type: 'pullEnd'},+ ]);+ expect(effects).toEqual([+ {type: 'trigger'},+ {type: 'end'},+ {type: 'settle', to: 'top'},+ ]);+ });++ it('ignores a release with no pull in progress', () => {+ expect(run([{type: 'pullEnd'}]).effects).toEqual([]);+ });+});diff --git a/packages/lab/src/RefreshControl/refreshModel.ts b/packages/lab/src/RefreshControl/refreshModel.tsnew file mode 100644index 0000000000..53aa74ac14--- /dev/null+++ b/packages/lab/src/RefreshControl/refreshModel.ts@@ -0,0 +1,117 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/**+ * @file refreshModel.ts+ * @input Pull events from the refresh pull recognizer, and programmatic begin+ * and end requests+ * @output Exports reduceRefresh (UIRefreshControl's state machine as a pure+ * reducer that returns the effects to run), the initial state and types+ * @position Pure logic for useRefreshControl; no DOM, no React+ *+ * SYNC: When modified, update:+ * - /packages/lab/src/RefreshControl/refreshModel.test.ts+ */++// The rules, as UIKit runs them:+// - A pull triggers once, with the finger down, when its overscroll reaches+// the trigger distance. Only overscroll that a finger drives triggers, never+// a momentum overshoot.+// - A release settles onto the refreshing inset while refreshing, and back to+// the top otherwise. A cancelled pull settles the same way.+// - A programmatic begin puts the control in the refreshing state. It calls+// the refresh handler only when it stands for the user's request, not when+// the app reports a refresh that it started.+// - Ending a refresh that is not running does nothing.+//+// One refresh runs at a time: a pull while refreshing only stretches.++export interface RefreshState {+ /** A refresh is in progress (`UIRefreshControl.isRefreshing`). */+ readonly isRefreshing: boolean;+ /** A finger is pulling the content. */+ readonly isPulling: boolean;+ /** The current pull has triggered (its mapping turns one to one). */+ readonly hasTriggered: boolean;+}++export type RefreshEvent =+ | {readonly type: 'pullStart'}+ | {+ readonly type: 'pullMove';+ readonly overscroll: number;+ /** The trigger distance for this scroll owner. */+ readonly trigger: number;+ }+ | {readonly type: 'pullEnd'}+ | {readonly type: 'pullCancel'}+ | {readonly type: 'begin'; readonly source: 'user' | 'program'}+ | {readonly type: 'end'};++export type RefreshEffect =+ /** The pull reached the trigger: spin, announce, call the handler. */+ | {readonly type: 'trigger'}+ /** A refresh started without a pull; `callHandler` for the user's request. */+ | {readonly type: 'begin'; readonly callHandler: boolean}+ /** The finger let go: settle onto the inset or back to the top. */+ | {readonly type: 'settle'; readonly to: 'inset' | 'top'}+ /** The refresh ended: remove the inset and hide the indicator. */+ | {readonly type: 'end'};++export const INITIAL_REFRESH_STATE: RefreshState = {+ isRefreshing: false,+ isPulling: false,+ hasTriggered: false,+};++export function reduceRefresh(+ state: RefreshState,+ event: RefreshEvent,+): {state: RefreshState; effects: ReadonlyArray<RefreshEffect>} {+ switch (event.type) {+ case 'pullStart':+ return {+ state: {...state, isPulling: true, hasTriggered: false},+ effects: [],+ };+ case 'pullMove': {+ // One refresh at a time: a pull while refreshing only stretches.+ if (+ !state.isPulling ||+ state.hasTriggered ||+ state.isRefreshing ||+ event.overscroll < event.trigger+ ) {+ return {state, effects: []};+ }+ return {+ state: {...state, isRefreshing: true, hasTriggered: true},+ effects: [{type: 'trigger'}],+ };+ }+ case 'pullEnd':+ case 'pullCancel':+ if (!state.isPulling) {+ return {state, effects: []};+ }+ return {+ state: {...state, isPulling: false},+ effects: [{type: 'settle', to: state.isRefreshing ? 'inset' : 'top'}],+ };+ case 'begin':+ if (state.isRefreshing) {+ return {state, effects: []};+ }+ return {+ state: {...state, isRefreshing: true},+ effects: [{type: 'begin', callHandler: event.source === 'user'}],+ };+ case 'end':+ if (!state.isRefreshing) {+ return {state, effects: []};+ }+ return {+ state: {...state, isRefreshing: false},+ effects: [{type: 'end'}],+ };+ }+}diff --git a/packages/lab/src/RefreshControl/refreshPull.test.ts b/packages/lab/src/RefreshControl/refreshPull.test.tsnew file mode 100644index 0000000000..d1a1d60b9a--- /dev/null+++ b/packages/lab/src/RefreshControl/refreshPull.test.ts@@ -0,0 +1,270 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/**+ * @file refreshPull.test.ts+ * @input vitest, refreshPull+ * @output Holds the pull mapping to UIKit's own frames, and the trigger+ * distance to UIKit's on four view heights. Checks the inverse, the reveal,+ * the release target, the end motion and the end's theme timing+ * @position Testing; colocated with refreshPull.ts+ */++import {describe, expect, it} from 'vitest';+import {+ endMotion,+ endTiming,+ modeAfterTrigger,+ pullOverscroll,+ pullSlope,+ pullTravel,+ REFRESH_HEIGHT,+ releaseTarget,+ revealFraction,+ revealProgress,+ triggerDistance,+} from './refreshPull';++/**+ * UIKit lab capture: a UIRefreshControl on a 334 pt tall scroll view, iOS 26.2+ * simulator, HID drags at about 150 pt/s. Each row is [finger travel since+ * touch-down, overscroll shown, whether the pull triggered], from the+ * setContentOffset log. The pan's 10 pt hysteresis is part of the travel here.+ */+const UIKIT_PULLS: Record<string, ReadonlyArray<[number, number, 0 | 1]>> = {+ pull120: [+ [12.67, 2.67, 0],+ [15, 5, 0],+ [20, 10, 0],+ [25, 15, 0],+ [27.67, 17.67, 0],+ [32.33, 22.33, 0],+ [35, 25, 0],+ [40, 30, 0],+ [45, 35, 0],+ [50, 40, 0],+ [52.67, 42.67, 0],+ [55, 45, 0],+ [60, 50, 0],+ [62.33, 52.33, 0],+ [67.67, 57.67, 0],+ [70, 60, 0],+ [75, 62.67, 0],+ [77.33, 64, 0],+ [82.67, 66.67, 0],+ [87.67, 69.33, 0],+ [92.33, 72, 0],+ [95, 73.33, 0],+ [100, 75.67, 0],+ [105, 95, 1],+ [110, 100, 1],+ [115, 105, 1],+ [117.67, 107.67, 1],+ [120, 110, 1],+ ],+ pull200: [+ [15, 5, 0],+ [20, 10, 0],+ [25, 15, 0],+ [30, 20, 0],+ [35, 25, 0],+ [37.67, 27.67, 0],+ [40, 30, 0],+ [42.67, 32.67, 0],+ [47.33, 37.33, 0],+ [52.67, 42.67, 0],+ [57.67, 47.67, 0],+ [62.33, 52.33, 0],+ [67.67, 57.67, 0],+ [72.67, 61.33, 0],+ [75, 62.67, 0],+ [80, 65.33, 0],+ [85, 68, 0],+ [90, 70.67, 0],+ [95, 73.33, 0],+ [97.67, 74.67, 0],+ [102.67, 92.67, 1],+ [107.33, 97.33, 1],+ [110, 100, 1],+ [112.67, 102.67, 1],+ [115, 105, 1],+ [120, 110, 1],+ [125, 115, 1],+ [127.67, 117.67, 1],+ ],+};+const UIKIT_VIEW_HEIGHT = 334;+const HYSTERESIS = 10;++describe('pullOverscroll', () => {+ it('reproduces UIKit’s pull frame by frame, before and after the trigger', () => {+ for (const [name, rows] of Object.entries(UIKIT_PULLS)) {+ for (const [travel, shown, triggered] of rows) {+ const model = pullOverscroll(+ travel - HYSTERESIS,+ UIKIT_VIEW_HEIGHT,+ triggered === 1 ? modeAfterTrigger(travel - HYSTERESIS) : 'reveal',+ );+ expect(+ Math.abs(model - shown),+ `${name} at ${travel} pt of travel: ${model} vs ${shown}`,+ ).toBeLessThanOrEqual(triggered === 1 ? 0.01 : 0.2);+ }+ }+ });++ it('tracks the finger one to one up to the control’s height', () => {+ expect(REFRESH_HEIGHT).toBe(60);+ for (const travel of [0.5, 10, 30, 59.9, 60]) {+ expect(pullOverscroll(travel, 800, 'reveal')).toBe(travel);+ }+ });++ it('rubber-bands the excess past the height, never reaching the view’s height', () => {+ const at = (travel: number) => pullOverscroll(travel, 800, 'reveal');+ expect(at(61)).toBeGreaterThan(60);+ expect(at(61) - 60).toBeLessThan(1);+ expect(at(2000)).toBeLessThan(60 + 800);+ expect(at(200)).toBeGreaterThan(at(150));+ });++ it('is one to one up to twice the height in the band', () => {+ expect(pullOverscroll(95, 800, 'band')).toBe(95);+ expect(pullOverscroll(120, 800, 'band')).toBe(120);+ expect(pullOverscroll(121, 800, 'band')).toBeLessThan(121);+ });++ it('steps onto the finger only for a trigger within the band', () => {+ expect(modeAfterTrigger(90)).toBe('band');+ expect(modeAfterTrigger(120)).toBe('band');+ // A tall view triggers past the band: the pull keeps its curve.+ expect(modeAfterTrigger(296)).toBe('reveal');+ });++ it('shows nothing for a pull that has not started or went the other way', () => {+ expect(pullOverscroll(0, 800, 'reveal')).toBe(0);+ expect(pullOverscroll(-25, 800, 'reveal')).toBe(0);+ expect(pullOverscroll(Number.NaN, 800, 'reveal')).toBe(0);+ });+});++describe('pullTravel', () => {+ it('inverts pullOverscroll in both modes', () => {+ for (const mode of ['reveal', 'band'] as const) {+ for (const travel of [0, 12, 60, 61, 90, 140, 400]) {+ const shown = pullOverscroll(travel, 874, mode);+ expect(pullTravel(shown, 874, mode)).toBeCloseTo(travel, 6);+ }+ }+ });+});++describe('trigger and reveal', () => {+ it('triggers at UIKit’s distance for each view height', () => {+ // Measured: 334 pt → 73.0–73.3; 400 → 79.0–79.3; 874 → 168.3–173.7;+ // 1366 → about 271.+ expect(triggerDistance(334)).toBeCloseTo(73, 0);+ expect(triggerDistance(400)).toBeGreaterThanOrEqual(79);+ expect(triggerDistance(400)).toBeLessThanOrEqual(79.3);+ expect(triggerDistance(874)).toBeGreaterThanOrEqual(168.3);+ expect(triggerDistance(874)).toBeLessThanOrEqual(173.7);+ expect(Math.abs(triggerDistance(1366) - 271)).toBeLessThan(2);+ // Never below the floor, even for a view with no height yet.+ expect(triggerDistance(0)).toBe(73);+ });++ it('triggers on UIKit’s frames, at most one frame ahead of UIKit’s own report', () => {+ // UIKit reports valueChanged on the frame after the crossing.+ const trigger = triggerDistance(UIKIT_VIEW_HEIGHT);+ for (const rows of Object.values(UIKIT_PULLS)) {+ const reported = rows.findIndex(row => row[2] === 1);+ const shown = (travel: number) =>+ pullOverscroll(travel - HYSTERESIS, UIKIT_VIEW_HEIGHT, 'reveal');+ expect(shown(rows[reported - 1][0])).toBeGreaterThanOrEqual(trigger);+ expect(shown(rows[reported - 3][0])).toBeLessThan(trigger);+ }+ });++ it('reveals in proportion to the pull, fully at the trigger', () => {+ expect(revealFraction(0, 874)).toBe(0);+ expect(revealFraction(triggerDistance(874) / 2, 874)).toBeCloseTo(0.5, 6);+ expect(revealFraction(triggerDistance(874), 874)).toBe(1);+ expect(revealFraction(500, 874)).toBe(1);+ expect(revealFraction(-5, 874)).toBe(0);+ });++ it('eases the reveal on UIKit’s reveal curve (0.42, 0, 0.58, 1)', () => {+ const trigger = triggerDistance(334);+ expect(revealProgress(0, 334)).toBe(0);+ expect(revealProgress(trigger, 334)).toBeCloseTo(1, 6);+ // The ease-in-out curve is symmetric: halfway through is halfway.+ expect(revealProgress(trigger / 2, 334)).toBeCloseTo(0.5, 3);+ expect(revealProgress(trigger / 4, 334)).toBeLessThan(0.25);+ });+});++describe('release and end', () => {+ it('releases onto the inset while refreshing and back to the top otherwise', () => {+ expect(releaseTarget(true)).toBe(60);+ expect(releaseTarget(false)).toBe(0);+ });++ it('slides the content up to close a visible gap, then drops inset and offset together', () => {+ expect(endMotion(0)).toEqual({animateTo: 0, scrollBy: -0});+ expect(endMotion(25)).toEqual({animateTo: 25, scrollBy: -25});+ });++ it('moves nothing when the control has scrolled out of view', () => {+ expect(endMotion(60)).toEqual({animateTo: null, scrollBy: -60});+ expect(endMotion(500)).toEqual({animateTo: null, scrollBy: -60});+ });+});++describe('the end’s timing from the theme’s tokens', () => {+ it('plays the theme’s duration and move easing tokens as the element computes them (spec:AST-094 FR45)', () => {+ const style = (values: Record<string, string>) => ({+ getPropertyValue: (name: string) => values[name] ?? '',+ });+ expect(+ endTiming(+ style({+ '--duration-medium': '300ms',+ '--ease-move': 'cubic-bezier(0.24, 1, 0.4, 1)',+ }),+ ),+ ).toEqual({ms: 300, points: [0.24, 1, 0.4, 1]});+ // A theme's tempo reaches the end through the token's value.+ expect(+ endTiming(style({'--duration-medium': '450ms', '--ease-move': 'ease'}))+ ?.ms,+ ).toBe(450);+ // No tokens, or tokens in a form it cannot read: no slide.+ expect(+ endTiming(+ style({'--duration-medium': 'calc(300ms * 1)', '--ease-move': 'ease'}),+ ),+ ).toBeNull();+ expect(endTiming(style({}))).toBeNull();+ });+});++describe('pullSlope', () => {+ it('is 1 where the pull tracks the finger, and the rubber band slope past it', () => {+ expect(pullSlope(0, 334, 'reveal')).toBe(0);+ expect(pullSlope(30, 334, 'reveal')).toBeCloseTo(1, 6);+ const past = 100;+ const slope = pullSlope(past, 334, 'reveal');+ expect(slope).toBeGreaterThan(0);+ expect(slope).toBeLessThan(1);+ // The slope of the mapping itself, and it falls as the band stretches.+ const step = 0.5;+ expect(slope).toBeCloseTo(+ (pullOverscroll(past + step, 334, 'reveal') -+ pullOverscroll(past - step, 334, 'reveal')) /+ (2 * step),+ 3,+ );+ expect(pullSlope(past + 100, 334, 'reveal')).toBeLessThan(slope);+ // The band after a trigger tracks one to one for twice as long.+ expect(pullSlope(100, 334, 'band')).toBeCloseTo(1, 6);+ });+});diff --git a/packages/lab/src/RefreshControl/refreshPull.ts b/packages/lab/src/RefreshControl/refreshPull.tsnew file mode 100644index 0000000000..c8d935ffa6--- /dev/null+++ b/packages/lab/src/RefreshControl/refreshPull.ts@@ -0,0 +1,186 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/**+ * @file refreshPull.ts+ * @input The pull values (refreshValues.ts), and the rubber band, the cubic+ * Bézier and the motion-role parsers (Core's internal touch entry)+ * @output Exports the pull mapping (finger travel → overscroll), its slope+ * and its inverse, and the trigger distance. It also exports the reveal, a+ * refresh's release and end targets, and the end's timing from the theme's+ * tokens.+ * @position Pure math for useRefreshControl; no DOM, no React+ *+ * SYNC: When modified, update:+ * - /packages/lab/src/RefreshControl/refreshPull.test.ts+ */++// UIKit's refresh pull, as measured: the first `height` of overscroll tracks+// the finger one to one, after the pan's hysteresis. Past it, the scroll+// view's rubber band applies to the excess. The trigger distance grows with+// the scroll view's height. After a trigger within twice the height, the+// overscroll steps back onto the finger. It stays one to one up to twice the+// height, with resistance past that.++import {cubicBezier} from '@astryxdesign/core/internal/touch';+import {+ rubberBand,+ rubberBandInverse,+ rubberBandSlope,+} from '@astryxdesign/core/internal/touch';+import {+ parseCssEasing,+ parseMotionRoleValue,+} from '@astryxdesign/core/internal/touch';+import {refreshControl} from './refreshValues';++/** The refreshing inset and one-to-one stretch, pt. */+export const REFRESH_HEIGHT: number = refreshControl.height;++/**+ * Which mapping a pull follows.+ * - `reveal`: before the trigger. One to one up to `height`, then the rubber+ * band on the excess.+ * - `band`: after a trigger within twice the height, and for a pull from the+ * refreshing inset. One to one up to twice the height, then the rubber band.+ */+export type PullMode = 'reveal' | 'band';++function linearStretch(mode: PullMode): number {+ return mode === 'band'+ ? refreshControl.height * refreshControl.postTriggerLinearHeights+ : refreshControl.height;+}++/**+ * Overscroll shown for `travel` px of pull (the pan's translation, which+ * already leaves out its hysteresis). `dimension` is the scroll owner's+ * height, the rubber band's dimension.+ */+export function pullOverscroll(+ travel: number,+ dimension: number,+ mode: PullMode,+): number {+ if (!(travel > 0)) {+ return 0;+ }+ const linear = linearStretch(mode);+ if (travel <= linear) {+ return travel;+ }+ return linear + rubberBand(travel - linear, dimension);+}++/**+ * How fast the overscroll moves per px of finger travel at `travel`: 1 where+ * it tracks the finger, the rubber band's slope past it. A release's speed+ * times this slope is the content's speed, which its settle starts at.+ */+export function pullSlope(+ travel: number,+ dimension: number,+ mode: PullMode,+): number {+ if (!(travel > 0)) {+ return 0;+ }+ const linear = linearStretch(mode);+ return travel <= linear ? 1 : rubberBandSlope(travel - linear, dimension);+}++/**+ * The travel that shows `overscroll`: where a finger landing on content+ * already pulled (a re-grab mid-settle) resumes without a jump.+ */+export function pullTravel(+ overscroll: number,+ dimension: number,+ mode: PullMode,+): number {+ if (!(overscroll > 0)) {+ return 0;+ }+ const linear = linearStretch(mode);+ if (overscroll <= linear) {+ return overscroll;+ }+ return linear + rubberBandInverse(overscroll - linear, dimension);+}++/**+ * The mapping after a trigger at `travel`. It is the one-to-one band when the+ * trigger falls within it, and the next frame steps onto the finger. Otherwise+ * it is the reveal mapping, as when a tall scroll view triggers past the band.+ */+export function modeAfterTrigger(travel: number): PullMode {+ return travel <= linearStretch('band') ? 'band' : 'reveal';+}++/**+ * The overscroll at which a pull triggers, for a scroll owner `dimension`+ * tall: a fraction of its height, never below the minimum.+ */+export function triggerDistance(dimension: number): number {+ return Math.max(+ refreshControl.triggerMinimum,+ refreshControl.triggerHeightFraction * Math.max(0, dimension),+ );+}++/** How much of the indicator a pull reveals, 0 to 1 (linear in the pull). */+export function revealFraction(overscroll: number, dimension: number): number {+ return Math.min(1, Math.max(0, overscroll / triggerDistance(dimension)));+}++const revealEasing = cubicBezier(refreshControl.revealCurve);++/** The reveal fraction on UIKit's reveal curve: the indicator's opacity. */+export function revealProgress(overscroll: number, dimension: number): number {+ return revealEasing(revealFraction(overscroll, dimension));+}++/**+ * Where the content comes to rest when the finger lifts: on the refreshing+ * inset while refreshing, back at the top otherwise.+ */+export function releaseTarget(isRefreshing: boolean): number {+ return isRefreshing ? refreshControl.height : 0;+}++/**+ * How the end of a refresh moves the content. `scrolled` (≥ 0) is how far the+ * scroll owner is scrolled with the inset still in place. While the gap+ * shows, the content slides up until the gap closes: the inset animates from+ * `height` to `scrolled`. Then the inset and the scroll offset drop together+ * with no visible change. Scrolled past the gap, nothing moves, and the inset+ * and the offset drop at once.+ */+export function endMotion(scrolled: number): {+ animateTo: number | null;+ scrollBy: number;+} {+ const height = refreshControl.height;+ const offset = Math.max(0, scrolled);+ if (offset >= height) {+ return {animateTo: null, scrollBy: -height};+ }+ return {animateTo: offset, scrollBy: -offset};+}++/**+ * The end's duration and curve: the theme tokens that `refreshControl` names,+ * as the end's element computes them. Null when either token is missing or+ * in a form it cannot read, such as `calc()`, `var()` or `steps()`.+ */+export function endTiming(+ style: Pick<CSSStyleDeclaration, 'getPropertyValue'>,+): {ms: number; points: readonly [number, number, number, number]} | null {+ const ms = parseMotionRoleValue(+ 'duration',+ style.getPropertyValue(refreshControl.endDurationToken),+ );+ const points = parseCssEasing(+ style.getPropertyValue(refreshControl.endEasingToken),+ );+ return ms == null || points == null ? null : {ms, points};+}diff --git a/packages/lab/src/RefreshControl/refreshTouchController.ts b/packages/lab/src/RefreshControl/refreshTouchController.tsnew file mode 100644index 0000000000..9fd8d2cd70--- /dev/null+++ b/packages/lab/src/RefreshControl/refreshTouchController.ts@@ -0,0 +1,838 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++'use client';++/**+ * @file refreshTouchController.ts+ * @input The refresh's state and dispatch (refreshModel.ts), the pull's+ * mapping (refreshPull.ts), and Core's internal touch entry+ * @output useRefreshTouchController: the refresh's touch layer (the pull, the+ * inset, the indicator's place and every motion) and its refs+ * @position Internal to useRefreshControl; useRefreshControl.ts is its one+ * import site, so a page loads this code only with the hook.+ *+ * SYNC: When modified, update:+ * - /packages/lab/src/RefreshControl/useRefreshControl.ts+ * - /packages/lab/src/RefreshControl/useRefreshControl.test.tsx+ */++// A pull at the top translates the content by the overscroll that UIKit shows+// for that travel: one write per move, and no React render. The pull applies+// in the nearest element that scrolls and overflows, never on the page+// itself. While that element overflows, it gets `overscroll-behavior-y: none`+// near its top, so the browser draws no rubber band where the pull draws+// instead. A scroll container that fits passes scrolls on to its ancestors,+// so it gets nothing. Scrolling stays native.+//+// The pull triggers with the finger down, and the refresh starts. A release+// settles onto the refreshing inset, or back to the top, on the scroll view's+// bounce. The end slides the content up by the inset. When the content is out+// of view, the end drops the inset and the matching offset in one task. A+// programmatic begin adds the inset with no motion.+//+// The indicator is the app's. The touch layer pins it at the top of the+// scroll view and writes how much of it the pull reveals. It fades it as a+// settle takes the content back.+//+// The settle hands the table's spring to the animator. The end plays the+// theme's duration and move easing tokens, read at its start, so the theme's+// tempo scales it. Finger tracking runs on the main thread, because the+// browser has no refresh pull to ride. Every release, settle and end runs on+// the compositor.++import {+ useCallback,+ useEffect,+ useMemo,+ useRef,+ useState,+ type RefCallback,+} from 'react';+import type {PointerKind} from '@astryxdesign/core/internal/touch';+import {useGestureRecognizer} from '@astryxdesign/core/internal/touch';+import type {MotionCurve} from '@astryxdesign/core/internal/touch';+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 {+ RefreshPullRecognizer,+ RefreshScrollPullRecognizer,+} from './RefreshPullRecognizer';+import {REFRESH_REVEAL_VAR} from './refreshIndicator';+import type {RefreshEvent, RefreshState} from './refreshModel';+import {+ endMotion,+ endTiming,+ modeAfterTrigger,+ pullOverscroll,+ pullSlope,+ pullTravel,+ REFRESH_HEIGHT,+ releaseTarget,+ revealProgress,+ triggerDistance,+ type PullMode,+} from './refreshPull';++export interface RefreshTouchControllerOptions {+ /** Whether the pull applies. */+ readonly isPullEnabled: boolean;+ /** The state machine's state, shared with the wiring. */+ readonly model: {readonly current: RefreshState};+ /** The wiring's dispatch: the pull's events go to the state machine. */+ readonly dispatchRef: {readonly current: (event: RefreshEvent) => void};+}++export interface RefreshTouchController {+ readonly contentRef: RefCallback<HTMLElement>;+ readonly indicatorRef: RefCallback<HTMLElement>;+ /** A pull triggered: the indicator shows in full; the release settles onto the inset. */+ trigger(): void;+ /** A refresh began without a pull: the inset arrives with no visible motion. */+ begin(): void;+ /** The release settles onto the inset or back to the top. */+ settle(to: 'inset' | 'top'): void;+ /** The refresh ended. */+ end(): void;+}++/** The ancestors of `start` that scroll on y, nearest first, below the page. */+function scrollContainersOf(start: HTMLElement): HTMLElement[] {+ const doc = start.ownerDocument;+ const containers: HTMLElement[] = [];+ for (+ let node = start.parentElement;+ node != null && node !== doc.body && node !== doc.documentElement;+ node = node.parentElement+ ) {+ const overflowY = getComputedStyle(node).overflowY;+ if (+ overflowY === 'auto' ||+ overflowY === 'scroll' ||+ overflowY === 'overlay'+ ) {+ containers.push(node);+ }+ }+ return containers;+}++function overflows(element: HTMLElement): boolean {+ return element.scrollHeight > element.clientHeight;+}++/**+ * The element whose scroll moves the content: the nearest scroll container+ * that overflows. A container that fits passes scrolls on to its ancestors,+ * so it is not the owner. Null when none overflows: the page itself is never+ * the pull's.+ */+function findScrollOwner(start: HTMLElement): HTMLElement | null {+ return scrollContainersOf(start).find(overflows) ?? null;+}++function scrollTopOf(owner: HTMLElement | null): number {+ return owner?.scrollTop ?? 0;+}++function heightOf(owner: HTMLElement): number {+ return owner.clientHeight;+}++function scrollOwnerBy(owner: HTMLElement | null, delta: number): void {+ if (owner != null && delta !== 0) {+ owner.scrollTop += delta;+ }+}++/** A curve from `from` to `to` over `ms` on a cubic bézier. */+function bezierCurve(+ from: number,+ to: number,+ ms: number,+ points: readonly [number, number, number, number],+): MotionCurve {+ const ease = cubicBezier(points);+ const duration = ms / 1000;+ const at = (t: number) =>+ from + (to - from) * ease(Math.min(1, Math.max(0, t / duration)));+ return {duration, at, velocity: derivative(at, duration)};+}++function derivative(+ at: (t: number) => number,+ duration: number,+): (t: number) => number {+ const step = 1 / 1000;+ return t => {+ const a = Math.max(0, t - step);+ const b = Math.min(duration, t + step);+ return b > a ? (at(b) - at(a)) / (b - a) : 0;+ };+}++/**+ * The refresh's touch layer. The wiring owns the state and the+ * announcements; this owns everything a finger drives.+ */+export function useRefreshTouchController({+ isPullEnabled,+ model,+ dispatchRef,+}: RefreshTouchControllerOptions): RefreshTouchController {+ const dispatch = useCallback(+ (event: RefreshEvent) => dispatchRef.current(event),+ [dispatchRef],+ );+ const content = useMotionAnimator();+ const indicator = useMotionAnimator();+ const contentElement = useRef<HTMLElement | null>(null);+ const indicatorElement = useRef<HTMLElement | null>(null);+ // Whether the content holds the refreshing inset.+ const hasInset = useRef(false);+ // An end waiting for the frame after its render, and that frame.+ const pendingEnd = useRef<(() => void) | null>(null);+ const endFrame = useRef<number | null>(null);+ // Counts ends: each one renders, and the slide starts after that commit.+ const [endTick, setEndTick] = useState(0);+ const cancelPendingEnd = useCallback(() => {+ pendingEnd.current = null;+ if (endFrame.current != null) {+ cancelAnimationFrame(endFrame.current);+ endFrame.current = null;+ }+ }, []);++ const owner = useRef<HTMLElement | null>(null);+ const pull = useRef<{+ travel0: number;+ scrollTop0: number;+ dimension: number;+ floor: number;+ trigger: number;+ mode: PullMode;+ }>({+ travel0: 0,+ scrollTop0: 0,+ dimension: 1,+ floor: 0,+ trigger: triggerDistance(1),+ mode: 'reveal',+ });+ // How fast the overscroll follows the finger at its last move.+ const fingerSlope = useRef(0);+ // The content's speed as the finger lifts, px/s, for the settle it starts.+ const releaseVelocity = useRef(0);++ // -- Indicator ------------------------------------------------------------++ const setReveal = useCallback((value: number) => {+ indicatorElement.current?.style.setProperty(+ REFRESH_REVEAL_VAR,+ String(value),+ );+ }, []);++ /**+ * The pointer of the latest pull. Under Reduce Motion, a finger's release+ * cross-fades, as the animator does for any release under a coarse primary+ * pointer. A trackpad's release lands at once.+ */+ const pullPointer = useRef<PointerKind>('touch');++ /**+ * Places the content at `y` and pins the indicator at the top of the scroll+ * view. The indicator rides on the content's edge, so it moves by the inset+ * minus `y`.+ */+ const place = useCallback(+ (y: number) => {+ content.animator.set({y});+ indicator.animator.set({y: REFRESH_HEIGHT - y});+ },+ [content.animator, indicator.animator],+ );+ const stopPlacing = useCallback(() => {+ content.animator.stop(['y']);+ indicator.animator.stop(['y']);+ }, [content.animator, indicator.animator]);++ /**+ * Puts the indicator back to opaque, and writes only if it changed. Each+ * animator write promotes its layer for a while. A release of that layer+ * during a settle costs a layout and a paint.+ */+ const restoreIndicator = useCallback(() => {+ if (indicator.animator.get('opacity') !== 1) {+ indicator.animator.set({opacity: 1});+ }+ }, [indicator.animator]);++ const resetIndicator = useCallback(() => {+ setReveal(0);+ restoreIndicator();+ }, [restoreIndicator, setReveal]);++ /**+ * Ends the indicator's fade and keeps what it shows. A finger that catches+ * the settle back to the top pulls on, or resumes the settle, from the+ * screen.+ */+ const keepShownIndicator = useCallback(() => {+ const opacity = indicator.animator.get('opacity');+ if (opacity === 1) {+ return;+ }+ const shown = Number(+ indicatorElement.current?.style.getPropertyValue(REFRESH_REVEAL_VAR) || 0,+ );+ setReveal(shown * opacity);+ restoreIndicator();+ }, [indicator.animator, restoreIndicator, setReveal]);++ /** The indicator in full: a trigger, or a refresh begun without a pull. */+ const showIndicator = useCallback(() => {+ setReveal(1);+ restoreIndicator();+ }, [restoreIndicator, setReveal]);++ // -- Scroll owner and its top-edge policy ----------------------------------++ const edge = useRef<{element: HTMLElement | null; saved: string | null}>({+ element: null,+ saved: null,+ });++ const releaseEdge = useCallback(() => {+ const state = edge.current;+ if (state.element != null && state.saved != null) {+ state.element.style.overscrollBehaviorY = state.saved;+ }+ edge.current = {element: null, saved: null};+ }, []);++ const isPullEnabledRef = useRef(isPullEnabled);+ isPullEnabledRef.current = isPullEnabled;++ /**+ * Near the top, the browser draws no overscroll: the pull does. Only an+ * element that scrolls and overflows: a container that fits, and the+ * page's own top edge, stay the browser's.+ */+ const applyEdge = useCallback(() => {+ const current = owner.current;+ const near =+ isPullEnabledRef.current &&+ current != null &&+ overflows(current) &&+ scrollTopOf(current) < Math.max(heightOf(current), REFRESH_HEIGHT);+ const state = edge.current;+ if (!near || state.element !== current) {+ releaseEdge();+ }+ if (!near || current == null) {+ return;+ }+ if (current.style.overscrollBehaviorY !== 'none') {+ // First claim, or the owner's own render replaced the value.+ edge.current = {+ element: current,+ saved: current.style.overscrollBehaviorY,+ };+ current.style.overscrollBehaviorY = 'none';+ }+ }, [releaseEdge]);++ // The owner's own scroll moves its top edge, so the pull listens there and+ // nowhere else, and only while a finger can pull. The listener moves with+ // the owner.+ const ownerScroll = useRef<{+ isActive: boolean;+ element: HTMLElement | null;+ }>({isActive: false, element: null});+ const onOwnerScroll = useCallback(() => applyEdge(), [applyEdge]);+ const listenToOwner = useCallback(() => {+ const state = ownerScroll.current;+ const next = state.isActive ? owner.current : null;+ if (next !== state.element) {+ state.element?.removeEventListener('scroll', onOwnerScroll);+ next?.addEventListener('scroll', onOwnerScroll, {passive: true});+ state.element = next;+ }+ }, [onOwnerScroll]);++ const resolveOwner = useCallback((): HTMLElement | null => {+ const element = contentElement.current;+ if (element == null) {+ return owner.current;+ }+ const next = findScrollOwner(element);+ if (next !== owner.current) {+ releaseEdge();+ owner.current = next;+ listenToOwner();+ }+ return next;+ }, [listenToOwner, releaseEdge]);++ // Content that mounts after the hook has no owner, listener or resize+ // observation yet, so attaching it runs the edge setup again.+ const setUpEdge = useRef<(() => void) | null>(null);++ useEffect(() => {+ // The pull watches the owner and its top edge only while a finger can+ // pull. Otherwise it holds no listener, and a contact re-resolves the+ // owner. The edge is claimed before a touch lands. The gesture host's+ // listeners are passive, so a claim at touch-down can come after the+ // browser's own overscroll starts.+ if (!isPullEnabled) {+ releaseEdge();+ return undefined;+ }+ ownerScroll.current.isActive = true;+ const update = () => {+ if (contentElement.current == null) {+ // Detached content leaves no owner to claim or listen to.+ releaseEdge();+ owner.current = null;+ } else {+ resolveOwner();+ applyEdge();+ }+ listenToOwner();+ };+ // A container starts or stops overflowing as the content or the+ // container resizes, with no scroll event. So the owner is read again on+ // each resize of the content and of its scroll containers.+ let unobserve: (() => void)[] = [];+ const observe = () => {+ for (const stop of unobserve) {+ stop();+ }+ const element = contentElement.current;+ unobserve =+ element == null+ ? []+ : [element, ...scrollContainersOf(element)].map(node =>+ observeResize(node, update),+ );+ };+ const setUp = () => {+ update();+ observe();+ };+ setUpEdge.current = setUp;+ setUp();+ // A scroll container can scroll only after its own effects run, which is+ // after this effect. ScrollableArea clips its viewport until it measures+ // it. So the owner is read again once those effects render.+ let frame = requestAnimationFrame(() => {+ frame = requestAnimationFrame(setUp);+ });+ return () => {+ setUpEdge.current = null;+ cancelAnimationFrame(frame);+ for (const stop of unobserve) {+ stop();+ }+ ownerScroll.current.isActive = false;+ listenToOwner();+ releaseEdge();+ };+ }, [applyEdge, isPullEnabled, listenToOwner, releaseEdge, resolveOwner]);++ // -- Motion of the state machine's effects ----------------------------------++ const startSettle = useCallback(+ (to: 'inset' | 'top') => {+ const target = releaseTarget(to === 'inset');+ const from = content.animator.get('y');+ // The settle starts at the content's speed as the finger lifts. A+ // caught settle that resumes starts from rest.+ const velocity = releaseVelocity.current;+ releaseVelocity.current = 0;+ // No start time: the animator starts the settle when the compositor+ // does, so its first frame is the curve's start. A finger's release+ // starts it as a touch release. So under Reduce Motion the animator+ // cross-fades it instead of moving it, as it does for any release under+ // a coarse primary pointer. A trackpad's release lands at once.+ const touchRelease = pullPointer.current === 'touch';+ const contentSettle = content.animator.animate(+ {y: target},+ {spring: scroll.bounce, velocity: {y: velocity}},+ {touchRelease},+ );+ indicator.animator.animate(+ {y: REFRESH_HEIGHT - target},+ {spring: scroll.bounce, velocity: {y: -velocity}},+ {touchRelease},+ );+ if (to === 'top' && !model.current.isRefreshing && from > 0) {+ // The indicator fades as the content covers it, along the content's+ // own settle curve. Started in the same task, the two start on the+ // same compositor frame. Under Reduce Motion the settle has no curve,+ // and the indicator resets once the settle ends.+ const curve = contentSettle.curve('y');+ const {dimension} = pull.current;+ const start = revealProgress(from, dimension) || 1;+ const finished =+ curve == null+ ? contentSettle.finished+ : indicator.animator.play(+ {+ opacity: mapProgress(+ curve,+ y => revealProgress(y, dimension) / start,+ ),+ },+ {touchRelease},+ ).finished;+ finished.then(done => {+ if (done && !model.current.isRefreshing) {+ resetIndicator();+ }+ });+ }+ },+ [content.animator, indicator.animator, resetIndicator],+ );++ const settle = useCallback(+ (to: 'inset' | 'top') => {+ if (to === 'inset') {+ hasInset.current = true;+ }+ // Started in the lift's own task. The frame right after a long task+ // carries the time it was due. An animation started there would begin+ // in the past.+ startSettle(to);+ },+ [startSettle],+ );++ const end = useCallback(() => {+ const hadInset = hasInset.current;+ hasInset.current = false;+ if (model.current.isPulling) {+ // Under the finger: the release settles back to the top, and the+ // indicator retracts with it.+ pull.current.floor = 0;+ return;+ }+ if (!hadInset) {+ // A refresh that never showed (begun without a finger): nothing to move.+ resetIndicator();+ return;+ }+ // From rest: a settle still easing onto the inset stops where it is+ // shown. Ending over it would continue it with a fixed start time, which+ // WebKit skips past when a block follows.+ stopPlacing();+ const current = resolveOwner();+ const {animateTo, scrollBy} = endMotion(scrollTopOf(current));+ if (animateTo == null) {+ place(0);+ scrollOwnerBy(current, scrollBy);+ resetIndicator();+ return;+ }+ // The slide starts two frames after the refresh's end renders, with the+ // app's update and the busy state. WebKit starts an animation created just+ // before a long task at the frame before that task. The first frame after+ // a long task carries the time it was due. Either way, the start of the+ // slide would never show.+ pendingEnd.current = () => {+ // The indicator stays opaque while the content slides up over its gap+ // (UIKit holds it at opacity 1 for nearly the whole end). Under Reduce+ // Motion, the animator cross-fades the slide.+ const from = content.animator.get('y');+ const element = contentElement.current;+ const finish = () => {+ place(0);+ scrollOwnerBy(current, scrollBy);+ if (!model.current.isRefreshing) {+ resetIndicator();+ }+ };+ // The theme's tokens as they apply here, at the end's start. With no+ // tokens, or tokens in a form it cannot read, the end has no slide.+ const timing =+ element == null ? null : endTiming(getComputedStyle(element));+ if (timing == null || timing.ms <= 0) {+ finish();+ return;+ }+ const {ms, points} = timing;+ indicator.animator.play({+ y: bezierCurve(+ REFRESH_HEIGHT - from,+ REFRESH_HEIGHT - animateTo,+ ms,+ points,+ ),+ });+ content.animator+ .play({y: bezierCurve(from, animateTo, ms, points)})+ .finished.then(done => {+ if (done) {+ finish();+ }+ });+ };+ setEndTick(tick => tick + 1);+ }, [+ content.animator,+ indicator.animator,+ place,+ resetIndicator,+ resolveOwner,+ stopPlacing,+ ]);++ // Plays a pending end once the refresh's end renders. This effect runs+ // after the commit that carries the end's tick, and the slide starts two+ // frames later. A tick is used, not the rendered `isRefreshing`. A refresh+ // that begins and ends before React renders never changes `isRefreshing`,+ // for example a timer's `refresh()` whose `onRefresh` settles at once.+ useEffect(() => {+ if (pendingEnd.current == null) {+ return;+ }+ endFrame.current = requestAnimationFrame(() => {+ endFrame.current = requestAnimationFrame(() => {+ endFrame.current = null;+ const play = pendingEnd.current;+ pendingEnd.current = null;+ play?.();+ });+ });+ }, [endTick]);+ useEffect(+ () => () => {+ if (endFrame.current != null) {+ cancelAnimationFrame(endFrame.current);+ }+ },+ [],+ );++ // -- The pull -------------------------------------------------------------++ // The pan's vertical translation where the pull starts: null until the+ // content is at its top under a finger moving down.+ const anchor = useRef<number | null>(null);+ const lastTranslation = useRef(0);+ // A settle a finger caught (it stops where it is on touch-down) resumes+ // when no pull follows.+ const resumeSettle = useCallback(() => {+ if (model.current.isPulling) {+ return;+ }+ const target = releaseTarget(model.current.isRefreshing);+ if (Math.abs(content.animator.get('y') - target) > 0.05) {+ settle(model.current.isRefreshing ? 'inset' : 'top');+ }+ }, [content.animator, model, settle]);++ const onPull = (pan: RefreshPullRecognizer) => {+ const state = model.current;+ if (pan.state === 'began' || pan.state === 'changed') {+ const translation = pan.translation().y;+ if (anchor.current == null) {+ // Not pulling yet: the browser can be scrolling the content, in a drag+ // that began as a scroll. The pull starts in the same touch once the+ // content is at its top and the finger moves down. The browser keeps+ // the finger all along, and the pan only watches, so nothing changes+ // hands.+ const current = pan.state === 'began' ? resolveOwner() : owner.current;+ // At `began` the finger's whole move counts, the threshold's+ // included (a slow drag begins at a translation of zero).+ const isMovingDown =+ pan.state === 'began'+ ? translation + pan.travelAtBegan.y > 0+ : translation > lastTranslation.current;+ lastTranslation.current = translation;+ if (!isMovingDown || current == null || scrollTopOf(current) > 0) {+ return;+ }+ // From rest the travel is the pan's (which leaves out its+ // hysteresis, as UIKit's does); past a scroll it starts where the+ // content ran out.+ anchor.current = pan.state === 'began' ? 0 : translation;+ pullPointer.current = pan.pointerType;+ const shown = content.animator.get('y');+ stopPlacing();+ const dimension = heightOf(current);+ const mode: PullMode = state.isRefreshing ? 'band' : 'reveal';+ pull.current = {+ dimension,+ mode,+ trigger: triggerDistance(dimension),+ floor: state.isRefreshing ? REFRESH_HEIGHT : 0,+ travel0: pullTravel(shown, dimension, mode),+ scrollTop0: scrollTopOf(current),+ };+ dispatch({type: 'pullStart'});+ }+ lastTranslation.current = translation;+ const geometry = pull.current;+ // A browser that scrolls the content back as the finger returns+ // (Chromium) takes over from the pull.+ const scrolledBack =+ scrollTopOf(owner.current) - geometry.scrollTop0 > 0.5;+ const travel = scrolledBack+ ? 0+ : geometry.travel0 + (translation - anchor.current);+ const pulled = pullOverscroll(travel, geometry.dimension, geometry.mode);+ const overscroll = Math.max(geometry.floor, pulled);+ // The content follows the finger by the pull's slope, unless the+ // refreshing inset holds it.+ fingerSlope.current =+ pulled > geometry.floor+ ? pullSlope(travel, geometry.dimension, geometry.mode)+ : 0;+ const hadTriggered = model.current.hasTriggered;+ dispatch({type: 'pullMove', overscroll, trigger: geometry.trigger});+ if (!hadTriggered && model.current.hasTriggered) {+ // The frame after the trigger steps onto the finger (within the+ // one-to-one band).+ geometry.mode =+ geometry.mode === 'band' ? 'band' : modeAfterTrigger(travel);+ }+ place(overscroll);+ if (!model.current.isRefreshing) {+ setReveal(revealProgress(overscroll, geometry.dimension));+ }+ return;+ }+ if (pan.state !== 'ended' && pan.state !== 'cancelled') {+ return;+ }+ const wasPulling = anchor.current != null;+ anchor.current = null;+ if (!wasPulling) {+ // A scroll that never reached the top: a settle the finger caught+ // resumes.+ resumeSettle();+ return;+ }+ // A lift hands the content's speed to the settle: the scroll view's+ // release velocity times the pull's slope. A cancelled pull's finger never+ // lifted, so its settle starts from rest.+ releaseVelocity.current =+ pan.state === 'ended' ? pan.scrollVelocity().y * fingerSlope.current : 0;+ dispatch({type: pan.state === 'ended' ? 'pullEnd' : 'pullCancel'});+ releaseVelocity.current = 0;+ };+ // The touch pull takes no scroll. It watches a contact from the start of a+ // drag, so it would take a scroll in the middle of the page.+ const recognizer = useGestureRecognizer(+ contentElement,+ () => new RefreshPullRecognizer(),+ onPull,+ );+ // A trackpad's two-finger scroll pulls through a second pan, which takes+ // only that scroll and never a mouse wheel's notches. It begins only where+ // nothing under the pointer could scroll: the owner at its top and the+ // content moving down. It claims what it takes, so its blocking `wheel`+ // listener is a claimer's.+ const scrollRecognizer = useGestureRecognizer(+ contentElement,+ () => new RefreshScrollPullRecognizer(),+ onPull,+ );+ // Syncs whether the pull applies with the recognizer, an object outside+ // React. Turned off mid-pull, the recognizer reports `cancelled` to the+ // listener above. The listener settles the content back and ends the pull,+ // where the hook's own `isEnabled` would end it silently.+ useEffect(() => {+ recognizer.setEnabled(isPullEnabled);+ scrollRecognizer.setEnabled(isPullEnabled);+ }, [isPullEnabled, recognizer, scrollRecognizer]);++ useEffect(() => {+ // A finger landing on a settle in flight stops it (UIScrollView brakes),+ // as a trackpad's scroll starting does; if no pull follows, the settle+ // resumes.+ const pans = [recognizer, scrollRecognizer];+ const stops = pans.map(pan => {+ pan.onTouchDown = () => {+ resolveOwner();+ applyEdge();+ cancelPendingEnd();+ stopPlacing();+ keepShownIndicator();+ };+ return pan.addTransitionListener(current => {+ if (current.state === 'failed') {+ resumeSettle();+ }+ });+ });+ return () => {+ for (const pan of pans) {+ pan.onTouchDown = null;+ }+ for (const stop of stops) {+ stop();+ }+ };+ }, [+ applyEdge,+ cancelPendingEnd,+ keepShownIndicator,+ recognizer,+ resolveOwner,+ resumeSettle,+ scrollRecognizer,+ stopPlacing,+ ]);++ const contentRef = useCallback(+ (element: HTMLElement | null) => {+ contentElement.current = element;+ content.ref(element);+ setUpEdge.current?.();+ },+ [content],+ );+ const indicatorRef = useCallback(+ (element: HTMLElement | null) => {+ indicatorElement.current = element;+ indicator.ref(element);+ },+ [indicator],+ );++ const trigger = useCallback(() => {+ // Only a pull triggers: it settles onto the inset.+ hasInset.current = true;+ showIndicator();+ }, [showIndicator]);++ const begin = useCallback(() => {+ showIndicator();+ if (!model.current.isPulling) {+ // The inset arrives with no visible motion, as beginRefreshing().+ cancelPendingEnd();+ const current = resolveOwner();+ place(REFRESH_HEIGHT);+ scrollOwnerBy(current, REFRESH_HEIGHT);+ hasInset.current = true;+ }+ }, [cancelPendingEnd, model, place, resolveOwner, showIndicator]);++ return useMemo(+ () => ({+ contentRef,+ indicatorRef,+ trigger,+ begin,+ settle,+ end,+ }),+ [begin, contentRef, end, indicatorRef, settle, trigger],+ );+}diff --git a/packages/lab/src/RefreshControl/refreshValues.ts b/packages/lab/src/RefreshControl/refreshValues.tsnew file mode 100644index 0000000000..e431e63612--- /dev/null+++ b/packages/lab/src/RefreshControl/refreshValues.ts@@ -0,0 +1,80 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/**+ * @file refreshValues.ts+ * @input Nothing; data only+ * @output Exports `refreshControl`, UIRefreshControl's pull values: the+ * refreshing inset, the trigger, the pull after it, the reveal, the end, and+ * the theme tokens the end plays+ * @position Internal to the refresh pull. A release onto the inset uses Core's+ * `scroll.bounce`, and a pull past `height` uses Core's rubber band.+ */++// Lengths are in pt (CSS px), durations in ms, and curves are cubic-bézier+// control points.+export const refreshControl = {+ /**+ * The refreshing inset: while refreshing, the content rests this far below+ * the top of the scroll view, with the indicator in the gap. Also the+ * stretch of a pull that tracks the finger one to one before the rubber+ * band starts.+ * @source measured: UIKit lab (injected host app), iOS 26.2 simulator,+ * iPhone 17 Pro, UIRefreshControl on a 334 pt scroll view: content held+ * at −60.33 while refreshing (inset top 60), offset equal to finger+ * travel − 10 pt up to 60, Oct 23 2026+ */+ height: 60,+ /**+ * The trigger distance as a fraction of the scroll view's height. A pull+ * triggers when its overscroll reaches this × the height, or+ * `triggerMinimum` if that is larger. The indicator is then fully revealed.+ * @source measured: UIKit lab (injected host app), iOS 26.2 simulator,+ * iPhone 17 Pro, UIRefreshControl on scroll views 400 pt (trigger at+ * 79.0–79.3), 874 pt (168.3–173.7) and 1366 pt (about 271, from the+ * reveal's slope) tall, Oct 23 2026+ */+ triggerHeightFraction: 0.198,+ /**+ * The shortest trigger distance, pt of overscroll: short scroll views+ * trigger here.+ * @source measured: UIKit lab (injected host app), iOS 26.2 simulator,+ * iPhone 17 Pro, UIRefreshControl on a 334 pt scroll view: trigger at+ * 73.0–73.3 at the top of the screen and 540 pt down, Oct 23 2026+ */+ triggerMinimum: 73,+ /**+ * After the trigger, the offset follows the finger one to one again, up to+ * this many `height`s of overscroll. Past it, the pull resists again.+ * @source measured: UIKit lab (injected host app), iOS 26.2 simulator,+ * iPhone 17 Pro, UIRefreshControl on a 334 pt scroll view, setContentOffset+ * log: one to one from the frame after the trigger to −117.67, Oct 23 2026+ */+ postTriggerLinearHeights: 2,+ /**+ * The indicator's reveal curve: the reveal goes from 0 to 1 on it as the+ * overscroll goes from 0 to the trigger distance.+ * @source measured: UIKit lab (injected host app), iOS 26.2 simulator,+ * iPhone 17 Pro, CAAnimation dump (CABasicAnimation on the indicator's+ * opacity, 1 s, timing function (0.42, 0, 0.58, 1)) and per-frame reads+ * of its speed, timeOffset and opacity, Oct 23 2026+ */+ revealCurve: [0.42, 0, 0.58, 1],+ /**+ * `endRefreshing()` while the control is visible: the inset leaves (the+ * content moves up by `height`) over this long. The end plays the theme+ * duration token nearest it (`endDurationToken`). This value stays as the+ * reference for that choice.+ * @source measured: UIKit lab (injected host app), iOS 26.2 simulator,+ * iPhone 17 Pro, setContentOffset per frame over 0.3 s inside+ * UIView.animate(withDuration: 0.3), three runs at rest identical to the+ * frame, Oct 23 2026+ */+ endMs: 300,+ /**+ * The theme duration token that the end plays. In the neutral theme its+ * value is the one nearest `endMs`: 300 ms. The theme's tempo scales it.+ */+ endDurationToken: '--duration-medium',+ /** The easing token that the end plays: the content moves. */+ endEasingToken: '--ease-move',+} as const;diff --git a/packages/lab/src/RefreshControl/useMotionAnimator.ts b/packages/lab/src/RefreshControl/useMotionAnimator.tsnew file mode 100644index 0000000000..697641a6e3--- /dev/null+++ b/packages/lab/src/RefreshControl/useMotionAnimator.ts@@ -0,0 +1,35 @@+// 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.tsxnew file mode 100644index 0000000000..062d8d7f25--- /dev/null+++ b/packages/lab/src/RefreshControl/useRefreshControl.test.tsx@@ -0,0 +1,1315 @@+// 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 {useState, type ReactNode} from 'react';+import {act, render, screen, waitFor} from '@testing-library/react';+import {+ GestureRecognizer,+ PanGestureRecognizer,+ type MotionAnimator,+ type MotionCurve,+} from '@astryxdesign/core/internal/touch';+import {afterEach, beforeEach, describe, expect, it, vi} from 'vitest';+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('./useMotionAnimator', async importOriginal => {+ const real = await importOriginal<typeof import('./useMotionAnimator')>();+ return {+ ...real,+ useMotionAnimator: (+ ...args: Parameters<typeof real.useMotionAnimator>+ ): ReturnType<typeof real.useMotionAnimator> => {+ const result = real.useMotionAnimator(...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 MotionAnimator[];+ 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 MotionAnimator[];+ 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']+ >;+ 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('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 MotionAnimator[];+ 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;+ }+ });+});diff --git a/packages/lab/src/RefreshControl/useRefreshControl.ts b/packages/lab/src/RefreshControl/useRefreshControl.tsnew file mode 100644index 0000000000..d614c13a68--- /dev/null+++ b/packages/lab/src/RefreshControl/useRefreshControl.ts@@ -0,0 +1,255 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++'use client';++/**+ * @file useRefreshControl.ts+ * @input onRefresh, isRefreshing, isDisabled and announce; the touch+ * layer (refreshTouchController.ts)+ * @output Exports useRefreshControl: refs for the pulled content and the+ * app's indicator, `isRefreshing`, and `refresh()` for the non-gesture path+ * @position Lab's pull to refresh: the state, `onRefresh`, the announcement+ * and the gate. refreshTouchController.ts holds everything a finger drives,+ * and only this file imports it.+ *+ * SYNC: When modified, update:+ * - /packages/lab/src/RefreshControl/refreshTouchController.ts+ * - /packages/lab/src/RefreshControl/useRefreshControl.test.tsx+ */++// A finger pulls, and so does a trackpad's two-finger scroll once the content+// is at its top, with the same mapping, trigger and settle. The pull applies+// in an element that scrolls. A mouse or pen drag stays the browser's, for+// text selection. The app draws the indicator and says what is announced.++import {+ useCallback,+ useEffect,+ useLayoutEffect,+ useRef,+ useState,+ type RefCallback,+} from 'react';+import {useAnnounce} from '@astryxdesign/core/hooks';+import {+ INITIAL_REFRESH_STATE,+ reduceRefresh,+ type RefreshEffect,+ type RefreshEvent,+ type RefreshState,+} from './refreshModel';+import {useRefreshTouchController} from './refreshTouchController';++export {REFRESH_REVEAL_VAR} from './refreshIndicator';++export interface UseRefreshControlOptions {+ /**+ * Called when a pull triggers, or when `refresh()` runs. Return a promise to+ * keep the control refreshing until it settles (uncontrolled use).+ */+ onRefresh?: () => unknown;+ /**+ * Controlled refreshing state: `true` puts the control in the refreshing+ * state (as `beginRefreshing()`), `false` ends it (as `endRefreshing()`).+ * Omit it to let the promise `onRefresh` returns decide.+ */+ isRefreshing?: boolean;+ /** Turns the pull off. A refresh in progress keeps running. */+ isDisabled?: boolean;+ /**+ * Announced politely when a refresh starts, for example "Refreshing". The+ * app supplies it in its own language. Omit it to announce nothing.+ */+ announce?: string;+}++export interface UseRefreshControlResult {+ /** Attach to the element that wraps the scrolled content (it is pulled). */+ contentRef: RefCallback<HTMLElement>;+ /**+ * Attach this ref to the app's indicator, for example a Spinner. The+ * indicator is a band as tall as the refresh height. It sits at the bottom+ * of an overflow-hidden box that rides on the content's top edge. The hook+ * moves the band against the content, so it stays pinned at the top of the+ * scroll view, where UIRefreshControl sits. The content's edge covers it.+ * The hook writes how much of it the pull reveals, 0 to 1, to+ * `REFRESH_REVEAL_VAR`, and fades it as a settle takes the content back.+ */+ indicatorRef: RefCallback<HTMLElement>;+ /** Whether a refresh is in progress. */+ isRefreshing: boolean;+ /** Starts a refresh without a pull (the non-gesture path). */+ refresh: () => void;+}++/**+ * Pull to refresh, as UIRefreshControl, for the app's own scroll container.+ * Pulling the content down past the top reveals the app's indicator. Pulling+ * past the trigger starts a refresh with the finger still down. Letting go+ * settles the content onto the refreshing inset until the refresh ends, and+ * then it slides back up.+ *+ * A finger pulls, and so does a trackpad's two-finger scroll at the top. A+ * mouse or pen drag stays the browser's, for text selection, and a mouse+ * wheel's notches never pull. Always give people another way to refresh, such+ * as a button that calls `refresh()`: a pull has no keyboard or+ * assistive-technology equivalent.+ *+ * @example+ * ```+ * const pull = useRefreshControl({onRefresh: reload, announce: 'Refreshing'});+ * <div style={{overflowY: 'auto', height: '100%'}}>+ * <div ref={pull.contentRef} aria-busy={pull.isRefreshing || undefined}>+ * <List>…</List>+ * <div style={{position: 'absolute', insetInline: 0, bottom: '100%', height: '100lvh', overflow: 'hidden'}}>+ * <div ref={pull.indicatorRef} aria-hidden style={{position: 'absolute', insetInline: 0, bottom: 0, height: 60}}>+ * <Spinner />+ * </div>+ * </div>+ * </div>+ * </div>+ * ```+ */+export function useRefreshControl({+ onRefresh,+ isRefreshing: isRefreshingProp,+ isDisabled = false,+ announce,+}: UseRefreshControlOptions = {}): UseRefreshControlResult {+ const announcer = useAnnounce();+ const [isRefreshing, setIsRefreshing] = useState(false);+ // Controlled: a refresh the hook started waits one commit for the parent+ // to take it.+ const awaitingProp = useRef(false);+ const [controlledCheck, setControlledCheck] = useState(0);++ const model = useRef<RefreshState>(INITIAL_REFRESH_STATE);+ const refreshToken = useRef(0);+ const isControlled = isRefreshingProp !== undefined;+ const latest = useRef({onRefresh, isControlled, announce, announcer});+ // Syncs the handlers' ref with the newest options.+ useLayoutEffect(() => {+ latest.current = {onRefresh, isControlled, announce, announcer};+ });++ const dispatchRef = useRef<(event: RefreshEvent) => void>(() => {});+ const touch = useRefreshTouchController({+ isPullEnabled: !isDisabled,+ model,+ dispatchRef,+ });++ // -- Effects of the state machine -----------------------------------------++ const callHandler = useCallback(() => {+ const token = ++refreshToken.current;+ const result = latest.current.onRefresh?.();+ if (latest.current.isControlled) {+ // The prop is the source: unless the parent takes this refresh by+ // setting `isRefreshing`, it ends on the next commit.+ awaitingProp.current = true;+ setControlledCheck(count => count + 1);+ return;+ }+ const settle = () => {+ if (token === refreshToken.current) {+ dispatchRef.current({type: 'end'});+ }+ };+ void Promise.resolve(result).then(settle, settle);+ }, []);++ const run = useCallback(+ (effect: RefreshEffect) => {+ const {announce: words, announcer: say} = latest.current;+ switch (effect.type) {+ case 'trigger':+ setIsRefreshing(true);+ touch.trigger();+ if (words) {+ say(words);+ }+ callHandler();+ break;+ case 'begin': {+ setIsRefreshing(true);+ if (words) {+ say(words);+ }+ touch.begin();+ if (effect.callHandler) {+ callHandler();+ }+ break;+ }+ case 'settle':+ touch.settle(effect.to);+ break;+ case 'end':+ setIsRefreshing(false);+ touch.end();+ break;+ }+ },+ [callHandler, touch],+ );++ const dispatch = useCallback(+ (event: RefreshEvent) => {+ const next = reduceRefresh(model.current, event);+ model.current = next.state;+ for (const effect of next.effects) {+ run(effect);+ }+ },+ [run],+ );+ dispatchRef.current = dispatch;++ // -- Programmatic control -------------------------------------------------++ // Syncs a controlled `isRefreshing` into the systems outside React: the+ // touch layer and the announcer. The touch layer runs the inset and the+ // slide on the compositor. The rendered value is the prop itself.+ useEffect(() => {+ if (isRefreshingProp === undefined) {+ return;+ }+ dispatch(+ isRefreshingProp ? {type: 'begin', source: 'program'} : {type: 'end'},+ );+ }, [dispatch, isRefreshingProp]);++ // A refresh that the hook started, by a pull or `refresh()`, under a+ // controlled `isRefreshing`. If the prop is now true, the parent took it.+ // Otherwise the refresh ends, for example when a parent keeps false. The end+ // goes to the touch layer, outside React, and slides the inset off.+ useEffect(() => {+ if (!awaitingProp.current) {+ return;+ }+ awaitingProp.current = false;+ if (isRefreshingProp === false) {+ dispatch({type: 'end'});+ }+ }, [controlledCheck, dispatch, isRefreshingProp]);++ const refresh = useCallback(() => {+ dispatch({type: 'begin', source: 'user'});+ }, [dispatch]);++ useEffect(+ () => () => {+ refreshToken.current++;+ },+ [],+ );++ return {+ contentRef: touch.contentRef,+ indicatorRef: touch.indicatorRef,+ // Controlled, the prop is the source from the first render.+ isRefreshing: isControlled ? Boolean(isRefreshingProp) : isRefreshing,+ refresh,+ };+}diff --git a/packages/lab/src/index.ts b/packages/lab/src/index.tsindex c28ce99d49..92178abd14 100644--- a/packages/lab/src/index.ts+++ b/packages/lab/src/index.ts@@ -327,3 +327,12 @@ export {// RichTextEditor (RFC meta/astryx#3899) moved out of @astryxdesign/lab into// its own package, @astryxdesign/richtext. Import it from there:// import {RichTextEditor, RichTextView} from '@astryxdesign/richtext';++// Pull to refresh as UIRefreshControl, applied by the app to its own scroll+// container, on Core's touch foundation.+export {+ REFRESH_REVEAL_VAR,+ useRefreshControl,+ type UseRefreshControlOptions,+ type UseRefreshControlResult,+} from './RefreshControl';