Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

chore(gestures): a Storybook harness to check presented hit testing on a phone (#9400)

Christopher Chedeau4e963dff08fa
diff --git a/apps/storybook/stories/PresentedHitTestingLab.stories.tsx b/apps/storybook/stories/PresentedHitTestingLab.stories.tsx
new file mode 100644
index 0000000000..14c079001d
--- /dev/null
+++ b/apps/storybook/stories/PresentedHitTestingLab.stories.tsx
@@ -0,0 +1,34 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file PresentedHitTestingLab.stories.tsx
+ * @input The gesture host's device-check harness
+ * @output One full-screen story for checking presented hit testing on a phone
+ * @position Storybook: open it on a preview from an iPhone. Not a component
+ * story; the harness is not exported.
+ */
+
+import type {Meta, StoryObj} from '@storybook/react';
+import {PresentedHitTestingLab} from '../../../packages/core/src/__tests__/PresentedHitTestingLab';
+
+const meta: Meta<typeof PresentedHitTestingLab> = {
+ title: 'Core/Gestures',
+ component: PresentedHitTestingLab,
+ parameters: {
+ layout: 'fullscreen',
+ docs: {
+ description: {
+ component:
+ 'A device check for the gesture host. A sheet springs up slowly over a full-page scrim. Tap Done or drag the sheet while it rises: on an iPhone, with the correction on, Done clicks once, the scrim takes nothing, and the page does not scroll. Turn the correction off to see the engine without it.',
+ },
+ },
+ },
+};
+
+export default meta;
+
+type Story = StoryObj<typeof PresentedHitTestingLab>;
+
+export const PresentedHitTesting: Story = {
+ name: 'Presented hit testing',
+};
diff --git a/packages/core/src/__tests__/PresentedHitTestingLab.test.tsx b/packages/core/src/__tests__/PresentedHitTestingLab.test.tsx
new file mode 100644
index 0000000000..f19778c34c
--- /dev/null
+++ b/packages/core/src/__tests__/PresentedHitTestingLab.test.tsx
@@ -0,0 +1,152 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file PresentedHitTestingLab.test.tsx
+ * @input Uses PresentedHitTestingLab, stubMatchMedia and Testing Library
+ * @output Tests for the device-check harness's readouts
+ * @position The harness measures every touch at the page root, because on
+ * iOS WebKit a touch on the moving sheet targets the scrim.
+ */
+
+import {afterEach, describe, expect, it, vi} from 'vitest';
+import {act, fireEvent, render, screen} from '@testing-library/react';
+import {coarsePrimaryPointer} from '../gestures/__tests__/pointerQuery';
+import {registerPresentedOffset} from '../motion/presentation';
+import {PresentedHitTestingLab} from './PresentedHitTestingLab';
+import {stubMatchMedia} from './stubMatchMedia';
+
+interface Box {
+ left: number;
+ top: number;
+ right: number;
+ bottom: number;
+}
+
+const rect = ({left, top, right, bottom}: Box): DOMRect => ({
+ left,
+ top,
+ right,
+ bottom,
+ x: left,
+ y: top,
+ width: right - left,
+ height: bottom - top,
+ toJSON: () => ({}),
+});
+
+const inside = (box: Box, x: number, y: number) =>
+ x >= box.left && x < box.right && y >= box.top && y < box.bottom;
+
+/** A touch the engine sends to `target`, at `at`. */
+function touch(
+ type: 'touchstart' | 'touchend',
+ target: EventTarget,
+ at: {x: number; y: number},
+ time: number,
+): void {
+ const event = new Event(type, {bubbles: true, cancelable: true});
+ const contact = {identifier: 1, clientX: at.x, clientY: at.y, target};
+ Object.defineProperty(event, 'changedTouches', {value: [contact]});
+ Object.defineProperty(event, 'touches', {
+ value: type === 'touchend' ? [] : [contact],
+ });
+ Object.defineProperty(event, 'timeStamp', {value: time});
+ target.dispatchEvent(event);
+}
+
+afterEach(() => {
+ vi.unstubAllGlobals();
+ vi.restoreAllMocks();
+ Reflect.deleteProperty(document, 'elementsFromPoint');
+ Reflect.deleteProperty(document, 'elementFromPoint');
+});
+
+describe('PresentedHitTestingLab', () => {
+ it('logs and measures a touch that the engine sends to the scrim', () => {
+ stubMatchMedia({reduceMotion: false, matches: false});
+ render(<PresentedHitTestingLab />);
+ // The scrim sits just before the sheet.
+ const scrim = screen.getByRole('region', {
+ name: 'Sheet',
+ }).previousElementSibling;
+ if (scrim == null) {
+ throw new Error('no scrim');
+ }
+ fireEvent.touchStart(scrim, {touches: [{clientX: 10, clientY: 10}]});
+ fireEvent.touchEnd(scrim, {touches: []});
+ expect(
+ screen.getByText(/touch-down: the engine hit-tested the scrim/),
+ ).toBeInTheDocument();
+ expect(
+ screen.getByText(/page scrolled 0 px in the last touch/),
+ ).toBeInTheDocument();
+ });
+
+ it('says when Reduce Motion is on, since the sheet then does not move', () => {
+ stubMatchMedia({reduceMotion: true, matches: false});
+ render(<PresentedHitTestingLab />);
+ expect(screen.getByText(/Reduce Motion is on/)).toBeInTheDocument();
+ });
+
+ it('with the correction on in iOS WebKit, a tap on the drawn Done clicks it, though the engine hit-tests the scrim', () => {
+ const restorePointer = coarsePrimaryPointer();
+ vi.stubGlobal('CSS', {
+ ...globalThis.CSS,
+ supports: (query: string) => query === '(-webkit-touch-callout: none)',
+ });
+ render(<PresentedHitTestingLab />);
+ const sheet = screen.getByRole('region', {name: 'Sheet'});
+ const done = screen.getByRole('button', {name: 'Done'});
+ const scrim = sheet.previousElementSibling;
+ if (scrim == null) {
+ throw new Error('no scrim');
+ }
+ // The sheet's motion started below the screen, where iOS WebKit still
+ // hit-tests it, and it is drawn 544 px higher.
+ const sheetBox: Box = {left: 0, top: 844, right: 390, bottom: 1244};
+ const doneBox: Box = {left: 300, top: 854, right: 380, bottom: 894};
+ let resolvedY = 0;
+ const moved = (box: Box): Box => ({
+ ...box,
+ top: box.top + resolvedY,
+ bottom: box.bottom + resolvedY,
+ });
+ vi.spyOn(sheet, 'getBoundingClientRect').mockImplementation(() =>
+ rect(moved(sheetBox)),
+ );
+ vi.spyOn(done, 'getBoundingClientRect').mockImplementation(() =>
+ rect(moved(doneBox)),
+ );
+ const stack = (x: number, y: number): Element[] => [
+ ...(inside(moved(doneBox), x, y) ? [done] : []),
+ ...(inside(moved(sheetBox), x, y) ? [sheet] : []),
+ scrim,
+ document.body,
+ document.documentElement,
+ ];
+ Object.defineProperty(document, 'elementsFromPoint', {
+ configurable: true,
+ value: stack,
+ });
+ Object.defineProperty(document, 'elementFromPoint', {
+ configurable: true,
+ value: (x: number, y: number) => stack(x, y)[0],
+ });
+ const unregister = registerPresentedOffset(sheet, {
+ offset: () => ({x: 0, y: -544 - resolvedY}),
+ resolve: () => {
+ resolvedY = -544;
+ },
+ });
+ const onDrawnDone = {x: 340, y: 330};
+ act(() => {
+ touch('touchstart', scrim, onDrawnDone, 0);
+ touch('touchend', scrim, onDrawnDone, 80);
+ });
+ unregister();
+ restorePointer();
+ expect(
+ screen.getByText(/Done clicked 1 · scrim took 0/),
+ ).toBeInTheDocument();
+ });
+});
diff --git a/packages/core/src/__tests__/PresentedHitTestingLab.tsx b/packages/core/src/__tests__/PresentedHitTestingLab.tsx
new file mode 100644
index 0000000000..ceaf5f159a
--- /dev/null
+++ b/packages/core/src/__tests__/PresentedHitTestingLab.tsx
@@ -0,0 +1,333 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file PresentedHitTestingLab.tsx
+ * @input Touches on a sheet that springs up over a full-page scrim, the
+ * Replay button and the correction switch
+ * @output PresentedHitTestingLab: the sheet, its Done button and the scrim,
+ * driven by the gesture host and the motion animator, with readouts of what
+ * the engine hit-tested at each touch-down, Done's clicks, the scrim's taps,
+ * the sheet pan's translation and how far the page scrolled in the last
+ * touch. A checkbox turns the host's presented hit testing off.
+ * @position A device-check harness for the gesture host's presented hit
+ * testing. The Storybook story "Core/Gestures/Presented hit testing"
+ * renders it, so a phone can open it on a preview. Not exported.
+ */
+
+import {useCallback, useEffect, useRef, useState, type TouchEvent} from 'react';
+import * as stylex from '@stylexjs/stylex';
+import {Button} from '../Button/Button';
+import {Heading} from '../Heading/Heading';
+import {HStack} from '../HStack/HStack';
+import {Text} from '../Text/Text';
+import {VStack} from '../VStack/VStack';
+import {
+ colorVars,
+ radiusVars,
+ shadowVars,
+ spacingVars,
+} from '../theme/tokens.stylex';
+import {
+ createMotionEngine,
+ defaultPrefersReducedMotion,
+} from '../motion/animator';
+import {isIosWebKit} from '../utils/touchQueries';
+import {GestureHost} from '../gestures/GestureHost';
+import {PanGestureRecognizer} from '../gestures/PanGestureRecognizer';
+import {TapGestureRecognizer} from '../gestures/TapGestureRecognizer';
+
+/**
+ * The sheet's spring: critically damped like UIKit's sheet, slowed from
+ * about a 0.5 s response to 3 s so a finger can land on it while it moves.
+ */
+const SPRING = {response: 3, dampingRatio: 1} as const;
+
+/** How many of the latest events the log shows. */
+const LOG_LENGTH = 3;
+
+/** Rows behind the scrim, so the page can scroll. */
+const ROWS = Array.from({length: 40}, (_, index) => index + 1);
+
+type Animator = ReturnType<typeof createMotionEngine>;
+
+const s = stylex.create({
+ page: {
+ minHeight: '100vh',
+ backgroundColor: colorVars['--color-background-surface'],
+ },
+ bar: {
+ position: 'sticky',
+ top: 0,
+ zIndex: 3,
+ paddingBlock: spacingVars['--spacing-2'],
+ paddingInline: spacingVars['--spacing-3'],
+ backgroundColor: colorVars['--color-background-surface'],
+ borderBottomWidth: 1,
+ borderBottomStyle: 'solid',
+ borderBottomColor: colorVars['--color-border'],
+ },
+ rows: {
+ padding: spacingVars['--spacing-4'],
+ },
+ scrim: {
+ position: 'fixed',
+ inset: 0,
+ zIndex: 1,
+ backgroundColor: colorVars['--color-overlay'],
+ },
+ sheet: {
+ position: 'fixed',
+ insetInline: 0,
+ bottom: 0,
+ zIndex: 2,
+ height: 240,
+ padding: spacingVars['--spacing-4'],
+ backgroundColor: colorVars['--color-background-surface'],
+ borderStartStartRadius: radiusVars['--radius-element'],
+ borderStartEndRadius: radiusVars['--radius-element'],
+ boxShadow: shadowVars['--shadow-high'],
+ },
+});
+
+/** Which part of the lab `target` is in, for the log. */
+function partOf(
+ target: EventTarget | null,
+ parts: {
+ done: HTMLElement | null;
+ sheet: HTMLElement | null;
+ scrim: HTMLElement | null;
+ },
+): string {
+ if (!(target instanceof Node)) {
+ return 'nothing';
+ }
+ if (parts.done?.contains(target) === true) {
+ return 'Done';
+ }
+ if (parts.sheet?.contains(target) === true) {
+ return 'the sheet';
+ }
+ if (parts.scrim?.contains(target) === true) {
+ return 'the scrim';
+ }
+ return 'the page';
+}
+
+export function PresentedHitTestingLab() {
+ const scrimRef = useRef<HTMLDivElement>(null);
+ const sheetRef = useRef<HTMLElement | null>(null);
+ const doneRef = useRef<HTMLDivElement>(null);
+ const animatorRef = useRef<Animator | null>(null);
+ const scrollAtTouchRef = useRef<number | null>(null);
+ const [correction, setCorrection] = useState(true);
+ // Storybook renders this on the client only, so the engine and the
+ // motion setting can be read on the first render.
+ const [iosWebKit] = useState(() => isIosWebKit());
+ const [reducedMotion] = useState(() => defaultPrefersReducedMotion());
+ const [log, setLog] = useState<ReadonlyArray<string>>([]);
+ const [doneClicks, setDoneClicks] = useState(0);
+ const [scrimTaps, setScrimTaps] = useState(0);
+ const [panY, setPanY] = useState(0);
+ const [scrolled, setScrolled] = useState<number | null>(null);
+
+ const record = useCallback((line: string) => {
+ const at = (performance.now() / 1000).toFixed(2);
+ setLog(lines => [`${at} s: ${line}`, ...lines].slice(0, LOG_LENGTH));
+ }, []);
+
+ // The animator lives as long as the sheet element.
+ const attachSheet = useCallback((sheet: HTMLElement | null) => {
+ if (sheet == null) {
+ return undefined;
+ }
+ sheetRef.current = sheet;
+ const animator = createMotionEngine(sheet);
+ animatorRef.current = animator;
+ return () => {
+ animator.dispose();
+ animatorRef.current = null;
+ sheetRef.current = null;
+ };
+ }, []);
+
+ // The page root logs the engine's own target: no host changes it. On iOS
+ // WebKit a touch on the moving sheet targets the scrim, so a handler on the
+ // sheet would miss it.
+ const onTouchStartCapture = (event: TouchEvent<HTMLDivElement>) => {
+ const parts = {
+ done: doneRef.current,
+ sheet: sheetRef.current,
+ scrim: scrimRef.current,
+ };
+ record(`touch-down: the engine hit-tested ${partOf(event.target, parts)}`);
+ if (event.touches.length === 1) {
+ scrollAtTouchRef.current = window.scrollY;
+ }
+ };
+ const onTouchFinishCapture = (event: TouchEvent<HTMLDivElement>) => {
+ const start = scrollAtTouchRef.current;
+ if (start == null || event.touches.length > 0) {
+ return;
+ }
+ setScrolled(Math.round(Math.abs(window.scrollY - start)));
+ scrollAtTouchRef.current = null;
+ };
+
+ // Drives the scrim's tap and the sheet's pan through a gesture host with
+ // the correction on (`auto`: iOS WebKit only) or off, rebuilt on a switch.
+ useEffect(() => {
+ const scrim = scrimRef.current;
+ const sheet = sheetRef.current;
+ if (scrim == null || sheet == null) {
+ return;
+ }
+ const host = new GestureHost(document, {
+ presentedHitTesting: correction ? 'auto' : 'never',
+ });
+ const scrimTap = new TapGestureRecognizer({name: 'scrim'});
+ const sheetPan = new PanGestureRecognizer({
+ name: 'sheet',
+ direction: 'down',
+ });
+ let caughtAt: number | null = null;
+ const stopTap = scrimTap.addTransitionListener((_recognizer, _from, to) => {
+ if (to === 'ended') {
+ setScrimTaps(count => count + 1);
+ record('the scrim took a tap');
+ }
+ });
+ const stopPan = sheetPan.addListener(recognizer => {
+ const animator = animatorRef.current;
+ if (animator == null) {
+ return;
+ }
+ if (recognizer.state === 'began') {
+ // The pan catches the sheet where it is drawn and holds it there.
+ caughtAt = animator.get('y');
+ animator.set({y: caughtAt});
+ record('the sheet’s pan began');
+ } else if (recognizer.state === 'changed' && caughtAt != null) {
+ const translation = recognizer.translation().y;
+ animator.set({y: Math.max(0, caughtAt + translation)});
+ setPanY(Math.round(translation));
+ } else if (
+ (recognizer.state === 'ended' || recognizer.state === 'cancelled') &&
+ caughtAt != null
+ ) {
+ caughtAt = null;
+ record(`the sheet’s pan ${recognizer.state}`);
+ animator.animate({y: 0}, {spring: SPRING});
+ }
+ });
+ const detachScrim = host.attach(scrim, scrimTap);
+ const detachSheet = host.attach(sheet, sheetPan);
+ return () => {
+ detachScrim();
+ detachSheet();
+ stopTap();
+ stopPan();
+ };
+ }, [correction, record]);
+
+ const replay = () => {
+ const animator = animatorRef.current;
+ const sheet = sheetRef.current;
+ if (animator == null || sheet == null) {
+ return;
+ }
+ animator.set({y: sheet.offsetHeight + 48});
+ animator.animate({y: 0}, {spring: SPRING});
+ record('Replay: the sheet springs up');
+ };
+
+ const engine = iosWebKit
+ ? 'engine: iOS WebKit, so the correction applies'
+ : 'engine: not iOS WebKit, so the switch changes nothing here';
+
+ return (
+ <div
+ onTouchStartCapture={onTouchStartCapture}
+ onTouchEndCapture={onTouchFinishCapture}
+ onTouchCancelCapture={onTouchFinishCapture}
+ {...stylex.props(s.page)}>
+ <VStack gap={1} xstyle={s.bar}>
+ <HStack gap={3} vAlign="center" hAlign="between" wrap="wrap">
+ <Heading level={1}>Presented hit testing</Heading>
+ <HStack gap={3} vAlign="center">
+ {/* A native checkbox, not Core's Switch: the Switch attaches to
+ the document's shared gesture host, which would resolve the
+ moving sheet before this page's host and hide the correction. */}
+ <label>
+ <input
+ type="checkbox"
+ checked={correction}
+ onChange={event => {
+ setCorrection(event.currentTarget.checked);
+ }}
+ />{' '}
+ Correction
+ </label>
+ <Button
+ label="Replay"
+ variant="primary"
+ size="sm"
+ onClick={replay}
+ />
+ </HStack>
+ </HStack>
+ {reducedMotion ? (
+ <Text type="supporting" color="primary">
+ Reduce Motion is on, so the sheet does not move and there is nothing
+ to check. Turn Reduce Motion off and reload.
+ </Text>
+ ) : (
+ <Text type="supporting">
+ Press Replay, then tap Done or drag the sheet down while it rises (
+ {engine}).
+ </Text>
+ )}
+ <Text type="supporting" color="primary">
+ Done clicked {doneClicks} · scrim took {scrimTaps} · pan {panY} px ·
+ page scrolled {scrolled == null ? '–' : `${scrolled} px`} in the last
+ touch
+ </Text>
+ <VStack gap={0}>
+ {log.map(line => (
+ <Text key={line} type="code" size="xsm">
+ {line}
+ </Text>
+ ))}
+ </VStack>
+ </VStack>
+ <VStack gap={2} xstyle={s.rows}>
+ {ROWS.map(row => (
+ <Text key={row} color="secondary">
+ Row {row} of the page behind the sheet
+ </Text>
+ ))}
+ </VStack>
+ <div ref={scrimRef} aria-hidden={true} {...stylex.props(s.scrim)} />
+ <section ref={attachSheet} aria-label="Sheet" {...stylex.props(s.sheet)}>
+ <VStack gap={2}>
+ <HStack gap={2} vAlign="center" hAlign="between">
+ <Heading level={2}>Sheet</Heading>
+ <div ref={doneRef}>
+ <Button
+ label="Done"
+ onClick={() => {
+ setDoneClicks(count => count + 1);
+ record('Done clicked');
+ }}
+ />
+ </div>
+ </HStack>
+ <Text type="supporting">
+ Drag me down while I move: the pan catches me where I am drawn.
+ </Text>
+ </VStack>
+ </section>
+ </div>
+ );
+}