diff --git a/.changeset/nested-control-press-every-pointer.md b/.changeset/nested-control-press-every-pointer.md new file mode 100644 index 0000000000000..28f4fd892cc49 --- /dev/null +++ b/.changeset/nested-control-press-every-pointer.md @@ -0,0 +1,7 @@ +--- +'@astryxdesign/core': patch +--- + +[fix] A mouse or pen press on a control inside a ClickableCard, SelectableCard, Item row, TreeList row or Token now paints only that control, as a finger's press already did. The container keeps its hover look and shows no pressed state. A press on the container's own surface still paints the container, and an Item row whose root is a link still paints, because a press there runs the row. + +@cixzhang diff --git a/apps/storybook/stories/NestedControlPress.stories.tsx b/apps/storybook/stories/NestedControlPress.stories.tsx new file mode 100644 index 0000000000000..130e24302d6bb --- /dev/null +++ b/apps/storybook/stories/NestedControlPress.stories.tsx @@ -0,0 +1,94 @@ +// Copyright (c) Meta Platforms, Inc. and affiliates. + +/** + * @file NestedControlPress.stories.tsx + * @input ClickableCard, SelectableCard, Item, TreeList, Token and Button from + * @astryxdesign/core + * @output One story with each container that holds a nested control: a + * ClickableCard and a SelectableCard with a Button, an Item row and a + * TreeList row with an end-content Button, and a Token with a remove + * button, and a standalone Button. A press on the nested control paints + * only that control; a press on the container's own surface paints the + * container + * @position Fixture for __tests__/NestedControlPress.a11y.chromium.spec.ts + */ + +import type {ReactNode} from 'react'; +import type {Meta, StoryObj} from '@storybook/react'; +import {ClickableCard} from '@astryxdesign/core/ClickableCard'; +import {SelectableCard} from '@astryxdesign/core/SelectableCard'; +import {Item} from '@astryxdesign/core/Item'; +import {TreeList} from '@astryxdesign/core/TreeList'; +import {Token} from '@astryxdesign/core/Token'; +import {Button} from '@astryxdesign/core/Button'; +import {Text} from '@astryxdesign/core/Text'; +import {VStack} from '@astryxdesign/core/Layout'; + +const meta: Meta = { + title: 'Core/Nested Control Press', + tags: ['no-visual'], + parameters: {layout: 'padded'}, +}; +export default meta; + +type Story = StoryObj; + +function Case({id, children}: {id: string; children: ReactNode}) { + return ( +
+ {children} +
+ ); +} + +function NestedButton() { + return + ); +} + +interface Case { + name: string; + render: () => ReactNode; + /** The element whose press paint the rule turns off. */ + container: (nested: HTMLElement) => HTMLElement; + /** An element on the container's own surface. */ + surface: () => HTMLElement; +} + +function closestOrThrow(element: Element, selector: string): HTMLElement { + const found = element.closest(selector); + if (!(found instanceof HTMLElement)) { + throw new Error(`no ${selector} around the element`); + } + return found; +} + +const CASES: Case[] = [ + { + name: 'ClickableCard', + render: () => ( + {}}> + Surface + + + ), + container: nested => closestOrThrow(nested, '[data-pressable-container]'), + surface: () => screen.getByText('Surface'), + }, + { + name: 'SelectableCard', + render: () => ( + {}}> + Surface + + + ), + container: nested => closestOrThrow(nested, '[data-pressable-container]'), + surface: () => screen.getByText('Surface'), + }, + { + name: 'Item with onClick', + render: () => ( + {}} endContent={} /> + ), + container: nested => closestOrThrow(nested, '.astryx-item'), + surface: () => screen.getByText('Surface'), + }, + { + name: 'Item with href', + render: () => } />, + container: nested => closestOrThrow(nested, '.astryx-item'), + surface: () => screen.getByText('Surface'), + }, + { + name: 'TreeList row', + render: () => ( + {}, + endContent: , + }, + ]} + /> + ), + container: nested => closestOrThrow(nested, '.astryx-tree-list-item'), + surface: () => screen.getByText('Surface'), + }, + { + name: 'Token with a remove button', + render: () => ( + {}} onRemove={() => {}} /> + ), + container: nested => closestOrThrow(nested, '.astryx-token'), + surface: () => screen.getByText('Surface'), + }, +]; + +function nestedOf(name: string): HTMLElement { + return name.startsWith('Token') + ? screen.getByRole('button', {name: /remove/i}) + : screen.getByRole('button', {name: 'Nested'}); +} + +afterEach(() => { + vi.useRealTimers(); +}); + +describe.each(CASES)('$name', testCase => { + it.each(['mouse', 'pen'] as const)( + 'turns off its press paint for a %s press on a nested control, until the press ends', + pointerType => { + render(testCase.render()); + const nested = nestedOf(testCase.name); + const container = testCase.container(nested); + fireEvent.pointerDown(nested, {pointerType, button: 0}); + expect(container.style.getPropertyValue(PAINT)).toBe( + 'var(--_nested-press-rest)', + ); + fireEvent.pointerUp(nested, {pointerType, button: 0}); + expect(container.style.getPropertyValue(PAINT)).toBe(''); + }, + ); + + it('paints no press on the container for a finger press on a nested control, and paints one for a finger on its surface', () => { + vi.useFakeTimers(); + render(testCase.render()); + const nested = nestedOf(testCase.name); + const container = testCase.container(nested); + fireEvent.pointerDown(nested, { + pointerType: 'touch', + pointerId: 1, + button: 0, + }); + act(() => { + vi.advanceTimersByTime(PRESS_ONSET_MS * 2); + }); + expect(container.hasAttribute(PRESSED_ATTRIBUTE)).toBe(false); + fireEvent.pointerUp(nested, { + pointerType: 'touch', + pointerId: 1, + button: 0, + }); + act(() => { + vi.advanceTimersByTime(1000); + }); + const surface = testCase.surface(); + fireEvent.pointerDown(surface, { + pointerType: 'touch', + pointerId: 2, + button: 0, + }); + act(() => { + vi.advanceTimersByTime(PRESS_ONSET_MS * 2); + }); + expect(container.hasAttribute(PRESSED_ATTRIBUTE)).toBe(true); + fireEvent.pointerUp(surface, { + pointerType: 'touch', + pointerId: 2, + button: 0, + }); + }); + + it('keeps its press paint for a mouse press on its own surface', () => { + render(testCase.render()); + const surface = testCase.surface(); + const container = testCase.container(nestedOf(testCase.name)); + fireEvent.pointerDown(surface, {pointerType: 'mouse', button: 0}); + expect(container.style.getPropertyValue(PAINT)).toBe(''); + fireEvent.pointerUp(surface, {pointerType: 'mouse', button: 0}); + }); + + it('ends a mark that outlived its press at the next press', () => { + render(testCase.render()); + const nested = nestedOf(testCase.name); + const container = testCase.container(nested); + container.style.setProperty(PAINT, 'var(--_nested-press-rest)'); + fireEvent.pointerDown(testCase.surface(), { + pointerType: 'mouse', + button: 0, + }); + expect(container.style.getPropertyValue(PAINT)).toBe(''); + }); +}); + +describe('the press rule’s other edges', () => { + it('leaves a secondary button press on a nested control alone', () => { + render( + {}}> + + , + ); + const nested = screen.getByRole('button', {name: 'Nested'}); + fireEvent.pointerDown(nested, {pointerType: 'mouse', button: 2}); + expect( + closestOrThrow( + nested, + '[data-pressable-container]', + ).style.getPropertyValue(PAINT), + ).toBe(''); + }); + + it('keeps the press paint of an Item row for a press on its delegated control', () => { + function DelegatingRow() { + const ref = useRef(null); + return ( + + } + endContent={} + /> + ); + } + render(); + const checkbox = screen.getByRole('checkbox', {name: 'Pick row'}); + const row = closestOrThrow(checkbox, '.astryx-item'); + fireEvent.pointerDown(checkbox, {pointerType: 'mouse', button: 0}); + expect(row.style.getPropertyValue(PAINT)).toBe(''); + fireEvent.pointerUp(checkbox, {pointerType: 'mouse', button: 0}); + fireEvent.pointerDown(screen.getByRole('button', {name: 'Nested'}), { + pointerType: 'mouse', + button: 0, + }); + expect(row.style.getPropertyValue(PAINT)).toBe('var(--_nested-press-rest)'); + }); + + it('keeps the press paint of a Token for a press on its own action', () => { + render( {}} onRemove={() => {}} />); + const token = closestOrThrow(screen.getByText('Surface'), '.astryx-token'); + const action = token.querySelector(':scope > button'); + if (!(action instanceof HTMLElement)) { + throw new Error('no own action in the token'); + } + fireEvent.pointerDown(action, {pointerType: 'mouse', button: 0}); + expect(token.style.getPropertyValue(PAINT)).toBe(''); + }); + + it('keeps the press paint of an Item row whose root is a link, since a press on its nested control runs the row', () => { + function RowLink(props: {href?: string; children?: ReactNode}) { + return ; + } + render( + } />, + ); + const nested = screen.getByRole('button', {name: 'Nested'}); + fireEvent.pointerDown(nested, {pointerType: 'mouse', button: 0}); + expect( + closestOrThrow(nested, '.astryx-item').style.getPropertyValue(PAINT), + ).toBe(''); + }); +}); diff --git a/packages/core/src/hooks/useClickableContainer.doc.mjs b/packages/core/src/hooks/useClickableContainer.doc.mjs index 92abfabcbf1b8..9598c880ac6f3 100644 --- a/packages/core/src/hooks/useClickableContainer.doc.mjs +++ b/packages/core/src/hooks/useClickableContainer.doc.mjs @@ -4,7 +4,17 @@ export const docs = { name: 'useClickableContainer', displayName: 'useClickableContainer', - keywords: ['click', 'container', 'card', 'pressable', 'interactive', 'nested', 'link', 'button', 'delegate'], + keywords: [ + 'click', + 'container', + 'card', + 'pressable', + 'interactive', + 'nested', + 'link', + 'button', + 'delegate', + ], params: [ { name: 'options', @@ -21,25 +31,29 @@ export const docs = { { name: 'options.interactiveRef', type: 'RefObject', - description: 'Ref to the primary interactive element inside (link, button). If no onClick or href is provided, clicks are proxied to this element.', + description: + 'Ref to the primary interactive element inside (link, button). If no onClick or href is provided, clicks are proxied to this element.', required: false, }, { name: 'options.onClick', type: '(event: MouseEvent) => void', - description: 'Click handler fired when the container surface (not a nested interactive element) is clicked.', + description: + 'Click handler fired when the container surface (not a nested interactive element) is clicked.', required: false, }, { name: 'options.href', type: 'string', - description: 'Navigation URL. When provided, clicking the container navigates to this URL.', + description: + 'Navigation URL. When provided, clicking the container navigates to this URL.', required: false, }, { name: 'options.target', type: 'string', - description: "Link target (e.g., '_blank'). Used with href for navigation behavior.", + description: + "Link target (e.g., '_blank'). Used with href for navigation behavior.", required: false, }, { @@ -59,22 +73,40 @@ export const docs = { { name: 'onMouseUp', type: '(event: MouseEvent) => void', - description: 'Mouse up handler to attach to the container (handles middle-click navigation for href).', + description: + 'Mouse up handler to attach to the container (handles middle-click navigation for href).', }, { name: 'onPointerDown', type: '(event: PointerEvent) => void', - description: 'Pointer down handler to attach to the container. On a container that paints its press with usePressFeedback, it drops a touch press that starts on a nested interactive element, which does not activate the container. A mouse :active press paint is unchanged. Without it, the container keeps its click rules and its pressed state for every press.', + description: + 'Pointer down handler to attach to the container. A press that starts on a nested interactive element does not activate the container, so the container shows no press for it: for a finger it drops the usePressFeedback press, and for a mouse or a pen it turns off the :active paint of the shared press styles (interactionOverlayStyles and the press styles). A press on the container itself paints as before. Without it, the container keeps its click rules and its pressed state for every press.', }, ], usage: { description: 'Makes a container element clickable while preserving nested interactive element behavior. Solves the "nested interactive elements" problem: when a card is clickable but contains buttons/links, clicking those should NOT trigger the card\'s action. Detects interactive ancestors between the click target and the container, and ignores text selections. Supports href navigation (including middle-click and Ctrl/Cmd+click for new tabs).', bestPractices: [ - { guidance: true, description: 'Attach onClick, onMouseUp and onPointerDown to the container element: full click handling including middle-click, and no touch pressed state for a press on a nested control.' }, - { guidance: true, description: 'Use inside ClickableCard or SelectableCard for the standard card interaction pattern.' }, - { guidance: true, description: 'For a pressable surface without Card chrome, such as a quoted message that jumps on press, compose it yourself: this hook on the surface; `usePressFeedback()` and `interactionOverlayStyles.backgroundColor` (from `@astryxdesign/core/utils`) on the same element for the hover tint and touch press; a native `