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.tsxnew file mode 100644index 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.tsxnew file mode 100644index 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.tsxnew file mode 100644index 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>+ );+}