Skip to content

fix(press): a press on a control inside a card, row or token paints only the control, for every pointer - #12231

Draft
cixzhang wants to merge 29 commits into
mainfrom
l0/container-nested-press
Draft

cixzhang wants to merge 29 commits into
mainfrom
l0/container-nested-press

Conversation

@cixzhang

@cixzhang cixzhang commented Nov 17, 2026 •

Copy link
Copy Markdown
Contributor

User impact

  • Who: anyone using a mouse or a pen on a ClickableCard, SelectableCard, Item row, TreeList row or Token that holds a control, such as a card with a button or a row with an end-content action.
  • Before: pressing that control also painted the whole card or row as pressed, while a finger on the same control pressed only the control. The surface the person was about to act on looked like the wrong one.
  • After: a press on the nested control paints only the control, for a mouse, a pen and a finger alike. The container keeps the look it had under the pointer, its hover tint included. A press on the container's own surface still paints the container.
  • Unchanged: an Item row whose root is a link, or that has a parent-supplied role, still paints for a press on its nested control, because that press runs the row. A delegated control (an Item's interactiveRef) and a Token's own button paint the container, as its own action. A held Space key still paints a control's press (a Button's).

Problem and solution fit

  1. Why does the container paint? A mouse or pen press paints at CSS :active, and a browser applies :active to every ancestor of the pressed element, so the container's :active arm matches too.
  2. Why does that harm the task? The pressed tint tells a person which surface their press acts on. A container tint during a press on its button says the press opens the card, and it doesn't.
  3. Why does that matter? The same press already behaves correctly under a finger: the shared container rule (cancelNestedPress) ends the press controller's paint for a press that starts on a nested control. Mouse and pen presses were the gap.

The fix extends that same rule to a mouse and a pen. A press that starts on a nested control, other than the container's own action, sets --_nested-press-paint on the container until the press ends. The shared press styles' :active arms paint var(--_nested-press-paint, <pressed overlay>). Each style also declares --_nested-press-rest, its look at rest under the pointer, and the mark points the container's paint at that. Each style resets --_nested-press-paint on its own element, so a nested control, a nested row or a nested card keeps its own press. The press keeps :active timing; only where it paints changes.

Expected behavior and authority

Smallest restoration

  • hooks/useClickableContainer.ts: cancelNestedPress marks the container for a primary mouse or pen press on a nested control and clears the mark at the release, a cancel, or the container's next press. It no longer needs the press-box check, since the rule now covers every pointer.
  • utils/interactionOverlay.stylex.ts and privateAttributes/press.stylex.ts: the :active arms read the custom property; each style resets it and declares its rest look.
  • ClickableCard.tsx and SelectableCard.tsx: the cards' own overlay arms do the same.
  • No new data attribute, prop, export or default. Hover, the finger path and :active timing are unchanged. Moving mouse presses onto the press engine (INV5) stays out of scope.

Evidence

  • Reproduction before the change: __tests__/nestedControlPress.test.tsx fails on the base for all five containers, for both a mouse and a pen (the container is never marked). hooks/useClickableContainer.test.tsx "turns off the container’s press paint for a mouse or pen press…" fails on the base.
  • Result after the change: those jsdom tests pass at this head (53 of 53 across the two files). __tests__/NestedControlPress.a11y.chromium.spec.ts checks the presented pixels in Chromium for each container:
    • a mouse, a pen and a finger press on the nested control leave the container's pixel as it was under the pointer;
    • a mouse press on the container's surface paints it;
    • a held Space key on a standalone Button paints its press until the release.
      Real-Chrome stills follow below once the run finishes.
  • Representative unchanged path: the Button, List, CheckboxList, RadioList, Thumbnail, Item, TreeList, Token, card, hook, util and press-style suites pass (176 files, 3,882 tests). scripts/build-css.test.mjs still finds the shared overlay's pressed arm after its hover arm at equal specificity, and the bare pressed rule for touch.
  • Regression test or other mutation-sensitive proof: removing the mark in cancelNestedPress fails the jsdom tests. Removing the var() read from an arm fails that container's Chromium case.

Records

  • architecture:press-feedback:
    • INV5 gains one sentence: a key press that activates a control on release (Space) paints its press until release, through the same recipe; a key that activates on key down (Enter) paints no press.
    • The readiness row drops the INV7 gap note, since this change closes it. It names a new INV5 gap instead: a held Space on a container's own action paints no press on the container yet. Chromium gives a key's :active only to the focused element, and that was so before this change; a follow-up pull request fixes it.
  • component:ClickableCard FR5, component:SelectableCard FR4, component:Item FR9, component:TreeList FR7 and component:Token FR6 drop their mouse-and-pen gap notes. Their verification rows name the new tests and the finger, pen and mouse cases. Item's row keeps a gap for a row with a parent-supplied role.

Writing rubric results

Records touched: architecture:press-feedback; component:ClickableCard, component:SelectableCard, component:Item, component:TreeList, component:Token (gap notes and verification rows).

  • Present tense, system only: both edits describe behavior. No history, pull requests or status.
  • One topic per sentence; active voice: yes.
  • Claims are checkable: the Space half of the INV5 key-press sentence is checked by the Chromium Button Space case, and its container gap is named. Its Enter half (no press paint on key down) records existing behavior and has no case in this change. INV7 and the five component rules are checked by the nested-control cases.
  • No new terms: "recipe" and "control" are the record's own terms.

Scope

Components: ClickableCard, SelectableCard, Item, TreeList, Token, useClickableContainer, interactionOverlay, press styles

  • One defect is restored.
  • Separable contradictory or unsettled tagalongs were removed or split.
  • No new public API, visual representation, default, or interaction model is hidden under the bug-fix label.
  • Public text and artifacts contain no internal Meta context.

Testing

  • vitest run packages/core/src/__tests__/nestedControlPress.test.tsx packages/core/src/hooks/useClickableContainer.test.tsx: red on the base for the mouse and pen cases, green here; the finger case per container passes on both.
  • vitest run over hooks, ClickableCard, SelectableCard, Item, TreeList, Token, List, CheckboxList, RadioList, Button, utils, privateAttributes and Thumbnail: 3,882 pass. One Tokenizer bottom-sheet announcement case timed out under machine load; it passes alone.
  • scripts/build-css.test.mjs: pass. TypeScript, ESLint, check:knowledge, check:changesets and the private-attribute baseline: clean.
  • playwright test NestedControlPress.a11y.chromium.spec.ts (Chromium, desktop and phone contexts): on the base the 10 mouse and pen nested cases fail; at this change they pass, with the finger, surface and Button Space cases passing on both. Stills follow at that later head.

Builds on cixzhang's draft in #9930, which marked the cards for a mouse press.

#12115, the record this implements, has merged; main is merged in. In the merge order this PR follows the device-tested pull requests #11813, #10062, #8200, #9777 and #8206, #8084 and #10462, whose device evidence it would void, and takes its real-Chrome stills at that head.

Overlap checked: #12115 (base of this stack; records only), #9930 (closed draft this supersedes)

Owner: Astryx fix-loop lane 0. Land path: CodeBunny approval of the exact head, Specs stamp, CI, then the merge queue after #12115.

… cards stop painting for nested mouse presses
…en Remove cases; scope each gap to what is untested
…nly the control, for every pointer

A browser applies :active to every ancestor of the pressed element, so a
mouse or pen press on a control inside a ClickableCard, SelectableCard,
Item row, TreeList row or Token also painted the container. The
container rule, which already stopped a finger's press there, now marks
the container for a mouse or pen press too: the shared press styles read
--_nested-press-paint in their :active arms, and the marked container
paints its rest look instead, hover included. Each style resets the
property on its own element, so the nested control keeps its own press.

press-feedback INV5 states that a key press that activates a control
paints its press until release; INV7's gap note goes.

Builds on cixzhang's draft in #9930.
@vercel

vercel Bot commented Nov 17, 2026 •

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated
astryx Ready Ready Preview Nov 17, 2026 11:46am UTC

Request Review

@meta-cla meta-cla Bot added the CLA Signed This label is managed by the Meta Open Source bot. label Nov 17, 2026
@astracat-bot

astracat-bot Bot commented Nov 17, 2026 •

Copy link
Copy Markdown
Contributor

AI review status for this pull request.

Review status Updated
🟢 Reviewed (for maintainers only) Nov 17, 2026, 12:06 PM UTC

@cixzhang cixzhang added the lane:0 Astryx fix-loop lane 0 owns this label Nov 17, 2026
@cixzhang

Copy link
Copy Markdown
Contributor Author

/approve-spec 3270bc6

@astracat-bot astracat-bot Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Changes requested: five component records still describe the gap this change closes.

The fix itself works: in Chromium, a mouse press on the nested control leaves ClickableCard, SelectableCard, the Item row, the TreeList row and Token at their hover tint, a press on the container's own surface still paints it, and the new jsdom tests fail on the base and pass here.

  • The ClickableCard (FR5), SelectableCard (FR4), Item (FR9), TreeList (FR7) and Token (FR6) records still say a mouse or pen press on a nested control paints the container, and the Item and Token verification rows still list those cases as untested, so drop the five gap sentences and point those rows at the new tests, as this pull request already does for the press-feedback record, then re-approve the records at the new head.

Smaller points: nothing checks the Enter half of the new INV5 sentence, and the Chromium results the description promises are not posted yet. This lands only after #12115, whose records it implements.

Claims and files checked

Review mode: full; reason: no-earlier-review

Claims:

  • Changeset: a mouse or pen press on a control inside the five containers paints only the control: verified (Chromium mouse captures; jsdom mouse and pen tests).
  • Changeset: the container keeps its hover look: verified (its surface keeps the hover value during the press).
  • Changeset: a press on the container's own surface still paints it, and a link-root Item row still paints: verified (surface capture; jsdom link-root case).
  • Description: before, a mouse or pen press on the nested control painted the container while a finger did not: verified (base captures; the base rule skipped non-touch presses).
  • Description: link-root and parent-role Item rows, an Item's delegated control and Token's own button still paint the container: verified (jsdom cases; a parent-role row gets no handler).
  • Description: a held Space key still paints a control's and a container's action press: verified by code (no key handling changed); the pull request's Chromium cases are not reported yet.
  • Description: the mark is set on pointerdown and cleared at release, cancel or the next press, and the press-box check is gone: verified (code and jsdom).
  • Description: the shared press styles read the property in their :active arms, reset it on their own element and declare a rest look: verified (code).
  • Description: no new data attribute, prop, export or default; hover, the finger path and :active timing unchanged: verified (source diff; hover frames identical).
  • Description: the new jsdom tests fail on the base and pass here (47): verified (20 of 47 fail on the base; all pass on the head).
  • Description: the Chromium spec checks the presented pixels, with results to follow: the checks are as described; results not posted (this review's own captures cover the mouse cases).
  • Description: the wider suites, the build-css guard, typecheck, lint and repository checks pass: partly verified (436 tests in 14 neighbouring files and the build-css test pass here; the rest not rerun).
  • Description: removing the mark fails the jsdom tests: verified (the base, without it, fails them); removing the var() read fails the Chromium case: not rerun (base frames, without it, paint the container).
  • Description: the INV7 gap note goes because this change closes it: true for the press-feedback record, but the same gap stays in five component records (blocking finding).
  • Description: the INV5 sentence is checked by the Space-key cases: partly; nothing checks the Enter half.

Files:

  • .changeset/nested-control-press-every-pointer.md: clear
  • apps/storybook/stories/NestedControlPress.stories.tsx: clear
  • docs/architecture/press-feedback.md: finding (the component records keep the gap it removes)
  • packages/core/src/ClickableCard/ClickableCard.nestedPress.test.tsx: clear
  • packages/core/src/ClickableCard/ClickableCard.tsx: clear
  • packages/core/src/SelectableCard/SelectableCard.tsx: clear
  • packages/core/src/__tests__/NestedControlPress.a11y.chromium.spec.ts: clear (results not posted)
  • packages/core/src/__tests__/nestedControlPress.test.tsx: clear
  • packages/core/src/hooks/useClickableContainer.test.tsx: clear
  • packages/core/src/hooks/useClickableContainer.ts: clear (one comment-wording suggestion)
  • packages/core/src/privateAttributes/press.stylex.ts: clear
  • packages/core/src/utils/interactionOverlay.stylex.ts: clear
  • scripts/build-css.test.mjs: clear
  • The other 150 files: carried unchanged from main by a merge of main (identical to main), not this pull request's changes

Automated review (maintainer link)

Comment thread docs/architecture/press-feedback.md Resolved
}

/**
* The custom property that turns off a container's `:active` press paint. The

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Non-blocking (comment style): the second sentence of this JSDoc runs to 30 words. A shorter form: "The SYNC styles paint the pressed overlay as var(--_nested-press-paint, <pressed overlay>). Each resets it to initial on its own element, so a nested control keeps its press."

…ress

# Conflicts:
#	docs/architecture/press-feedback.md
…d-control press gaps close

Each record drops its mouse-and-pen gap note, and its verification row
names the tests that press a nested control with a finger, a pen and a
mouse. The jsdom test adds the finger case for each container.
…ction paints no container press yet

Chromium gives a key's :active only to the focused element, so a card's
or row's hidden action paints nothing on the container. The readiness
row names the gap; the real-browser spec keeps the Button's held-Space
guard and leaves the containers' cases to the follow-up.
@cixzhang
cixzhang changed the base branch from specs/press-feedback-recipes to main November 17, 2026 05:46
@cixzhang

Copy link
Copy Markdown
Contributor Author

/approve-spec 8b27ee4

@astracat-bot astracat-bot Bot left a comment •

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Changes requested: the fix works, but three pieces of text still describe the old behavior.

In Chromium, a mouse press on the nested control now leaves ClickableCard, SelectableCard, the Item row, the TreeList row and Token at their hover tint, a press on the container's own surface still paints it, and the new jsdom tests fail on main and pass here. Once the points below are fixed, this can be approved pending CI.

  • Miss: packages/core/src/hooks/useClickableContainer.doc.mjs still says at lines 67 and 102 that a mouse :active press paint is unchanged, so builders who compose the documented interactionOverlayStyles recipe are told the opposite of what ships; update both onPointerDown descriptions to match the new JSDoc.
  • docs/specs/components/Token/Token.spec.md:252 names the new tests for a pen and a mouse press on Remove, but its Gap sentence still says no test asserts that case, so drop that clause.
  • The description says the two new test files pass 47/47 although they hold 53 tests at this head, and says the Button Space case checks the new INV5 sentence although nothing checks its Enter half, so correct the count and either add an Enter case or narrow that line.
Claims and files checked

Review mode: same-head; reason: none

Claims

  • A mouse or pen press on a control inside the five containers no longer paints the container, as a finger's press already did: verified (jsdom tests fail on the base and pass here; Chromium press frames).
  • The container keeps its hover look: verified (cards and rows stay at the hover tint in Chromium).
  • A press on the container's own surface still paints it, and a link-root Item row still paints for a nested press: verified (Chromium surface press; jsdom link-root case).
  • A parent-role Item row still paints for a nested press: verified by code (the row gets no nested-press handler).
  • A delegated control and Token's own button paint the container: verified (jsdom cases).
  • A held Space key still paints a Button's press: verified (Chromium probe, both trees).
  • The cause is :active reaching every ancestor, and the container rule already covered the finger: verified (the base's early return for non-touch presses; base frames).
  • The mark lasts until the release, a cancel or the container's next press, and the press-box check is gone: verified (useClickableContainer.ts:152-215).
  • The shared styles and both cards read the mark, reset it and declare their rest look: verified.
  • No new data attribute, prop, export or default; hover, the finger path and :active timing are unchanged: verified (one existing export's type gains two private keys).
  • The new tests fail on the base for all five containers, mouse and pen: verified (20 of 53 fail on the base).
  • Those tests pass 47/47: false (53 tests at this head, all passing).
  • The Chromium spec covers mouse, pen, finger, surface and the Button's Space press: verified by reading the spec; not run.
  • The neighbouring suites pass: verified at this head.
  • The CSS build test still finds the shared overlay's arms: verified (16 tests pass).
  • Removing the mark fails the jsdom tests: verified (the base run).
  • The records add the Space sentence, drop the nested-press gap and name the held-Space container gap, which predates this change: verified (records; Chromium probe on both trees).
  • Five component records drop their gap notes and name the new tests: false for Token, whose verification row keeps the Remove gap.
  • The new key-press sentence is checked by the Button Space case: false for its Enter half.
  • TypeScript, ESLint, the knowledge check and the changeset check are clean: verified (core typecheck, ESLint on the changed files, both checks).
  • Changeset: a mouse or pen press on a nested control paints only that control, the container keeps its hover look, and surface and link-root presses still paint: verified, with a wording note on Token's Remove.

Files

  • .changeset/nested-control-press-every-pointer.md: clear (non-blocking wording note on Token's Remove).
  • apps/storybook/stories/NestedControlPress.stories.tsx: clear.
  • docs/architecture/press-feedback.md: clear.
  • docs/specs/components/ClickableCard/ClickableCard.spec.md: clear.
  • docs/specs/components/Item/Item.spec.md: clear.
  • docs/specs/components/SelectableCard/SelectableCard.spec.md: clear.
  • docs/specs/components/Token/Token.spec.md: finding (verification row keeps a tested case as a gap).
  • docs/specs/components/TreeList/TreeList.spec.md: clear.
  • packages/core/src/ClickableCard/ClickableCard.nestedPress.test.tsx: clear.
  • packages/core/src/ClickableCard/ClickableCard.tsx: clear.
  • packages/core/src/SelectableCard/SelectableCard.tsx: clear.
  • packages/core/src/__tests__/NestedControlPress.a11y.chromium.spec.ts: clear.
  • packages/core/src/__tests__/nestedControlPress.test.tsx: clear.
  • packages/core/src/hooks/useClickableContainer.test.tsx: clear.
  • packages/core/src/hooks/useClickableContainer.ts: finding (its published doc file still describes the old mouse behavior); non-blocking comment-length note.
  • packages/core/src/privateAttributes/press.stylex.ts: clear.
  • packages/core/src/utils/interactionOverlay.stylex.ts: clear.
  • scripts/build-css.test.mjs: clear.

Automated review (maintainer link)

@github-actions github-actions Bot added the needs:spec-owner-review Current knowledge records await owner approval label Nov 17, 2026
@cixzhang

Copy link
Copy Markdown
Contributor Author

/approve-spec 62e8b70

@github-actions github-actions Bot removed the needs:spec-owner-review Current knowledge records await owner approval label Nov 17, 2026
@github-actions

Copy link
Copy Markdown
Contributor

PR Analysis Report

Current run: The current CI run concluded skipped. Current analysis is unavailable.


Generated by PR Enrichment workflow | View current CI run

@astracat-bot astracat-bot Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Approved pending CI: CI has not run on this head yet.

The fix holds: in Chromium, a mouse press on the nested control now leaves ClickableCard, SelectableCard, the Item and TreeList rows and Token at their hover tint, a press on the card's own surface still paints it, and the new jsdom tests fail on main and pass here. The three text issues from the last review (the hook docs, Token's verification row and the description) are fixed.

Non-blocking:

  • The changeset says a press "now paints only that control", but Token's Remove button has no press paint of its own, so nothing on screen changes for it; "shows no pressed state on the container" matches what ships.
  • A few new comments run past the 25-word sentence limit (useClickableContainer.ts:140-143, ClickableCard.tsx:100-102, SelectableCard.tsx:120-122).
Claims and files checked

Review mode: full; reason: spec-record

Claims:

  • A mouse or pen press on a nested control no longer paints ClickableCard, SelectableCard, Item rows, TreeList rows or Token, matching the finger: verified (new jsdom cases fail on the base and pass here; Chromium frames for all five).
  • The container keeps its hover look, and a press on its own surface still paints it: verified (Chromium hover tint kept; surface press paints on both trees).
  • Link-root and parent-role Item rows, delegated controls and Token's own button still paint for their own press: verified (jsdom cases; the parent-role row gets no handler in Item.tsx).
  • A held Space still paints a Button's press: verified (Chromium, identical on both trees).
  • Only where the press paints changes; hover, the finger path and :active timing are unchanged, with no new data attribute, prop, export or default: verified (diff; the one public type change is two private keys on interactionOverlayStyles).
  • The new tests fail on the base for every container and pointer, and 53 of 53 pass here: verified (20 of 53 fail on the base).
  • The neighbouring suites and the CSS order guard pass: verified (177 files, 3,889 tests; build-css.test.mjs 16 tests).
  • TypeScript, ESLint, the knowledge check, the changeset check and the private-attribute baseline are clean: verified.
  • The Chromium spec's mouse, surface and Space cases fail or pass as described: verified by this review's own Chromium capture; its pen and finger cases were not re-run here.
  • The press-feedback record gains the Space and Enter sentence, drops the nested-press gap and names a held-Space container gap; five component records drop their gap notes and name the new tests: verified (the Enter half has no test, as the description says).
  • Changeset: a mouse or pen press on a nested control paints only that control, the container keeps its hover, and its own surface and link-root rows still paint: verified, with the Remove wording note above.

Files:

  • .changeset/nested-control-press-every-pointer.md: non-blocking wording note.
  • apps/storybook/stories/NestedControlPress.stories.tsx: clear.
  • docs/architecture/press-feedback.md: clear.
  • docs/specs/components/ClickableCard/ClickableCard.spec.md: clear.
  • docs/specs/components/Item/Item.spec.md: clear.
  • docs/specs/components/SelectableCard/SelectableCard.spec.md: clear.
  • docs/specs/components/Token/Token.spec.md: clear.
  • docs/specs/components/TreeList/TreeList.spec.md: clear.
  • packages/core/src/ClickableCard/ClickableCard.nestedPress.test.tsx: clear.
  • packages/core/src/ClickableCard/ClickableCard.tsx: non-blocking comment length.
  • packages/core/src/SelectableCard/SelectableCard.tsx: non-blocking comment length.
  • packages/core/src/__tests__/NestedControlPress.a11y.chromium.spec.ts: clear.
  • packages/core/src/__tests__/nestedControlPress.test.tsx: clear.
  • packages/core/src/hooks/useClickableContainer.doc.mjs: clear.
  • packages/core/src/hooks/useClickableContainer.test.tsx: clear.
  • packages/core/src/hooks/useClickableContainer.ts: non-blocking comment length.
  • packages/core/src/privateAttributes/press.stylex.ts: clear.
  • packages/core/src/utils/interactionOverlay.stylex.ts: clear.
  • scripts/build-css.test.mjs: clear.

Automated review (maintainer link)

'@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.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Non-blocking: Token's Remove button has no press paint of its own, so after this change a mouse press on it shows no press anywhere; "now paints only that control" reads as if Remove lights up. "shows no pressed state on the container" matches what ships.

This branch was successfully deployed

1 active deployment
Preview — 62e8b705 Deployed Nov 17, 2026 by vercel[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

CLA Signed This label is managed by the Meta Open Source bot. lane:0 Astryx fix-loop lane 0 owns this needs:design-review Affects visuals — Design should review

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant