From fcd23bd64c959dc5eb210c9f4941189065c2b215 Mon Sep 17 00:00:00 2001 From: Cindy Zhang Date: Mon, 16 Nov 2026 09:20:10 -0800 Subject: [PATCH 01/24] docs(architecture): press feedback has one engine and three recipes --- docs/architecture/press-feedback.md | 151 ++++++++++++++++++++++++++++ 1 file changed, 151 insertions(+) create mode 100644 docs/architecture/press-feedback.md diff --git a/docs/architecture/press-feedback.md b/docs/architecture/press-feedback.md new file mode 100644 index 0000000000000..d1163d9053675 --- /dev/null +++ b/docs/architecture/press-feedback.md @@ -0,0 +1,151 @@ +--- +schema_version: 1 +template_version: 1 +kind: architecture +id: architecture:press-feedback +authority: current +archive_reason: null +superseded_by: null +approved_by: cixzhang +approved_at: 2026-11-16 +owners: [cixzhang] +applies_to: + [ + packages/core/src/utils/pressFeedback.ts, + packages/core/src/hooks/usePressFeedback.ts, + packages/core/src/privateAttributes/press.ts, + packages/core/src/privateAttributes/press.stylex.ts, + packages/core/src/privateAttributes/pressBox.stylex.ts, + packages/core/src/privateAttributes/pressGroupItem.stylex.ts, + packages/core/src/privateAttributes/pressHeld.stylex.ts, + packages/core/src/privateAttributes/pressHoldsDrag.stylex.ts, + packages/core/src/privateAttributes/menuPressLit.stylex.ts, + packages/core/src/hooks/useGroupPressTracking.ts, + packages/core/src/gestures/PressTracker.ts, + packages/core/src/hooks/useMenuPress.ts, + ] +verified_by: + [ + packages/core/src/utils/pressFeedback.test.ts, + packages/core/src/privateAttributes/press.test.ts, + ] +deciding_specs: [spec:AST-094/FR5, spec:AST-094/FR11, spec:AST-094/DEC-21] +--- + +# Press feedback architecture + +## Contract at a glance + +| Area | Contract | +| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Governing contract | How a press looks and when it shows: `spec:AST-094` FR5, FR8, FR11, FR20 and DEC-21; `design:user-states` DR1–DR5; `design:reduced-motion` DR1–DR2; `architecture:layer-runtime` INV22; `component:Item` FR9. | +| System behavior | One press engine, the page press controller, writes every pressed state in Core. Each pressable surface uses one of three recipes: a momentary control, a row-wide target, or a cell or menu row. A press paints and does nothing else: it never changes layout, the hit area, or hit-testing. Every release fades on the theme's exit motion tokens. A coarse first press paints in the frame the finger lands. | +| End-user impact | A person sees the same press on every Astryx surface: the same tint, the same start delay inside scrolling content, the same release fade, and the same cancel when a scroll takes the touch. A press never moves a tap target, so a tap lands where the person aims it. | +| Builder impact | A component picks a recipe and states it in its own record. It adds no press attribute, tracker, timer, or tint variable of its own. A press fix lands once, in the engine or the recipe, and reaches every component that uses it. No public API changes; the recipes are exports of the private press modules. | +| Compatibility/readiness | No public API change. INV1 gap: the group tracker, the touch-runtime press tracker, the menu lit-row attribute, and local copies in ClickableCard, SelectableCard, Thumbnail, Tab, Switch, Slider and the Selector-family triggers write their own press state. INV4 gap: Switch, Slider and the SegmentedControl lens release in a fixed 200 ms, and controller surfaces end a press after 10 px of drift outside scrolling content. INV5 gap: under a mouse or a pen, most surfaces paint CSS `:active`. INV8 gap: Selector-family triggers scale under reduced motion. | +| Review checks | Reject a new press attribute, tracker, timer, or tint variable outside the recipes; a press style that changes layout, the containing block, or the hit area; a fixed release duration; a container that paints for a finger or pen press that starts on a nested interactive element; and press engine code moved off first load. | +| Governing rules | `spec:AST-094` FR5, FR8, FR11, FR20, DEC-14, DEC-21; `design:user-states` DR1–DR5; `design:reduced-motion` DR1–DR2; `architecture:layer-runtime` INV22; `component:Item` FR9; `component:Button` anatomy and FR15; `module:DropdownMenu/useMenuPress` FR6; `architecture:component-import-boundaries` INV10; `spec:AST-013` FR9. | + +## Purpose + +This record owns the shared press code. Component records name the recipe they +use and state only what differs for them. The rules for how a press looks and +when it shows stay in their deciding records; this record says how Core builds +them once. + +## System model + +The engine is the page press controller (`usePressFeedback` and +`utils/pressFeedback.ts`). It finds the innermost element marked pressable, +writes the private press attribute (`on`, then `fading`), starts the delay +timer, and ends the press on a release, a cancel, or a scroll that takes the +touch. The recipe styles paint from that attribute. + +| Recipe | Used by | What paints | Start | End | +| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ | +| 1. Momentary control | Button family, Link, Switch, Tab, Token, SegmentedControl segment, navigation items, Selector-family triggers, Step, Calendar day | The system pressed tint on the control's own press layer. A standalone control may also scale, as its record states. Option: keeps its press through a drag (Slider thumb, SegmentedControl lens, Switch thumb; `design:user-states` DR4). | Touch-down outside scrolling content; 150 ms after touch-down inside it (`spec:AST-094` FR11). | The lift, with the release fade. A scroll that takes the touch ends it with no fade. | +| 2. Row-wide target | Item and ListItem, TreeList rows, CheckboxList and RadioList rows, Collapsible trigger, ClickableCard, SelectableCard, Thumbnail; a control whose caller stretches it across a row (its root static and its `::after` covering the row, `component:Button` anatomy and FR17), which tints the row it covers | The pressed tint on the whole row or card, only for a press that would activate it. A press on a row's own box presses the row (`component:CheckboxListItem` AR3). | As recipe 1. | As recipe 1. | +| 3. Cell or menu row | Menu rows, picker options, Table cells, CommandPalette rows | The pressed tint on the row. At most one row of a menu is lit; a sliding finger moves the light (`module:DropdownMenu/useMenuPress` FR6). | 150 ms after touch-down inside scrolling content; at once in a menu whose rows fit (`spec:AST-094` DEC-14). | The lift acts on the lit row. A scroll that takes the touch ends it with no fade. | + +## Boundaries and invariants + +- **INV1 — One engine.** The page press controller is the only code that + writes a pressed state in Core. A group slide, a press held through a drag, + and a menu's lit row are profiles of that engine. A component adds no press + attribute, tracker, timer, or tint variable of its own. +- **INV2 — Three recipes.** Every pressable Core surface uses one recipe from + the table above, and its record names the recipe. The recipes are exports of + the private press modules; they add no module and no public API. +- **INV3 — A press only paints.** A press never changes layout, an element's + size, the containing block of a descendant, the hit area, or hit-testing. It + never writes a caller's `::before` or `::after`. A layer anchors to its + trigger's untransformed box (`architecture:layer-runtime` INV22). +- **INV4 — One timing source.** Every profile reads its start delay, cancel, + and release from the engine. A press ends when a scroll takes the touch + (`spec:AST-094` FR20), or when the pointer leaves the target by more than the + control profile's tracking margin of 70 px. Every release that fades plays + the theme's exit motion tokens, with the reduced-motion treatment of + `design:reduced-motion` DR2 (`spec:AST-094` FR5, FR8). No profile uses a + fixed duration. +- **INV5 — Every pointer through the engine.** A mouse or pen press paints at + once on `pointerdown` through the engine, with the same release fade as a + finger's, in place of CSS `:active` (`spec:AST-094` DEC-21). +- **INV6 — The first press.** The engine's core stays on first load: it finds + the pressable element, writes the attribute, starts the delay timer, and + ends the press on a scroll. A coarse first press paints in the frame the + finger lands; this code never moves into the deferred touch runtime. + Optional profiles (the group slide, the menu scrub, a press held through a + drag, a row's box hold) load with their opt-in or with the touch runtime and + cost an unused page at most what `architecture:component-import-boundaries` + INV10 allows. Before an optional profile loads, each pressable keeps its own + press. Nothing is painted into server HTML that has not hydrated + (`spec:AST-013` FR9). +- **INV3a — A stretched control.** When a caller stretches a control across a + row, the control's own press layer covers the same box as its hit area: a + press tints the row it covers, and the whole row stays the tap target for the + whole press. +- **INV7 — A nested control.** In recipe 2, a finger or pen press that starts + on a nested interactive element paints that element only and never its row + or card (`component:Item` FR9). A mouse press there keeps the container's + press paint as `component:ClickableCard` FR5 states. +- **INV8 — Reduced motion and disabled.** Under reduced motion no press + scales (`design:reduced-motion` DR1). A disabled surface paints no press + (`design:user-states` DR2). A control whose own popup is open does not scale + (`component:Button` FR15). + +## Change coupling + +- A change to the engine's timing, cancel, or release changes every recipe at + once; update this record and the evidence for each recipe together. +- A new pressable component names its recipe in its own record. A component + that needs behavior no recipe covers amends this record before it builds. +- A component record that restates a rule here points at the recipe instead. + +## Owning code + +- Engine: `packages/core/src/utils/pressFeedback.ts`, + `packages/core/src/hooks/usePressFeedback.ts`. +- Recipe styles and attribute: `packages/core/src/privateAttributes/press.ts` + and the `press*.stylex.ts` modules beside it. +- Profiles to fold into the engine: `packages/core/src/hooks/useGroupPressTracking.ts`, + `packages/core/src/gestures/PressTracker.ts`, `packages/core/src/hooks/useMenuPress.ts`. + +## Deciding specs + +- `spec:AST-094` FR5, FR11, DEC-21: the release, the press profiles, and the + fine-pointer profile. +- Owner decision (`cixzhang`, 2026-11-16): one record for the press code that + ships, with three recipes, no new module, and no public API change. + +## Verification + +| Invariant | Evidence | Failure signal | +| --------- | ----------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------ | +| INV1 | Review: no new press attribute, tracker, or tint variable outside the recipe modules | A component writes its own pressed state | +| INV2 | Each pressable component record names its recipe | A record restates press rules without a recipe | +| INV3 | `pressFeedback.test.ts`; a browser test that a point inside a caller's stretched target still hits during a press | A tap during a press misses its target, or layout shifts | +| INV4 | Computed release durations follow the theme's exit tokens and tempo on every recipe | A fixed duration, or two surfaces that cancel the same drift differently | +| INV5 | A mouse press test per recipe asserts the press attribute, not `:active` | A mouse press paints with no shared release fade | +| INV6 | Size report: the engine core is on first load; a first-touch browser test paints in the landing frame | A first finger press paints late or not at all | +| INV7 | A press on a nested control in a row and in a card, for finger, pen, and mouse | A finger or pen press on a nested control paints the container | +| INV8 | Reduced-motion and disabled press tests per recipe | A scale under reduced motion, or paint on a disabled surface | From 854a0e939ce8dd16d1295531cb610bacf5421207 Mon Sep 17 00:00:00 2001 From: Cindy Zhang Date: Mon, 16 Nov 2026 09:25:05 -0800 Subject: [PATCH 02/24] docs(architecture): press feedback review fixes (per-recipe tracking, first-load scope, INV9) --- docs/architecture/press-feedback.md | 92 ++++++++++++++--------------- 1 file changed, 46 insertions(+), 46 deletions(-) diff --git a/docs/architecture/press-feedback.md b/docs/architecture/press-feedback.md index d1163d9053675..bc0bc20e63c23 100644 --- a/docs/architecture/press-feedback.md +++ b/docs/architecture/press-feedback.md @@ -1,6 +1,6 @@ --- schema_version: 1 -template_version: 1 +template_version: 3 kind: architecture id: architecture:press-feedback authority: current @@ -36,15 +36,15 @@ deciding_specs: [spec:AST-094/FR5, spec:AST-094/FR11, spec:AST-094/DEC-21] ## Contract at a glance -| Area | Contract | -| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Governing contract | How a press looks and when it shows: `spec:AST-094` FR5, FR8, FR11, FR20 and DEC-21; `design:user-states` DR1–DR5; `design:reduced-motion` DR1–DR2; `architecture:layer-runtime` INV22; `component:Item` FR9. | -| System behavior | One press engine, the page press controller, writes every pressed state in Core. Each pressable surface uses one of three recipes: a momentary control, a row-wide target, or a cell or menu row. A press paints and does nothing else: it never changes layout, the hit area, or hit-testing. Every release fades on the theme's exit motion tokens. A coarse first press paints in the frame the finger lands. | -| End-user impact | A person sees the same press on every Astryx surface: the same tint, the same start delay inside scrolling content, the same release fade, and the same cancel when a scroll takes the touch. A press never moves a tap target, so a tap lands where the person aims it. | -| Builder impact | A component picks a recipe and states it in its own record. It adds no press attribute, tracker, timer, or tint variable of its own. A press fix lands once, in the engine or the recipe, and reaches every component that uses it. No public API changes; the recipes are exports of the private press modules. | -| Compatibility/readiness | No public API change. INV1 gap: the group tracker, the touch-runtime press tracker, the menu lit-row attribute, and local copies in ClickableCard, SelectableCard, Thumbnail, Tab, Switch, Slider and the Selector-family triggers write their own press state. INV4 gap: Switch, Slider and the SegmentedControl lens release in a fixed 200 ms, and controller surfaces end a press after 10 px of drift outside scrolling content. INV5 gap: under a mouse or a pen, most surfaces paint CSS `:active`. INV8 gap: Selector-family triggers scale under reduced motion. | -| Review checks | Reject a new press attribute, tracker, timer, or tint variable outside the recipes; a press style that changes layout, the containing block, or the hit area; a fixed release duration; a container that paints for a finger or pen press that starts on a nested interactive element; and press engine code moved off first load. | -| Governing rules | `spec:AST-094` FR5, FR8, FR11, FR20, DEC-14, DEC-21; `design:user-states` DR1–DR5; `design:reduced-motion` DR1–DR2; `architecture:layer-runtime` INV22; `component:Item` FR9; `component:Button` anatomy and FR15; `module:DropdownMenu/useMenuPress` FR6; `architecture:component-import-boundaries` INV10; `spec:AST-013` FR9. | +| Area | Contract | +| ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Governing contract | How a press looks and when it shows: `spec:AST-094` FR5, FR8, FR11, FR20 and DEC-21; `design:user-states` DR1–DR5; `design:reduced-motion` DR1–DR2; `architecture:layer-runtime` INV22; `component:Item` FR9. | +| System behavior | One press engine, the page press controller, writes every pressed state in Core. Each pressable surface uses one of three recipes: a momentary control, a row-wide target, or a cell or menu row. A press paints and does nothing else: it never changes layout, the hit area, or hit-testing. Every release fades on the theme's exit motion tokens. A coarse first press paints in the frame the finger lands. | +| End-user impact | A person sees the same press on every Astryx surface: the same tint, the same start delay inside scrolling content, the same release fade, and the same cancel when a scroll takes the touch. A press never moves a tap target, so a tap lands where the person aims it. | +| Builder impact | A component picks a recipe and states it in its own record. It adds no press attribute, tracker, timer, or tint variable of its own. A press fix lands once, in the engine or the recipe, and reaches every component that uses it. No public API changes; the recipes are exports of the private press modules. | +| Compatibility/readiness | No public API change. INV1 gap: the group tracker, the touch-runtime press tracker, the menu lit-row attribute, and local copies in ClickableCard, SelectableCard, Thumbnail, Tab, Switch, Slider and the Selector-family triggers write their own press state. INV4 gap: Switch, Slider and the SegmentedControl lens release in a fixed 200 ms, and controller controls end a press after 10 px of drift outside scrolling content. INV2 gap: Table cells paint no press. INV5 gap: under a mouse or a pen, most surfaces paint CSS `:active`. INV8 gap: Selector-family triggers scale under reduced motion. | +| Review checks | Reject a new press attribute, tracker, timer, or tint variable outside the recipes; a press style that changes layout, the containing block, or the hit area; a fixed release duration; a container that paints for a finger or pen press that starts on a nested interactive element; and press engine code moved off first load. | +| Governing rules | `spec:AST-094` FR5, FR8, FR11, FR20, DEC-14, DEC-21; `design:user-states` DR1–DR5; `design:reduced-motion` DR1–DR2; `architecture:layer-runtime` INV22; `component:Item` FR9; `component:Button` anatomy and FR15; `module:DropdownMenu/useMenuPress` FR6; `architecture:component-import-boundaries` INV10; `spec:AST-013` FR9. | ## Purpose @@ -61,11 +61,11 @@ writes the private press attribute (`on`, then `fading`), starts the delay timer, and ends the press on a release, a cancel, or a scroll that takes the touch. The recipe styles paint from that attribute. -| Recipe | Used by | What paints | Start | End | -| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ | -| 1. Momentary control | Button family, Link, Switch, Tab, Token, SegmentedControl segment, navigation items, Selector-family triggers, Step, Calendar day | The system pressed tint on the control's own press layer. A standalone control may also scale, as its record states. Option: keeps its press through a drag (Slider thumb, SegmentedControl lens, Switch thumb; `design:user-states` DR4). | Touch-down outside scrolling content; 150 ms after touch-down inside it (`spec:AST-094` FR11). | The lift, with the release fade. A scroll that takes the touch ends it with no fade. | -| 2. Row-wide target | Item and ListItem, TreeList rows, CheckboxList and RadioList rows, Collapsible trigger, ClickableCard, SelectableCard, Thumbnail; a control whose caller stretches it across a row (its root static and its `::after` covering the row, `component:Button` anatomy and FR17), which tints the row it covers | The pressed tint on the whole row or card, only for a press that would activate it. A press on a row's own box presses the row (`component:CheckboxListItem` AR3). | As recipe 1. | As recipe 1. | -| 3. Cell or menu row | Menu rows, picker options, Table cells, CommandPalette rows | The pressed tint on the row. At most one row of a menu is lit; a sliding finger moves the light (`module:DropdownMenu/useMenuPress` FR6). | 150 ms after touch-down inside scrolling content; at once in a menu whose rows fit (`spec:AST-094` DEC-14). | The lift acts on the lit row. A scroll that takes the touch ends it with no fade. | +| Recipe | Used by | What paints | Start | End | +| -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ | +| 1. Momentary control | Button family, Link, Switch, Tab, Token, SegmentedControl segment, TopNavItem, SideNavItem, NavItem, Selector-family triggers, Step, Calendar day | The system pressed tint on the control's own press layer. A standalone control may also scale, as its record states. Option: keeps its press through a drag (Slider thumb, SegmentedControl lens, Switch thumb; `design:user-states` DR4). | Touch-down outside scrolling content; 150 ms after touch-down inside it (`spec:AST-094` FR11). | The lift, with the release fade. A scroll that takes the touch ends it with no fade. | +| 2. Row-wide target | Item and ListItem, TreeList rows, CheckboxList and RadioList rows, Collapsible trigger, ClickableCard, SelectableCard, Thumbnail; a control whose caller stretches it across a row (its root static and its `::after` covering the row; INV9) | The pressed tint on the whole row or card, only for a press that would activate it. A press on a row's own box presses the row (`component:CheckboxListItem` AR3). | As recipe 1. | As recipe 1. | +| 3. Cell or menu row | Menu rows, picker options, CommandPalette rows, Table cells (INV2 gap) | The pressed tint on the row. At most one row of a menu is lit; a sliding finger moves the light (`module:DropdownMenu/useMenuPress` FR6). | 150 ms after touch-down inside scrolling content; at once in a menu whose rows fit (`spec:AST-094` DEC-14). | The lift acts on the lit row. A scroll that takes the touch ends it with no fade. | ## Boundaries and invariants @@ -81,29 +81,23 @@ touch. The recipe styles paint from that attribute. never writes a caller's `::before` or `::after`. A layer anchors to its trigger's untransformed box (`architecture:layer-runtime` INV22). - **INV4 — One timing source.** Every profile reads its start delay, cancel, - and release from the engine. A press ends when a scroll takes the touch - (`spec:AST-094` FR20), or when the pointer leaves the target by more than the - control profile's tracking margin of 70 px. Every release that fades plays - the theme's exit motion tokens, with the reduced-motion treatment of - `design:reduced-motion` DR2 (`spec:AST-094` FR5, FR8). No profile uses a - fixed duration. + and release from the engine. A control keeps its press until the pointer + leaves its bounds expanded by UIControl's tracking margin (70 pt, + measurement M-G12). A row, card, or cell ends its press at the cell + profile's travel, the pan hysteresis. Inside a scroll view, a scroll that + takes the touch ends any press (`spec:AST-094` FR20). Every release that + fades plays the theme's exit motion tokens, with the reduced-motion + treatment of `design:reduced-motion` DR2 (`spec:AST-094` FR5, FR8). No + profile uses a fixed duration. - **INV5 — Every pointer through the engine.** A mouse or pen press paints at once on `pointerdown` through the engine, with the same release fade as a - finger's, in place of CSS `:active` (`spec:AST-094` DEC-21). + finger's, in place of CSS `:active` (`spec:AST-094` DEC-21; `component:Button` FR15), except the container case INV7 keeps. - **INV6 — The first press.** The engine's core stays on first load: it finds the pressable element, writes the attribute, starts the delay timer, and - ends the press on a scroll. A coarse first press paints in the frame the - finger lands; this code never moves into the deferred touch runtime. - Optional profiles (the group slide, the menu scrub, a press held through a - drag, a row's box hold) load with their opt-in or with the touch runtime and - cost an unused page at most what `architecture:component-import-boundaries` - INV10 allows. Before an optional profile loads, each pressable keeps its own - press. Nothing is painted into server HTML that has not hydrated - (`spec:AST-013` FR9). -- **INV3a — A stretched control.** When a caller stretches a control across a - row, the control's own press layer covers the same box as its hit area: a - press tints the row it covers, and the whole row stays the tap target for the - whole press. + ends the press on a scroll. Optional profiles (the group slide, the menu + scrub, a press held through a drag, a row's box hold) cost an unused page at + most what `architecture:component-import-boundaries` INV10 allows. Nothing + is painted into server HTML that has not hydrated (`spec:AST-013` FR9). - **INV7 — A nested control.** In recipe 2, a finger or pen press that starts on a nested interactive element paints that element only and never its row or card (`component:Item` FR9). A mouse press there keeps the container's @@ -112,6 +106,11 @@ touch. The recipe styles paint from that attribute. scales (`design:reduced-motion` DR1). A disabled surface paints no press (`design:user-states` DR2). A control whose own popup is open does not scale (`component:Button` FR15). +- **INV9 — A stretched control.** A control paints its press on its own + `::before` (`component:Button` FR15). When a caller stretches the control + across a row, its static root gives that layer and its hit area the row's + box (`component:Button` anatomy), so a press tints the row the control + covers, and the whole row stays the tap target for the whole press. ## Change coupling @@ -134,18 +133,19 @@ touch. The recipe styles paint from that attribute. - `spec:AST-094` FR5, FR11, DEC-21: the release, the press profiles, and the fine-pointer profile. -- Owner decision (`cixzhang`, 2026-11-16): one record for the press code that - ships, with three recipes, no new module, and no public API change. +- Owner decision (`cixzhang`, 2026-11-16): "A record for today's press code, + 3 recipes", with no new module and no public API change. ## Verification -| Invariant | Evidence | Failure signal | -| --------- | ----------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------ | -| INV1 | Review: no new press attribute, tracker, or tint variable outside the recipe modules | A component writes its own pressed state | -| INV2 | Each pressable component record names its recipe | A record restates press rules without a recipe | -| INV3 | `pressFeedback.test.ts`; a browser test that a point inside a caller's stretched target still hits during a press | A tap during a press misses its target, or layout shifts | -| INV4 | Computed release durations follow the theme's exit tokens and tempo on every recipe | A fixed duration, or two surfaces that cancel the same drift differently | -| INV5 | A mouse press test per recipe asserts the press attribute, not `:active` | A mouse press paints with no shared release fade | -| INV6 | Size report: the engine core is on first load; a first-touch browser test paints in the landing frame | A first finger press paints late or not at all | -| INV7 | A press on a nested control in a row and in a card, for finger, pen, and mouse | A finger or pen press on a nested control paints the container | -| INV8 | Reduced-motion and disabled press tests per recipe | A scale under reduced motion, or paint on a disabled surface | +| Invariant | Evidence | Failure signal | +| --------- | --------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------ | +| INV1 | Review: no new press attribute, tracker, or tint variable outside the recipe modules | A component writes its own pressed state | +| INV2 | Each pressable component record names its recipe | A record restates press rules without a recipe | +| INV3 | `pressFeedback.test.ts`; a browser test that a point inside a caller's stretched target still hits during a press | A tap during a press misses its target, or layout shifts | +| INV4 | Computed release durations follow the theme's exit tokens and tempo on every recipe | A fixed duration, or two surfaces that cancel the same drift differently | +| INV5 | A mouse press test per recipe asserts the press attribute, not `:active` | A mouse press paints with no shared release fade | +| INV6 | Size report: the engine core is on first load; optional profiles within INV10 | The engine core moves off first load, or an unused profile exceeds INV10 | +| INV7 | A press on a nested control in a row and in a card, for finger, pen, and mouse | A finger or pen press on a nested control paints the container | +| INV8 | Reduced-motion and disabled press tests per recipe | A scale under reduced motion, or paint on a disabled surface | +| INV9 | A browser test: a point inside a caller's stretched target still hits during a press, and the press tints that target | A tap during a press misses, or the tint and the target disagree | From 5e54d737a47f93bb66fbbc09f799dd16abe3a869 Mon Sep 17 00:00:00 2001 From: Cindy Zhang Date: Mon, 16 Nov 2026 09:27:55 -0800 Subject: [PATCH 03/24] docs(architecture): press feedback states the stretched-control gap on main --- docs/architecture/press-feedback.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/docs/architecture/press-feedback.md b/docs/architecture/press-feedback.md index bc0bc20e63c23..5062a2396f1ae 100644 --- a/docs/architecture/press-feedback.md +++ b/docs/architecture/press-feedback.md @@ -36,15 +36,15 @@ deciding_specs: [spec:AST-094/FR5, spec:AST-094/FR11, spec:AST-094/DEC-21] ## Contract at a glance -| Area | Contract | -| ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Governing contract | How a press looks and when it shows: `spec:AST-094` FR5, FR8, FR11, FR20 and DEC-21; `design:user-states` DR1–DR5; `design:reduced-motion` DR1–DR2; `architecture:layer-runtime` INV22; `component:Item` FR9. | -| System behavior | One press engine, the page press controller, writes every pressed state in Core. Each pressable surface uses one of three recipes: a momentary control, a row-wide target, or a cell or menu row. A press paints and does nothing else: it never changes layout, the hit area, or hit-testing. Every release fades on the theme's exit motion tokens. A coarse first press paints in the frame the finger lands. | -| End-user impact | A person sees the same press on every Astryx surface: the same tint, the same start delay inside scrolling content, the same release fade, and the same cancel when a scroll takes the touch. A press never moves a tap target, so a tap lands where the person aims it. | -| Builder impact | A component picks a recipe and states it in its own record. It adds no press attribute, tracker, timer, or tint variable of its own. A press fix lands once, in the engine or the recipe, and reaches every component that uses it. No public API changes; the recipes are exports of the private press modules. | -| Compatibility/readiness | No public API change. INV1 gap: the group tracker, the touch-runtime press tracker, the menu lit-row attribute, and local copies in ClickableCard, SelectableCard, Thumbnail, Tab, Switch, Slider and the Selector-family triggers write their own press state. INV4 gap: Switch, Slider and the SegmentedControl lens release in a fixed 200 ms, and controller controls end a press after 10 px of drift outside scrolling content. INV2 gap: Table cells paint no press. INV5 gap: under a mouse or a pen, most surfaces paint CSS `:active`. INV8 gap: Selector-family triggers scale under reduced motion. | -| Review checks | Reject a new press attribute, tracker, timer, or tint variable outside the recipes; a press style that changes layout, the containing block, or the hit area; a fixed release duration; a container that paints for a finger or pen press that starts on a nested interactive element; and press engine code moved off first load. | -| Governing rules | `spec:AST-094` FR5, FR8, FR11, FR20, DEC-14, DEC-21; `design:user-states` DR1–DR5; `design:reduced-motion` DR1–DR2; `architecture:layer-runtime` INV22; `component:Item` FR9; `component:Button` anatomy and FR15; `module:DropdownMenu/useMenuPress` FR6; `architecture:component-import-boundaries` INV10; `spec:AST-013` FR9. | +| Area | Contract | +| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Governing contract | How a press looks and when it shows: `spec:AST-094` FR5, FR8, FR11, FR20 and DEC-21; `design:user-states` DR1–DR5; `design:reduced-motion` DR1–DR2; `architecture:layer-runtime` INV22; `component:Item` FR9. | +| System behavior | One press engine, the page press controller, writes every pressed state in Core. Each pressable surface uses one of three recipes: a momentary control, a row-wide target, or a cell or menu row. A press paints and does nothing else: it never changes layout, the hit area, or hit-testing. Every release fades on the theme's exit motion tokens. A coarse first press paints in the frame the finger lands. | +| End-user impact | A person sees the same press on every Astryx surface: the same tint, the same start delay inside scrolling content, the same release fade, and the same cancel when a scroll takes the touch. A press never moves a tap target, so a tap lands where the person aims it. | +| Builder impact | A component picks a recipe and states it in its own record. It adds no press attribute, tracker, timer, or tint variable of its own. A press fix lands once, in the engine or the recipe, and reaches every component that uses it. No public API changes; the recipes are exports of the private press modules. | +| Compatibility/readiness | No public API change. INV1 gap: the group tracker, the touch-runtime press tracker, the menu lit-row attribute, and local copies in ClickableCard, SelectableCard, Thumbnail, Tab, Switch, Slider and the Selector-family triggers write their own press state. INV4 gap: Switch, Slider and the SegmentedControl lens release in a fixed 200 ms, and controller controls end a press after 10 px of drift outside scrolling content. INV2 gap: Table cells paint no press. INV3 and INV9 gap: under a finger, a press makes a control's root the containing block, so a stretched control's press layer and tap target shrink to the control mid-press. INV5 gap: under a mouse or a pen, most surfaces paint CSS `:active`. INV8 gap: Selector-family triggers scale under reduced motion. | +| Review checks | Reject a new press attribute, tracker, timer, or tint variable outside the recipes; a press style that changes layout, the containing block, or the hit area; a fixed release duration; a container that paints for a finger or pen press that starts on a nested interactive element; and press engine code moved off first load. | +| Governing rules | `spec:AST-094` FR5, FR8, FR11, FR20, DEC-14, DEC-21; `design:user-states` DR1–DR5; `design:reduced-motion` DR1–DR2; `architecture:layer-runtime` INV22; `component:Item` FR9; `component:Button` anatomy and FR15; `module:DropdownMenu/useMenuPress` FR6; `architecture:component-import-boundaries` INV10; `spec:AST-013` FR9. | ## Purpose From f48376d4dfcd2e95a11237d4ed342dfd74285299 Mon Sep 17 00:00:00 2001 From: Cindy Zhang Date: Mon, 16 Nov 2026 10:18:06 -0800 Subject: [PATCH 04/24] docs(architecture): press feedback scopes INV7 to non-activating presses and states INV9 as its own rule --- docs/architecture/press-feedback.md | 52 ++++++++++++++++------------- 1 file changed, 28 insertions(+), 24 deletions(-) diff --git a/docs/architecture/press-feedback.md b/docs/architecture/press-feedback.md index 5062a2396f1ae..e196782087e1b 100644 --- a/docs/architecture/press-feedback.md +++ b/docs/architecture/press-feedback.md @@ -36,15 +36,15 @@ deciding_specs: [spec:AST-094/FR5, spec:AST-094/FR11, spec:AST-094/DEC-21] ## Contract at a glance -| Area | Contract | -| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Governing contract | How a press looks and when it shows: `spec:AST-094` FR5, FR8, FR11, FR20 and DEC-21; `design:user-states` DR1–DR5; `design:reduced-motion` DR1–DR2; `architecture:layer-runtime` INV22; `component:Item` FR9. | -| System behavior | One press engine, the page press controller, writes every pressed state in Core. Each pressable surface uses one of three recipes: a momentary control, a row-wide target, or a cell or menu row. A press paints and does nothing else: it never changes layout, the hit area, or hit-testing. Every release fades on the theme's exit motion tokens. A coarse first press paints in the frame the finger lands. | -| End-user impact | A person sees the same press on every Astryx surface: the same tint, the same start delay inside scrolling content, the same release fade, and the same cancel when a scroll takes the touch. A press never moves a tap target, so a tap lands where the person aims it. | -| Builder impact | A component picks a recipe and states it in its own record. It adds no press attribute, tracker, timer, or tint variable of its own. A press fix lands once, in the engine or the recipe, and reaches every component that uses it. No public API changes; the recipes are exports of the private press modules. | -| Compatibility/readiness | No public API change. INV1 gap: the group tracker, the touch-runtime press tracker, the menu lit-row attribute, and local copies in ClickableCard, SelectableCard, Thumbnail, Tab, Switch, Slider and the Selector-family triggers write their own press state. INV4 gap: Switch, Slider and the SegmentedControl lens release in a fixed 200 ms, and controller controls end a press after 10 px of drift outside scrolling content. INV2 gap: Table cells paint no press. INV3 and INV9 gap: under a finger, a press makes a control's root the containing block, so a stretched control's press layer and tap target shrink to the control mid-press. INV5 gap: under a mouse or a pen, most surfaces paint CSS `:active`. INV8 gap: Selector-family triggers scale under reduced motion. | -| Review checks | Reject a new press attribute, tracker, timer, or tint variable outside the recipes; a press style that changes layout, the containing block, or the hit area; a fixed release duration; a container that paints for a finger or pen press that starts on a nested interactive element; and press engine code moved off first load. | -| Governing rules | `spec:AST-094` FR5, FR8, FR11, FR20, DEC-14, DEC-21; `design:user-states` DR1–DR5; `design:reduced-motion` DR1–DR2; `architecture:layer-runtime` INV22; `component:Item` FR9; `component:Button` anatomy and FR15; `module:DropdownMenu/useMenuPress` FR6; `architecture:component-import-boundaries` INV10; `spec:AST-013` FR9. | +| Area | Contract | +| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Governing contract | How a press looks and when it shows: `spec:AST-094` FR5, FR8, FR11, FR20 and DEC-21; `design:user-states` DR1–DR5; `design:reduced-motion` DR1–DR2; `architecture:layer-runtime` INV22; `component:Item` FR9. | +| System behavior | One press engine, the page press controller, writes every pressed state in Core. Each pressable surface uses one of three recipes: a momentary control, a row-wide target, or a cell or menu row. A press paints and does nothing else: it never changes layout, the hit area, or hit-testing. Every release fades on the theme's exit motion tokens. | +| End-user impact | A person sees the same press on every Astryx surface: the same tint, the same start delay inside scrolling content, the same release fade, and the same cancel when a scroll takes the touch. A press never moves a tap target, so a tap lands where the person aims it. | +| Builder impact | A component picks a recipe and states it in its own record. It adds no press attribute, tracker, timer, or tint variable of its own. A press fix lands once, in the engine or the recipe, and reaches every component that uses it. No public API changes; the recipes are exports of the private press modules. | +| Compatibility/readiness | No public API change. INV1 gap: the group tracker, the touch-runtime press tracker, the menu lit-row attribute, and local copies in ClickableCard, SelectableCard, Thumbnail, Tab, Switch, Slider and the Selector-family triggers write their own press state. INV4 gap: Switch, Slider and the SegmentedControl lens release in a fixed 200 ms, and controller controls end a press after 10 px of drift outside scrolling content. INV2 gap: no component record names its recipe, and Table cells paint no press. INV3 and INV9 gap: under a finger, a press makes a control's root the containing block, so a stretched control's press layer and tap target shrink to the control mid-press. INV5 gap: under a mouse or a pen, most surfaces paint CSS `:active`. INV8 gap: Selector-family triggers scale under reduced motion. | +| Review checks | Reject a new press attribute, tracker, timer, or tint variable outside the recipes; a press style that changes layout, the containing block, or the hit area; a fixed release duration; a container that paints for a finger or pen press on a nested control that does not activate it; and press engine code moved off first load. | +| Governing rules | `spec:AST-094` FR5, FR8, FR11, FR20, DEC-14, DEC-21; `design:user-states` DR1–DR5; `design:reduced-motion` DR1–DR2; `architecture:layer-runtime` INV22; `component:Item` FR9; `component:Button` anatomy and FR15; `module:DropdownMenu/useMenuPress` FR6; `architecture:component-import-boundaries` INV10; `spec:AST-013` FR9. | ## Purpose @@ -61,11 +61,11 @@ writes the private press attribute (`on`, then `fading`), starts the delay timer, and ends the press on a release, a cancel, or a scroll that takes the touch. The recipe styles paint from that attribute. -| Recipe | Used by | What paints | Start | End | -| -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ | -| 1. Momentary control | Button family, Link, Switch, Tab, Token, SegmentedControl segment, TopNavItem, SideNavItem, NavItem, Selector-family triggers, Step, Calendar day | The system pressed tint on the control's own press layer. A standalone control may also scale, as its record states. Option: keeps its press through a drag (Slider thumb, SegmentedControl lens, Switch thumb; `design:user-states` DR4). | Touch-down outside scrolling content; 150 ms after touch-down inside it (`spec:AST-094` FR11). | The lift, with the release fade. A scroll that takes the touch ends it with no fade. | -| 2. Row-wide target | Item and ListItem, TreeList rows, CheckboxList and RadioList rows, Collapsible trigger, ClickableCard, SelectableCard, Thumbnail; a control whose caller stretches it across a row (its root static and its `::after` covering the row; INV9) | The pressed tint on the whole row or card, only for a press that would activate it. A press on a row's own box presses the row (`component:CheckboxListItem` AR3). | As recipe 1. | As recipe 1. | -| 3. Cell or menu row | Menu rows, picker options, CommandPalette rows, Table cells (INV2 gap) | The pressed tint on the row. At most one row of a menu is lit; a sliding finger moves the light (`module:DropdownMenu/useMenuPress` FR6). | 150 ms after touch-down inside scrolling content; at once in a menu whose rows fit (`spec:AST-094` DEC-14). | The lift acts on the lit row. A scroll that takes the touch ends it with no fade. | +| Recipe | Used by | What paints | Start | End | +| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ | +| 1. Momentary control | Button family, Link, Switch, Tab, Token, SegmentedControl segment, TopNavItem, SideNavItem, NavItem, Selector-family triggers, Step, Calendar day | The system pressed tint on the control's own press layer. A standalone control may also scale, as its record states. Option: keeps its press through a drag (Slider thumb, SegmentedControl lens, Switch thumb; `design:user-states` DR4). | Touch-down outside scrolling content; 150 ms after touch-down inside it (`spec:AST-094` FR11). | The lift, with the release fade. A scroll that takes the touch ends it with no fade. | +| 2. Row-wide target | Item and ListItem, TreeList rows, CheckboxList and RadioList rows, Collapsible trigger, ClickableCard, SelectableCard, Thumbnail; a control whose caller stretches it across a row (its root made static by the caller and its `::after` covering the row; INV9) | The pressed tint on the whole row or card, only for a press that would activate it. A press on a row's own box presses the row (`component:CheckboxListItem` AR3). | As recipe 1. | As recipe 1. | +| 3. Cell or menu row | Menu rows, picker options, CommandPalette rows, Table cells (INV2 gap) | The pressed tint on the row. At most one row of a menu is lit; a sliding finger moves the light (`module:DropdownMenu/useMenuPress` FR6). | 150 ms after touch-down inside scrolling content; at once in a menu whose rows fit (`spec:AST-094` DEC-14). | The lift acts on the lit row. A scroll that takes the touch ends it with no fade. | ## Boundaries and invariants @@ -99,18 +99,22 @@ touch. The recipe styles paint from that attribute. most what `architecture:component-import-boundaries` INV10 allows. Nothing is painted into server HTML that has not hydrated (`spec:AST-013` FR9). - **INV7 — A nested control.** In recipe 2, a finger or pen press that starts - on a nested interactive element paints that element only and never its row - or card (`component:Item` FR9). A mouse press there keeps the container's - press paint as `component:ClickableCard` FR5 states. + on a nested interactive element that does not activate the container paints + that element only, never its row or card (`component:Item` FR9). A press on + the row's own action, its delegated control, or its box presses the row + (`component:Item` FR9; `component:CheckboxListItem` AR3). A mouse press on a + nested control keeps the container's press paint as `component:ClickableCard` + FR5 states. - **INV8 — Reduced motion and disabled.** Under reduced motion no press scales (`design:reduced-motion` DR1). A disabled surface paints no press (`design:user-states` DR2). A control whose own popup is open does not scale (`component:Button` FR15). - **INV9 — A stretched control.** A control paints its press on its own - `::before` (`component:Button` FR15). When a caller stretches the control - across a row, its static root gives that layer and its hit area the row's - box (`component:Button` anatomy), so a press tints the row the control - covers, and the whole row stays the tap target for the whole press. + press layer (`component:Button` FR15). When a caller's styles make the + control's root static so that its `::after` covers a row (`component:Button` + FR17), the press layer and the hit area take that row's box: a press tints + the row the control covers, and the whole row stays the tap target for the + whole press. ## Change coupling @@ -126,15 +130,15 @@ touch. The recipe styles paint from that attribute. `packages/core/src/hooks/usePressFeedback.ts`. - Recipe styles and attribute: `packages/core/src/privateAttributes/press.ts` and the `press*.stylex.ts` modules beside it. -- Profiles to fold into the engine: `packages/core/src/hooks/useGroupPressTracking.ts`, +- Other press trackers (INV1 gap): `packages/core/src/hooks/useGroupPressTracking.ts`, `packages/core/src/gestures/PressTracker.ts`, `packages/core/src/hooks/useMenuPress.ts`. ## Deciding specs - `spec:AST-094` FR5, FR11, DEC-21: the release, the press profiles, and the fine-pointer profile. -- Owner decision (`cixzhang`, 2026-11-16): "A record for today's press code, - 3 recipes", with no new module and no public API change. +- Owner decision (`cixzhang`, 2026-11-16): Core's press code is one engine + with three recipes, with no new module and no public API change. ## Verification From c251ce2842c29d4ea1443fec1c4d24d5bca7fa40 Mon Sep 17 00:00:00 2001 From: Cindy Zhang Date: Mon, 16 Nov 2026 10:54:44 -0800 Subject: [PATCH 05/24] docs(architecture): a stretched control keeps its press paint on its own box --- docs/architecture/press-feedback.md | 61 ++++++++++++++--------------- 1 file changed, 30 insertions(+), 31 deletions(-) diff --git a/docs/architecture/press-feedback.md b/docs/architecture/press-feedback.md index e196782087e1b..cc3766739db65 100644 --- a/docs/architecture/press-feedback.md +++ b/docs/architecture/press-feedback.md @@ -36,15 +36,15 @@ deciding_specs: [spec:AST-094/FR5, spec:AST-094/FR11, spec:AST-094/DEC-21] ## Contract at a glance -| Area | Contract | -| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Governing contract | How a press looks and when it shows: `spec:AST-094` FR5, FR8, FR11, FR20 and DEC-21; `design:user-states` DR1–DR5; `design:reduced-motion` DR1–DR2; `architecture:layer-runtime` INV22; `component:Item` FR9. | -| System behavior | One press engine, the page press controller, writes every pressed state in Core. Each pressable surface uses one of three recipes: a momentary control, a row-wide target, or a cell or menu row. A press paints and does nothing else: it never changes layout, the hit area, or hit-testing. Every release fades on the theme's exit motion tokens. | -| End-user impact | A person sees the same press on every Astryx surface: the same tint, the same start delay inside scrolling content, the same release fade, and the same cancel when a scroll takes the touch. A press never moves a tap target, so a tap lands where the person aims it. | -| Builder impact | A component picks a recipe and states it in its own record. It adds no press attribute, tracker, timer, or tint variable of its own. A press fix lands once, in the engine or the recipe, and reaches every component that uses it. No public API changes; the recipes are exports of the private press modules. | -| Compatibility/readiness | No public API change. INV1 gap: the group tracker, the touch-runtime press tracker, the menu lit-row attribute, and local copies in ClickableCard, SelectableCard, Thumbnail, Tab, Switch, Slider and the Selector-family triggers write their own press state. INV4 gap: Switch, Slider and the SegmentedControl lens release in a fixed 200 ms, and controller controls end a press after 10 px of drift outside scrolling content. INV2 gap: no component record names its recipe, and Table cells paint no press. INV3 and INV9 gap: under a finger, a press makes a control's root the containing block, so a stretched control's press layer and tap target shrink to the control mid-press. INV5 gap: under a mouse or a pen, most surfaces paint CSS `:active`. INV8 gap: Selector-family triggers scale under reduced motion. | -| Review checks | Reject a new press attribute, tracker, timer, or tint variable outside the recipes; a press style that changes layout, the containing block, or the hit area; a fixed release duration; a container that paints for a finger or pen press on a nested control that does not activate it; and press engine code moved off first load. | -| Governing rules | `spec:AST-094` FR5, FR8, FR11, FR20, DEC-14, DEC-21; `design:user-states` DR1–DR5; `design:reduced-motion` DR1–DR2; `architecture:layer-runtime` INV22; `component:Item` FR9; `component:Button` anatomy and FR15; `module:DropdownMenu/useMenuPress` FR6; `architecture:component-import-boundaries` INV10; `spec:AST-013` FR9. | +| Area | Contract | +| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Governing contract | How a press looks and when it shows: `spec:AST-094` FR5, FR8, FR11, FR20 and DEC-21; `design:user-states` DR1–DR5; `design:reduced-motion` DR1–DR2; `architecture:layer-runtime` INV22; `component:Item` FR9. | +| System behavior | One press engine, the page press controller, writes every pressed state in Core. Each pressable surface uses one of three recipes: a momentary control, a row-wide target, or a cell or menu row. A press paints and does nothing else: it never changes layout, the hit area, or hit-testing. Every release fades on the theme's exit motion tokens. | +| End-user impact | A person sees the same press on every Astryx surface: the same tint, the same start delay inside scrolling content, the same release fade, and the same cancel when a scroll takes the touch. A press never moves a tap target, so a tap lands where the person aims it. | +| Builder impact | A component picks a recipe and states it in its own record. It adds no press attribute, tracker, timer, or tint variable of its own. A press fix lands once, in the engine or the recipe, and reaches every component that uses it. No public API changes; the recipes are exports of the private press modules. | +| Compatibility/readiness | No public API change. INV1 gap: the group tracker, the touch-runtime press tracker, the menu lit-row attribute, and local copies in ClickableCard, SelectableCard, Thumbnail, Tab, Switch, Slider and the Selector-family triggers write their own press state. INV4 gap: Switch, Slider and the SegmentedControl lens release in a fixed 200 ms, and controller controls end a press after 10 px of drift outside scrolling content. INV2 gap: no component record names its recipe, and Table cells paint no press. INV3 and INV9 gap: under a finger, a press makes a control's root the containing block, so a stretched control's tap target shrinks to the control mid-press. INV5 gap: under a mouse or a pen, most surfaces paint CSS `:active`. INV8 gap: Selector-family triggers scale under reduced motion. | +| Review checks | Reject a new press attribute, tracker, timer, or tint variable outside the recipes; a press style that changes layout, the containing block, or the hit area; a fixed release duration; a container that paints for a finger or pen press on a nested control that does not activate it; and press engine code moved off first load. | +| Governing rules | `spec:AST-094` FR5, FR8, FR11, FR20, DEC-14, DEC-21; `design:user-states` DR1–DR5; `design:reduced-motion` DR1–DR2; `architecture:layer-runtime` INV22; `component:Item` FR9; `component:Button` anatomy and FR15; `module:DropdownMenu/useMenuPress` FR6; `architecture:component-import-boundaries` INV10; `spec:AST-013` FR9. | ## Purpose @@ -61,11 +61,11 @@ writes the private press attribute (`on`, then `fading`), starts the delay timer, and ends the press on a release, a cancel, or a scroll that takes the touch. The recipe styles paint from that attribute. -| Recipe | Used by | What paints | Start | End | -| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ | -| 1. Momentary control | Button family, Link, Switch, Tab, Token, SegmentedControl segment, TopNavItem, SideNavItem, NavItem, Selector-family triggers, Step, Calendar day | The system pressed tint on the control's own press layer. A standalone control may also scale, as its record states. Option: keeps its press through a drag (Slider thumb, SegmentedControl lens, Switch thumb; `design:user-states` DR4). | Touch-down outside scrolling content; 150 ms after touch-down inside it (`spec:AST-094` FR11). | The lift, with the release fade. A scroll that takes the touch ends it with no fade. | -| 2. Row-wide target | Item and ListItem, TreeList rows, CheckboxList and RadioList rows, Collapsible trigger, ClickableCard, SelectableCard, Thumbnail; a control whose caller stretches it across a row (its root made static by the caller and its `::after` covering the row; INV9) | The pressed tint on the whole row or card, only for a press that would activate it. A press on a row's own box presses the row (`component:CheckboxListItem` AR3). | As recipe 1. | As recipe 1. | -| 3. Cell or menu row | Menu rows, picker options, CommandPalette rows, Table cells (INV2 gap) | The pressed tint on the row. At most one row of a menu is lit; a sliding finger moves the light (`module:DropdownMenu/useMenuPress` FR6). | 150 ms after touch-down inside scrolling content; at once in a menu whose rows fit (`spec:AST-094` DEC-14). | The lift acts on the lit row. A scroll that takes the touch ends it with no fade. | +| Recipe | Used by | What paints | Start | End | +| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ | +| 1. Momentary control | Button family, Link, Switch, Tab, Token, SegmentedControl segment, TopNavItem, SideNavItem, NavItem, Selector-family triggers, Step, Calendar day | The system pressed tint on the control's own press layer. A standalone control may also scale, as its record states. Option: keeps its press through a drag (Slider thumb, SegmentedControl lens, Switch thumb; `design:user-states` DR4). | Touch-down outside scrolling content; 150 ms after touch-down inside it (`spec:AST-094` FR11). | The lift, with the release fade. A scroll that takes the touch ends it with no fade. | +| 2. Row-wide target | Item and ListItem, TreeList rows, CheckboxList and RadioList rows, Collapsible trigger, ClickableCard, SelectableCard, Thumbnail | The pressed tint on the whole row or card, only for a press that would activate it. A press on a row's own box presses the row (`component:CheckboxListItem` AR3). | As recipe 1. | As recipe 1. | +| 3. Cell or menu row | Menu rows, picker options, CommandPalette rows, Table cells (INV2 gap) | The pressed tint on the row. At most one row of a menu is lit; a sliding finger moves the light (`module:DropdownMenu/useMenuPress` FR6). | 150 ms after touch-down inside scrolling content; at once in a menu whose rows fit (`spec:AST-094` DEC-14). | The lift acts on the lit row. A scroll that takes the touch ends it with no fade. | ## Boundaries and invariants @@ -109,12 +109,11 @@ touch. The recipe styles paint from that attribute. scales (`design:reduced-motion` DR1). A disabled surface paints no press (`design:user-states` DR2). A control whose own popup is open does not scale (`component:Button` FR15). -- **INV9 — A stretched control.** A control paints its press on its own - press layer (`component:Button` FR15). When a caller's styles make the - control's root static so that its `::after` covers a row (`component:Button` - FR17), the press layer and the hit area take that row's box: a press tints - the row the control covers, and the whole row stays the tap target for the - whole press. +- **INV9 — A stretched control.** When a caller's styles make a control's + root static so that its `::after` covers a row (`component:Button` FR17), + the hit area takes that row's box and stays the tap target for the whole + press, while the press paint stays on the control's own box + (`design:user-states` DR1, the named visual part). ## Change coupling @@ -142,14 +141,14 @@ touch. The recipe styles paint from that attribute. ## Verification -| Invariant | Evidence | Failure signal | -| --------- | --------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------ | -| INV1 | Review: no new press attribute, tracker, or tint variable outside the recipe modules | A component writes its own pressed state | -| INV2 | Each pressable component record names its recipe | A record restates press rules without a recipe | -| INV3 | `pressFeedback.test.ts`; a browser test that a point inside a caller's stretched target still hits during a press | A tap during a press misses its target, or layout shifts | -| INV4 | Computed release durations follow the theme's exit tokens and tempo on every recipe | A fixed duration, or two surfaces that cancel the same drift differently | -| INV5 | A mouse press test per recipe asserts the press attribute, not `:active` | A mouse press paints with no shared release fade | -| INV6 | Size report: the engine core is on first load; optional profiles within INV10 | The engine core moves off first load, or an unused profile exceeds INV10 | -| INV7 | A press on a nested control in a row and in a card, for finger, pen, and mouse | A finger or pen press on a nested control paints the container | -| INV8 | Reduced-motion and disabled press tests per recipe | A scale under reduced motion, or paint on a disabled surface | -| INV9 | A browser test: a point inside a caller's stretched target still hits during a press, and the press tints that target | A tap during a press misses, or the tint and the target disagree | +| Invariant | Evidence | Failure signal | +| --------- | -------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------ | +| INV1 | Review: no new press attribute, tracker, or tint variable outside the recipe modules | A component writes its own pressed state | +| INV2 | Each pressable component record names its recipe | A record restates press rules without a recipe | +| INV3 | `pressFeedback.test.ts`; a browser test that a point inside a caller's stretched target still hits during a press | A tap during a press misses its target, or layout shifts | +| INV4 | Computed release durations follow the theme's exit tokens and tempo on every recipe | A fixed duration, or two surfaces that cancel the same drift differently | +| INV5 | A mouse press test per recipe asserts the press attribute, not `:active` | A mouse press paints with no shared release fade | +| INV6 | Size report: the engine core is on first load; optional profiles within INV10 | The engine core moves off first load, or an unused profile exceeds INV10 | +| INV7 | A press on a nested control in a row and in a card, for finger, pen, and mouse | A finger or pen press on a nested control paints the container | +| INV8 | Reduced-motion and disabled press tests per recipe | A scale under reduced motion, or paint on a disabled surface | +| INV9 | A browser test: a point inside a caller's stretched target still hits during a press, and only the control's own box tints | A tap during a press misses, or the tint spreads past the control | From 2eff03c444c44a4854f6c408711681bc3a3fdb9f Mon Sep 17 00:00:00 2001 From: Cindy Zhang Date: Mon, 16 Nov 2026 11:05:10 -0800 Subject: [PATCH 06/24] docs(architecture): press feedback scopes drift rules to untracked presses and INV7's failure signal --- docs/architecture/press-feedback.md | 58 +++++++++++++++-------------- 1 file changed, 30 insertions(+), 28 deletions(-) diff --git a/docs/architecture/press-feedback.md b/docs/architecture/press-feedback.md index cc3766739db65..7fedae5ac0526 100644 --- a/docs/architecture/press-feedback.md +++ b/docs/architecture/press-feedback.md @@ -36,15 +36,15 @@ deciding_specs: [spec:AST-094/FR5, spec:AST-094/FR11, spec:AST-094/DEC-21] ## Contract at a glance -| Area | Contract | -| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Governing contract | How a press looks and when it shows: `spec:AST-094` FR5, FR8, FR11, FR20 and DEC-21; `design:user-states` DR1–DR5; `design:reduced-motion` DR1–DR2; `architecture:layer-runtime` INV22; `component:Item` FR9. | -| System behavior | One press engine, the page press controller, writes every pressed state in Core. Each pressable surface uses one of three recipes: a momentary control, a row-wide target, or a cell or menu row. A press paints and does nothing else: it never changes layout, the hit area, or hit-testing. Every release fades on the theme's exit motion tokens. | -| End-user impact | A person sees the same press on every Astryx surface: the same tint, the same start delay inside scrolling content, the same release fade, and the same cancel when a scroll takes the touch. A press never moves a tap target, so a tap lands where the person aims it. | -| Builder impact | A component picks a recipe and states it in its own record. It adds no press attribute, tracker, timer, or tint variable of its own. A press fix lands once, in the engine or the recipe, and reaches every component that uses it. No public API changes; the recipes are exports of the private press modules. | -| Compatibility/readiness | No public API change. INV1 gap: the group tracker, the touch-runtime press tracker, the menu lit-row attribute, and local copies in ClickableCard, SelectableCard, Thumbnail, Tab, Switch, Slider and the Selector-family triggers write their own press state. INV4 gap: Switch, Slider and the SegmentedControl lens release in a fixed 200 ms, and controller controls end a press after 10 px of drift outside scrolling content. INV2 gap: no component record names its recipe, and Table cells paint no press. INV3 and INV9 gap: under a finger, a press makes a control's root the containing block, so a stretched control's tap target shrinks to the control mid-press. INV5 gap: under a mouse or a pen, most surfaces paint CSS `:active`. INV8 gap: Selector-family triggers scale under reduced motion. | -| Review checks | Reject a new press attribute, tracker, timer, or tint variable outside the recipes; a press style that changes layout, the containing block, or the hit area; a fixed release duration; a container that paints for a finger or pen press on a nested control that does not activate it; and press engine code moved off first load. | -| Governing rules | `spec:AST-094` FR5, FR8, FR11, FR20, DEC-14, DEC-21; `design:user-states` DR1–DR5; `design:reduced-motion` DR1–DR2; `architecture:layer-runtime` INV22; `component:Item` FR9; `component:Button` anatomy and FR15; `module:DropdownMenu/useMenuPress` FR6; `architecture:component-import-boundaries` INV10; `spec:AST-013` FR9. | +| Area | Contract | +| ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Governing contract | How a press looks and when it shows: `spec:AST-094` FR5, FR8, FR11, FR20 and DEC-21; `design:user-states` DR1–DR5; `design:reduced-motion` DR1–DR2; `architecture:layer-runtime` INV22; `component:Item` FR9. | +| System behavior | One press engine, the page press controller, writes every pressed state in Core. Each pressable surface uses one of three recipes: a momentary control, a row-wide target, or a cell or menu row. A press paints and does nothing else: it never changes layout, the hit area, or hit-testing. Every release fades on the theme's exit motion tokens. | +| End-user impact | A person sees the same press on every Astryx surface: the same tint, the same start delay inside scrolling content, the same release fade, and the same cancel when a scroll takes the touch. A press never moves a tap target, so a tap lands where the person aims it. | +| Builder impact | A component picks a recipe and states it in its own record. It adds no press attribute, tracker, timer, or tint variable of its own. A press fix lands once, in the engine or the recipe, and reaches every component that uses it. No public API changes; the recipes are exports of the private press modules. | +| Compatibility/readiness | No public API change. INV1 gap: the group tracker, the touch-runtime press tracker, the menu lit-row attribute, and ClickableCard, SelectableCard, Thumbnail, Tab, Switch, Slider and the Selector-family triggers re-declare press styles (their own press variable, scale, or state) instead of using a recipe's. INV4 gap: Switch, Slider and the SegmentedControl lens release in a fixed 200 ms, and controller controls end a press after 10 px of drift outside scrolling content. INV2 gap: no component record names its recipe, and Table cells paint no press. INV3 and INV9 gap: under a finger, a press makes a control's root the containing block, so a stretched control's tap target shrinks to the control mid-press. INV5 gap: under a mouse or a pen, most surfaces paint CSS `:active`. INV8 gap: Selector-family triggers scale under reduced motion. | +| Review checks | Reject a new press attribute, tracker, timer, or tint variable outside the recipes; a press style that changes layout, the containing block, or the hit area; a fixed release duration; a container that paints for a finger or pen press on a nested control that does not activate it; and press engine code moved off first load. | +| Governing rules | `spec:AST-094` FR5, FR8, FR11, FR20, FR27, DEC-14, DEC-21; `family:action-groups` FR2; `design:user-states` DR1–DR5; `design:reduced-motion` DR1–DR2; `architecture:layer-runtime` INV22; `component:Item` FR9; `component:Button` FR15 and FR17; `module:DropdownMenu/useMenuPress` FR6; `architecture:component-import-boundaries` INV10; `spec:AST-013` FR9. | ## Purpose @@ -81,14 +81,16 @@ touch. The recipe styles paint from that attribute. never writes a caller's `::before` or `::after`. A layer anchors to its trigger's untransformed box (`architecture:layer-runtime` INV22). - **INV4 — One timing source.** Every profile reads its start delay, cancel, - and release from the engine. A control keeps its press until the pointer - leaves its bounds expanded by UIControl's tracking margin (70 pt, - measurement M-G12). A row, card, or cell ends its press at the cell - profile's travel, the pan hysteresis. Inside a scroll view, a scroll that - takes the touch ends any press (`spec:AST-094` FR20). Every release that - fades plays the theme's exit motion tokens, with the reduced-motion - treatment of `design:reduced-motion` DR2 (`spec:AST-094` FR5, FR8). No - profile uses a fixed duration. + and release from the engine. For a press no group or menu profile tracks, a + control keeps its press until the pointer leaves its bounds expanded by + UIControl's tracking margin (70 pt, measurement M-G12), and a row, card, or + cell ends its press at the cell profile's travel, the pan hysteresis. A group + member follows `family:action-groups` FR2, and a menu row follows + `spec:AST-094` FR27. Inside a scroll view, a scroll that takes the touch ends + any press (`spec:AST-094` FR20). Every release that fades plays the theme's + exit motion tokens, with the reduced-motion treatment of + `design:reduced-motion` DR2 (`spec:AST-094` FR5, FR8). No profile uses a + fixed duration. - **INV5 — Every pointer through the engine.** A mouse or pen press paints at once on `pointerdown` through the engine, with the same release fade as a finger's, in place of CSS `:active` (`spec:AST-094` DEC-21; `component:Button` FR15), except the container case INV7 keeps. @@ -141,14 +143,14 @@ touch. The recipe styles paint from that attribute. ## Verification -| Invariant | Evidence | Failure signal | -| --------- | -------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------ | -| INV1 | Review: no new press attribute, tracker, or tint variable outside the recipe modules | A component writes its own pressed state | -| INV2 | Each pressable component record names its recipe | A record restates press rules without a recipe | -| INV3 | `pressFeedback.test.ts`; a browser test that a point inside a caller's stretched target still hits during a press | A tap during a press misses its target, or layout shifts | -| INV4 | Computed release durations follow the theme's exit tokens and tempo on every recipe | A fixed duration, or two surfaces that cancel the same drift differently | -| INV5 | A mouse press test per recipe asserts the press attribute, not `:active` | A mouse press paints with no shared release fade | -| INV6 | Size report: the engine core is on first load; optional profiles within INV10 | The engine core moves off first load, or an unused profile exceeds INV10 | -| INV7 | A press on a nested control in a row and in a card, for finger, pen, and mouse | A finger or pen press on a nested control paints the container | -| INV8 | Reduced-motion and disabled press tests per recipe | A scale under reduced motion, or paint on a disabled surface | -| INV9 | A browser test: a point inside a caller's stretched target still hits during a press, and only the control's own box tints | A tap during a press misses, or the tint spreads past the control | +| Invariant | Evidence | Failure signal | +| --------- | -------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| INV1 | Review: no new press attribute, tracker, or tint variable outside the recipe modules | A component writes its own pressed state | +| INV2 | Each pressable component record names its recipe | A record restates press rules without a recipe | +| INV3 | `pressFeedback.test.ts`; a browser test that a point inside a caller's stretched target still hits during a press | A tap during a press misses its target, or layout shifts | +| INV4 | Computed release durations follow the theme's exit tokens and tempo on every recipe | A fixed duration, or two surfaces of one recipe that cancel the same drift differently | +| INV5 | A mouse press test per recipe asserts the press attribute, not `:active` | A mouse press paints with no shared release fade | +| INV6 | Size report: the engine core is on first load; optional profiles within INV10 | The engine core moves off first load, or an unused profile exceeds INV10 | +| INV7 | A press on a nested control in a row and in a card, for finger, pen, and mouse | A finger or pen press on a nested control that does not activate the container paints the container, or a press on the row's own action, delegated control, or box does not paint the row | +| INV8 | Reduced-motion and disabled press tests per recipe | A scale under reduced motion, or paint on a disabled surface | +| INV9 | A browser test: a point inside a caller's stretched target still hits during a press, and only the control's own box tints | A tap during a press misses, or the tint spreads past the control | From 3eaca16242c0f9656bdfe70be38664842e8f4669 Mon Sep 17 00:00:00 2001 From: Cindy Zhang Date: Mon, 16 Nov 2026 11:17:49 -0800 Subject: [PATCH 07/24] docs(architecture): press feedback keeps interaction-modality INV13's group and menu tracking owners --- docs/architecture/press-feedback.md | 37 +++++++++++++++++------------ 1 file changed, 22 insertions(+), 15 deletions(-) diff --git a/docs/architecture/press-feedback.md b/docs/architecture/press-feedback.md index 7fedae5ac0526..c7a0d270dac93 100644 --- a/docs/architecture/press-feedback.md +++ b/docs/architecture/press-feedback.md @@ -36,15 +36,15 @@ deciding_specs: [spec:AST-094/FR5, spec:AST-094/FR11, spec:AST-094/DEC-21] ## Contract at a glance -| Area | Contract | -| ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Governing contract | How a press looks and when it shows: `spec:AST-094` FR5, FR8, FR11, FR20 and DEC-21; `design:user-states` DR1–DR5; `design:reduced-motion` DR1–DR2; `architecture:layer-runtime` INV22; `component:Item` FR9. | -| System behavior | One press engine, the page press controller, writes every pressed state in Core. Each pressable surface uses one of three recipes: a momentary control, a row-wide target, or a cell or menu row. A press paints and does nothing else: it never changes layout, the hit area, or hit-testing. Every release fades on the theme's exit motion tokens. | -| End-user impact | A person sees the same press on every Astryx surface: the same tint, the same start delay inside scrolling content, the same release fade, and the same cancel when a scroll takes the touch. A press never moves a tap target, so a tap lands where the person aims it. | -| Builder impact | A component picks a recipe and states it in its own record. It adds no press attribute, tracker, timer, or tint variable of its own. A press fix lands once, in the engine or the recipe, and reaches every component that uses it. No public API changes; the recipes are exports of the private press modules. | -| Compatibility/readiness | No public API change. INV1 gap: the group tracker, the touch-runtime press tracker, the menu lit-row attribute, and ClickableCard, SelectableCard, Thumbnail, Tab, Switch, Slider and the Selector-family triggers re-declare press styles (their own press variable, scale, or state) instead of using a recipe's. INV4 gap: Switch, Slider and the SegmentedControl lens release in a fixed 200 ms, and controller controls end a press after 10 px of drift outside scrolling content. INV2 gap: no component record names its recipe, and Table cells paint no press. INV3 and INV9 gap: under a finger, a press makes a control's root the containing block, so a stretched control's tap target shrinks to the control mid-press. INV5 gap: under a mouse or a pen, most surfaces paint CSS `:active`. INV8 gap: Selector-family triggers scale under reduced motion. | -| Review checks | Reject a new press attribute, tracker, timer, or tint variable outside the recipes; a press style that changes layout, the containing block, or the hit area; a fixed release duration; a container that paints for a finger or pen press on a nested control that does not activate it; and press engine code moved off first load. | -| Governing rules | `spec:AST-094` FR5, FR8, FR11, FR20, FR27, DEC-14, DEC-21; `family:action-groups` FR2; `design:user-states` DR1–DR5; `design:reduced-motion` DR1–DR2; `architecture:layer-runtime` INV22; `component:Item` FR9; `component:Button` FR15 and FR17; `module:DropdownMenu/useMenuPress` FR6; `architecture:component-import-boundaries` INV10; `spec:AST-013` FR9. | +| Area | Contract | +| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Governing contract | How a press looks and when it shows: `spec:AST-094` FR5, FR8, FR11, FR20 and DEC-21; `design:user-states` DR1–DR5; `design:reduced-motion` DR1–DR2; `architecture:layer-runtime` INV22; `component:Item` FR9. | +| System behavior | One press engine, the page press controller, writes every pressed state in Core. Each pressable surface uses one of three recipes: a momentary control, a row-wide target, or a cell or menu row. A press paints and does nothing else: it never changes layout, the hit area, or hit-testing. Every release fades on the theme's exit motion tokens. | +| End-user impact | A person sees the same press on every Astryx surface: the same tint, the same start delay inside scrolling content, the same release fade, and the same cancel when a scroll takes the touch. A press never moves a tap target, so a tap lands where the person aims it. | +| Builder impact | A component picks a recipe and states it in its own record. It adds no press attribute, tracker, timer, or tint variable of its own. A press fix lands once, in the engine or the recipe, and reaches every component that uses it. No public API changes; the recipes are exports of the private press modules. | +| Compatibility/readiness | No public API change. INV1 gap: the touch-runtime press tracker, and ClickableCard, SelectableCard, Thumbnail, Tab, Switch, Slider and the Selector-family triggers re-declare press styles (their own press variable, scale, or state) instead of using a recipe's. INV4 gap: Switch, Slider and the SegmentedControl lens release in a fixed 200 ms, and controller controls end a press after 10 px of drift outside scrolling content. INV2 gap: no component record names its recipe, and Table cells paint no press. INV3 and INV9 gap: under a finger, a press makes a control's root the containing block, so a stretched control's tap target shrinks to the control mid-press. INV5 gap: under a mouse or a pen, most surfaces paint CSS `:active`. INV8 gap: Selector-family triggers scale under reduced motion. | +| Review checks | Reject a new press attribute, tracker, timer, or tint variable outside the recipes; a press style that changes layout, the containing block, or the hit area; a fixed release duration; a container that paints for a finger or pen press on a nested control that does not activate it; and press engine code moved off first load. | +| Governing rules | `spec:AST-094` FR5, FR8, FR11, FR20, FR27, DEC-14, DEC-21; `family:action-groups` FR2; `design:user-states` DR1–DR5; `design:reduced-motion` DR1–DR2; `architecture:layer-runtime` INV22; `architecture:interaction-modality` INV13; `component:Item` FR9; `component:Button` FR15 and FR17; `module:DropdownMenu/useMenuPress` FR6; `architecture:component-import-boundaries` INV10; `spec:AST-013` FR9. | ## Purpose @@ -69,10 +69,15 @@ touch. The recipe styles paint from that attribute. ## Boundaries and invariants -- **INV1 — One engine.** The page press controller is the only code that - writes a pressed state in Core. A group slide, a press held through a drag, - and a menu's lit row are profiles of that engine. A component adds no press - attribute, tracker, timer, or tint variable of its own. +- **INV1 — One engine.** The page press controller writes the pressed state + of every press in Core. Tracking a held pointer across a group keeps the + owners `architecture:interaction-modality` INV13 names: the action-group + tracker for `family:action-groups` members, reached through + `useGroupPressTracking`, and `module:DropdownMenu/useMenuPress` for menus + and Selector's and MultiSelector's options. They are this record's group and + menu profiles. A press held through a drag is a profile of the engine. A + component adds no press attribute, tracker, timer, or tint variable of its + own. - **INV2 — Three recipes.** Every pressable Core surface uses one recipe from the table above, and its record names the recipe. The recipes are exports of the private press modules; they add no module and no public API. @@ -131,8 +136,10 @@ touch. The recipe styles paint from that attribute. `packages/core/src/hooks/usePressFeedback.ts`. - Recipe styles and attribute: `packages/core/src/privateAttributes/press.ts` and the `press*.stylex.ts` modules beside it. -- Other press trackers (INV1 gap): `packages/core/src/hooks/useGroupPressTracking.ts`, - `packages/core/src/gestures/PressTracker.ts`, `packages/core/src/hooks/useMenuPress.ts`. +- Group and menu profiles (`architecture:interaction-modality` INV13): + `packages/core/src/hooks/useGroupPressTracking.ts`, + `packages/core/src/hooks/useMenuPress.ts`. +- Other press tracker (INV1 gap): `packages/core/src/gestures/PressTracker.ts`. ## Deciding specs From 4ef2cbfdbfe58ef3fbdb80d5b76ead6e7464eb80 Mon Sep 17 00:00:00 2001 From: Cindy Zhang Date: Mon, 16 Nov 2026 11:44:24 -0800 Subject: [PATCH 08/24] docs(architecture): the surface under the finger paints (owner rule); cards stop painting for nested mouse presses --- docs/architecture/press-feedback.md | 68 ++++++++++--------- .../ClickableCard/ClickableCard.spec.md | 16 ++--- .../SelectableCard/SelectableCard.spec.md | 16 ++--- 3 files changed, 52 insertions(+), 48 deletions(-) diff --git a/docs/architecture/press-feedback.md b/docs/architecture/press-feedback.md index c7a0d270dac93..7645b480c7354 100644 --- a/docs/architecture/press-feedback.md +++ b/docs/architecture/press-feedback.md @@ -36,15 +36,15 @@ deciding_specs: [spec:AST-094/FR5, spec:AST-094/FR11, spec:AST-094/DEC-21] ## Contract at a glance -| Area | Contract | -| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Governing contract | How a press looks and when it shows: `spec:AST-094` FR5, FR8, FR11, FR20 and DEC-21; `design:user-states` DR1–DR5; `design:reduced-motion` DR1–DR2; `architecture:layer-runtime` INV22; `component:Item` FR9. | -| System behavior | One press engine, the page press controller, writes every pressed state in Core. Each pressable surface uses one of three recipes: a momentary control, a row-wide target, or a cell or menu row. A press paints and does nothing else: it never changes layout, the hit area, or hit-testing. Every release fades on the theme's exit motion tokens. | -| End-user impact | A person sees the same press on every Astryx surface: the same tint, the same start delay inside scrolling content, the same release fade, and the same cancel when a scroll takes the touch. A press never moves a tap target, so a tap lands where the person aims it. | -| Builder impact | A component picks a recipe and states it in its own record. It adds no press attribute, tracker, timer, or tint variable of its own. A press fix lands once, in the engine or the recipe, and reaches every component that uses it. No public API changes; the recipes are exports of the private press modules. | -| Compatibility/readiness | No public API change. INV1 gap: the touch-runtime press tracker, and ClickableCard, SelectableCard, Thumbnail, Tab, Switch, Slider and the Selector-family triggers re-declare press styles (their own press variable, scale, or state) instead of using a recipe's. INV4 gap: Switch, Slider and the SegmentedControl lens release in a fixed 200 ms, and controller controls end a press after 10 px of drift outside scrolling content. INV2 gap: no component record names its recipe, and Table cells paint no press. INV3 and INV9 gap: under a finger, a press makes a control's root the containing block, so a stretched control's tap target shrinks to the control mid-press. INV5 gap: under a mouse or a pen, most surfaces paint CSS `:active`. INV8 gap: Selector-family triggers scale under reduced motion. | -| Review checks | Reject a new press attribute, tracker, timer, or tint variable outside the recipes; a press style that changes layout, the containing block, or the hit area; a fixed release duration; a container that paints for a finger or pen press on a nested control that does not activate it; and press engine code moved off first load. | -| Governing rules | `spec:AST-094` FR5, FR8, FR11, FR20, FR27, DEC-14, DEC-21; `family:action-groups` FR2; `design:user-states` DR1–DR5; `design:reduced-motion` DR1–DR2; `architecture:layer-runtime` INV22; `architecture:interaction-modality` INV13; `component:Item` FR9; `component:Button` FR15 and FR17; `module:DropdownMenu/useMenuPress` FR6; `architecture:component-import-boundaries` INV10; `spec:AST-013` FR9. | +| Area | Contract | +| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Governing contract | How a press looks and when it shows: `spec:AST-094` FR5, FR8, FR11, FR20 and DEC-21; `design:user-states` DR1–DR5; `design:reduced-motion` DR1–DR2; `architecture:layer-runtime` INV22; `component:Item` FR9. | +| System behavior | One press engine, the page press controller, writes every pressed state in Core. Each pressable surface uses one of three recipes: a momentary control, a row-wide target, or a cell or menu row. A press paints and does nothing else: it never changes layout, the hit area, or hit-testing. Every release fades on the theme's exit motion tokens. | +| End-user impact | A person sees the same press on every Astryx surface: the same tint, the same start delay inside scrolling content, the same release fade, and the same cancel when a scroll takes the touch. A press never moves a tap target, so a tap lands where the person aims it. | +| Builder impact | A component picks a recipe and states it in its own record. It adds no press attribute, tracker, timer, or tint variable of its own. A press fix lands once, in the engine or the recipe, and reaches every component that uses it. No public API changes; the recipes are exports of the private press modules. | +| Compatibility/readiness | No public API change. INV1 gap: the touch-runtime press tracker, and ClickableCard, SelectableCard, Thumbnail, Tab, Switch, Slider and the Selector-family triggers re-declare press styles (their own press variable, scale, or state) instead of using a recipe's. INV4 gap: Switch, Slider and the SegmentedControl lens release in a fixed 200 ms, and controller controls end a press after 10 px of drift outside scrolling content. INV2 gap: no component record names its recipe, and Table cells paint no press. INV3 and INV9 gap: under a finger, a press makes a control's root the containing block, so a stretched control's tap target shrinks to the control mid-press. INV5 gap: under a mouse or a pen, most surfaces paint CSS `:active`. INV7 gap: a mouse press on a nested control in ClickableCard and SelectableCard paints the card's `:active`. INV8 gap: Selector-family triggers scale under reduced motion. | +| Review checks | Reject a new press attribute, tracker, timer, or tint variable outside the recipes; a press style that changes layout, the containing block, or the hit area; a fixed release duration; a container that paints for a press on a nested control, or a control that paints for a press on its container's own surface; and press engine code moved off first load. | +| Governing rules | `spec:AST-094` FR5, FR8, FR11, FR20, FR27, DEC-14, DEC-21; `family:action-groups` FR2; `design:user-states` DR1–DR5; `design:reduced-motion` DR1–DR2; `architecture:layer-runtime` INV22; `architecture:interaction-modality` INV13; `component:Item` FR9; `component:Button` FR15 and FR17; `module:DropdownMenu/useMenuPress` FR6; `architecture:component-import-boundaries` INV10; `spec:AST-013` FR9. | ## Purpose @@ -64,7 +64,7 @@ touch. The recipe styles paint from that attribute. | Recipe | Used by | What paints | Start | End | | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ | | 1. Momentary control | Button family, Link, Switch, Tab, Token, SegmentedControl segment, TopNavItem, SideNavItem, NavItem, Selector-family triggers, Step, Calendar day | The system pressed tint on the control's own press layer. A standalone control may also scale, as its record states. Option: keeps its press through a drag (Slider thumb, SegmentedControl lens, Switch thumb; `design:user-states` DR4). | Touch-down outside scrolling content; 150 ms after touch-down inside it (`spec:AST-094` FR11). | The lift, with the release fade. A scroll that takes the touch ends it with no fade. | -| 2. Row-wide target | Item and ListItem, TreeList rows, CheckboxList and RadioList rows, Collapsible trigger, ClickableCard, SelectableCard, Thumbnail | The pressed tint on the whole row or card, only for a press that would activate it. A press on a row's own box presses the row (`component:CheckboxListItem` AR3). | As recipe 1. | As recipe 1. | +| 2. Row-wide target | Item and ListItem, TreeList rows, CheckboxList and RadioList rows, Collapsible trigger, ClickableCard, SelectableCard, Thumbnail | The pressed tint on the whole row or card for a press on its own surface; a press on a nested control paints only that control (INV7). | As recipe 1. | As recipe 1. | | 3. Cell or menu row | Menu rows, picker options, CommandPalette rows, Table cells (INV2 gap) | The pressed tint on the row. At most one row of a menu is lit; a sliding finger moves the light (`module:DropdownMenu/useMenuPress` FR6). | 150 ms after touch-down inside scrolling content; at once in a menu whose rows fit (`spec:AST-094` DEC-14). | The lift acts on the lit row. A scroll that takes the touch ends it with no fade. | ## Boundaries and invariants @@ -98,29 +98,29 @@ touch. The recipe styles paint from that attribute. fixed duration. - **INV5 — Every pointer through the engine.** A mouse or pen press paints at once on `pointerdown` through the engine, with the same release fade as a - finger's, in place of CSS `:active` (`spec:AST-094` DEC-21; `component:Button` FR15), except the container case INV7 keeps. + finger's, in place of CSS `:active` (`spec:AST-094` DEC-21; `component:Button` FR15). - **INV6 — The first press.** The engine's core stays on first load: it finds the pressable element, writes the attribute, starts the delay timer, and ends the press on a scroll. Optional profiles (the group slide, the menu scrub, a press held through a drag, a row's box hold) cost an unused page at most what `architecture:component-import-boundaries` INV10 allows. Nothing is painted into server HTML that has not hydrated (`spec:AST-013` FR9). -- **INV7 — A nested control.** In recipe 2, a finger or pen press that starts - on a nested interactive element that does not activate the container paints - that element only, never its row or card (`component:Item` FR9). A press on - the row's own action, its delegated control, or its box presses the row - (`component:Item` FR9; `component:CheckboxListItem` AR3). A mouse press on a - nested control keeps the container's press paint as `component:ClickableCard` - FR5 states. +- **INV7 — The surface under the finger paints.** A press paints the surface + it lands on that invokes the action, and nothing else, for every pointer. A + press on a nested interactive element paints that element only, never its + row or card (`component:Item` FR9). A press on a row's or card's own surface + (its padding, icon, label, own action, delegated control, or box) paints the + row or card, never a control inside it (`component:Item` FR9; + `component:CheckboxListItem` AR3). - **INV8 — Reduced motion and disabled.** Under reduced motion no press scales (`design:reduced-motion` DR1). A disabled surface paints no press (`design:user-states` DR2). A control whose own popup is open does not scale (`component:Button` FR15). - **INV9 — A stretched control.** When a caller's styles make a control's root static so that its `::after` covers a row (`component:Button` FR17), - the hit area takes that row's box and stays the tap target for the whole - press, while the press paint stays on the control's own box - (`design:user-states` DR1, the named visual part). + the whole row stays the tap target for the whole press. Under INV7, a press + on the control's own box paints the control, and a press on the rest of the + row paints the row, not the control. ## Change coupling @@ -147,17 +147,21 @@ touch. The recipe styles paint from that attribute. fine-pointer profile. - Owner decision (`cixzhang`, 2026-11-16): Core's press code is one engine with three recipes, with no new module and no public API change. +- Owner decision (`cixzhang`, 2026-11-16 11:40 PT), the paint rule (INV7, INV9): + \"so pressed representation rule is the thing getting tapped and invoking the + operation is what gets tinted. so if you're pressing a button, the row + shouldn't tint.\" ## Verification -| Invariant | Evidence | Failure signal | -| --------- | -------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| INV1 | Review: no new press attribute, tracker, or tint variable outside the recipe modules | A component writes its own pressed state | -| INV2 | Each pressable component record names its recipe | A record restates press rules without a recipe | -| INV3 | `pressFeedback.test.ts`; a browser test that a point inside a caller's stretched target still hits during a press | A tap during a press misses its target, or layout shifts | -| INV4 | Computed release durations follow the theme's exit tokens and tempo on every recipe | A fixed duration, or two surfaces of one recipe that cancel the same drift differently | -| INV5 | A mouse press test per recipe asserts the press attribute, not `:active` | A mouse press paints with no shared release fade | -| INV6 | Size report: the engine core is on first load; optional profiles within INV10 | The engine core moves off first load, or an unused profile exceeds INV10 | -| INV7 | A press on a nested control in a row and in a card, for finger, pen, and mouse | A finger or pen press on a nested control that does not activate the container paints the container, or a press on the row's own action, delegated control, or box does not paint the row | -| INV8 | Reduced-motion and disabled press tests per recipe | A scale under reduced motion, or paint on a disabled surface | -| INV9 | A browser test: a point inside a caller's stretched target still hits during a press, and only the control's own box tints | A tap during a press misses, or the tint spreads past the control | +| Invariant | Evidence | Failure signal | +| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | +| INV1 | Review: no new press attribute, tracker, or tint variable outside the recipe modules | A component writes its own pressed state | +| INV2 | Each pressable component record names its recipe | A record restates press rules without a recipe | +| INV3 | `pressFeedback.test.ts`; a browser test that a point inside a caller's stretched target still hits during a press | A tap during a press misses its target, or layout shifts | +| INV4 | Computed release durations follow the theme's exit tokens and tempo on every recipe | A fixed duration, or two surfaces of one recipe that cancel the same drift differently | +| INV5 | A mouse press test per recipe asserts the press attribute, not `:active` | A mouse press paints with no shared release fade | +| INV6 | Size report: the engine core is on first load; optional profiles within INV10 | The engine core moves off first load, or an unused profile exceeds INV10 | +| INV7 | A press on a nested control in a row and in a card, for finger, pen, and mouse | A press from any pointer on a nested control paints the container, or a press on the row's own action, delegated control, or box does not paint the row | +| INV8 | Reduced-motion and disabled press tests per recipe | A scale under reduced motion, or paint on a disabled surface | +| INV9 | A browser test: a point inside a caller's stretched target still hits during a press; a press on the control tints the control and a press on the rest of the row tints the row | A tap during a press misses, a press on the control paints the row, or a press on the row paints the control | diff --git a/docs/specs/components/ClickableCard/ClickableCard.spec.md b/docs/specs/components/ClickableCard/ClickableCard.spec.md index 459cba23d7a23..60455705f15af 100644 --- a/docs/specs/components/ClickableCard/ClickableCard.spec.md +++ b/docs/specs/components/ClickableCard/ClickableCard.spec.md @@ -121,14 +121,14 @@ Consumer migration instructions belong in consumer docs and release notes. ## Behavioral and layout contract -| ID | Invariant | Basis | -| --- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- | -| FR1 | The root is Card's `div`. With `href`, a visually hidden native link holds the destination and `target`; otherwise a visually hidden `button type="button"` calls `onClick`. `label` names that control, and the hidden control is the card's tab stop. | Current source and tests | -| FR2 | A primary-button press on the card surface calls `onClick` once with the card as `currentTarget`, then performs an accepted navigation unless the callback cancels it. A middle press on the surface of a card given `href` opens an accepted destination in a new tab without calling `onClick`. A press inside a nested interactive descendant, inside an open Tooltip or HoverCard surface (`component:Tooltip` FR11), or one that ends a text selection, does not activate the card. Activating the hidden button of an action card calls `onClick` once; activating the hidden link navigates without calling `onClick`. | Current source and tests; `architecture:public-component-api` INV7 | -| FR3 | Plain, new-tab, modified, middle-click, and surface-delegated navigation use the shared destination decision; a blocked destination does not navigate. | `family:navigation-destinations` FR1, FR3–FR5 | -| FR4 | `isDisabled` keeps the hidden control focusable with `aria-disabled="true"`; Enter, Space, and clicks on it do nothing. A disabled link keeps its link role and name but has no `href` or `target`. The control stays focusable and announced (`spec:AST-085` FR1, FR2, FR5); the card's own click and mouseup handling and the caller's `onMouseUp` are removed, other caller event props still reach the root, and the surface shows no hover or pressed paint (`spec:AST-085` FR6), and renders at half opacity. The disabled state is reflected on the owning target (`architecture:component-theming-surface` INV6). Implementation gap: the `clickable-card` target reflects no disabled state (Current-state impact). | Current source and tests | -| FR5 | While enabled, the root paints the shared hover overlay under a hover-capable pointer and the pressed overlay for mouse and touch presses that would activate the card; a touch press that starts on a nested interactive element shows no pressed paint, since it does not activate the card (the counterpart of FR2's activation rule), while a mouse press there keeps the `:active` paint, and a bordered card's border responds to hover. A touch press shows at once. Under the touch presentation, its release fades on the theme's exit motion tokens (`--duration-exit`, `--ease-exit`), per `spec:AST-094` FR5; a mouse press keeps the card's desktop press styling. Keyboard focus on the hidden control shows the shared focus outline on the root. | Current source, stories, and `architecture:interaction-modality` | -| FR6 | The root carries the `clickable-card` target reflecting `variant` beside Card's target. `ref` reaches the root; supported DOM, ARIA, data, and event props reach it; a caller `onMouseUp` runs after the card's own; `xstyle`, `className`, and `style` compose after the component styles. | Current source and tests; `architecture:public-component-api` INV5–INV8 | +| ID | Invariant | Basis | +| --- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- | +| FR1 | The root is Card's `div`. With `href`, a visually hidden native link holds the destination and `target`; otherwise a visually hidden `button type="button"` calls `onClick`. `label` names that control, and the hidden control is the card's tab stop. | Current source and tests | +| FR2 | A primary-button press on the card surface calls `onClick` once with the card as `currentTarget`, then performs an accepted navigation unless the callback cancels it. A middle press on the surface of a card given `href` opens an accepted destination in a new tab without calling `onClick`. A press inside a nested interactive descendant, inside an open Tooltip or HoverCard surface (`component:Tooltip` FR11), or one that ends a text selection, does not activate the card. Activating the hidden button of an action card calls `onClick` once; activating the hidden link navigates without calling `onClick`. | Current source and tests; `architecture:public-component-api` INV7 | +| FR3 | Plain, new-tab, modified, middle-click, and surface-delegated navigation use the shared destination decision; a blocked destination does not navigate. | `family:navigation-destinations` FR1, FR3–FR5 | +| FR4 | `isDisabled` keeps the hidden control focusable with `aria-disabled="true"`; Enter, Space, and clicks on it do nothing. A disabled link keeps its link role and name but has no `href` or `target`. The control stays focusable and announced (`spec:AST-085` FR1, FR2, FR5); the card's own click and mouseup handling and the caller's `onMouseUp` are removed, other caller event props still reach the root, and the surface shows no hover or pressed paint (`spec:AST-085` FR6), and renders at half opacity. The disabled state is reflected on the owning target (`architecture:component-theming-surface` INV6). Implementation gap: the `clickable-card` target reflects no disabled state (Current-state impact). | Current source and tests | +| FR5 | While enabled, the root paints the shared hover overlay under a hover-capable pointer and the pressed overlay for mouse and touch presses that would activate the card; a press from any pointer that starts on a nested interactive element shows no pressed paint on the card, since it does not activate the card (the counterpart of FR2's activation rule; `architecture:press-feedback` INV7), and a bordered card's border responds to hover. A touch press shows at once. Under the touch presentation, its release fades on the theme's exit motion tokens (`--duration-exit`, `--ease-exit`), per `spec:AST-094` FR5; a mouse press keeps the card's desktop press styling. Keyboard focus on the hidden control shows the shared focus outline on the root. | Current source, stories, and `architecture:interaction-modality` | +| FR6 | The root carries the `clickable-card` target reflecting `variant` beside Card's target. `ref` reaches the root; supported DOM, ARIA, data, and event props reach it; a caller `onMouseUp` runs after the card's own; `xstyle`, `className`, and `style` compose after the component styles. | Current source and tests; `architecture:public-component-api` INV5–INV8 | ### Allowed variation diff --git a/docs/specs/components/SelectableCard/SelectableCard.spec.md b/docs/specs/components/SelectableCard/SelectableCard.spec.md index 2bf43ee9063f3..7ff6b56a046f0 100644 --- a/docs/specs/components/SelectableCard/SelectableCard.spec.md +++ b/docs/specs/components/SelectableCard/SelectableCard.spec.md @@ -145,14 +145,14 @@ Consumer migration instructions belong in consumer docs and release notes. ## Behavioral and layout contract -| ID | Invariant | Basis | -| --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------ | -| FR1 | SelectableCard renders `component:Card` with the given `variant`, `elevation`, `padding`, and sizing. The root also carries the `selectable-card` target reflecting `variant` and `selected`, and the first child is a visually hidden native `input type="checkbox"` named by `label` with `checked` equal to `isSelected`. | Current source and tests | -| FR2 | While enabled, a click on the card surface, a click or Space on the checkbox, or Enter on the checkbox calls `onChange(!isSelected)` exactly once. A click that belongs to nested interactive content, an open Tooltip or HoverCard surface (`component:Tooltip` FR11), or selected text does not toggle. A caller `onClick` runs after the toggle for a surface click, before it for a click or Space on the checkbox, and not at all for Enter; it also runs for clicks that do not toggle, including a click inside an open Tooltip or HoverCard surface. At the next minor, staged as `[breaking]`, a click inside an open layer stops at the layer root and the caller `onClick` no longer receives it (`architecture:layer-runtime` INV17); implementation gap: not built. A caller `onMouseUp` runs after the card's own handling. | Current source and tests | -| FR3 | Selection adds a 2px inset ring through Card's ring variable, so layout does not move, and composes with any elevation shadow. `default`, `transparent`, and `muted` ring in `--color-accent`; each palette variant rings in its `--color-border-`; a theme-added variant rings in `--selectable-card-ring-color`. Selection also colors the border in the ring color where Card draws one, which is only the `default` variant. | Current source and tests | -| FR4 | While enabled, the surface paints the shared hover overlay under a hover-capable pointer and the pressed overlay for mouse and touch presses; a touch press that starts on a nested interactive element shows no pressed paint, since it does not activate the card, while a mouse press there keeps the `:active` paint. A touch press shows at once. Under the touch presentation, its release fades on the theme's exit motion tokens (`--duration-exit`, `--ease-exit`), per `spec:AST-094` FR5; a mouse press keeps the card's desktop press styling. Keyboard focus on the hidden checkbox shows one indicator on the card root (`architecture:interaction-modality` INV3). Implementation gap: the root outlines while any descendant has `:focus-visible`, so focusing a nested control draws both the card outline and the control's own (Current-state impact). | Current source and tests | -| FR5 | `isDisabled` dims the card to half opacity, removes the card's own click and mouseup handling and the caller's `onClick` and `onMouseUp` (other caller event props still reach the root) and the hover and pressed overlays (`spec:AST-085` FR6), and keeps the checkbox focusable with `aria-disabled="true"`; no click, Space, or Enter calls `onChange`. The disabled state is reflected on the owning target (`architecture:component-theming-surface` INV6). Implementation gap: the `selectable-card` target reflects `variant` and `selected` but not the disabled state (Current-state impact). | Current source and tests | -| FR6 | `ref` reaches the Card root. Supported DOM, ARIA, data, and event props reach the root; `xstyle`, `className`, and `style` merge after the component's interactive styles. | Current source and tests | +| ID | Invariant | Basis | +| --- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------ | +| FR1 | SelectableCard renders `component:Card` with the given `variant`, `elevation`, `padding`, and sizing. The root also carries the `selectable-card` target reflecting `variant` and `selected`, and the first child is a visually hidden native `input type="checkbox"` named by `label` with `checked` equal to `isSelected`. | Current source and tests | +| FR2 | While enabled, a click on the card surface, a click or Space on the checkbox, or Enter on the checkbox calls `onChange(!isSelected)` exactly once. A click that belongs to nested interactive content, an open Tooltip or HoverCard surface (`component:Tooltip` FR11), or selected text does not toggle. A caller `onClick` runs after the toggle for a surface click, before it for a click or Space on the checkbox, and not at all for Enter; it also runs for clicks that do not toggle, including a click inside an open Tooltip or HoverCard surface. At the next minor, staged as `[breaking]`, a click inside an open layer stops at the layer root and the caller `onClick` no longer receives it (`architecture:layer-runtime` INV17); implementation gap: not built. A caller `onMouseUp` runs after the card's own handling. | Current source and tests | +| FR3 | Selection adds a 2px inset ring through Card's ring variable, so layout does not move, and composes with any elevation shadow. `default`, `transparent`, and `muted` ring in `--color-accent`; each palette variant rings in its `--color-border-`; a theme-added variant rings in `--selectable-card-ring-color`. Selection also colors the border in the ring color where Card draws one, which is only the `default` variant. | Current source and tests | +| FR4 | While enabled, the surface paints the shared hover overlay under a hover-capable pointer and the pressed overlay for mouse and touch presses; a press from any pointer that starts on a nested interactive element shows no pressed paint on the card, since it does not activate the card (`architecture:press-feedback` INV7). A touch press shows at once. Under the touch presentation, its release fades on the theme's exit motion tokens (`--duration-exit`, `--ease-exit`), per `spec:AST-094` FR5; a mouse press keeps the card's desktop press styling. Keyboard focus on the hidden checkbox shows one indicator on the card root (`architecture:interaction-modality` INV3). Implementation gap: the root outlines while any descendant has `:focus-visible`, so focusing a nested control draws both the card outline and the control's own (Current-state impact). | Current source and tests | +| FR5 | `isDisabled` dims the card to half opacity, removes the card's own click and mouseup handling and the caller's `onClick` and `onMouseUp` (other caller event props still reach the root) and the hover and pressed overlays (`spec:AST-085` FR6), and keeps the checkbox focusable with `aria-disabled="true"`; no click, Space, or Enter calls `onChange`. The disabled state is reflected on the owning target (`architecture:component-theming-surface` INV6). Implementation gap: the `selectable-card` target reflects `variant` and `selected` but not the disabled state (Current-state impact). | Current source and tests | +| FR6 | `ref` reaches the Card root. Supported DOM, ARIA, data, and event props reach the root; `xstyle`, `className`, and `style` merge after the component's interactive styles. | Current source and tests | ### Allowed variation From cec54c6393aa4bcdcb7a68519e025663d173b388 Mon Sep 17 00:00:00 2001 From: Cindy Zhang Date: Mon, 16 Nov 2026 11:51:33 -0800 Subject: [PATCH 09/24] docs(architecture): press feedback names who writes a group press, and scopes INV4's signal to one profile --- docs/architecture/press-feedback.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/architecture/press-feedback.md b/docs/architecture/press-feedback.md index 7645b480c7354..7febfc602eda2 100644 --- a/docs/architecture/press-feedback.md +++ b/docs/architecture/press-feedback.md @@ -70,14 +70,14 @@ touch. The recipe styles paint from that attribute. ## Boundaries and invariants - **INV1 — One engine.** The page press controller writes the pressed state - of every press in Core. Tracking a held pointer across a group keeps the - owners `architecture:interaction-modality` INV13 names: the action-group + of a single press in Core. Across a group, the owners + `architecture:interaction-modality` INV13 names write it: the action-group tracker for `family:action-groups` members, reached through `useGroupPressTracking`, and `module:DropdownMenu/useMenuPress` for menus and Selector's and MultiSelector's options. They are this record's group and - menu profiles. A press held through a drag is a profile of the engine. A - component adds no press attribute, tracker, timer, or tint variable of its - own. + menu profiles. A press held through a drag is a profile of the engine. No + other code writes a pressed state, and a component adds no press attribute, + tracker, timer, or tint variable of its own. - **INV2 — Three recipes.** Every pressable Core surface uses one recipe from the table above, and its record names the recipe. The recipes are exports of the private press modules; they add no module and no public API. @@ -159,7 +159,7 @@ touch. The recipe styles paint from that attribute. | INV1 | Review: no new press attribute, tracker, or tint variable outside the recipe modules | A component writes its own pressed state | | INV2 | Each pressable component record names its recipe | A record restates press rules without a recipe | | INV3 | `pressFeedback.test.ts`; a browser test that a point inside a caller's stretched target still hits during a press | A tap during a press misses its target, or layout shifts | -| INV4 | Computed release durations follow the theme's exit tokens and tempo on every recipe | A fixed duration, or two surfaces of one recipe that cancel the same drift differently | +| INV4 | Computed release durations follow the theme's exit tokens and tempo on every recipe | A fixed duration, or two surfaces of one recipe and one profile that cancel the same drift differently | | INV5 | A mouse press test per recipe asserts the press attribute, not `:active` | A mouse press paints with no shared release fade | | INV6 | Size report: the engine core is on first load; optional profiles within INV10 | The engine core moves off first load, or an unused profile exceeds INV10 | | INV7 | A press on a nested control in a row and in a card, for finger, pen, and mouse | A press from any pointer on a nested control paints the container, or a press on the row's own action, delegated control, or box does not paint the row | From a860b7b8feec9a900dbae0c42f434c6a5c3cdfc9 Mon Sep 17 00:00:00 2001 From: Cindy Zhang Date: Mon, 16 Nov 2026 12:03:51 -0800 Subject: [PATCH 10/24] docs(architecture): the menu profile names useMenuPress's own modules --- docs/architecture/press-feedback.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/architecture/press-feedback.md b/docs/architecture/press-feedback.md index 7febfc602eda2..66357d8a6e0ea 100644 --- a/docs/architecture/press-feedback.md +++ b/docs/architecture/press-feedback.md @@ -138,7 +138,9 @@ touch. The recipe styles paint from that attribute. and the `press*.stylex.ts` modules beside it. - Group and menu profiles (`architecture:interaction-modality` INV13): `packages/core/src/hooks/useGroupPressTracking.ts`, - `packages/core/src/hooks/useMenuPress.ts`. + `packages/core/src/hooks/useMenuPress.ts`, with its + `menuPressOnItems.ts` and `menuPressGesture.ts` modules + (`module:DropdownMenu/useMenuPress`). - Other press tracker (INV1 gap): `packages/core/src/gestures/PressTracker.ts`. ## Deciding specs From 68a13eb2f8b45944f12d3488d2a50b34b895f201 Mon Sep 17 00:00:00 2001 From: Cindy Zhang Date: Mon, 16 Nov 2026 12:39:04 -0800 Subject: [PATCH 11/24] docs: the surface under the finger paints for every pointer in Item, TreeList, Token and the cards; gaps stated --- docs/architecture/press-feedback.md | 52 ++++++++++--------- .../ClickableCard/ClickableCard.spec.md | 2 +- docs/specs/components/Item/Item.spec.md | 42 +++++++-------- .../SelectableCard/SelectableCard.spec.md | 18 +++---- docs/specs/components/Token/Token.spec.md | 20 +++---- .../components/TreeList/TreeList.spec.md | 40 +++++++------- 6 files changed, 88 insertions(+), 86 deletions(-) diff --git a/docs/architecture/press-feedback.md b/docs/architecture/press-feedback.md index 66357d8a6e0ea..0d0818eb01259 100644 --- a/docs/architecture/press-feedback.md +++ b/docs/architecture/press-feedback.md @@ -36,15 +36,15 @@ deciding_specs: [spec:AST-094/FR5, spec:AST-094/FR11, spec:AST-094/DEC-21] ## Contract at a glance -| Area | Contract | -| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Governing contract | How a press looks and when it shows: `spec:AST-094` FR5, FR8, FR11, FR20 and DEC-21; `design:user-states` DR1–DR5; `design:reduced-motion` DR1–DR2; `architecture:layer-runtime` INV22; `component:Item` FR9. | -| System behavior | One press engine, the page press controller, writes every pressed state in Core. Each pressable surface uses one of three recipes: a momentary control, a row-wide target, or a cell or menu row. A press paints and does nothing else: it never changes layout, the hit area, or hit-testing. Every release fades on the theme's exit motion tokens. | -| End-user impact | A person sees the same press on every Astryx surface: the same tint, the same start delay inside scrolling content, the same release fade, and the same cancel when a scroll takes the touch. A press never moves a tap target, so a tap lands where the person aims it. | -| Builder impact | A component picks a recipe and states it in its own record. It adds no press attribute, tracker, timer, or tint variable of its own. A press fix lands once, in the engine or the recipe, and reaches every component that uses it. No public API changes; the recipes are exports of the private press modules. | -| Compatibility/readiness | No public API change. INV1 gap: the touch-runtime press tracker, and ClickableCard, SelectableCard, Thumbnail, Tab, Switch, Slider and the Selector-family triggers re-declare press styles (their own press variable, scale, or state) instead of using a recipe's. INV4 gap: Switch, Slider and the SegmentedControl lens release in a fixed 200 ms, and controller controls end a press after 10 px of drift outside scrolling content. INV2 gap: no component record names its recipe, and Table cells paint no press. INV3 and INV9 gap: under a finger, a press makes a control's root the containing block, so a stretched control's tap target shrinks to the control mid-press. INV5 gap: under a mouse or a pen, most surfaces paint CSS `:active`. INV7 gap: a mouse press on a nested control in ClickableCard and SelectableCard paints the card's `:active`. INV8 gap: Selector-family triggers scale under reduced motion. | -| Review checks | Reject a new press attribute, tracker, timer, or tint variable outside the recipes; a press style that changes layout, the containing block, or the hit area; a fixed release duration; a container that paints for a press on a nested control, or a control that paints for a press on its container's own surface; and press engine code moved off first load. | -| Governing rules | `spec:AST-094` FR5, FR8, FR11, FR20, FR27, DEC-14, DEC-21; `family:action-groups` FR2; `design:user-states` DR1–DR5; `design:reduced-motion` DR1–DR2; `architecture:layer-runtime` INV22; `architecture:interaction-modality` INV13; `component:Item` FR9; `component:Button` FR15 and FR17; `module:DropdownMenu/useMenuPress` FR6; `architecture:component-import-boundaries` INV10; `spec:AST-013` FR9. | +| Area | Contract | +| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Governing contract | How a press looks and when it shows: `spec:AST-094` FR5, FR8, FR11, FR20 and DEC-21; `design:user-states` DR1–DR5; `design:reduced-motion` DR1–DR2; `architecture:layer-runtime` INV22; `component:Item` FR9. | +| System behavior | One press engine, the page press controller, writes the pressed state of a single press; across a group, the group and menu owners of `architecture:interaction-modality` INV13 write it. Each pressable surface uses one of three recipes: a momentary control, a row-wide target, or a cell or menu row. A press paints and does nothing else: it never changes layout, the hit area, or hit-testing. Every release fades on the theme's exit motion tokens. | +| End-user impact | A person sees the same press on every Astryx surface: the same tint, the same start delay inside scrolling content, the same release fade, and the same cancel when a scroll takes the touch. A press never moves a tap target, so a tap lands where the person aims it. | +| Builder impact | A component picks a recipe and states it in its own record. It adds no press attribute, tracker, timer, or tint variable of its own. A press fix lands once, in the engine or the recipe, and reaches every component that uses it. No public API changes; the recipes are exports of the private press modules. | +| Compatibility/readiness | No public API change. INV1 gap: the touch-runtime press tracker, and ClickableCard, SelectableCard, Thumbnail, Tab, Switch, Slider and the Selector-family triggers re-declare press styles (their own press variable, scale, or state) instead of using a recipe's. INV4 gap: Switch, Slider and the SegmentedControl lens release in a fixed 200 ms, and controller controls end a press after 10 px of drift outside scrolling content. INV2 gap: no component record names its recipe, and Table cells paint no press. INV3 and INV9 gap: under a finger, a press makes a control's root the containing block, so a stretched control's tap target shrinks to the control mid-press. INV5 gap: under a mouse or a pen, most surfaces paint CSS `:active`. INV7 gap: a mouse press on a nested control still paints the container's `:active` in Item rows (outside CheckboxList and RadioList), TreeList rows, Token, ClickableCard and SelectableCard. INV9 gap: a press beside a stretched control paints the control instead of the row. INV8 gap: Selector-family triggers scale under reduced motion. | +| Review checks | Reject a new press attribute, tracker, timer, or tint variable outside the recipes; a press style that changes layout, the containing block, or the hit area; a fixed release duration; a container that paints for a press on a nested control that does not activate it, or a control that paints for a press on its container's own surface; and press engine code moved off first load. | +| Governing rules | `spec:AST-094` FR5, FR8, FR11, FR20, FR27, DEC-14, DEC-21; `family:action-groups` FR2; `design:user-states` DR1–DR5; `design:reduced-motion` DR1–DR2; `architecture:layer-runtime` INV22; `architecture:interaction-modality` INV13; `component:Item` FR9; `component:Button` FR15 and FR17; `module:DropdownMenu/useMenuPress` FR6; `architecture:component-import-boundaries` INV10; `spec:AST-013` FR9. | ## Purpose @@ -64,7 +64,7 @@ touch. The recipe styles paint from that attribute. | Recipe | Used by | What paints | Start | End | | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ | | 1. Momentary control | Button family, Link, Switch, Tab, Token, SegmentedControl segment, TopNavItem, SideNavItem, NavItem, Selector-family triggers, Step, Calendar day | The system pressed tint on the control's own press layer. A standalone control may also scale, as its record states. Option: keeps its press through a drag (Slider thumb, SegmentedControl lens, Switch thumb; `design:user-states` DR4). | Touch-down outside scrolling content; 150 ms after touch-down inside it (`spec:AST-094` FR11). | The lift, with the release fade. A scroll that takes the touch ends it with no fade. | -| 2. Row-wide target | Item and ListItem, TreeList rows, CheckboxList and RadioList rows, Collapsible trigger, ClickableCard, SelectableCard, Thumbnail | The pressed tint on the whole row or card for a press on its own surface; a press on a nested control paints only that control (INV7). | As recipe 1. | As recipe 1. | +| 2. Row-wide target | Item and ListItem, TreeList rows, CheckboxList and RadioList rows, Collapsible trigger, ClickableCard, SelectableCard, Thumbnail | The pressed tint on the whole row or card for a press on its own surface; a press on a nested control that does not activate the row paints only that control (INV7). | As recipe 1. | As recipe 1. | | 3. Cell or menu row | Menu rows, picker options, CommandPalette rows, Table cells (INV2 gap) | The pressed tint on the row. At most one row of a menu is lit; a sliding finger moves the light (`module:DropdownMenu/useMenuPress` FR6). | 150 ms after touch-down inside scrolling content; at once in a menu whose rows fit (`spec:AST-094` DEC-14). | The lift acts on the lit row. A scroll that takes the touch ends it with no fade. | ## Boundaries and invariants @@ -107,10 +107,12 @@ touch. The recipe styles paint from that attribute. is painted into server HTML that has not hydrated (`spec:AST-013` FR9). - **INV7 — The surface under the finger paints.** A press paints the surface it lands on that invokes the action, and nothing else, for every pointer. A - press on a nested interactive element paints that element only, never its - row or card (`component:Item` FR9). A press on a row's or card's own surface - (its padding, icon, label, own action, delegated control, or box) paints the - row or card, never a control inside it (`component:Item` FR9; + press on a nested interactive element that does not activate the row or card + paints that element only, never the row or card. A press on a row's or card's + own surface (its padding, icon, label, own action, delegated control, or + box) paints the row or card, never a control inside it. In a row whose root + is a link or that carries a parent-supplied `role`, a press on a nested + control activates the row, so the row paints (`component:Item` FR9; `component:CheckboxListItem` AR3). - **INV8 — Reduced motion and disabled.** Under reduced motion no press scales (`design:reduced-motion` DR1). A disabled surface paints no press @@ -156,14 +158,14 @@ touch. The recipe styles paint from that attribute. ## Verification -| Invariant | Evidence | Failure signal | -| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | -| INV1 | Review: no new press attribute, tracker, or tint variable outside the recipe modules | A component writes its own pressed state | -| INV2 | Each pressable component record names its recipe | A record restates press rules without a recipe | -| INV3 | `pressFeedback.test.ts`; a browser test that a point inside a caller's stretched target still hits during a press | A tap during a press misses its target, or layout shifts | -| INV4 | Computed release durations follow the theme's exit tokens and tempo on every recipe | A fixed duration, or two surfaces of one recipe and one profile that cancel the same drift differently | -| INV5 | A mouse press test per recipe asserts the press attribute, not `:active` | A mouse press paints with no shared release fade | -| INV6 | Size report: the engine core is on first load; optional profiles within INV10 | The engine core moves off first load, or an unused profile exceeds INV10 | -| INV7 | A press on a nested control in a row and in a card, for finger, pen, and mouse | A press from any pointer on a nested control paints the container, or a press on the row's own action, delegated control, or box does not paint the row | -| INV8 | Reduced-motion and disabled press tests per recipe | A scale under reduced motion, or paint on a disabled surface | -| INV9 | A browser test: a point inside a caller's stretched target still hits during a press; a press on the control tints the control and a press on the rest of the row tints the row | A tap during a press misses, a press on the control paints the row, or a press on the row paints the control | +| Invariant | Evidence | Failure signal | +| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| INV1 | Review: no new press attribute, tracker, or tint variable outside the recipe modules | A component writes its own pressed state | +| INV2 | Each pressable component record names its recipe | A record restates press rules without a recipe | +| INV3 | `pressFeedback.test.ts`; a browser test that a point inside a caller's stretched target still hits during a press | A tap during a press misses its target, or layout shifts | +| INV4 | Computed release durations follow the theme's exit tokens and tempo on every recipe | A fixed duration, or two surfaces of one recipe and one profile that cancel the same drift differently | +| INV5 | A mouse press test per recipe asserts the press attribute, not `:active` | A mouse press paints with no shared release fade | +| INV6 | Size report: the engine core is on first load; optional profiles within INV10 | The engine core moves off first load, or an unused profile exceeds INV10 | +| INV7 | A press on a nested control in a row and in a card, for finger, pen, and mouse; a press on a nested control in a link-root or role row | A press on a nested control that does not activate the container paints the container, a press on the row's own action, delegated control, or box does not paint the row, or a press that activates a link-root or role row does not paint it | +| INV8 | Reduced-motion and disabled press tests per recipe | A scale under reduced motion, or paint on a disabled surface | +| INV9 | A browser test: a point inside a caller's stretched target still hits during a press; a press on the control tints the control and a press on the rest of the row tints the row | A tap during a press misses, a press on the control paints the row, or a press on the row paints the control | diff --git a/docs/specs/components/ClickableCard/ClickableCard.spec.md b/docs/specs/components/ClickableCard/ClickableCard.spec.md index 60455705f15af..fe5970d9fc62e 100644 --- a/docs/specs/components/ClickableCard/ClickableCard.spec.md +++ b/docs/specs/components/ClickableCard/ClickableCard.spec.md @@ -57,7 +57,7 @@ system_specs: [spec:AST-005, spec:AST-009, spec:AST-085] | Behavior | A visually hidden native button or link owns the card's action; the whole card surface activates it, while nested controls and selected text keep their own outcomes. | | End-user impact | People can activate a card from anywhere on it, by pointer or keyboard, and a disabled card stays reachable and announced while doing nothing. | | Builder impact | A theme's exit duration and easing set the touch press release (FR5); no API changes. | -| Compatibility/readiness | No API changes; the touch press release changes (FR5, `spec:AST-094` FR5). Two implementation gaps are listed under Current-state impact. | +| Compatibility/readiness | No API changes; the touch press release changes (FR5, `spec:AST-094` FR5). Two implementation gaps are listed under Current-state impact. FR5 gap: a mouse press that starts on a nested control still paints the card's `:active`. | | Review checks | Reject a live destination while disabled, duplicate activation, activation from a nested control or selected text, a destination that skips the shared decision, or lost focus paint. | | Governing rules | `family:navigation-destinations/FR1,FR3–FR5`; `architecture:interaction-modality/INV2–INV5`; `architecture:public-component-api/INV5–INV8`; `spec:AST-085` FR1, FR2, FR5, FR6; `component:ClickableCard/FR5` (the touch press release); `spec:AST-094/FR5` (the press release's exit tokens). | diff --git a/docs/specs/components/Item/Item.spec.md b/docs/specs/components/Item/Item.spec.md index 0cc9743819456..77e8ef16c3f33 100644 --- a/docs/specs/components/Item/Item.spec.md +++ b/docs/specs/components/Item/Item.spec.md @@ -45,15 +45,15 @@ claims it. ## Contract at a glance -| Area | Contract | -| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Public contract | `align?: 'center' \| 'start' \| 'first-line'` on Item, ListItem, RadioListItem, and CheckboxListItem; default `center`. | -| Behavior | `first-line` centers each start and end slot on the label's first line, for any slot height; a slot taller than that line moves the text down rather than leaving the row. | -| End-user impact | A small status dot, radio, or age stays level with the first line of a wrapped label instead of drifting to the middle of the row (`center`) or riding above the line (`start`). | -| Builder impact | None by default. A builder opts in per row with `align="first-line"`; theme authors may style the `item` target's `first-line` alignment. | -| Compatibility/readiness | Additive: a new value on an existing closed axis and typed forwarding of an existing runtime pass-through. Rows that omit `align` are unchanged. | -| Review checks | Reject a changed default, changed `center`/`start` geometry, JavaScript measurement, a slot pushed outside the row, a second theme target, or a composing row that drops the value. | -| Governing rules | FR1–FR8 below; `architecture:component-theming-surface/INV6`; `spec:AST-017/FR3`. | +| Area | Contract | +| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Public contract | `align?: 'center' \| 'start' \| 'first-line'` on Item, ListItem, RadioListItem, and CheckboxListItem; default `center`. | +| Behavior | `first-line` centers each start and end slot on the label's first line, for any slot height; a slot taller than that line moves the text down rather than leaving the row. | +| End-user impact | A small status dot, radio, or age stays level with the first line of a wrapped label instead of drifting to the middle of the row (`center`) or riding above the line (`start`). | +| Builder impact | None by default. A builder opts in per row with `align="first-line"`; theme authors may style the `item` target's `first-line` alignment. | +| Compatibility/readiness | Additive: a new value on an existing closed axis and typed forwarding of an existing runtime pass-through. Rows that omit `align` are unchanged. FR9 gap: outside a CheckboxList or RadioList row, a mouse press that starts on a nested control still paints the row's `:active`. | +| Review checks | Reject a changed default, changed `center`/`start` geometry, JavaScript measurement, a slot pushed outside the row, a second theme target, or a composing row that drops the value. | +| Governing rules | FR1–FR8 below; `architecture:component-theming-surface/INV6`; `spec:AST-017/FR3`. | This table is a review projection; the body below is authoritative. @@ -104,18 +104,18 @@ Consumer migration instructions belong in consumer docs and release notes. ## Behavioral and layout contract -| ID | Invariant | Basis | Draft review state | -| ---- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------- | -| FR1 | Item MUST accept `align` with exactly `center`, `start`, and `first-line`, and MUST resolve an omitted value to `center`. The geometry of `center` and `start` MUST NOT change. | `component:Item/DEC-1` | settled | -| FR2 | Under `first-line`, the block-axis center of each rendered start-content and end-content slot MUST coincide with the block-axis center of the label's first line box, for every slot block size. | Owner direction | settled | -| FR3 | Under `first-line`, a slot taller than the label's first line MUST stay inside the row's content box: the label and description move down by the difference, and the row grows to fit. No slot is clipped or painted into the row's block padding. | Owner direction | settled | -| FR4 | A row whose label renders a single line and which has no description MUST render identically under `first-line` and `center`, for every slot block size. | Follows from FR2 and FR3 | settled | -| FR5 | The first line box is the label line as Item styles it, from the active theme's body text size and leading. A theme that changes those tokens moves the alignment with them. Caller content inside `label` that sets its own font size or line height is outside the FR2 guarantee. | Shared typography source | settled | -| FR6 | `first-line` MUST hold in every density, in `stacked` and `inline` layouts, with `labelLines` truncation, and in plain, button, link, link-root, delegated, and parent-role rows. In right-to-left text it MUST produce the same block-axis placement with the slots mirrored by logical order and no DOM reordering. | `architecture:internationalization` | settled | -| FR7 | The `item` theme target MUST reflect the resolved alignment as its existing `align` selector axis, including `first-line`, and Item's public theming metadata MUST list that value. The alignment axis adds no new target or theme-level default. | `architecture:component-theming-surface/INV6`; `component:Item/DEC-2` | settled | -| FR8 | ListItem, RadioListItem, and CheckboxListItem MUST expose `align` with Item's values and default and forward it unchanged to the Item row they render. A composing row MUST NOT drop, remap, or narrow the value. | Owner direction | settled | -| FR9 | An interactive row (an `onClick` row, an `href` row, or a delegated row with `interactiveRef`) shows its touch pressed paint only for a press that would activate it: a finger press on the row's surface or on its own action (its invisible button or link, or the control it delegates to) paints the row, and a finger press that starts on another interactive element inside the row paints none. In a row with a parent-supplied `role`, or a row whose root is a link, a press on a nested control activates the row, so it paints. On a row that owns a control's box, as a CheckboxList or RadioList row does, a mouse's or a pen's press that starts on another interactive element shows no touch pressed paint either. Such a mouse press keeps the row's `:active` paint. | Owner direction, 2026-11-03: no pressed state on a container for a press that does not activate it; owner decision, 2026-11-11: a mouse and a pen too, on a row that owns a control's box | settled | -| FR10 | The `item` theme target MUST reflect a highlighted, selected, or disabled row as `data-highlighted`, `data-selected`, and `data-disabled`, each present only while its state holds, with the names CommandPaletteItem uses. A row that composes Item reflects the states it passes to Item. | `architecture:component-theming-surface/INV6`; shipped source and focused tests, not owner-reviewed | settled; not owner-reviewed | +| ID | Invariant | Basis | Draft review state | +| ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------- | +| FR1 | Item MUST accept `align` with exactly `center`, `start`, and `first-line`, and MUST resolve an omitted value to `center`. The geometry of `center` and `start` MUST NOT change. | `component:Item/DEC-1` | settled | +| FR2 | Under `first-line`, the block-axis center of each rendered start-content and end-content slot MUST coincide with the block-axis center of the label's first line box, for every slot block size. | Owner direction | settled | +| FR3 | Under `first-line`, a slot taller than the label's first line MUST stay inside the row's content box: the label and description move down by the difference, and the row grows to fit. No slot is clipped or painted into the row's block padding. | Owner direction | settled | +| FR4 | A row whose label renders a single line and which has no description MUST render identically under `first-line` and `center`, for every slot block size. | Follows from FR2 and FR3 | settled | +| FR5 | The first line box is the label line as Item styles it, from the active theme's body text size and leading. A theme that changes those tokens moves the alignment with them. Caller content inside `label` that sets its own font size or line height is outside the FR2 guarantee. | Shared typography source | settled | +| FR6 | `first-line` MUST hold in every density, in `stacked` and `inline` layouts, with `labelLines` truncation, and in plain, button, link, link-root, delegated, and parent-role rows. In right-to-left text it MUST produce the same block-axis placement with the slots mirrored by logical order and no DOM reordering. | `architecture:internationalization` | settled | +| FR7 | The `item` theme target MUST reflect the resolved alignment as its existing `align` selector axis, including `first-line`, and Item's public theming metadata MUST list that value. The alignment axis adds no new target or theme-level default. | `architecture:component-theming-surface/INV6`; `component:Item/DEC-2` | settled | +| FR8 | ListItem, RadioListItem, and CheckboxListItem MUST expose `align` with Item's values and default and forward it unchanged to the Item row they render. A composing row MUST NOT drop, remap, or narrow the value. | Owner direction | settled | +| FR9 | An interactive row (an `onClick` row, an `href` row, or a delegated row with `interactiveRef`) shows its pressed paint only for a press that would activate it, from any pointer: a press on the row's surface or on its own action (its invisible button or link, or the control it delegates to) paints the row, and a press that starts on another interactive element inside the row paints none (`architecture:press-feedback` INV7). In a row with a parent-supplied `role`, or a row whose root is a link, a press on a nested control activates the row, so it paints. | Owner direction, 2026-11-03: no pressed state on a container for a press that does not activate it; owner decision, 2026-11-11: a mouse and a pen too, on a row that owns a control's box; owner decision, 2026-11-16: every pointer, every row | settled | +| FR10 | The `item` theme target MUST reflect a highlighted, selected, or disabled row as `data-highlighted`, `data-selected`, and `data-disabled`, each present only while its state holds, with the names CommandPaletteItem uses. A row that composes Item reflects the states it passes to Item. | `architecture:component-theming-surface/INV6`; shipped source and focused tests, not owner-reviewed | settled; not owner-reviewed | ### Allowed variation diff --git a/docs/specs/components/SelectableCard/SelectableCard.spec.md b/docs/specs/components/SelectableCard/SelectableCard.spec.md index 7ff6b56a046f0..0e57be3822ccd 100644 --- a/docs/specs/components/SelectableCard/SelectableCard.spec.md +++ b/docs/specs/components/SelectableCard/SelectableCard.spec.md @@ -39,15 +39,15 @@ system_specs: [spec:AST-009, spec:AST-020, spec:AST-085] ## Contract at a glance -| Area | Contract | -| ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Public contract | A Card that toggles a controlled `isSelected` through `onChange`, named by a required `label`, with `isDisabled` and Card's `variant`, `elevation`, `padding`, and sizing. | -| Behavior | A visually hidden native checkbox carries the role, name, and checked state; the whole surface toggles; selection draws an inset ring without moving layout. | -| End-user impact | Screen-reader users hear a named checkbox and its state; pointer users click anywhere on the card; disabled cards stay discoverable by keyboard. | -| Builder impact | At the next minor, a click inside an open layer inside the card (e.g. a Tooltip or HoverCard surface) no longer reaches the caller's `onClick`; a handler that needs those presses moves to the layer content. A theme's exit duration and easing set the touch press release (FR4). | -| Compatibility/readiness | No API changes. One `[breaking]` behavior change is staged for the next minor and not built: `onClick` stops receiving clicks inside an open layer. Three implementation gaps are listed under Current-state impact. The touch press release changes (FR4, `spec:AST-094` FR5). | -| Review checks | Reject a toggle that fires twice for one press, a disabled card that toggles or leaves the tab order, a ring that shifts layout, or a nested control that toggles the card. | -| Governing rules | `spec:AST-085/FR1,FR2,FR5,FR6`; `spec:AST-020/FR9`; `architecture:interaction-modality/INV3`; `architecture:component-theming-surface/INV6,INV14`; `architecture:public-component-api/INV5,INV6,INV7,INV8`; `component:SelectableCard/FR4` (the touch press release); `spec:AST-094/FR5` (the press release's exit tokens). | +| Area | Contract | +| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Public contract | A Card that toggles a controlled `isSelected` through `onChange`, named by a required `label`, with `isDisabled` and Card's `variant`, `elevation`, `padding`, and sizing. | +| Behavior | A visually hidden native checkbox carries the role, name, and checked state; the whole surface toggles; selection draws an inset ring without moving layout. | +| End-user impact | Screen-reader users hear a named checkbox and its state; pointer users click anywhere on the card; disabled cards stay discoverable by keyboard. | +| Builder impact | At the next minor, a click inside an open layer inside the card (e.g. a Tooltip or HoverCard surface) no longer reaches the caller's `onClick`; a handler that needs those presses moves to the layer content. A theme's exit duration and easing set the touch press release (FR4). | +| Compatibility/readiness | No API changes. One `[breaking]` behavior change is staged for the next minor and not built: `onClick` stops receiving clicks inside an open layer. Three implementation gaps are listed under Current-state impact. FR4 gap: a mouse press that starts on a nested control still paints the card's `:active`. The touch press release changes (FR4, `spec:AST-094` FR5). | +| Review checks | Reject a toggle that fires twice for one press, a disabled card that toggles or leaves the tab order, a ring that shifts layout, or a nested control that toggles the card. | +| Governing rules | `spec:AST-085/FR1,FR2,FR5,FR6`; `spec:AST-020/FR9`; `architecture:interaction-modality/INV3`; `architecture:component-theming-surface/INV6,INV14`; `architecture:public-component-api/INV5,INV6,INV7,INV8`; `component:SelectableCard/FR4` (the touch press release); `spec:AST-094/FR5` (the press release's exit tokens). | This table is a review projection; the body below is authoritative. diff --git a/docs/specs/components/Token/Token.spec.md b/docs/specs/components/Token/Token.spec.md index 0f750db12ce5c..b771d0bcdd967 100644 --- a/docs/specs/components/Token/Token.spec.md +++ b/docs/specs/components/Token/Token.spec.md @@ -36,15 +36,15 @@ system_specs: [spec:AST-005, spec:AST-009, spec:AST-085] ## Contract at a glance -| Area | Contract | -| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Public contract | An inline chip with a required string `label`, `size`, theme-extensible `color`, optional `icon` and `endContent`, and optional `onClick`, `href`, and `onRemove` interactions. | -| Behavior | `href` renders a link, `onClick` (or an enclosing trigger context) renders a container whose inner button wraps the label, and `onRemove` adds a separate remove button beside, never inside, them. | -| End-user impact | Pointer users can activate the whole chip; keyboard and screen-reader users reach the chip's action and its remove action as separate, named controls. | -| Builder impact | None; the record describes shipped behavior. | -| Compatibility/readiness | Released behavior recorded as current; no API, default, or output changes. Four implementation gaps are listed under Current-state impact. | -| Review checks | Reject a remove button nested in the link or the inner button, a remove target smaller than 24 by 24 CSS pixels, a native `disabled` attribute, or a token that navigates around the shared destination rule. | -| Governing rules | `family:navigation-destinations`; `spec:AST-005`; `spec:AST-085/FR1,FR2,FR5`; `architecture:public-component-api/INV5,INV6,INV8`; `architecture:component-theming-surface/INV6,INV14`. | +| Area | Contract | +| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Public contract | An inline chip with a required string `label`, `size`, theme-extensible `color`, optional `icon` and `endContent`, and optional `onClick`, `href`, and `onRemove` interactions. | +| Behavior | `href` renders a link, `onClick` (or an enclosing trigger context) renders a container whose inner button wraps the label, and `onRemove` adds a separate remove button beside, never inside, them. | +| End-user impact | Pointer users can activate the whole chip; keyboard and screen-reader users reach the chip's action and its remove action as separate, named controls. | +| Builder impact | None; the record describes shipped behavior. | +| Compatibility/readiness | Released behavior recorded as current; no API, default, or output changes. Four implementation gaps are listed under Current-state impact. FR6 gap: a mouse press that starts on a nested control still paints the token's `:active`. | +| Review checks | Reject a remove button nested in the link or the inner button, a remove target smaller than 24 by 24 CSS pixels, a native `disabled` attribute, or a token that navigates around the shared destination rule. | +| Governing rules | `family:navigation-destinations`; `spec:AST-005`; `spec:AST-085/FR1,FR2,FR5`; `architecture:public-component-api/INV5,INV6,INV8`; `architecture:component-theming-surface/INV6,INV14`. | This table is a review projection; the body below is authoritative. @@ -133,7 +133,7 @@ Consumer migration instructions belong in consumer docs and release notes. | FR3 | With an enabled `href` and no `onRemove`, the token root is the shared link component carrying the destination; it takes the root ref, passthrough props, and its own focus-visible outline. A supplied `onClick`, as an accepted event input, reaches the element that owns the contract (`architecture:public-component-api` INV5). Implementation gap: in both link structures `onClick` is not attached or called (Current-state impact). | Current source and tests | | FR4 | With `onClick`, or an enclosing trigger context that resolves the token to a button, the root is a `span` container holding an inner `button` that wraps only the Label and calls `onClick`; a click on the container outside any nested button or link also calls `onClick`, except a click inside an open Tooltip or HoverCard surface (`component:Tooltip` FR11). With an enabled `href` and `onRemove`, the container instead holds an inner link wrapping only the Label; a plain click on the surface outside the Remove button follows that link, and a Cmd/Ctrl-click or middle click on the surface opens it in a new tab. A caller `onMouseUp` on the link-and-remove container runs before its delegation. | Current source and tests | | FR5 | A disabled token renders at half opacity with pointer events off and fires neither `onClick` nor `onRemove` from pointer, Enter, or Space; inner and Remove buttons stay focusable with `aria-disabled="true"` and never receive native `disabled`. A disabled control keeps its tab stop and exposes its disabled state (`spec:AST-085` FR1, FR5), and the disabled state is reflected on the owning target (`architecture:component-theming-surface` INV6). A disabled token with `href` and no `onClick` or trigger context renders a focusable link with `aria-disabled="true"` and no `href`, and every structure reflects the disabled state on the `token` target. | Current source and tests | -| FR6 | `onRemove` renders a `type="button"` Remove button holding a close glyph; a click stops propagation before `onRemove` runs, so it never triggers the token's own action or link. The button is a sibling of the inner button or link, never nested in it. A finger press that starts on the Remove button, or on a control in end content, paints no press on the token, since it does not run the token's own action; a mouse press keeps the token's `:active` paint. | Current source and tests | +| FR6 | `onRemove` renders a `type="button"` Remove button holding a close glyph; a click stops propagation before `onRemove` runs, so it never triggers the token's own action or link. The button is a sibling of the inner button or link, never nested in it. A press from any pointer that starts on the Remove button, or on a control in end content, paints no press on the token, since it does not run the token's own action (`architecture:press-feedback` INV7). | Current source and tests | | FR7 | The label never wraps: the root is capped at its container's inline size and clips overflow. In the static and link structures the Label ends in an ellipsis; in the clickable and link-and-remove structures the inner control clips the Label without an ellipsis. `isLabelHidden` keeps the Label in the DOM with a visually hidden clip treatment. | Current source and tests | | FR8 | `color` defaults to `default`, painting `--color-neutral` with primary text; every other built-in tone paints its tinted background with its matching colored text. The `token` target reflects the resolved `color` and `size` for every value, including a theme-added color, which receives no component fill or text color until a theme paints it. | Current source and tests | | FR9 | Clickable and link structures paint the shared hover overlay under a hover-capable pointer and the shared pressed overlay for mouse and touch presses; the static structure paints neither. | Current source | diff --git a/docs/specs/components/TreeList/TreeList.spec.md b/docs/specs/components/TreeList/TreeList.spec.md index 64b5692e47b9d..1c84591520210 100644 --- a/docs/specs/components/TreeList/TreeList.spec.md +++ b/docs/specs/components/TreeList/TreeList.spec.md @@ -37,15 +37,15 @@ system_specs: ## Contract at a glance -| Area | Contract | -| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Public contract | Each `TreeListItemData` may carry the standard `className`, `style`, and `xstyle` styling inputs for its Item row. | -| Behavior | All supplied styling inputs compose on the same Item row box—the element that paints the row, owns its hover state, and contains its visible content. They do not target the outer semantic `
  • `. | -| End-user impact | A builder can reveal or style content for one row without causing every row in the tree to react. | -| Builder impact | The three standard styling mechanisms remain interchangeable parts of one row-styling seam. A builder may use one or combine them; no existing callsite must opt in. | -| Compatibility/readiness | The contract is additive and keeps default output, except FR8's coarse-pointer glide and DD5's Guides. Its authority is current; implementation support may arrive separately, but the durable API is incomplete until all three mechanisms are supported on the same row. | -| Review checks | Reject an implementation that omits one mechanism from the durable API, sends the mechanisms to different elements, drops a supplied value, targets the semantic `
  • `, or moves the promised row target without an explicit compatibility decision. | -| Governing rules | [Public component API INV5–INV6](../../../architecture/public-component-api.md) and [AST-002 FR1, FR4, FR7–FR10, FR12, and DEC-1](../../AST-002/spec.md) govern admission, predictability, and composition of the component-local styling seam. | +| Area | Contract | +| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Public contract | Each `TreeListItemData` may carry the standard `className`, `style`, and `xstyle` styling inputs for its Item row. | +| Behavior | All supplied styling inputs compose on the same Item row box—the element that paints the row, owns its hover state, and contains its visible content. They do not target the outer semantic `
  • `. | +| End-user impact | A builder can reveal or style content for one row without causing every row in the tree to react. | +| Builder impact | The three standard styling mechanisms remain interchangeable parts of one row-styling seam. A builder may use one or combine them; no existing callsite must opt in. | +| Compatibility/readiness | The contract is additive and keeps default output, except FR8's coarse-pointer glide and DD5's Guides. Its authority is current; implementation support may arrive separately, but the durable API is incomplete until all three mechanisms are supported on the same row. FR7 gap: a mouse press that starts on a nested control still paints the row's `:active`. | +| Review checks | Reject an implementation that omits one mechanism from the durable API, sends the mechanisms to different elements, drops a supplied value, targets the semantic `
  • `, or moves the promised row target without an explicit compatibility decision. | +| Governing rules | [Public component API INV5–INV6](../../../architecture/public-component-api.md) and [AST-002 FR1, FR4, FR7–FR10, FR12, and DEC-1](../../AST-002/spec.md) govern admission, predictability, and composition of the component-local styling seam. | This table is a review projection; the body below is authoritative. @@ -107,17 +107,17 @@ Supporting one does not justify omitting another from the durable contract. ## Behavioral and layout contract -| ID | Invariant | Basis | Contract state | -| --- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- | --------------------------------------------------- | -| FR1 | The current render contains one Tree list, one Item and Item label per rendered node, optional Header, Chevron, Item description, Start content, End content, and Guide parts, and delegated Chevron glyphs. | Current source, docs, and tests | Current behavior | -| FR2 | Tree list, Item, Chevron, Item label, and Guide carry the five current `tree-list*` targets documented below. | Current source and target docs | Current behavior | -| FR3 | Chevron glyph delegates to Icon's `icon` target. Header, Start content, and End content are consumer-owned and have no TreeList target. | Current source and component docs | Current ownership | -| FR4 | Item description is a stable library-rendered part below Item label and currently has no public target. It does not inherit through `tree-list-item-label`; both spans are siblings inside the row content. | Current source and target docs | Current reachability gap; no new target is accepted | -| FR5 | `TreeListItemData` MUST admit `className`, `style`, and `xstyle` as one per-item styling seam. Every supplied value MUST compose on the same Item row box; an implementation MUST NOT treat current support for only one mechanism as authority to exclude the other two. | Owner decision; `architecture:public-component-api` INV5–INV6; `spec:AST-002/DEC-1` | Settled intent; implementation may be staged | -| FR6 | The Item row box is the logical element that paints the row, owns its hover state, and contains Start content, Item label and description, and End content. The styling seam MUST NOT move to the semantic `
  • ` or another element without a compatibility decision. | Owner decision and the caller-owned per-row interaction boundary | Settled intent | -| FR7 | A click on an Item row outside its Item label performs the row's action: an Item with `onClick` runs it; otherwise an Item with children toggles; otherwise an Item whose only action is its link follows that link as Enter does, with modified and middle clicks following the shared enlarged-surface rule in `family:navigation-destinations`. The Chevron and controls in Start content and End content keep their own activation, and on any row a touch press that starts on one of them, or on the Chevron of a row whose surface runs a different action, shows no pressed paint on the row (a mouse press keeps the `:active` paint, as `component:Item` FR9 states); a disabled Item does nothing. A press inside an open Tooltip or HoverCard surface performs no row action (`component:Tooltip` FR11). | Owner decision; `family:navigation-destinations` | Settled intent; implementation may be staged | -| FR8 | Expanding or collapsing an Item with children under a coarse primary pointer MUST play its motion. When a branch expands or collapses, the rows below glide on the shared layout glide (`spec:AST-105` FR4, `--duration-medium`) and the entering or leaving children fade on the same timing, so the tree moves as one; the children take the glide's timing, not `--duration-fast`. The Chevron turns on that timing, and a collapsing group's rows leave the accessibility tree at the tap. Without an `animatedLayout` handle the motion stays inside the tree, so content after the tree takes its place at once (`spec:AST-105` DEC-1), and under a fine pointer the group appears and leaves at once. With a handle, the group and the content after it follow its shared motion under every pointer (FR9). | `spec:AST-105` FR4; Owner feedback, Nov 6 2026 (Cindy): the expand felt too jumpy. | Current behavior | -| FR9 | `TreeList` MUST accept `animatedLayout?: AnimatedLayout`. With a handle, expanding and collapsing a row report the row's size change through it, so the content after the row glides inside the handle's container, and the shown rows and the row's Chevron move on the same motion (`spec:AST-105` FR1–FR4; `spec:AST-108` FR4a). Without one, expanding and collapsing follow FR8. The prop MUST NOT change tree semantics or keyboard behavior. | `spec:AST-105` FR1, FR2; `spec:AST-108` FR4a | Current behavior | +| ID | Invariant | Basis | Contract state | +| --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------- | --------------------------------------------------- | +| FR1 | The current render contains one Tree list, one Item and Item label per rendered node, optional Header, Chevron, Item description, Start content, End content, and Guide parts, and delegated Chevron glyphs. | Current source, docs, and tests | Current behavior | +| FR2 | Tree list, Item, Chevron, Item label, and Guide carry the five current `tree-list*` targets documented below. | Current source and target docs | Current behavior | +| FR3 | Chevron glyph delegates to Icon's `icon` target. Header, Start content, and End content are consumer-owned and have no TreeList target. | Current source and component docs | Current ownership | +| FR4 | Item description is a stable library-rendered part below Item label and currently has no public target. It does not inherit through `tree-list-item-label`; both spans are siblings inside the row content. | Current source and target docs | Current reachability gap; no new target is accepted | +| FR5 | `TreeListItemData` MUST admit `className`, `style`, and `xstyle` as one per-item styling seam. Every supplied value MUST compose on the same Item row box; an implementation MUST NOT treat current support for only one mechanism as authority to exclude the other two. | Owner decision; `architecture:public-component-api` INV5–INV6; `spec:AST-002/DEC-1` | Settled intent; implementation may be staged | +| FR6 | The Item row box is the logical element that paints the row, owns its hover state, and contains Start content, Item label and description, and End content. The styling seam MUST NOT move to the semantic `
  • ` or another element without a compatibility decision. | Owner decision and the caller-owned per-row interaction boundary | Settled intent | +| FR7 | A click on an Item row outside its Item label performs the row's action: an Item with `onClick` runs it; otherwise an Item with children toggles; otherwise an Item whose only action is its link follows that link as Enter does, with modified and middle clicks following the shared enlarged-surface rule in `family:navigation-destinations`. The Chevron and controls in Start content and End content keep their own activation, and on any row a press from any pointer that starts on one of them, or on the Chevron of a row whose surface runs a different action, shows no pressed paint on the row (`component:Item` FR9); a disabled Item does nothing. A press inside an open Tooltip or HoverCard surface performs no row action (`component:Tooltip` FR11). | Owner decision; `family:navigation-destinations` | Settled intent; implementation may be staged | +| FR8 | Expanding or collapsing an Item with children under a coarse primary pointer MUST play its motion. When a branch expands or collapses, the rows below glide on the shared layout glide (`spec:AST-105` FR4, `--duration-medium`) and the entering or leaving children fade on the same timing, so the tree moves as one; the children take the glide's timing, not `--duration-fast`. The Chevron turns on that timing, and a collapsing group's rows leave the accessibility tree at the tap. Without an `animatedLayout` handle the motion stays inside the tree, so content after the tree takes its place at once (`spec:AST-105` DEC-1), and under a fine pointer the group appears and leaves at once. With a handle, the group and the content after it follow its shared motion under every pointer (FR9). | `spec:AST-105` FR4; Owner feedback, Nov 6 2026 (Cindy): the expand felt too jumpy. | Current behavior | +| FR9 | `TreeList` MUST accept `animatedLayout?: AnimatedLayout`. With a handle, expanding and collapsing a row report the row's size change through it, so the content after the row glides inside the handle's container, and the shown rows and the row's Chevron move on the same motion (`spec:AST-105` FR1–FR4; `spec:AST-108` FR4a). Without one, expanding and collapsing follow FR8. The prop MUST NOT change tree semantics or keyboard behavior. | `spec:AST-105` FR1, FR2; `spec:AST-108` FR4a | Current behavior | ### Allowed variation From 57d537b46189474ee74da6b08ae986d6846fe7cc Mon Sep 17 00:00:00 2001 From: Cindy Zhang Date: Mon, 16 Nov 2026 12:41:43 -0800 Subject: [PATCH 12/24] docs: verification rows cover every pointer for nested presses in Item, TreeList and Token --- docs/specs/components/Item/Item.spec.md | 18 +++++------ docs/specs/components/Token/Token.spec.md | 26 +++++++-------- .../components/TreeList/TreeList.spec.md | 32 +++++++++---------- 3 files changed, 38 insertions(+), 38 deletions(-) diff --git a/docs/specs/components/Item/Item.spec.md b/docs/specs/components/Item/Item.spec.md index 77e8ef16c3f33..f92e9d22edf22 100644 --- a/docs/specs/components/Item/Item.spec.md +++ b/docs/specs/components/Item/Item.spec.md @@ -184,15 +184,15 @@ Consumer migration instructions belong in consumer docs and release notes. ## Verification map -| Contract | Verification | Representative states | Mutation or failure expectation | Audit section | -| -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- | --------------------- | -| FR1, FR7 | `Item.test.tsx` alignment and theme-reflection suites; public type test | Omitted, `center`, `start`, `first-line` | A changed default, a missing `data-align="first-line"`, or a widened type fails. | `audit:Item/api` | -| FR2–FR6 | Real-Chromium geometry assertions over the Item alignment stories | Wrapped label with dot and age; avatar; densities; RTL; theme | A slot center off the first line center by more than 0.5px, or a clipped slot, fails. | `audit:Item/layout` | -| FR8 | `List.test.tsx`, `RadioList.test.tsx`, `CheckboxList.test.tsx` forwarding cases | Each composing row with `align="first-line"` | A row whose Item root lacks `data-align="first-line"` fails. | `audit:Item/api` | -| FR9 | `nestedTouchPress.adopters.test.tsx`; `Item.nestedPress.test.tsx`; the nested-control cases in `CheckboxList.test.tsx`, `RadioList.test.tsx` and `useClickableContainer.test.tsx` | A finger on the delegated control; a finger on another control in the row; a mouse and a pen on another control in a CheckboxList or RadioList row | A row painted for a press on another control, or not painted for a press on its delegated control, fails. | `audit:Item/behavior` | -| FR10 | `Item.test.tsx` "reflects highlighted, selected, and disabled on the item theme target" | Plain, highlighted only, selected only, disabled only, and all three together | A missing attribute, or an attribute left on a row whose state does not hold, fails. | `audit:Item/theming` | -| AR1, AR2 | Accessibility-tree snapshot of a `first-line` row against a `center` row | Plain and option rows | Any difference in name, role, description, or order fails. | `audit:Item/a11y` | -| PR1 | Source review of Item's alignment styles | All values | A ref, observer, or Effect added for alignment fails review. | `audit:Item/layout` | +| Contract | Verification | Representative states | Mutation or failure expectation | Audit section | +| -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- | --------------------- | +| FR1, FR7 | `Item.test.tsx` alignment and theme-reflection suites; public type test | Omitted, `center`, `start`, `first-line` | A changed default, a missing `data-align="first-line"`, or a widened type fails. | `audit:Item/api` | +| FR2–FR6 | Real-Chromium geometry assertions over the Item alignment stories | Wrapped label with dot and age; avatar; densities; RTL; theme | A slot center off the first line center by more than 0.5px, or a clipped slot, fails. | `audit:Item/layout` | +| FR8 | `List.test.tsx`, `RadioList.test.tsx`, `CheckboxList.test.tsx` forwarding cases | Each composing row with `align="first-line"` | A row whose Item root lacks `data-align="first-line"` fails. | `audit:Item/api` | +| FR9 | `nestedTouchPress.adopters.test.tsx`; `Item.nestedPress.test.tsx`; the nested-control cases in `CheckboxList.test.tsx`, `RadioList.test.tsx` and `useClickableContainer.test.tsx` | A finger on the delegated control; a finger on another control in the row; a mouse and a pen on another control in any interactive row (`onClick`, `href`, delegated), and on a nested control in a link-root or role row | A row painted for a press on another control, or not painted for a press on its delegated control, fails. | `audit:Item/behavior` | +| FR10 | `Item.test.tsx` "reflects highlighted, selected, and disabled on the item theme target" | Plain, highlighted only, selected only, disabled only, and all three together | A missing attribute, or an attribute left on a row whose state does not hold, fails. | `audit:Item/theming` | +| AR1, AR2 | Accessibility-tree snapshot of a `first-line` row against a `center` row | Plain and option rows | Any difference in name, role, description, or order fails. | `audit:Item/a11y` | +| PR1 | Source review of Item's alignment styles | All values | A ref, observer, or Effect added for alignment fails review. | `audit:Item/layout` | ## Decision log diff --git a/docs/specs/components/Token/Token.spec.md b/docs/specs/components/Token/Token.spec.md index b771d0bcdd967..a86f6996f2e1e 100644 --- a/docs/specs/components/Token/Token.spec.md +++ b/docs/specs/components/Token/Token.spec.md @@ -245,19 +245,19 @@ token's text color. ## Verification map -| Contract | Verification | Representative states | Mutation or failure expectation | Audit section | -| ----------------------------- | -------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------- | -| FR2, FR10 | `Token.test.tsx` render, ref, and pass-through suites | Static, clickable, and link roots; caller props; caller naming on a clickable and a disabled link token | A wrong root element, a detached ref, a dropped caller prop, or a clickable token's `aria-labelledby` left on its root fails DOM assertions. Gap: no test covers the ref on the link-and-remove container. | `audit:Token/behavior` | -| FR1, FR7 | `Token.stories.tsx` size, icon, and end-content fixtures in a browser | Sizes, icon and end content | Gap: the size and overflow unit tests assert presence only, and no story renders a long label; slot order and block size are visible only in the rendered fixtures, and the ellipsis has no check. | `audit:Token/layout` | -| FR3, FR4, FR6, AR1 | `Token.test.tsx` link, clickable, and link-with-remove suites | Link, clickable, link and remove, modified and middle clicks | Nesting the Remove button, firing the token action from Remove, or losing delegation fails. Gap: no test asserts that `onClick` is dropped with `href`. | `audit:Token/behavior` | -| FR5, AR5 | `Token.test.tsx` disabled tests | Disabled clickable with remove; disabled static; disabled link with and without remove | A native `disabled`, a lost tab stop, a disabled link with a destination, an unreflected disabled state, or a fired callback fails. | `audit:Token/a11y` | -| AR2, AR3, AR7 | `Token.test.tsx` accessibility suite | Remove name, hidden label, description | A missing remove name, lost hidden label, or missing description fails. Gap: no test asserts the link structure's content-derived name. | `audit:Token/a11y` | -| AR6 | `TokenRemoveTarget.a11y.chromium.spec.ts` | Pre-set filter tokens (default size), LTR and RTL | A remove target that misses its X edge or swallows a label press fails in real Chromium. Gap: the `sm` clipping is not covered. | `audit:Token/a11y` | -| FR8 | `Token.test.tsx` custom-color test; `extensibleAxes.test.ts`; `themingTargets.test.ts` | Theme-added color; map wiring | Dropping the `color` reflection fails. Gap: no test asserts `data-size` or any tone's paint; those are visible only in `Token.stories.tsx`. | `audit:Token/theming` | -| FR9, AR4 | `Token.stories.tsx` clickable and link fixtures in a browser | Hover, press, keyboard focus on the token | Gap: no automated check covers overlays or indicators, and no story renders a clickable or link token with Remove, so the double indicator on Remove has no fixture. | `audit:Token/design` | -| PR1 | Source review | Every structure | Gap: no automated check fails if Token adds a per-token listener, observer, or timer. | `audit:Token/behavior` | -| AR2, AR3, AR5, AR7 | Accessibility-tree evidence (`spec:AST-009` FR3) | Every structure; hidden label; description; disabled | Gap: no accessibility-tree check proves the computed names, the hidden-label name, the description, or the disabled state; the unit tests assert DOM attributes only. | `audit:Token/a11y` | -| `design:bidirectionality` DR2 | `MixedDirectionText.a11y.chromium.spec.ts` | `https://`, `.com`, `+3`, `@alice`, `iPhone جديد` and `example.com موقع` under RTL and LTR (Mixed Direction story) | A label whose weak or neutral characters reorder under RTL (`//:https`, `com.`, `3+`, `alice@`), or right-to-left text with a leading Latin word that lays out left to right, fails on each character's rendered position. | `audit:Token/layout` | +| Contract | Verification | Representative states | Mutation or failure expectation | Audit section | +| ----------------------------- | -------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------- | +| FR2, FR10 | `Token.test.tsx` render, ref, and pass-through suites | Static, clickable, and link roots; caller props; caller naming on a clickable and a disabled link token | A wrong root element, a detached ref, a dropped caller prop, or a clickable token's `aria-labelledby` left on its root fails DOM assertions. Gap: no test covers the ref on the link-and-remove container. | `audit:Token/behavior` | +| FR1, FR7 | `Token.stories.tsx` size, icon, and end-content fixtures in a browser | Sizes, icon and end content | Gap: the size and overflow unit tests assert presence only, and no story renders a long label; slot order and block size are visible only in the rendered fixtures, and the ellipsis has no check. | `audit:Token/layout` | +| FR3, FR4, FR6, AR1 | `Token.test.tsx` link, clickable, and link-with-remove suites | Link, clickable, link and remove, modified and middle clicks; a finger, a pen and a mouse press on the Remove button (no token press paint) | Nesting the Remove button, firing the token action from Remove, or losing delegation fails. Gap: no test asserts that `onClick` is dropped with `href`. | `audit:Token/behavior` | +| FR5, AR5 | `Token.test.tsx` disabled tests | Disabled clickable with remove; disabled static; disabled link with and without remove | A native `disabled`, a lost tab stop, a disabled link with a destination, an unreflected disabled state, or a fired callback fails. | `audit:Token/a11y` | +| AR2, AR3, AR7 | `Token.test.tsx` accessibility suite | Remove name, hidden label, description | A missing remove name, lost hidden label, or missing description fails. Gap: no test asserts the link structure's content-derived name. | `audit:Token/a11y` | +| AR6 | `TokenRemoveTarget.a11y.chromium.spec.ts` | Pre-set filter tokens (default size), LTR and RTL | A remove target that misses its X edge or swallows a label press fails in real Chromium. Gap: the `sm` clipping is not covered. | `audit:Token/a11y` | +| FR8 | `Token.test.tsx` custom-color test; `extensibleAxes.test.ts`; `themingTargets.test.ts` | Theme-added color; map wiring | Dropping the `color` reflection fails. Gap: no test asserts `data-size` or any tone's paint; those are visible only in `Token.stories.tsx`. | `audit:Token/theming` | +| FR9, AR4 | `Token.stories.tsx` clickable and link fixtures in a browser | Hover, press, keyboard focus on the token | Gap: no automated check covers overlays or indicators, and no story renders a clickable or link token with Remove, so the double indicator on Remove has no fixture. | `audit:Token/design` | +| PR1 | Source review | Every structure | Gap: no automated check fails if Token adds a per-token listener, observer, or timer. | `audit:Token/behavior` | +| AR2, AR3, AR5, AR7 | Accessibility-tree evidence (`spec:AST-009` FR3) | Every structure; hidden label; description; disabled | Gap: no accessibility-tree check proves the computed names, the hidden-label name, the description, or the disabled state; the unit tests assert DOM attributes only. | `audit:Token/a11y` | +| `design:bidirectionality` DR2 | `MixedDirectionText.a11y.chromium.spec.ts` | `https://`, `.com`, `+3`, `@alice`, `iPhone جديد` and `example.com موقع` under RTL and LTR (Mixed Direction story) | A label whose weak or neutral characters reorder under RTL (`//:https`, `com.`, `3+`, `alice@`), or right-to-left text with a leading Latin word that lays out left to right, fails on each character's rendered position. | `audit:Token/layout` | ## Decision log diff --git a/docs/specs/components/TreeList/TreeList.spec.md b/docs/specs/components/TreeList/TreeList.spec.md index 1c84591520210..fd276a3593aa1 100644 --- a/docs/specs/components/TreeList/TreeList.spec.md +++ b/docs/specs/components/TreeList/TreeList.spec.md @@ -285,22 +285,22 @@ authorize or prohibit a future target. ## Verification map -| Contract | Verification | Representative states | Mutation or failure expectation | Audit section | -| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------ | -| FR1 | `TreeList.test.tsx` rendering, hierarchy, slot, and accessibility suites plus source inspection | Flat, nested, described, headed, and slotted items | Removing asserted Tree list, Header, Item, Chevron, Item label, Item description, Start content, End content, or Guide behavior fails existing role, content, hierarchy, or state assertions; Chevron glyph presence remains source-inspected only. | `audit:TreeList/anatomy` | -| FR2 | `TreeList.test.tsx` and `themingTargets.test.ts` | Five local targets and their documented states | Removing or moving any current local target fails focused class assertions or the global inventory. | `audit:TreeList/theming` | -| FR3 | Source inspection plus Icon public target metadata | Expandable rows and caller-provided slots | Existing focused tests do not assert the composed Icon instance; changing glyph or slot ownership requires this map and the relevant owner metadata to change. | `audit:TreeList/theming` | -| FR4 | `TreeList.test.tsx` description rendering test and source inspection | Item with description | Removing description fails content coverage; adding a target requires an explicit map update. | `audit:TreeList/anatomy` | -| AR1 | Tree View accessibility contract (`internal/a11y-spec`, pending) bound to TreeList, in jsdom and Chromium; `TreeList.test.tsx` row-naming cases ("names a parent row by its label alone, not the chevron toggle", "names a plain row by its label and describes it with its description", "names and describes link and action rows themselves, not only their inner control", "keeps start and end content, including controls, out of the row name", "typeahead matches the label, not the description or start content") and `TreeListRowNames.a11y.chromium.spec.ts` for the browser-computed names; `TreeList.test.tsx` structural ARIA cases ("sets aria-level, aria-posinset, and aria-setsize at the top level", "sets aria-level/posinset/setsize correctly at deeper levels", "sets aria-level across three depths"); `TreeList.test.tsx` and `useTreeFocus.test.tsx` keyboard suites | Flat and nested trees; expanded/collapsed; selected/unselected; LTR and RTL; typeahead | A row loses its role, label name, state or position, two rows hold a Tab stop, an arrow key stops moving or stops mirroring under RTL, Home/End or typeahead stop working, or the tree claims multi-select | `audit:TreeList/accessibility` | -| AR1 (empty header) | `TreeList.test.tsx` "TreeList empty slots" suite: "a header of %s names nothing; the tree keeps its own label" for `''`, `false`, `true`, and `null`, and `0` as a rendered Header | Empty, boolean, and null header with `aria-label`; `0` header | A tree named by an empty Header, or carrying `aria-labelledby` without a rendered Header, fails. | `audit:TreeList/accessibility` | -| FR5, FR6, ORD1 | Focused `TreeList.test.tsx` row-identity and styling-composition coverage, required with implementation | One input at a time; all three together; sibling rows | Dropping any mechanism, applying mechanisms to different elements, targeting the `
  • `, changing the merge order, or styling a sibling row fails. | `audit:TreeList/api` | -| FR7 | Focused `TreeList.test.tsx` row-click coverage, required with implementation | Action, parent, link, and disabled rows; clicks in the indent and padding, on the Chevron, and on Start and End content controls; plain, modified, and middle clicks | A click outside the label does nothing or runs the wrong action, a link-row click reaches ancestors twice, the Chevron or a Start or End content control activates the row, or a disabled row acts. | `audit:TreeList/behavior` | -| FR8 | `TreeListExpand.interaction.browser.spec.ts`: per-frame evidence under a finger and a mouse | expand and collapse; reduced motion; the theme's glide token; the rows below and content after the tree, with and without an `animatedLayout` handle | A blank band above the rows below, on any frame, a group that shows at rest before it fades in, rows below that jump, timing other than the theme's glide, motion under a fine pointer without a handle, travel under reduced motion, a collapsed group's rows in the accessibility tree after the tap, or content after the tree moving without a handle fails | `audit:TreeList/behavior` | -| FR9 | `animatedLayoutAdopters.test.tsx` (with and without a handle; `isExpanded` changed in `items` glides; the collapsing group kept inert and out of the keyboard order until its exit ends) and `animatedLayoutAdopters.interaction.browser.spec.ts` (the `Core/Animated layout` story through a ScrollableArea ref, expanding and collapsing) | No handle; a handle; click, keyboard, and `items`-driven changes; expanding and collapsing | The rows after a row jump with a handle, an `items` change lands at once, a collapsing group vanishes before its exit or its rows stay focusable during it, or anything changes without a handle | `audit:TreeList/behavior` | -| AR2 | `TreeList.test.tsx` collapse-focus suite; `animatedLayoutAdopters.test.tsx` collapse with focus inside during the exit; `TreeListCollapseFocus.a11y.chromium.spec.ts` | Focus on a child row, `items`-driven collapse, with and without a handle; nested outer and inner collapse; a disabled collapsing row; focus on another row or outside | Focus left in the removed or inert group, on the page body, or moved when it was not inside the group fails. | `audit:TreeList/accessibility` | -| DD4 | `TreeListGuideAlignment.interaction.browser.spec.ts` measures Chevron logical-start placement and Guide/Chevron center alignment in the built Fully Expanded story. | `lineGuides` and `noGuides`; LTR and RTL | Reintroducing Chevron edge margins, moving a Chevron when guides are hidden, or placing a Guide off the Chevron center fails the browser geometry assertions. | `audit:TreeList/anatomy` | -| DD5 | `TreeListExpand.interaction.browser.spec.ts` guide case: the Guide column measured on every frame | expand and collapse under a finger | A Guide line running past the last row it joins on any frame fails | `audit:TreeList/anatomy` | -| Theming anatomy map | `scripts/check-knowledge.mjs` | Canonical anatomy and five current local targets | Missing, extra, duplicated, prefixed, or stale mappings fail repository validation. | `audit:TreeList/theming` | +| Contract | Verification | Representative states | Mutation or failure expectation | Audit section | +| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------ | +| FR1 | `TreeList.test.tsx` rendering, hierarchy, slot, and accessibility suites plus source inspection | Flat, nested, described, headed, and slotted items | Removing asserted Tree list, Header, Item, Chevron, Item label, Item description, Start content, End content, or Guide behavior fails existing role, content, hierarchy, or state assertions; Chevron glyph presence remains source-inspected only. | `audit:TreeList/anatomy` | +| FR2 | `TreeList.test.tsx` and `themingTargets.test.ts` | Five local targets and their documented states | Removing or moving any current local target fails focused class assertions or the global inventory. | `audit:TreeList/theming` | +| FR3 | Source inspection plus Icon public target metadata | Expandable rows and caller-provided slots | Existing focused tests do not assert the composed Icon instance; changing glyph or slot ownership requires this map and the relevant owner metadata to change. | `audit:TreeList/theming` | +| FR4 | `TreeList.test.tsx` description rendering test and source inspection | Item with description | Removing description fails content coverage; adding a target requires an explicit map update. | `audit:TreeList/anatomy` | +| AR1 | Tree View accessibility contract (`internal/a11y-spec`, pending) bound to TreeList, in jsdom and Chromium; `TreeList.test.tsx` row-naming cases ("names a parent row by its label alone, not the chevron toggle", "names a plain row by its label and describes it with its description", "names and describes link and action rows themselves, not only their inner control", "keeps start and end content, including controls, out of the row name", "typeahead matches the label, not the description or start content") and `TreeListRowNames.a11y.chromium.spec.ts` for the browser-computed names; `TreeList.test.tsx` structural ARIA cases ("sets aria-level, aria-posinset, and aria-setsize at the top level", "sets aria-level/posinset/setsize correctly at deeper levels", "sets aria-level across three depths"); `TreeList.test.tsx` and `useTreeFocus.test.tsx` keyboard suites | Flat and nested trees; expanded/collapsed; selected/unselected; LTR and RTL; typeahead | A row loses its role, label name, state or position, two rows hold a Tab stop, an arrow key stops moving or stops mirroring under RTL, Home/End or typeahead stop working, or the tree claims multi-select | `audit:TreeList/accessibility` | +| AR1 (empty header) | `TreeList.test.tsx` "TreeList empty slots" suite: "a header of %s names nothing; the tree keeps its own label" for `''`, `false`, `true`, and `null`, and `0` as a rendered Header | Empty, boolean, and null header with `aria-label`; `0` header | A tree named by an empty Header, or carrying `aria-labelledby` without a rendered Header, fails. | `audit:TreeList/accessibility` | +| FR5, FR6, ORD1 | Focused `TreeList.test.tsx` row-identity and styling-composition coverage, required with implementation | One input at a time; all three together; sibling rows | Dropping any mechanism, applying mechanisms to different elements, targeting the `
  • `, changing the merge order, or styling a sibling row fails. | `audit:TreeList/api` | +| FR7 | Focused `TreeList.test.tsx` row-click coverage, required with implementation | Action, parent, link, and disabled rows; clicks in the indent and padding, on the Chevron, and on Start and End content controls; plain, modified, and middle clicks; a finger, a pen and a mouse press on a Start or End content control (no row press paint) | A click outside the label does nothing or runs the wrong action, a link-row click reaches ancestors twice, the Chevron or a Start or End content control activates the row, or a disabled row acts. | `audit:TreeList/behavior` | +| FR8 | `TreeListExpand.interaction.browser.spec.ts`: per-frame evidence under a finger and a mouse | expand and collapse; reduced motion; the theme's glide token; the rows below and content after the tree, with and without an `animatedLayout` handle | A blank band above the rows below, on any frame, a group that shows at rest before it fades in, rows below that jump, timing other than the theme's glide, motion under a fine pointer without a handle, travel under reduced motion, a collapsed group's rows in the accessibility tree after the tap, or content after the tree moving without a handle fails | `audit:TreeList/behavior` | +| FR9 | `animatedLayoutAdopters.test.tsx` (with and without a handle; `isExpanded` changed in `items` glides; the collapsing group kept inert and out of the keyboard order until its exit ends) and `animatedLayoutAdopters.interaction.browser.spec.ts` (the `Core/Animated layout` story through a ScrollableArea ref, expanding and collapsing) | No handle; a handle; click, keyboard, and `items`-driven changes; expanding and collapsing | The rows after a row jump with a handle, an `items` change lands at once, a collapsing group vanishes before its exit or its rows stay focusable during it, or anything changes without a handle | `audit:TreeList/behavior` | +| AR2 | `TreeList.test.tsx` collapse-focus suite; `animatedLayoutAdopters.test.tsx` collapse with focus inside during the exit; `TreeListCollapseFocus.a11y.chromium.spec.ts` | Focus on a child row, `items`-driven collapse, with and without a handle; nested outer and inner collapse; a disabled collapsing row; focus on another row or outside | Focus left in the removed or inert group, on the page body, or moved when it was not inside the group fails. | `audit:TreeList/accessibility` | +| DD4 | `TreeListGuideAlignment.interaction.browser.spec.ts` measures Chevron logical-start placement and Guide/Chevron center alignment in the built Fully Expanded story. | `lineGuides` and `noGuides`; LTR and RTL | Reintroducing Chevron edge margins, moving a Chevron when guides are hidden, or placing a Guide off the Chevron center fails the browser geometry assertions. | `audit:TreeList/anatomy` | +| DD5 | `TreeListExpand.interaction.browser.spec.ts` guide case: the Guide column measured on every frame | expand and collapse under a finger | A Guide line running past the last row it joins on any frame fails | `audit:TreeList/anatomy` | +| Theming anatomy map | `scripts/check-knowledge.mjs` | Canonical anatomy and five current local targets | Missing, extra, duplicated, prefixed, or stale mappings fail repository validation. | `audit:TreeList/theming` | Focused target-placement assertions cover all five local targets. Runtime support and mutation-sensitive coverage for the item styling seam may land separately, From 3273e63b63642891204e419cc20600c9d4383411 Mon Sep 17 00:00:00 2001 From: Cindy Zhang Date: Mon, 16 Nov 2026 13:10:25 -0800 Subject: [PATCH 13/24] docs: press feedback timing goes through the press-feedback engine (react-component-runtime INV13 reconciled) --- docs/architecture/press-feedback.md | 18 +++++++++--------- docs/architecture/react-component-runtime.md | 2 +- 2 files changed, 10 insertions(+), 10 deletions(-) diff --git a/docs/architecture/press-feedback.md b/docs/architecture/press-feedback.md index 0d0818eb01259..924864bd0c372 100644 --- a/docs/architecture/press-feedback.md +++ b/docs/architecture/press-feedback.md @@ -36,15 +36,15 @@ deciding_specs: [spec:AST-094/FR5, spec:AST-094/FR11, spec:AST-094/DEC-21] ## Contract at a glance -| Area | Contract | -| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Governing contract | How a press looks and when it shows: `spec:AST-094` FR5, FR8, FR11, FR20 and DEC-21; `design:user-states` DR1–DR5; `design:reduced-motion` DR1–DR2; `architecture:layer-runtime` INV22; `component:Item` FR9. | -| System behavior | One press engine, the page press controller, writes the pressed state of a single press; across a group, the group and menu owners of `architecture:interaction-modality` INV13 write it. Each pressable surface uses one of three recipes: a momentary control, a row-wide target, or a cell or menu row. A press paints and does nothing else: it never changes layout, the hit area, or hit-testing. Every release fades on the theme's exit motion tokens. | -| End-user impact | A person sees the same press on every Astryx surface: the same tint, the same start delay inside scrolling content, the same release fade, and the same cancel when a scroll takes the touch. A press never moves a tap target, so a tap lands where the person aims it. | -| Builder impact | A component picks a recipe and states it in its own record. It adds no press attribute, tracker, timer, or tint variable of its own. A press fix lands once, in the engine or the recipe, and reaches every component that uses it. No public API changes; the recipes are exports of the private press modules. | -| Compatibility/readiness | No public API change. INV1 gap: the touch-runtime press tracker, and ClickableCard, SelectableCard, Thumbnail, Tab, Switch, Slider and the Selector-family triggers re-declare press styles (their own press variable, scale, or state) instead of using a recipe's. INV4 gap: Switch, Slider and the SegmentedControl lens release in a fixed 200 ms, and controller controls end a press after 10 px of drift outside scrolling content. INV2 gap: no component record names its recipe, and Table cells paint no press. INV3 and INV9 gap: under a finger, a press makes a control's root the containing block, so a stretched control's tap target shrinks to the control mid-press. INV5 gap: under a mouse or a pen, most surfaces paint CSS `:active`. INV7 gap: a mouse press on a nested control still paints the container's `:active` in Item rows (outside CheckboxList and RadioList), TreeList rows, Token, ClickableCard and SelectableCard. INV9 gap: a press beside a stretched control paints the control instead of the row. INV8 gap: Selector-family triggers scale under reduced motion. | -| Review checks | Reject a new press attribute, tracker, timer, or tint variable outside the recipes; a press style that changes layout, the containing block, or the hit area; a fixed release duration; a container that paints for a press on a nested control that does not activate it, or a control that paints for a press on its container's own surface; and press engine code moved off first load. | -| Governing rules | `spec:AST-094` FR5, FR8, FR11, FR20, FR27, DEC-14, DEC-21; `family:action-groups` FR2; `design:user-states` DR1–DR5; `design:reduced-motion` DR1–DR2; `architecture:layer-runtime` INV22; `architecture:interaction-modality` INV13; `component:Item` FR9; `component:Button` FR15 and FR17; `module:DropdownMenu/useMenuPress` FR6; `architecture:component-import-boundaries` INV10; `spec:AST-013` FR9. | +| Area | Contract | +| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Governing contract | How a press looks and when it shows: `spec:AST-094` FR5, FR8, FR11, FR20 and DEC-21; `design:user-states` DR1–DR5; `design:reduced-motion` DR1–DR2; `architecture:layer-runtime` INV22; `component:Item` FR9. | +| System behavior | One press engine, the page press controller, writes the pressed state of a single press; across a group, the group and menu owners of `architecture:interaction-modality` INV13 write it. Each pressable surface uses one of three recipes: a momentary control, a row-wide target, or a cell or menu row. A press paints and does nothing else: it never changes layout, the hit area, or hit-testing. Every release fades on the theme's exit motion tokens. | +| End-user impact | A person sees the same press on every Astryx surface: the same tint, the same start delay inside scrolling content, the same release fade, and the same cancel when a scroll takes the touch. A press never moves a tap target, so a tap lands where the person aims it. | +| Builder impact | A component picks a recipe and states it in its own record. It adds no press attribute, tracker, timer, or tint variable of its own. A press fix lands once, in the engine or the recipe, and reaches every component that uses it. No public API changes; the recipes are exports of the private press modules. | +| Compatibility/readiness | No public API change. INV1 gap: the touch-runtime press tracker (`PressTracker`, `usePressTracker`), which `architecture:react-component-runtime` INV13 lists for press feedback timing, keeps its current direct users (Switch, Slider, the SegmentedControl lens, Lightbox) until the engine's held-through-drag profile replaces it, and no other component reaches it directly; ClickableCard, SelectableCard, Thumbnail, Tab, Switch, Slider and the Selector-family triggers re-declare press styles (their own press variable, scale, or state) instead of using a recipe's. INV4 gap: Switch, Slider and the SegmentedControl lens release in a fixed 200 ms, and controller controls end a press after 10 px of drift outside scrolling content. INV2 gap: no component record names its recipe, and Table cells paint no press. INV3 and INV9 gap: under a finger, a press makes a control's root the containing block, so a stretched control's tap target shrinks to the control mid-press. INV5 gap: under a mouse or a pen, most surfaces paint CSS `:active`. INV7 gap: a mouse press on a nested control still paints the container's `:active` in Item rows (outside CheckboxList and RadioList), TreeList rows, Token, ClickableCard and SelectableCard. INV9 gap: a press beside a stretched control paints the control instead of the row. INV8 gap: Selector-family triggers scale under reduced motion. | +| Review checks | Reject a new press attribute, tracker, timer, or tint variable outside the recipes; a press style that changes layout, the containing block, or the hit area; a fixed release duration; a container that paints for a press on a nested control that does not activate it, or a control that paints for a press on its container's own surface; and press engine code moved off first load. | +| Governing rules | `spec:AST-094` FR5, FR8, FR11, FR20, FR27, DEC-14, DEC-21; `family:action-groups` FR2; `design:user-states` DR1–DR5; `design:reduced-motion` DR1–DR2; `architecture:layer-runtime` INV22; `architecture:interaction-modality` INV13; `component:Item` FR9; `component:Button` FR15 and FR17; `module:DropdownMenu/useMenuPress` FR6; `architecture:component-import-boundaries` INV10; `spec:AST-013` FR9. | ## Purpose diff --git a/docs/architecture/react-component-runtime.md b/docs/architecture/react-component-runtime.md index 4a2e5bdeca518..9467af71e5bf4 100644 --- a/docs/architecture/react-component-runtime.md +++ b/docs/architecture/react-component-runtime.md @@ -301,7 +301,7 @@ those contracts. still the `VelocityTracker` class), and no internal factory shares a public factory's name (`spec:AST-107` FR6). Core and Lab components use `spec:AST-107`'s public layer wherever it covers their job and reach these modules directly only for - these known public-API gaps: press feedback timing; the Reduce Motion + these known public-API gaps: press feedback timing, through `architecture:press-feedback`'s engine and profiles (its INV1 gap names the touch press tracker's remaining direct users); the Reduce Motion cross-fade constants; press tracking across a group of actions; the selection lock during a gesture; the presentation hold; the input hold; lift-from-trigger and the rectangle morph; custom recognizer relationships; From 50ba22cb4b3fdc06f18cf875d80a062dde91c02a Mon Sep 17 00:00:00 2001 From: Cindy Zhang Date: Mon, 16 Nov 2026 16:50:51 -0800 Subject: [PATCH 14/24] docs(press-feedback): name the pen and CheckboxList rows in the nested-press gaps; list only tested cases --- docs/architecture/press-feedback.md | 18 ++++---- docs/architecture/react-component-runtime.md | 2 +- .../ClickableCard/ClickableCard.spec.md | 2 +- docs/specs/components/Item/Item.spec.md | 36 +++++++-------- .../SelectableCard/SelectableCard.spec.md | 18 ++++---- docs/specs/components/Token/Token.spec.md | 44 +++++++++---------- .../components/TreeList/TreeList.spec.md | 18 ++++---- 7 files changed, 69 insertions(+), 69 deletions(-) diff --git a/docs/architecture/press-feedback.md b/docs/architecture/press-feedback.md index 924864bd0c372..1d3ce7fee4294 100644 --- a/docs/architecture/press-feedback.md +++ b/docs/architecture/press-feedback.md @@ -36,15 +36,15 @@ deciding_specs: [spec:AST-094/FR5, spec:AST-094/FR11, spec:AST-094/DEC-21] ## Contract at a glance -| Area | Contract | -| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Governing contract | How a press looks and when it shows: `spec:AST-094` FR5, FR8, FR11, FR20 and DEC-21; `design:user-states` DR1–DR5; `design:reduced-motion` DR1–DR2; `architecture:layer-runtime` INV22; `component:Item` FR9. | -| System behavior | One press engine, the page press controller, writes the pressed state of a single press; across a group, the group and menu owners of `architecture:interaction-modality` INV13 write it. Each pressable surface uses one of three recipes: a momentary control, a row-wide target, or a cell or menu row. A press paints and does nothing else: it never changes layout, the hit area, or hit-testing. Every release fades on the theme's exit motion tokens. | -| End-user impact | A person sees the same press on every Astryx surface: the same tint, the same start delay inside scrolling content, the same release fade, and the same cancel when a scroll takes the touch. A press never moves a tap target, so a tap lands where the person aims it. | -| Builder impact | A component picks a recipe and states it in its own record. It adds no press attribute, tracker, timer, or tint variable of its own. A press fix lands once, in the engine or the recipe, and reaches every component that uses it. No public API changes; the recipes are exports of the private press modules. | -| Compatibility/readiness | No public API change. INV1 gap: the touch-runtime press tracker (`PressTracker`, `usePressTracker`), which `architecture:react-component-runtime` INV13 lists for press feedback timing, keeps its current direct users (Switch, Slider, the SegmentedControl lens, Lightbox) until the engine's held-through-drag profile replaces it, and no other component reaches it directly; ClickableCard, SelectableCard, Thumbnail, Tab, Switch, Slider and the Selector-family triggers re-declare press styles (their own press variable, scale, or state) instead of using a recipe's. INV4 gap: Switch, Slider and the SegmentedControl lens release in a fixed 200 ms, and controller controls end a press after 10 px of drift outside scrolling content. INV2 gap: no component record names its recipe, and Table cells paint no press. INV3 and INV9 gap: under a finger, a press makes a control's root the containing block, so a stretched control's tap target shrinks to the control mid-press. INV5 gap: under a mouse or a pen, most surfaces paint CSS `:active`. INV7 gap: a mouse press on a nested control still paints the container's `:active` in Item rows (outside CheckboxList and RadioList), TreeList rows, Token, ClickableCard and SelectableCard. INV9 gap: a press beside a stretched control paints the control instead of the row. INV8 gap: Selector-family triggers scale under reduced motion. | -| Review checks | Reject a new press attribute, tracker, timer, or tint variable outside the recipes; a press style that changes layout, the containing block, or the hit area; a fixed release duration; a container that paints for a press on a nested control that does not activate it, or a control that paints for a press on its container's own surface; and press engine code moved off first load. | -| Governing rules | `spec:AST-094` FR5, FR8, FR11, FR20, FR27, DEC-14, DEC-21; `family:action-groups` FR2; `design:user-states` DR1–DR5; `design:reduced-motion` DR1–DR2; `architecture:layer-runtime` INV22; `architecture:interaction-modality` INV13; `component:Item` FR9; `component:Button` FR15 and FR17; `module:DropdownMenu/useMenuPress` FR6; `architecture:component-import-boundaries` INV10; `spec:AST-013` FR9. | +| Area | Contract | +| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Governing contract | How a press looks and when it shows: `spec:AST-094` FR5, FR8, FR11, FR20 and DEC-21; `design:user-states` DR1–DR5; `design:reduced-motion` DR1–DR2; `architecture:layer-runtime` INV22; `component:Item` FR9. | +| System behavior | One press engine, the page press controller, writes the pressed state of a single press; across a group, the group and menu owners of `architecture:interaction-modality` INV13 write it. Each pressable surface uses one of three recipes: a momentary control, a row-wide target, or a cell or menu row. A press paints and does nothing else: it never changes layout, the hit area, or hit-testing. Every release fades on the theme's exit motion tokens. | +| End-user impact | A person sees the same press on every Astryx surface: the same tint, the same start delay inside scrolling content, the same release fade, and the same cancel when a scroll takes the touch. A press never moves a tap target, so a tap lands where the person aims it. | +| Builder impact | A component picks a recipe and states it in its own record. It adds no press attribute, tracker, timer, or tint variable of its own. A press fix lands once, in the engine or the recipe, and reaches every component that uses it. No public API changes; the recipes are exports of the private press modules. | +| Compatibility/readiness | No public API change. INV1 gap: the touch-runtime press tracker (`PressTracker`, `usePressTracker`), which `architecture:react-component-runtime` INV13 lists for press feedback timing, keeps its current direct users (Switch, Slider, the SegmentedControl lens, Lightbox), and no other component reaches it directly; ClickableCard, SelectableCard, Thumbnail, Tab, Switch, Slider and the Selector-family triggers re-declare press styles (their own press variable, scale, or state) instead of using a recipe's. INV4 gap: Switch, Slider and the SegmentedControl lens release in a fixed 200 ms, and controller controls end a press after 10 px of drift outside scrolling content. INV2 gap: no component record names its recipe, and Table cells paint no press. INV3 and INV9 gap: under a finger, a press makes a control's root the containing block, so a stretched control's tap target shrinks to the control mid-press. INV5 gap: under a mouse or a pen, most surfaces paint CSS `:active`. INV7 gap: a mouse or pen press on a nested control still paints the container in Item rows (outside a RadioList row), TreeList rows, Token, ClickableCard and SelectableCard. INV9 gap: a press beside a stretched control paints the control instead of the row. INV8 gap: Selector-family triggers scale under reduced motion. | +| Review checks | Reject a new press attribute, tracker, timer, or tint variable outside the recipes; a press style that changes layout, the containing block, or the hit area; a fixed release duration; a container that paints for a press on a nested control that does not activate it, or a control that paints for a press on its container's own surface; and press engine code moved off first load. | +| Governing rules | `spec:AST-094` FR5, FR8, FR11, FR20, FR27, DEC-14, DEC-21; `family:action-groups` FR2; `design:user-states` DR1–DR5; `design:reduced-motion` DR1–DR2; `architecture:layer-runtime` INV22; `architecture:interaction-modality` INV13; `component:Item` FR9; `component:Button` FR15 and FR17; `module:DropdownMenu/useMenuPress` FR6; `architecture:component-import-boundaries` INV10; `spec:AST-013` FR9. | ## Purpose diff --git a/docs/architecture/react-component-runtime.md b/docs/architecture/react-component-runtime.md index 9467af71e5bf4..b05c40df5d8ce 100644 --- a/docs/architecture/react-component-runtime.md +++ b/docs/architecture/react-component-runtime.md @@ -301,7 +301,7 @@ those contracts. still the `VelocityTracker` class), and no internal factory shares a public factory's name (`spec:AST-107` FR6). Core and Lab components use `spec:AST-107`'s public layer wherever it covers their job and reach these modules directly only for - these known public-API gaps: press feedback timing, through `architecture:press-feedback`'s engine and profiles (its INV1 gap names the touch press tracker's remaining direct users); the Reduce Motion + these known public-API gaps: press feedback timing, which components reach through `architecture:press-feedback`'s engine and profiles, not directly (its INV1 gap names the touch press tracker's remaining direct users); the Reduce Motion cross-fade constants; press tracking across a group of actions; the selection lock during a gesture; the presentation hold; the input hold; lift-from-trigger and the rectangle morph; custom recognizer relationships; diff --git a/docs/specs/components/ClickableCard/ClickableCard.spec.md b/docs/specs/components/ClickableCard/ClickableCard.spec.md index fe5970d9fc62e..7e6b2af4653f9 100644 --- a/docs/specs/components/ClickableCard/ClickableCard.spec.md +++ b/docs/specs/components/ClickableCard/ClickableCard.spec.md @@ -57,7 +57,7 @@ system_specs: [spec:AST-005, spec:AST-009, spec:AST-085] | Behavior | A visually hidden native button or link owns the card's action; the whole card surface activates it, while nested controls and selected text keep their own outcomes. | | End-user impact | People can activate a card from anywhere on it, by pointer or keyboard, and a disabled card stays reachable and announced while doing nothing. | | Builder impact | A theme's exit duration and easing set the touch press release (FR5); no API changes. | -| Compatibility/readiness | No API changes; the touch press release changes (FR5, `spec:AST-094` FR5). Two implementation gaps are listed under Current-state impact. FR5 gap: a mouse press that starts on a nested control still paints the card's `:active`. | +| Compatibility/readiness | No API changes; the touch press release changes (FR5, `spec:AST-094` FR5). Two implementation gaps are listed under Current-state impact. FR5 gap: a mouse or pen press that starts on a nested control still paints the card. | | Review checks | Reject a live destination while disabled, duplicate activation, activation from a nested control or selected text, a destination that skips the shared decision, or lost focus paint. | | Governing rules | `family:navigation-destinations/FR1,FR3–FR5`; `architecture:interaction-modality/INV2–INV5`; `architecture:public-component-api/INV5–INV8`; `spec:AST-085` FR1, FR2, FR5, FR6; `component:ClickableCard/FR5` (the touch press release); `spec:AST-094/FR5` (the press release's exit tokens). | diff --git a/docs/specs/components/Item/Item.spec.md b/docs/specs/components/Item/Item.spec.md index f92e9d22edf22..05f223145a774 100644 --- a/docs/specs/components/Item/Item.spec.md +++ b/docs/specs/components/Item/Item.spec.md @@ -45,15 +45,15 @@ claims it. ## Contract at a glance -| Area | Contract | -| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Public contract | `align?: 'center' \| 'start' \| 'first-line'` on Item, ListItem, RadioListItem, and CheckboxListItem; default `center`. | -| Behavior | `first-line` centers each start and end slot on the label's first line, for any slot height; a slot taller than that line moves the text down rather than leaving the row. | -| End-user impact | A small status dot, radio, or age stays level with the first line of a wrapped label instead of drifting to the middle of the row (`center`) or riding above the line (`start`). | -| Builder impact | None by default. A builder opts in per row with `align="first-line"`; theme authors may style the `item` target's `first-line` alignment. | -| Compatibility/readiness | Additive: a new value on an existing closed axis and typed forwarding of an existing runtime pass-through. Rows that omit `align` are unchanged. FR9 gap: outside a CheckboxList or RadioList row, a mouse press that starts on a nested control still paints the row's `:active`. | -| Review checks | Reject a changed default, changed `center`/`start` geometry, JavaScript measurement, a slot pushed outside the row, a second theme target, or a composing row that drops the value. | -| Governing rules | FR1–FR8 below; `architecture:component-theming-surface/INV6`; `spec:AST-017/FR3`. | +| Area | Contract | +| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Public contract | `align?: 'center' \| 'start' \| 'first-line'` on Item, ListItem, RadioListItem, and CheckboxListItem; default `center`. | +| Behavior | `first-line` centers each start and end slot on the label's first line, for any slot height; a slot taller than that line moves the text down rather than leaving the row. | +| End-user impact | A small status dot, radio, or age stays level with the first line of a wrapped label instead of drifting to the middle of the row (`center`) or riding above the line (`start`). | +| Builder impact | None by default. A builder opts in per row with `align="first-line"`; theme authors may style the `item` target's `first-line` alignment. | +| Compatibility/readiness | Additive: a new value on an existing closed axis and typed forwarding of an existing runtime pass-through. Rows that omit `align` are unchanged. FR9 gap: outside a RadioList row, a mouse or pen press that starts on a nested control still paints the row. | +| Review checks | Reject a changed default, changed `center`/`start` geometry, JavaScript measurement, a slot pushed outside the row, a second theme target, or a composing row that drops the value. | +| Governing rules | FR1–FR8 below; `architecture:component-theming-surface/INV6`; `spec:AST-017/FR3`. | This table is a review projection; the body below is authoritative. @@ -184,15 +184,15 @@ Consumer migration instructions belong in consumer docs and release notes. ## Verification map -| Contract | Verification | Representative states | Mutation or failure expectation | Audit section | -| -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- | --------------------- | -| FR1, FR7 | `Item.test.tsx` alignment and theme-reflection suites; public type test | Omitted, `center`, `start`, `first-line` | A changed default, a missing `data-align="first-line"`, or a widened type fails. | `audit:Item/api` | -| FR2–FR6 | Real-Chromium geometry assertions over the Item alignment stories | Wrapped label with dot and age; avatar; densities; RTL; theme | A slot center off the first line center by more than 0.5px, or a clipped slot, fails. | `audit:Item/layout` | -| FR8 | `List.test.tsx`, `RadioList.test.tsx`, `CheckboxList.test.tsx` forwarding cases | Each composing row with `align="first-line"` | A row whose Item root lacks `data-align="first-line"` fails. | `audit:Item/api` | -| FR9 | `nestedTouchPress.adopters.test.tsx`; `Item.nestedPress.test.tsx`; the nested-control cases in `CheckboxList.test.tsx`, `RadioList.test.tsx` and `useClickableContainer.test.tsx` | A finger on the delegated control; a finger on another control in the row; a mouse and a pen on another control in any interactive row (`onClick`, `href`, delegated), and on a nested control in a link-root or role row | A row painted for a press on another control, or not painted for a press on its delegated control, fails. | `audit:Item/behavior` | -| FR10 | `Item.test.tsx` "reflects highlighted, selected, and disabled on the item theme target" | Plain, highlighted only, selected only, disabled only, and all three together | A missing attribute, or an attribute left on a row whose state does not hold, fails. | `audit:Item/theming` | -| AR1, AR2 | Accessibility-tree snapshot of a `first-line` row against a `center` row | Plain and option rows | Any difference in name, role, description, or order fails. | `audit:Item/a11y` | -| PR1 | Source review of Item's alignment styles | All values | A ref, observer, or Effect added for alignment fails review. | `audit:Item/layout` | +| Contract | Verification | Representative states | Mutation or failure expectation | Audit section | +| -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------- | +| FR1, FR7 | `Item.test.tsx` alignment and theme-reflection suites; public type test | Omitted, `center`, `start`, `first-line` | A changed default, a missing `data-align="first-line"`, or a widened type fails. | `audit:Item/api` | +| FR2–FR6 | Real-Chromium geometry assertions over the Item alignment stories | Wrapped label with dot and age; avatar; densities; RTL; theme | A slot center off the first line center by more than 0.5px, or a clipped slot, fails. | `audit:Item/layout` | +| FR8 | `List.test.tsx`, `RadioList.test.tsx`, `CheckboxList.test.tsx` forwarding cases | Each composing row with `align="first-line"` | A row whose Item root lacks `data-align="first-line"` fails. | `audit:Item/api` | +| FR9 | `nestedTouchPress.adopters.test.tsx`; `Item.nestedPress.test.tsx`; the nested-control cases in `CheckboxList.test.tsx`, `RadioList.test.tsx` and `useClickableContainer.test.tsx` | A finger on the delegated control; a finger on another control in the row | A row painted for a finger press on another control, or not painted for a finger press on its delegated control, fails. Gap: no test yet covers a mouse or pen press on another control in an `onClick`, `href` or delegated row, or a press on a nested control in a link-root or role row; the `useClickableContainer.test.tsx` mouse-and-pen case asserts the earlier rule. | `audit:Item/behavior` | +| FR10 | `Item.test.tsx` "reflects highlighted, selected, and disabled on the item theme target" | Plain, highlighted only, selected only, disabled only, and all three together | A missing attribute, or an attribute left on a row whose state does not hold, fails. | `audit:Item/theming` | +| AR1, AR2 | Accessibility-tree snapshot of a `first-line` row against a `center` row | Plain and option rows | Any difference in name, role, description, or order fails. | `audit:Item/a11y` | +| PR1 | Source review of Item's alignment styles | All values | A ref, observer, or Effect added for alignment fails review. | `audit:Item/layout` | ## Decision log diff --git a/docs/specs/components/SelectableCard/SelectableCard.spec.md b/docs/specs/components/SelectableCard/SelectableCard.spec.md index 0e57be3822ccd..8ef88bd9368f6 100644 --- a/docs/specs/components/SelectableCard/SelectableCard.spec.md +++ b/docs/specs/components/SelectableCard/SelectableCard.spec.md @@ -39,15 +39,15 @@ system_specs: [spec:AST-009, spec:AST-020, spec:AST-085] ## Contract at a glance -| Area | Contract | -| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Public contract | A Card that toggles a controlled `isSelected` through `onChange`, named by a required `label`, with `isDisabled` and Card's `variant`, `elevation`, `padding`, and sizing. | -| Behavior | A visually hidden native checkbox carries the role, name, and checked state; the whole surface toggles; selection draws an inset ring without moving layout. | -| End-user impact | Screen-reader users hear a named checkbox and its state; pointer users click anywhere on the card; disabled cards stay discoverable by keyboard. | -| Builder impact | At the next minor, a click inside an open layer inside the card (e.g. a Tooltip or HoverCard surface) no longer reaches the caller's `onClick`; a handler that needs those presses moves to the layer content. A theme's exit duration and easing set the touch press release (FR4). | -| Compatibility/readiness | No API changes. One `[breaking]` behavior change is staged for the next minor and not built: `onClick` stops receiving clicks inside an open layer. Three implementation gaps are listed under Current-state impact. FR4 gap: a mouse press that starts on a nested control still paints the card's `:active`. The touch press release changes (FR4, `spec:AST-094` FR5). | -| Review checks | Reject a toggle that fires twice for one press, a disabled card that toggles or leaves the tab order, a ring that shifts layout, or a nested control that toggles the card. | -| Governing rules | `spec:AST-085/FR1,FR2,FR5,FR6`; `spec:AST-020/FR9`; `architecture:interaction-modality/INV3`; `architecture:component-theming-surface/INV6,INV14`; `architecture:public-component-api/INV5,INV6,INV7,INV8`; `component:SelectableCard/FR4` (the touch press release); `spec:AST-094/FR5` (the press release's exit tokens). | +| Area | Contract | +| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Public contract | A Card that toggles a controlled `isSelected` through `onChange`, named by a required `label`, with `isDisabled` and Card's `variant`, `elevation`, `padding`, and sizing. | +| Behavior | A visually hidden native checkbox carries the role, name, and checked state; the whole surface toggles; selection draws an inset ring without moving layout. | +| End-user impact | Screen-reader users hear a named checkbox and its state; pointer users click anywhere on the card; disabled cards stay discoverable by keyboard. | +| Builder impact | At the next minor, a click inside an open layer inside the card (e.g. a Tooltip or HoverCard surface) no longer reaches the caller's `onClick`; a handler that needs those presses moves to the layer content. A theme's exit duration and easing set the touch press release (FR4). | +| Compatibility/readiness | No API changes. One `[breaking]` behavior change is staged for the next minor and not built: `onClick` stops receiving clicks inside an open layer. Three implementation gaps are listed under Current-state impact. FR4 gap: a mouse or pen press that starts on a nested control still paints the card. The touch press release changes (FR4, `spec:AST-094` FR5). | +| Review checks | Reject a toggle that fires twice for one press, a disabled card that toggles or leaves the tab order, a ring that shifts layout, or a nested control that toggles the card. | +| Governing rules | `spec:AST-085/FR1,FR2,FR5,FR6`; `spec:AST-020/FR9`; `architecture:interaction-modality/INV3`; `architecture:component-theming-surface/INV6,INV14`; `architecture:public-component-api/INV5,INV6,INV7,INV8`; `component:SelectableCard/FR4` (the touch press release); `spec:AST-094/FR5` (the press release's exit tokens). | This table is a review projection; the body below is authoritative. diff --git a/docs/specs/components/Token/Token.spec.md b/docs/specs/components/Token/Token.spec.md index a86f6996f2e1e..6d49581530d99 100644 --- a/docs/specs/components/Token/Token.spec.md +++ b/docs/specs/components/Token/Token.spec.md @@ -36,15 +36,15 @@ system_specs: [spec:AST-005, spec:AST-009, spec:AST-085] ## Contract at a glance -| Area | Contract | -| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Public contract | An inline chip with a required string `label`, `size`, theme-extensible `color`, optional `icon` and `endContent`, and optional `onClick`, `href`, and `onRemove` interactions. | -| Behavior | `href` renders a link, `onClick` (or an enclosing trigger context) renders a container whose inner button wraps the label, and `onRemove` adds a separate remove button beside, never inside, them. | -| End-user impact | Pointer users can activate the whole chip; keyboard and screen-reader users reach the chip's action and its remove action as separate, named controls. | -| Builder impact | None; the record describes shipped behavior. | -| Compatibility/readiness | Released behavior recorded as current; no API, default, or output changes. Four implementation gaps are listed under Current-state impact. FR6 gap: a mouse press that starts on a nested control still paints the token's `:active`. | -| Review checks | Reject a remove button nested in the link or the inner button, a remove target smaller than 24 by 24 CSS pixels, a native `disabled` attribute, or a token that navigates around the shared destination rule. | -| Governing rules | `family:navigation-destinations`; `spec:AST-005`; `spec:AST-085/FR1,FR2,FR5`; `architecture:public-component-api/INV5,INV6,INV8`; `architecture:component-theming-surface/INV6,INV14`. | +| Area | Contract | +| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Public contract | An inline chip with a required string `label`, `size`, theme-extensible `color`, optional `icon` and `endContent`, and optional `onClick`, `href`, and `onRemove` interactions. | +| Behavior | `href` renders a link, `onClick` (or an enclosing trigger context) renders a container whose inner button wraps the label, and `onRemove` adds a separate remove button beside, never inside, them. | +| End-user impact | Pointer users can activate the whole chip; keyboard and screen-reader users reach the chip's action and its remove action as separate, named controls. | +| Builder impact | None; the record describes shipped behavior. | +| Compatibility/readiness | Released behavior recorded as current; no API, default, or output changes. Four implementation gaps are listed under Current-state impact. FR6 gap: a mouse or pen press that starts on a nested control still paints the token. | +| Review checks | Reject a remove button nested in the link or the inner button, a remove target smaller than 24 by 24 CSS pixels, a native `disabled` attribute, or a token that navigates around the shared destination rule. | +| Governing rules | `family:navigation-destinations`; `spec:AST-005`; `spec:AST-085/FR1,FR2,FR5`; `architecture:public-component-api/INV5,INV6,INV8`; `architecture:component-theming-surface/INV6,INV14`. | This table is a review projection; the body below is authoritative. @@ -245,19 +245,19 @@ token's text color. ## Verification map -| Contract | Verification | Representative states | Mutation or failure expectation | Audit section | -| ----------------------------- | -------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------- | -| FR2, FR10 | `Token.test.tsx` render, ref, and pass-through suites | Static, clickable, and link roots; caller props; caller naming on a clickable and a disabled link token | A wrong root element, a detached ref, a dropped caller prop, or a clickable token's `aria-labelledby` left on its root fails DOM assertions. Gap: no test covers the ref on the link-and-remove container. | `audit:Token/behavior` | -| FR1, FR7 | `Token.stories.tsx` size, icon, and end-content fixtures in a browser | Sizes, icon and end content | Gap: the size and overflow unit tests assert presence only, and no story renders a long label; slot order and block size are visible only in the rendered fixtures, and the ellipsis has no check. | `audit:Token/layout` | -| FR3, FR4, FR6, AR1 | `Token.test.tsx` link, clickable, and link-with-remove suites | Link, clickable, link and remove, modified and middle clicks; a finger, a pen and a mouse press on the Remove button (no token press paint) | Nesting the Remove button, firing the token action from Remove, or losing delegation fails. Gap: no test asserts that `onClick` is dropped with `href`. | `audit:Token/behavior` | -| FR5, AR5 | `Token.test.tsx` disabled tests | Disabled clickable with remove; disabled static; disabled link with and without remove | A native `disabled`, a lost tab stop, a disabled link with a destination, an unreflected disabled state, or a fired callback fails. | `audit:Token/a11y` | -| AR2, AR3, AR7 | `Token.test.tsx` accessibility suite | Remove name, hidden label, description | A missing remove name, lost hidden label, or missing description fails. Gap: no test asserts the link structure's content-derived name. | `audit:Token/a11y` | -| AR6 | `TokenRemoveTarget.a11y.chromium.spec.ts` | Pre-set filter tokens (default size), LTR and RTL | A remove target that misses its X edge or swallows a label press fails in real Chromium. Gap: the `sm` clipping is not covered. | `audit:Token/a11y` | -| FR8 | `Token.test.tsx` custom-color test; `extensibleAxes.test.ts`; `themingTargets.test.ts` | Theme-added color; map wiring | Dropping the `color` reflection fails. Gap: no test asserts `data-size` or any tone's paint; those are visible only in `Token.stories.tsx`. | `audit:Token/theming` | -| FR9, AR4 | `Token.stories.tsx` clickable and link fixtures in a browser | Hover, press, keyboard focus on the token | Gap: no automated check covers overlays or indicators, and no story renders a clickable or link token with Remove, so the double indicator on Remove has no fixture. | `audit:Token/design` | -| PR1 | Source review | Every structure | Gap: no automated check fails if Token adds a per-token listener, observer, or timer. | `audit:Token/behavior` | -| AR2, AR3, AR5, AR7 | Accessibility-tree evidence (`spec:AST-009` FR3) | Every structure; hidden label; description; disabled | Gap: no accessibility-tree check proves the computed names, the hidden-label name, the description, or the disabled state; the unit tests assert DOM attributes only. | `audit:Token/a11y` | -| `design:bidirectionality` DR2 | `MixedDirectionText.a11y.chromium.spec.ts` | `https://`, `.com`, `+3`, `@alice`, `iPhone جديد` and `example.com موقع` under RTL and LTR (Mixed Direction story) | A label whose weak or neutral characters reorder under RTL (`//:https`, `com.`, `3+`, `alice@`), or right-to-left text with a leading Latin word that lays out left to right, fails on each character's rendered position. | `audit:Token/layout` | +| Contract | Verification | Representative states | Mutation or failure expectation | Audit section | +| ----------------------------- | -------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------- | +| FR2, FR10 | `Token.test.tsx` render, ref, and pass-through suites | Static, clickable, and link roots; caller props; caller naming on a clickable and a disabled link token | A wrong root element, a detached ref, a dropped caller prop, or a clickable token's `aria-labelledby` left on its root fails DOM assertions. Gap: no test covers the ref on the link-and-remove container. | `audit:Token/behavior` | +| FR1, FR7 | `Token.stories.tsx` size, icon, and end-content fixtures in a browser | Sizes, icon and end content | Gap: the size and overflow unit tests assert presence only, and no story renders a long label; slot order and block size are visible only in the rendered fixtures, and the ellipsis has no check. | `audit:Token/layout` | +| FR3, FR4, FR6, AR1 | `Token.test.tsx` link, clickable, and link-with-remove suites | Link, clickable, link and remove, modified and middle clicks | Nesting the Remove button, firing the token action from Remove, or losing delegation fails. Gap: no test asserts that `onClick` is dropped with `href`, or that a finger, pen or mouse press on the Remove button paints no token press. | `audit:Token/behavior` | +| FR5, AR5 | `Token.test.tsx` disabled tests | Disabled clickable with remove; disabled static; disabled link with and without remove | A native `disabled`, a lost tab stop, a disabled link with a destination, an unreflected disabled state, or a fired callback fails. | `audit:Token/a11y` | +| AR2, AR3, AR7 | `Token.test.tsx` accessibility suite | Remove name, hidden label, description | A missing remove name, lost hidden label, or missing description fails. Gap: no test asserts the link structure's content-derived name. | `audit:Token/a11y` | +| AR6 | `TokenRemoveTarget.a11y.chromium.spec.ts` | Pre-set filter tokens (default size), LTR and RTL | A remove target that misses its X edge or swallows a label press fails in real Chromium. Gap: the `sm` clipping is not covered. | `audit:Token/a11y` | +| FR8 | `Token.test.tsx` custom-color test; `extensibleAxes.test.ts`; `themingTargets.test.ts` | Theme-added color; map wiring | Dropping the `color` reflection fails. Gap: no test asserts `data-size` or any tone's paint; those are visible only in `Token.stories.tsx`. | `audit:Token/theming` | +| FR9, AR4 | `Token.stories.tsx` clickable and link fixtures in a browser | Hover, press, keyboard focus on the token | Gap: no automated check covers overlays or indicators, and no story renders a clickable or link token with Remove, so the double indicator on Remove has no fixture. | `audit:Token/design` | +| PR1 | Source review | Every structure | Gap: no automated check fails if Token adds a per-token listener, observer, or timer. | `audit:Token/behavior` | +| AR2, AR3, AR5, AR7 | Accessibility-tree evidence (`spec:AST-009` FR3) | Every structure; hidden label; description; disabled | Gap: no accessibility-tree check proves the computed names, the hidden-label name, the description, or the disabled state; the unit tests assert DOM attributes only. | `audit:Token/a11y` | +| `design:bidirectionality` DR2 | `MixedDirectionText.a11y.chromium.spec.ts` | `https://`, `.com`, `+3`, `@alice`, `iPhone جديد` and `example.com موقع` under RTL and LTR (Mixed Direction story) | A label whose weak or neutral characters reorder under RTL (`//:https`, `com.`, `3+`, `alice@`), or right-to-left text with a leading Latin word that lays out left to right, fails on each character's rendered position. | `audit:Token/layout` | ## Decision log diff --git a/docs/specs/components/TreeList/TreeList.spec.md b/docs/specs/components/TreeList/TreeList.spec.md index fd276a3593aa1..6eda358e01ef9 100644 --- a/docs/specs/components/TreeList/TreeList.spec.md +++ b/docs/specs/components/TreeList/TreeList.spec.md @@ -37,15 +37,15 @@ system_specs: ## Contract at a glance -| Area | Contract | -| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Public contract | Each `TreeListItemData` may carry the standard `className`, `style`, and `xstyle` styling inputs for its Item row. | -| Behavior | All supplied styling inputs compose on the same Item row box—the element that paints the row, owns its hover state, and contains its visible content. They do not target the outer semantic `
  • `. | -| End-user impact | A builder can reveal or style content for one row without causing every row in the tree to react. | -| Builder impact | The three standard styling mechanisms remain interchangeable parts of one row-styling seam. A builder may use one or combine them; no existing callsite must opt in. | -| Compatibility/readiness | The contract is additive and keeps default output, except FR8's coarse-pointer glide and DD5's Guides. Its authority is current; implementation support may arrive separately, but the durable API is incomplete until all three mechanisms are supported on the same row. FR7 gap: a mouse press that starts on a nested control still paints the row's `:active`. | -| Review checks | Reject an implementation that omits one mechanism from the durable API, sends the mechanisms to different elements, drops a supplied value, targets the semantic `
  • `, or moves the promised row target without an explicit compatibility decision. | -| Governing rules | [Public component API INV5–INV6](../../../architecture/public-component-api.md) and [AST-002 FR1, FR4, FR7–FR10, FR12, and DEC-1](../../AST-002/spec.md) govern admission, predictability, and composition of the component-local styling seam. | +| Area | Contract | +| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Public contract | Each `TreeListItemData` may carry the standard `className`, `style`, and `xstyle` styling inputs for its Item row. | +| Behavior | All supplied styling inputs compose on the same Item row box—the element that paints the row, owns its hover state, and contains its visible content. They do not target the outer semantic `
  • `. | +| End-user impact | A builder can reveal or style content for one row without causing every row in the tree to react. | +| Builder impact | The three standard styling mechanisms remain interchangeable parts of one row-styling seam. A builder may use one or combine them; no existing callsite must opt in. | +| Compatibility/readiness | The contract is additive and keeps default output, except FR8's coarse-pointer glide and DD5's Guides. Its authority is current; implementation support may arrive separately, but the durable API is incomplete until all three mechanisms are supported on the same row. FR7 gap: a mouse or pen press that starts on a nested control still paints the row. | +| Review checks | Reject an implementation that omits one mechanism from the durable API, sends the mechanisms to different elements, drops a supplied value, targets the semantic `
  • `, or moves the promised row target without an explicit compatibility decision. | +| Governing rules | [Public component API INV5–INV6](../../../architecture/public-component-api.md) and [AST-002 FR1, FR4, FR7–FR10, FR12, and DEC-1](../../AST-002/spec.md) govern admission, predictability, and composition of the component-local styling seam. | This table is a review projection; the body below is authoritative. From 7fe942ba8d599c42c83d65a7107b092fc2b8461b Mon Sep 17 00:00:00 2001 From: Cindy Zhang Date: Mon, 16 Nov 2026 17:23:53 -0800 Subject: [PATCH 15/24] docs(press-feedback): keep the tested CheckboxList, RadioList and Token Remove cases; scope each gap to what is untested --- docs/specs/components/Item/Item.spec.md | 18 ++++++++-------- docs/specs/components/Token/Token.spec.md | 26 +++++++++++------------ 2 files changed, 22 insertions(+), 22 deletions(-) diff --git a/docs/specs/components/Item/Item.spec.md b/docs/specs/components/Item/Item.spec.md index 05f223145a774..97e278feb8560 100644 --- a/docs/specs/components/Item/Item.spec.md +++ b/docs/specs/components/Item/Item.spec.md @@ -184,15 +184,15 @@ Consumer migration instructions belong in consumer docs and release notes. ## Verification map -| Contract | Verification | Representative states | Mutation or failure expectation | Audit section | -| -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------- | -| FR1, FR7 | `Item.test.tsx` alignment and theme-reflection suites; public type test | Omitted, `center`, `start`, `first-line` | A changed default, a missing `data-align="first-line"`, or a widened type fails. | `audit:Item/api` | -| FR2–FR6 | Real-Chromium geometry assertions over the Item alignment stories | Wrapped label with dot and age; avatar; densities; RTL; theme | A slot center off the first line center by more than 0.5px, or a clipped slot, fails. | `audit:Item/layout` | -| FR8 | `List.test.tsx`, `RadioList.test.tsx`, `CheckboxList.test.tsx` forwarding cases | Each composing row with `align="first-line"` | A row whose Item root lacks `data-align="first-line"` fails. | `audit:Item/api` | -| FR9 | `nestedTouchPress.adopters.test.tsx`; `Item.nestedPress.test.tsx`; the nested-control cases in `CheckboxList.test.tsx`, `RadioList.test.tsx` and `useClickableContainer.test.tsx` | A finger on the delegated control; a finger on another control in the row | A row painted for a finger press on another control, or not painted for a finger press on its delegated control, fails. Gap: no test yet covers a mouse or pen press on another control in an `onClick`, `href` or delegated row, or a press on a nested control in a link-root or role row; the `useClickableContainer.test.tsx` mouse-and-pen case asserts the earlier rule. | `audit:Item/behavior` | -| FR10 | `Item.test.tsx` "reflects highlighted, selected, and disabled on the item theme target" | Plain, highlighted only, selected only, disabled only, and all three together | A missing attribute, or an attribute left on a row whose state does not hold, fails. | `audit:Item/theming` | -| AR1, AR2 | Accessibility-tree snapshot of a `first-line` row against a `center` row | Plain and option rows | Any difference in name, role, description, or order fails. | `audit:Item/a11y` | -| PR1 | Source review of Item's alignment styles | All values | A ref, observer, or Effect added for alignment fails review. | `audit:Item/layout` | +| Contract | Verification | Representative states | Mutation or failure expectation | Audit section | +| -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------- | +| FR1, FR7 | `Item.test.tsx` alignment and theme-reflection suites; public type test | Omitted, `center`, `start`, `first-line` | A changed default, a missing `data-align="first-line"`, or a widened type fails. | `audit:Item/api` | +| FR2–FR6 | Real-Chromium geometry assertions over the Item alignment stories | Wrapped label with dot and age; avatar; densities; RTL; theme | A slot center off the first line center by more than 0.5px, or a clipped slot, fails. | `audit:Item/layout` | +| FR8 | `List.test.tsx`, `RadioList.test.tsx`, `CheckboxList.test.tsx` forwarding cases | Each composing row with `align="first-line"` | A row whose Item root lacks `data-align="first-line"` fails. | `audit:Item/api` | +| FR9 | `nestedTouchPress.adopters.test.tsx`; `Item.nestedPress.test.tsx`; the nested-control cases in `CheckboxList.test.tsx`, `RadioList.test.tsx` and `useClickableContainer.test.tsx` | A finger on the delegated control; a finger on another control in the row; a mouse and a pen on another control in a CheckboxList or RadioList row | A row painted for a press on another control, or not painted for a press on its delegated control, fails. Gap: no test yet covers a mouse or pen press on another control in an `onClick`, `href` or delegated row outside CheckboxList and RadioList, or a press on a nested control in a link-root or role row; the `useClickableContainer.test.tsx` mouse-and-pen case asserts the earlier rule. | `audit:Item/behavior` | +| FR10 | `Item.test.tsx` "reflects highlighted, selected, and disabled on the item theme target" | Plain, highlighted only, selected only, disabled only, and all three together | A missing attribute, or an attribute left on a row whose state does not hold, fails. | `audit:Item/theming` | +| AR1, AR2 | Accessibility-tree snapshot of a `first-line` row against a `center` row | Plain and option rows | Any difference in name, role, description, or order fails. | `audit:Item/a11y` | +| PR1 | Source review of Item's alignment styles | All values | A ref, observer, or Effect added for alignment fails review. | `audit:Item/layout` | ## Decision log diff --git a/docs/specs/components/Token/Token.spec.md b/docs/specs/components/Token/Token.spec.md index 6d49581530d99..db3a3bad90360 100644 --- a/docs/specs/components/Token/Token.spec.md +++ b/docs/specs/components/Token/Token.spec.md @@ -245,19 +245,19 @@ token's text color. ## Verification map -| Contract | Verification | Representative states | Mutation or failure expectation | Audit section | -| ----------------------------- | -------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------- | -| FR2, FR10 | `Token.test.tsx` render, ref, and pass-through suites | Static, clickable, and link roots; caller props; caller naming on a clickable and a disabled link token | A wrong root element, a detached ref, a dropped caller prop, or a clickable token's `aria-labelledby` left on its root fails DOM assertions. Gap: no test covers the ref on the link-and-remove container. | `audit:Token/behavior` | -| FR1, FR7 | `Token.stories.tsx` size, icon, and end-content fixtures in a browser | Sizes, icon and end content | Gap: the size and overflow unit tests assert presence only, and no story renders a long label; slot order and block size are visible only in the rendered fixtures, and the ellipsis has no check. | `audit:Token/layout` | -| FR3, FR4, FR6, AR1 | `Token.test.tsx` link, clickable, and link-with-remove suites | Link, clickable, link and remove, modified and middle clicks | Nesting the Remove button, firing the token action from Remove, or losing delegation fails. Gap: no test asserts that `onClick` is dropped with `href`, or that a finger, pen or mouse press on the Remove button paints no token press. | `audit:Token/behavior` | -| FR5, AR5 | `Token.test.tsx` disabled tests | Disabled clickable with remove; disabled static; disabled link with and without remove | A native `disabled`, a lost tab stop, a disabled link with a destination, an unreflected disabled state, or a fired callback fails. | `audit:Token/a11y` | -| AR2, AR3, AR7 | `Token.test.tsx` accessibility suite | Remove name, hidden label, description | A missing remove name, lost hidden label, or missing description fails. Gap: no test asserts the link structure's content-derived name. | `audit:Token/a11y` | -| AR6 | `TokenRemoveTarget.a11y.chromium.spec.ts` | Pre-set filter tokens (default size), LTR and RTL | A remove target that misses its X edge or swallows a label press fails in real Chromium. Gap: the `sm` clipping is not covered. | `audit:Token/a11y` | -| FR8 | `Token.test.tsx` custom-color test; `extensibleAxes.test.ts`; `themingTargets.test.ts` | Theme-added color; map wiring | Dropping the `color` reflection fails. Gap: no test asserts `data-size` or any tone's paint; those are visible only in `Token.stories.tsx`. | `audit:Token/theming` | -| FR9, AR4 | `Token.stories.tsx` clickable and link fixtures in a browser | Hover, press, keyboard focus on the token | Gap: no automated check covers overlays or indicators, and no story renders a clickable or link token with Remove, so the double indicator on Remove has no fixture. | `audit:Token/design` | -| PR1 | Source review | Every structure | Gap: no automated check fails if Token adds a per-token listener, observer, or timer. | `audit:Token/behavior` | -| AR2, AR3, AR5, AR7 | Accessibility-tree evidence (`spec:AST-009` FR3) | Every structure; hidden label; description; disabled | Gap: no accessibility-tree check proves the computed names, the hidden-label name, the description, or the disabled state; the unit tests assert DOM attributes only. | `audit:Token/a11y` | -| `design:bidirectionality` DR2 | `MixedDirectionText.a11y.chromium.spec.ts` | `https://`, `.com`, `+3`, `@alice`, `iPhone جديد` and `example.com موقع` under RTL and LTR (Mixed Direction story) | A label whose weak or neutral characters reorder under RTL (`//:https`, `com.`, `3+`, `alice@`), or right-to-left text with a leading Latin word that lays out left to right, fails on each character's rendered position. | `audit:Token/layout` | +| Contract | Verification | Representative states | Mutation or failure expectation | Audit section | +| ----------------------------- | --------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------- | +| FR2, FR10 | `Token.test.tsx` render, ref, and pass-through suites | Static, clickable, and link roots; caller props; caller naming on a clickable and a disabled link token | A wrong root element, a detached ref, a dropped caller prop, or a clickable token's `aria-labelledby` left on its root fails DOM assertions. Gap: no test covers the ref on the link-and-remove container. | `audit:Token/behavior` | +| FR1, FR7 | `Token.stories.tsx` size, icon, and end-content fixtures in a browser | Sizes, icon and end content | Gap: the size and overflow unit tests assert presence only, and no story renders a long label; slot order and block size are visible only in the rendered fixtures, and the ellipsis has no check. | `audit:Token/layout` | +| FR3, FR4, FR6, AR1 | `Token.test.tsx` link, clickable, and link-with-remove suites; `nestedTouchPress.adopters.test.tsx` Token cases | Link, clickable, link and remove, modified and middle clicks; a finger press on the Remove button (no token press paint) | Nesting the Remove button, firing the token action from Remove, or losing delegation fails. Gap: no test asserts that `onClick` is dropped with `href`, or that a pen or mouse press on the Remove button paints no token press. | `audit:Token/behavior` | +| FR5, AR5 | `Token.test.tsx` disabled tests | Disabled clickable with remove; disabled static; disabled link with and without remove | A native `disabled`, a lost tab stop, a disabled link with a destination, an unreflected disabled state, or a fired callback fails. | `audit:Token/a11y` | +| AR2, AR3, AR7 | `Token.test.tsx` accessibility suite | Remove name, hidden label, description | A missing remove name, lost hidden label, or missing description fails. Gap: no test asserts the link structure's content-derived name. | `audit:Token/a11y` | +| AR6 | `TokenRemoveTarget.a11y.chromium.spec.ts` | Pre-set filter tokens (default size), LTR and RTL | A remove target that misses its X edge or swallows a label press fails in real Chromium. Gap: the `sm` clipping is not covered. | `audit:Token/a11y` | +| FR8 | `Token.test.tsx` custom-color test; `extensibleAxes.test.ts`; `themingTargets.test.ts` | Theme-added color; map wiring | Dropping the `color` reflection fails. Gap: no test asserts `data-size` or any tone's paint; those are visible only in `Token.stories.tsx`. | `audit:Token/theming` | +| FR9, AR4 | `Token.stories.tsx` clickable and link fixtures in a browser | Hover, press, keyboard focus on the token | Gap: no automated check covers overlays or indicators, and no story renders a clickable or link token with Remove, so the double indicator on Remove has no fixture. | `audit:Token/design` | +| PR1 | Source review | Every structure | Gap: no automated check fails if Token adds a per-token listener, observer, or timer. | `audit:Token/behavior` | +| AR2, AR3, AR5, AR7 | Accessibility-tree evidence (`spec:AST-009` FR3) | Every structure; hidden label; description; disabled | Gap: no accessibility-tree check proves the computed names, the hidden-label name, the description, or the disabled state; the unit tests assert DOM attributes only. | `audit:Token/a11y` | +| `design:bidirectionality` DR2 | `MixedDirectionText.a11y.chromium.spec.ts` | `https://`, `.com`, `+3`, `@alice`, `iPhone جديد` and `example.com موقع` under RTL and LTR (Mixed Direction story) | A label whose weak or neutral characters reorder under RTL (`//:https`, `com.`, `3+`, `alice@`), or right-to-left text with a leading Latin word that lays out left to right, fails on each character's rendered position. | `audit:Token/layout` | ## Decision log From 8e57323900b905e4c09b907bafb9cff33290eafe Mon Sep 17 00:00:00 2001 From: Cindy Zhang Date: Mon, 16 Nov 2026 17:55:58 -0800 Subject: [PATCH 16/24] docs(Token): name the untested end-content press in the FR6 gap --- docs/specs/components/Token/Token.spec.md | 26 +++++++++++------------ 1 file changed, 13 insertions(+), 13 deletions(-) diff --git a/docs/specs/components/Token/Token.spec.md b/docs/specs/components/Token/Token.spec.md index db3a3bad90360..66dda03dd84f5 100644 --- a/docs/specs/components/Token/Token.spec.md +++ b/docs/specs/components/Token/Token.spec.md @@ -245,19 +245,19 @@ token's text color. ## Verification map -| Contract | Verification | Representative states | Mutation or failure expectation | Audit section | -| ----------------------------- | --------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------- | -| FR2, FR10 | `Token.test.tsx` render, ref, and pass-through suites | Static, clickable, and link roots; caller props; caller naming on a clickable and a disabled link token | A wrong root element, a detached ref, a dropped caller prop, or a clickable token's `aria-labelledby` left on its root fails DOM assertions. Gap: no test covers the ref on the link-and-remove container. | `audit:Token/behavior` | -| FR1, FR7 | `Token.stories.tsx` size, icon, and end-content fixtures in a browser | Sizes, icon and end content | Gap: the size and overflow unit tests assert presence only, and no story renders a long label; slot order and block size are visible only in the rendered fixtures, and the ellipsis has no check. | `audit:Token/layout` | -| FR3, FR4, FR6, AR1 | `Token.test.tsx` link, clickable, and link-with-remove suites; `nestedTouchPress.adopters.test.tsx` Token cases | Link, clickable, link and remove, modified and middle clicks; a finger press on the Remove button (no token press paint) | Nesting the Remove button, firing the token action from Remove, or losing delegation fails. Gap: no test asserts that `onClick` is dropped with `href`, or that a pen or mouse press on the Remove button paints no token press. | `audit:Token/behavior` | -| FR5, AR5 | `Token.test.tsx` disabled tests | Disabled clickable with remove; disabled static; disabled link with and without remove | A native `disabled`, a lost tab stop, a disabled link with a destination, an unreflected disabled state, or a fired callback fails. | `audit:Token/a11y` | -| AR2, AR3, AR7 | `Token.test.tsx` accessibility suite | Remove name, hidden label, description | A missing remove name, lost hidden label, or missing description fails. Gap: no test asserts the link structure's content-derived name. | `audit:Token/a11y` | -| AR6 | `TokenRemoveTarget.a11y.chromium.spec.ts` | Pre-set filter tokens (default size), LTR and RTL | A remove target that misses its X edge or swallows a label press fails in real Chromium. Gap: the `sm` clipping is not covered. | `audit:Token/a11y` | -| FR8 | `Token.test.tsx` custom-color test; `extensibleAxes.test.ts`; `themingTargets.test.ts` | Theme-added color; map wiring | Dropping the `color` reflection fails. Gap: no test asserts `data-size` or any tone's paint; those are visible only in `Token.stories.tsx`. | `audit:Token/theming` | -| FR9, AR4 | `Token.stories.tsx` clickable and link fixtures in a browser | Hover, press, keyboard focus on the token | Gap: no automated check covers overlays or indicators, and no story renders a clickable or link token with Remove, so the double indicator on Remove has no fixture. | `audit:Token/design` | -| PR1 | Source review | Every structure | Gap: no automated check fails if Token adds a per-token listener, observer, or timer. | `audit:Token/behavior` | -| AR2, AR3, AR5, AR7 | Accessibility-tree evidence (`spec:AST-009` FR3) | Every structure; hidden label; description; disabled | Gap: no accessibility-tree check proves the computed names, the hidden-label name, the description, or the disabled state; the unit tests assert DOM attributes only. | `audit:Token/a11y` | -| `design:bidirectionality` DR2 | `MixedDirectionText.a11y.chromium.spec.ts` | `https://`, `.com`, `+3`, `@alice`, `iPhone جديد` and `example.com موقع` under RTL and LTR (Mixed Direction story) | A label whose weak or neutral characters reorder under RTL (`//:https`, `com.`, `3+`, `alice@`), or right-to-left text with a leading Latin word that lays out left to right, fails on each character's rendered position. | `audit:Token/layout` | +| Contract | Verification | Representative states | Mutation or failure expectation | Audit section | +| ----------------------------- | --------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------- | +| FR2, FR10 | `Token.test.tsx` render, ref, and pass-through suites | Static, clickable, and link roots; caller props; caller naming on a clickable and a disabled link token | A wrong root element, a detached ref, a dropped caller prop, or a clickable token's `aria-labelledby` left on its root fails DOM assertions. Gap: no test covers the ref on the link-and-remove container. | `audit:Token/behavior` | +| FR1, FR7 | `Token.stories.tsx` size, icon, and end-content fixtures in a browser | Sizes, icon and end content | Gap: the size and overflow unit tests assert presence only, and no story renders a long label; slot order and block size are visible only in the rendered fixtures, and the ellipsis has no check. | `audit:Token/layout` | +| FR3, FR4, FR6, AR1 | `Token.test.tsx` link, clickable, and link-with-remove suites; `nestedTouchPress.adopters.test.tsx` Token cases | Link, clickable, link and remove, modified and middle clicks; a finger press on the Remove button (no token press paint) | Nesting the Remove button, firing the token action from Remove, or losing delegation fails. Gap: no test asserts that `onClick` is dropped with `href`, that a pen or mouse press on the Remove button paints no token press, or that a press on a control in end content paints no token press. | `audit:Token/behavior` | +| FR5, AR5 | `Token.test.tsx` disabled tests | Disabled clickable with remove; disabled static; disabled link with and without remove | A native `disabled`, a lost tab stop, a disabled link with a destination, an unreflected disabled state, or a fired callback fails. | `audit:Token/a11y` | +| AR2, AR3, AR7 | `Token.test.tsx` accessibility suite | Remove name, hidden label, description | A missing remove name, lost hidden label, or missing description fails. Gap: no test asserts the link structure's content-derived name. | `audit:Token/a11y` | +| AR6 | `TokenRemoveTarget.a11y.chromium.spec.ts` | Pre-set filter tokens (default size), LTR and RTL | A remove target that misses its X edge or swallows a label press fails in real Chromium. Gap: the `sm` clipping is not covered. | `audit:Token/a11y` | +| FR8 | `Token.test.tsx` custom-color test; `extensibleAxes.test.ts`; `themingTargets.test.ts` | Theme-added color; map wiring | Dropping the `color` reflection fails. Gap: no test asserts `data-size` or any tone's paint; those are visible only in `Token.stories.tsx`. | `audit:Token/theming` | +| FR9, AR4 | `Token.stories.tsx` clickable and link fixtures in a browser | Hover, press, keyboard focus on the token | Gap: no automated check covers overlays or indicators, and no story renders a clickable or link token with Remove, so the double indicator on Remove has no fixture. | `audit:Token/design` | +| PR1 | Source review | Every structure | Gap: no automated check fails if Token adds a per-token listener, observer, or timer. | `audit:Token/behavior` | +| AR2, AR3, AR5, AR7 | Accessibility-tree evidence (`spec:AST-009` FR3) | Every structure; hidden label; description; disabled | Gap: no accessibility-tree check proves the computed names, the hidden-label name, the description, or the disabled state; the unit tests assert DOM attributes only. | `audit:Token/a11y` | +| `design:bidirectionality` DR2 | `MixedDirectionText.a11y.chromium.spec.ts` | `https://`, `.com`, `+3`, `@alice`, `iPhone جديد` and `example.com موقع` under RTL and LTR (Mixed Direction story) | A label whose weak or neutral characters reorder under RTL (`//:https`, `com.`, `3+`, `alice@`), or right-to-left text with a leading Latin word that lays out left to right, fails on each character's rendered position. | `audit:Token/layout` | ## Decision log From adeaa5d8a4c2301ed2776343669124c95c2da03a Mon Sep 17 00:00:00 2001 From: Cindy Zhang Date: Mon, 16 Nov 2026 19:35:21 -0800 Subject: [PATCH 17/24] docs(cards): a mouse press keeps desktop timing; where any press paints follows the every-pointer rule --- docs/specs/components/ClickableCard/ClickableCard.spec.md | 3 ++- docs/specs/components/SelectableCard/SelectableCard.spec.md | 3 ++- 2 files changed, 4 insertions(+), 2 deletions(-) diff --git a/docs/specs/components/ClickableCard/ClickableCard.spec.md b/docs/specs/components/ClickableCard/ClickableCard.spec.md index 7e6b2af4653f9..4a2e42a5d293b 100644 --- a/docs/specs/components/ClickableCard/ClickableCard.spec.md +++ b/docs/specs/components/ClickableCard/ClickableCard.spec.md @@ -72,7 +72,8 @@ without taking activation away from the interactive content inside it. - Released default preserved: `no` for the touch press release: it fades on the theme's exit duration and easing, as FR5 and `spec:AST-094` FR5. A - mouse press keeps the card's desktop press styling. + mouse press keeps the card's desktop press timing; where any press paints + follows FR5 for every pointer (`architecture:press-feedback` INV7). - Compatibility class: nonbreaking behavior change; no public prop, default, DOM, or target changes - Controlled/uncontrolled behavior: not applicable diff --git a/docs/specs/components/SelectableCard/SelectableCard.spec.md b/docs/specs/components/SelectableCard/SelectableCard.spec.md index 8ef88bd9368f6..34800bcb8b253 100644 --- a/docs/specs/components/SelectableCard/SelectableCard.spec.md +++ b/docs/specs/components/SelectableCard/SelectableCard.spec.md @@ -61,7 +61,8 @@ toggling, and the selection ring; the caller owns the selection state. - Released default preserved: `no` for the touch press release: it fades on the theme's exit duration and easing, as FR4 and `spec:AST-094` FR5. A - mouse press keeps the card's desktop press styling. + mouse press keeps the card's desktop press timing; where any press paints + follows FR4 for every pointer (`architecture:press-feedback` INV7). Otherwise `yes` until the next minor; then `no` for the caller `onClick` (FR2). - Compatibility class: no public prop, default or DOM changes; the touch From e3da183dc9fce1e7236c7faf06718943872cbd34 Mon Sep 17 00:00:00 2001 From: Cindy Zhang Date: Mon, 16 Nov 2026 19:39:40 -0800 Subject: [PATCH 18/24] docs(press-feedback): state the owner's paint rule in neutral words --- docs/architecture/press-feedback.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/architecture/press-feedback.md b/docs/architecture/press-feedback.md index 1d3ce7fee4294..b29cad16a0b0d 100644 --- a/docs/architecture/press-feedback.md +++ b/docs/architecture/press-feedback.md @@ -151,10 +151,10 @@ touch. The recipe styles paint from that attribute. fine-pointer profile. - Owner decision (`cixzhang`, 2026-11-16): Core's press code is one engine with three recipes, with no new module and no public API change. -- Owner decision (`cixzhang`, 2026-11-16 11:40 PT), the paint rule (INV7, INV9): - \"so pressed representation rule is the thing getting tapped and invoking the - operation is what gets tinted. so if you're pressing a button, the row - shouldn't tint.\" +- Owner decision (`cixzhang`, 2026-11-16), the paint rule (INV7, INV9): the + surface a press lands on that invokes the action paints, and nothing else; + a press on a control inside a row or card paints only that control, and a + press on the row or card paints only the row or card, for every pointer. ## Verification From 1e0afc2d51c0ebdec1d66a9f5965c1e6201d4a8c Mon Sep 17 00:00:00 2001 From: Cindy Zhang Date: Mon, 16 Nov 2026 19:47:07 -0800 Subject: [PATCH 19/24] docs(press-feedback): Decider line with the decision time --- docs/architecture/press-feedback.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/docs/architecture/press-feedback.md b/docs/architecture/press-feedback.md index b29cad16a0b0d..5449e5530c3e2 100644 --- a/docs/architecture/press-feedback.md +++ b/docs/architecture/press-feedback.md @@ -149,9 +149,7 @@ touch. The recipe styles paint from that attribute. - `spec:AST-094` FR5, FR11, DEC-21: the release, the press profiles, and the fine-pointer profile. -- Owner decision (`cixzhang`, 2026-11-16): Core's press code is one engine - with three recipes, with no new module and no public API change. -- Owner decision (`cixzhang`, 2026-11-16), the paint rule (INV7, INV9): the +- Decider: `cixzhang`, 2026-11-16 11:40 PT, the paint rule (INV7, INV9): the surface a press lands on that invokes the action paints, and nothing else; a press on a control inside a row or card paints only that control, and a press on the row or card paints only the row or card, for every pointer. From 8848813e92c6ceb62b86fddcacb3af07829f3b5d Mon Sep 17 00:00:00 2001 From: Cindy Zhang Date: Mon, 16 Nov 2026 20:34:19 -0800 Subject: [PATCH 20/24] fix(press): a press on a control inside a card, row or token paints only 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. --- .../nested-control-press-every-pointer.md | 7 + .../stories/NestedControlPress.stories.tsx | 94 +++++ docs/architecture/press-feedback.md | 20 +- .../ClickableCard.nestedPress.test.tsx | 3 +- .../core/src/ClickableCard/ClickableCard.tsx | 19 +- .../src/SelectableCard/SelectableCard.tsx | 19 +- .../NestedControlPress.a11y.chromium.spec.ts | 367 ++++++++++++++++++ .../src/__tests__/nestedControlPress.test.tsx | 229 +++++++++++ .../src/hooks/useClickableContainer.test.tsx | 17 +- .../core/src/hooks/useClickableContainer.ts | 83 +++- .../src/privateAttributes/press.stylex.ts | 37 +- .../src/utils/interactionOverlay.stylex.ts | 51 ++- scripts/build-css.test.mjs | 6 +- 13 files changed, 910 insertions(+), 42 deletions(-) create mode 100644 .changeset/nested-control-press-every-pointer.md create mode 100644 apps/storybook/stories/NestedControlPress.stories.tsx create mode 100644 packages/core/src/__tests__/NestedControlPress.a11y.chromium.spec.ts create mode 100644 packages/core/src/__tests__/nestedControlPress.test.tsx 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..a9657c5eb5cb3 --- /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, or a held + * Space key on its action, 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'}); +} + +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('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.test.tsx b/packages/core/src/hooks/useClickableContainer.test.tsx index 97f505de2219f..9e9b49a530401 100644 --- a/packages/core/src/hooks/useClickableContainer.test.tsx +++ b/packages/core/src/hooks/useClickableContainer.test.tsx @@ -282,12 +282,21 @@ describe('onPointerDown', () => { expect(cancelPress).toHaveBeenCalledWith(screen.getByTestId('container')); }); - it('leaves a mouse or pen press to its own paint on a container that owns no control’s box', () => { + it('turns off the container’s press paint for a mouse or pen press that starts on a nested control, until the press ends', () => { render(); const nested = screen.getByRole('button', {name: 'Nested'}); - fireEvent.pointerDown(nested, {pointerType: 'mouse'}); - fireEvent.pointerDown(nested, {pointerType: 'pen'}); - expect(cancelPress).not.toHaveBeenCalled(); + const container = screen.getByTestId('container'); + for (const pointerType of ['mouse', 'pen']) { + fireEvent.pointerDown(nested, {pointerType, button: 0}); + expect(container.style.getPropertyValue('--_nested-press-paint')).toBe( + 'var(--_nested-press-rest)', + ); + expect(cancelPress).toHaveBeenCalledWith(container); + fireEvent.pointerUp(nested, {pointerType, button: 0}); + expect(container.style.getPropertyValue('--_nested-press-paint')).toBe( + '', + ); + } }); it('cancels a mouse or pen press on a nested control of a container that owns a control’s box, and leaves one on the surface alone', () => { diff --git a/packages/core/src/hooks/useClickableContainer.ts b/packages/core/src/hooks/useClickableContainer.ts index a505b76a262b6..8bc612f815404 100644 --- a/packages/core/src/hooks/useClickableContainer.ts +++ b/packages/core/src/hooks/useClickableContainer.ts @@ -11,8 +11,16 @@ * handlers without the marker * @position Core hook for clickable containers with nested interactive * elements. A click on a nested button or link does not run the card's - * action, and a finger press there shows no press on the card. Each navigation - * passes the rule in utils/safeUrl.ts first. + * action, and a press there, from any pointer, shows no press on the card. + * Each navigation passes the rule in utils/safeUrl.ts first. + * + * SYNC: Each style that paints a container's `:active` press reads + * `--_nested-press-paint` there, resets it on its own element, and declares + * `--_nested-press-rest`: + * - /packages/core/src/utils/interactionOverlay.stylex.ts + * - /packages/core/src/privateAttributes/press.stylex.ts + * - /packages/core/src/ClickableCard/ClickableCard.tsx + * - /packages/core/src/SelectableCard/SelectableCard.tsx * * SYNC: When modified, update: * - /packages/core/src/hooks/index.ts (export) @@ -28,7 +36,7 @@ import { import {isLayerSurface} from '../Layer/layerSurfacePress'; import {isSafeUrl} from '../utils/safeUrl'; import {cancelPress} from '../utils/pressFeedback'; -import {pressBoxesIn} from '../privateAttributes/pressBox.stylex'; +import {subscribeInput} from '../utils/inputStream'; /** * The attribute this hook sets on the container it makes clickable. A click @@ -129,14 +137,53 @@ function belongsToSomethingElse(element: Element): boolean { return matchesInteractiveSelectors(element) || isLayerSurface(element); } +/** + * The custom property that turns off a container's `:active` press paint. The + * styles in this file's SYNC list paint the pressed overlay as + * `var(--_nested-press-paint, )` and reset it to `initial` on + * their own element, so a nested control keeps its own press. Each also + * declares `--_nested-press-rest`, what it paints at rest under the pointer + * (its hover overlay, or none). A marked container paints that instead of + * its press, so it keeps its hover. + */ +const NESTED_PRESS_PAINT = '--_nested-press-paint'; + +/** Gives `container` its `:active` press paint back. */ +function clearNestedPress(container: HTMLElement): void { + container.style.removeProperty(NESTED_PRESS_PAINT); +} + +/** + * Turns off `container`'s `:active` press paint until the press ends. A + * browser applies `:active` to every ancestor of the pressed element, so a + * mouse's or a pen's press on a nested control would paint the container too. + */ +function markNestedPress(container: HTMLElement): void { + const view = container.ownerDocument.defaultView; + if (view == null) { + return; + } + container.style.setProperty(NESTED_PRESS_PAINT, 'var(--_nested-press-rest)'); + const stops = [ + subscribeInput(view, 'pointerup', end), + subscribeInput(view, 'pointercancel', end), + ]; + function end() { + clearNestedPress(container); + for (const stop of stops) { + stop(); + } + } +} + /** * The press half of a container's press rule. A press that starts on a nested * interactive element other than the container's own action does not activate - * the container. So it ends the press controller's paint on `container`. The - * rule covers a finger's press on every container. On a container that owns a - * control's box (pressBox.stylex.ts), it covers a mouse's and a pen's press - * too. A press on the container's surface or on `ownAction` is left alone. - * Not part of the package's public API. + * the container, so the container shows no press for it, for every pointer. + * The press controller's paint on `container` ends. For a mouse or a pen, the + * container's `:active` paint also stays off until the press ends. A press on + * the container's surface or on `ownAction` is left alone. Not part of the + * package's public API. */ export function cancelNestedPress( event: PointerEvent, @@ -144,9 +191,14 @@ export function cancelNestedPress( ownAction: Element | null, ): void { const target = event.target; + // A mark that outlived its press, such as one whose release the page never + // saw, does not hold back this press. + if (container != null) { + clearNestedPress(container); + } if ( container == null || - (event.pointerType !== 'touch' && pressBoxesIn(container).length === 0) || + event.button !== 0 || !(target instanceof Element) || target === event.currentTarget || !hasInteractiveAncestor(target, container) || @@ -156,6 +208,9 @@ export function cancelNestedPress( ) { return; } + if (event.pointerType !== 'touch') { + markNestedPress(container); + } cancelPress(container); } @@ -202,10 +257,9 @@ export interface ClickableContainerResult { onMouseUp: (event: MouseEvent) => void; /** * Spread on the container with `onClick`. A press that starts on a nested - * interactive element does not activate the container. On a container that - * paints its press with `usePressFeedback`, this drops that touch press. - * A mouse `:active` press paint is unchanged. A container without it keeps - * its activation rule and shows its pressed state for every press. + * interactive element does not activate the container, so the container + * shows no press for it: this drops the press controller's paint and, for + * a mouse or a pen, the `:active` paint of the shared press styles. */ onPointerDown: (event: PointerEvent) => void; } @@ -370,8 +424,7 @@ export function useClickableContainerProxy({ ); // The press-state counterpart of onClick's rule: a press that would not - // activate the container shows no press on it. That holds for a finger on - // every container, and for a mouse or a pen on one that owns a control's box. + // activate the container shows no press on it, for every pointer. const onPointerDown = useCallback( (event: PointerEvent) => { if (disabled) { diff --git a/packages/core/src/privateAttributes/press.stylex.ts b/packages/core/src/privateAttributes/press.stylex.ts index 59d7eb3a90495..a3d59ff445e58 100644 --- a/packages/core/src/privateAttributes/press.stylex.ts +++ b/packages/core/src/privateAttributes/press.stylex.ts @@ -73,7 +73,14 @@ const NESTED_CONTROL_ACTIVE = const PRESS_ALPHA = pressVars['--astryx-press-alpha']; const hoverImage = `linear-gradient(${colorVars['--color-overlay-hover']}, ${colorVars['--color-overlay-hover']})`; -const pressedImage = `linear-gradient(${colorVars['--color-overlay-pressed']}, ${colorVars['--color-overlay-pressed']})`; +/** + * The pressed overlay a mouse or a pen paints at `:active`, which a container + * turns off for a press on a nested control (hooks/useClickableContainer.ts). + * Each style below that reads it resets it on its own element and declares + * its own rest paint. + */ +const mousePressed = `var(--_nested-press-paint, ${colorVars['--color-overlay-pressed']})`; +const pressedImage = `linear-gradient(${mousePressed}, ${mousePressed})`; /** The overlay's paint, read back off the element (its gradient layer). */ const pressedOverlayImage = 'var(--_press-paint-image)'; @@ -255,6 +262,17 @@ export const rowPressLayerStyles = stylex.create({ * travelling row's surface, which this shadow replaces otherwise. */ overDividers: { + '--_nested-press-paint': 'initial', + '--_nested-press-rest': { + default: 'transparent', + [ENABLED]: { + default: null, + [HOVER_HOVER]: { + default: null, + ':hover': colorVars['--color-overlay-hover'], + }, + }, + }, boxShadow: { default: TRAVELLING_SURFACE, [ENABLED]: { @@ -262,13 +280,13 @@ export const rowPressLayerStyles = stylex.create({ ':not(:first-child)': { default: null, ':active': { - default: tintAbove(colorVars['--color-overlay-pressed']), + default: tintAbove(mousePressed), [COARSE]: TRAVELLING_SURFACE, }, [HOVER_HOVER]: { default: null, ':hover': tintAbove(colorVars['--color-overlay-hover']), - ':active': tintAbove(colorVars['--color-overlay-pressed']), + ':active': tintAbove(mousePressed), }, // A press the controller paints. Under a coarse pointer, the press // layer covers the divider above. Elsewhere the strip takes the @@ -332,6 +350,17 @@ export const rowPressLayerStyles = stylex.create({ * touch press paint yielding to the layer under a coarse primary pointer. */ cellOnImage: { + '--_nested-press-paint': 'initial', + '--_nested-press-rest': { + default: 'transparent', + [ENABLED]: { + default: null, + [HOVER_HOVER]: { + default: null, + ':hover': colorVars['--color-overlay-hover'], + }, + }, + }, backgroundImage: { default: null, [ENABLED]: { @@ -356,6 +385,8 @@ export const rowPressLayerStyles = stylex.create({ * pressed row, so the row shows only its press. */ cellOnImagePressOnly: { + '--_nested-press-paint': 'initial', + '--_nested-press-rest': 'transparent', backgroundImage: { default: null, [ENABLED]: { diff --git a/packages/core/src/utils/interactionOverlay.stylex.ts b/packages/core/src/utils/interactionOverlay.stylex.ts index 3cf8008b6a0ae..fab0aa66863c1 100644 --- a/packages/core/src/utils/interactionOverlay.stylex.ts +++ b/packages/core/src/utils/interactionOverlay.stylex.ts @@ -111,7 +111,15 @@ const PRESSED_FADING: string = '[data-astryx-press="fading"]'; const PRESS_ALPHA = pressVars['--astryx-press-alpha']; const hoverImage = `linear-gradient(${colorVars['--color-overlay-hover']}, ${colorVars['--color-overlay-hover']})`; -const pressedImage = `linear-gradient(${colorVars['--color-overlay-pressed']}, ${colorVars['--color-overlay-pressed']})`; +/** + * The pressed overlay a mouse or a pen paints at `:active`. A container whose + * press starts on a nested control sets `--_nested-press-paint` on itself + * (hooks/useClickableContainer.ts), so it paints its `--_nested-press-rest` + * instead. Each style below that reads it resets it on its own element, so a + * nested control keeps its press, and declares its own rest paint. + */ +const mousePressed = `var(--_nested-press-paint, ${colorVars['--color-overlay-pressed']})`; +const pressedImage = `linear-gradient(${mousePressed}, ${mousePressed})`; const neutralImage = `linear-gradient(${colorVars['--color-neutral']}, ${colorVars['--color-neutral']})`; /** @@ -211,18 +219,29 @@ export const interactionOverlayStyles = stylex.create({ [PRESS_ALPHA]: pressStrength, ...pressReleaseAnimation, ...pressPaint, + '--_nested-press-paint': 'initial', + '--_nested-press-rest': { + default: 'transparent', + [ENABLED]: { + default: null, + [HOVER_HOVER]: { + default: null, + ':hover': colorVars['--color-overlay-hover'], + }, + }, + }, backgroundColor: { default: 'transparent', [ENABLED]: { default: null, ':active': { - default: colorVars['--color-overlay-pressed'], + default: mousePressed, [COARSE]: 'transparent', }, [HOVER_HOVER]: { default: null, ':hover': colorVars['--color-overlay-hover'], - ':active': colorVars['--color-overlay-pressed'], + ':active': mousePressed, }, // While the controller paints, the colour arms yield to the image. A // device with a touchscreen beside a mouse matches `:active` and the @@ -245,6 +264,17 @@ export const interactionOverlayStyles = stylex.create({ [PRESS_ALPHA]: pressStrength, ...pressReleaseAnimation, ...pressPaint, + '--_nested-press-paint': 'initial', + '--_nested-press-rest': { + default: 'transparent', + [ENABLED]: { + default: null, + [HOVER_HOVER]: { + default: null, + ':hover': colorVars['--color-overlay-hover'], + }, + }, + }, backgroundImage: { default: null, [ENABLED]: { @@ -267,6 +297,17 @@ export const interactionOverlayStyles = stylex.create({ [PRESS_ALPHA]: pressStrength, ...pressReleaseAnimation, ...pressPaint, + '--_nested-press-paint': 'initial', + '--_nested-press-rest': { + default: 'transparent', + [ENABLED]: { + default: null, + [HOVER_HOVER]: { + default: null, + ':hover': colorVars['--color-overlay-hover'], + }, + }, + }, backgroundImage: { default: neutralImage, [ENABLED]: { @@ -295,12 +336,14 @@ export const interactionOverlayStyles = stylex.create({ [PRESS_ALPHA]: pressStrength, ...pressReleaseAnimation, ...pressPaint, + '--_nested-press-paint': 'initial', + '--_nested-press-rest': 'transparent', backgroundColor: { default: null, [ENABLED]: { default: null, ':active': { - default: colorVars['--color-overlay-pressed'], + default: mousePressed, [COARSE]: 'transparent', }, // The mouse arm yields to the image while the controller paints; see diff --git a/scripts/build-css.test.mjs b/scripts/build-css.test.mjs index e9bb569cb680d..3a2fd3bf3ede9 100644 --- a/scripts/build-css.test.mjs +++ b/scripts/build-css.test.mjs @@ -114,9 +114,11 @@ function specificity(selector) { function stateRule(css, {property, token, state, media}) { const lines = css.split('\n'); // The token as the fallback of another variable is one component's own - // paint, not the shared overlay this guard orders. + // paint, not the shared overlay this guard orders. The shared overlay's own + // press reads it as the fallback of `--_nested-press-paint`, which a + // container sets for a press on a nested control. const asFallback = new RegExp( - `var\\(--[\\w-]+,\\s*var\\(--color-overlay-${token}\\)`, + `var\\(--(?!_nested-press-paint,)[\\w-]+,\\s*var\\(--color-overlay-${token}\\)`, ); return lines.find(line => { const inHoverMedia = line.includes('@media (hover: hover)'); From 3270bc6065444eb046d739b28fc4132ce6ac85a6 Mon Sep 17 00:00:00 2001 From: Cindy Zhang Date: Mon, 16 Nov 2026 20:40:53 -0800 Subject: [PATCH 21/24] docs(press-feedback): a Space key press paints until release; Enter, which acts on key down, paints none --- docs/architecture/press-feedback.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/architecture/press-feedback.md b/docs/architecture/press-feedback.md index a2d4653a9e5e0..377a4f2395cd6 100644 --- a/docs/architecture/press-feedback.md +++ b/docs/architecture/press-feedback.md @@ -99,8 +99,9 @@ touch. The recipe styles paint from that attribute. - **INV5 — Every pointer through the engine.** A mouse or pen press paints at once on `pointerdown` through the engine, with the same release fade as a finger's, in place of CSS `:active` (`spec:AST-094` DEC-21; `component:Button` FR15). - A key press that activates a control paints its press until release, - through the same recipe. + 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. - **INV6 — The first press.** The engine's core stays on first load: it finds the pressable element, writes the attribute, starts the delay timer, and ends the press on a scroll. Optional profiles (the group slide, the menu From 66888dc31af5f8c3b1f1fd535a933181016598bf Mon Sep 17 00:00:00 2001 From: Cindy Zhang Date: Mon, 16 Nov 2026 21:15:41 -0800 Subject: [PATCH 22/24] docs(ClickableCard, SelectableCard, Item, TreeList, Token): the nested-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. --- .../ClickableCard/ClickableCard.spec.md | 22 ++++---- docs/specs/components/Item/Item.spec.md | 36 ++++++------ .../SelectableCard/SelectableCard.spec.md | 40 ++++++------- docs/specs/components/Token/Token.spec.md | 44 +++++++-------- .../components/TreeList/TreeList.spec.md | 20 +++---- .../src/__tests__/nestedControlPress.test.tsx | 56 +++++++++++++++++-- 6 files changed, 132 insertions(+), 86 deletions(-) diff --git a/docs/specs/components/ClickableCard/ClickableCard.spec.md b/docs/specs/components/ClickableCard/ClickableCard.spec.md index 4a2e42a5d293b..e3ade4f55b486 100644 --- a/docs/specs/components/ClickableCard/ClickableCard.spec.md +++ b/docs/specs/components/ClickableCard/ClickableCard.spec.md @@ -57,7 +57,7 @@ system_specs: [spec:AST-005, spec:AST-009, spec:AST-085] | Behavior | A visually hidden native button or link owns the card's action; the whole card surface activates it, while nested controls and selected text keep their own outcomes. | | End-user impact | People can activate a card from anywhere on it, by pointer or keyboard, and a disabled card stays reachable and announced while doing nothing. | | Builder impact | A theme's exit duration and easing set the touch press release (FR5); no API changes. | -| Compatibility/readiness | No API changes; the touch press release changes (FR5, `spec:AST-094` FR5). Two implementation gaps are listed under Current-state impact. FR5 gap: a mouse or pen press that starts on a nested control still paints the card. | +| Compatibility/readiness | No API changes; the touch press release changes (FR5, `spec:AST-094` FR5). Two implementation gaps are listed under Current-state impact. | | Review checks | Reject a live destination while disabled, duplicate activation, activation from a nested control or selected text, a destination that skips the shared decision, or lost focus paint. | | Governing rules | `family:navigation-destinations/FR1,FR3–FR5`; `architecture:interaction-modality/INV2–INV5`; `architecture:public-component-api/INV5–INV8`; `spec:AST-085` FR1, FR2, FR5, FR6; `component:ClickableCard/FR5` (the touch press release); `spec:AST-094/FR5` (the press release's exit tokens). | @@ -216,16 +216,16 @@ Consumer migration instructions belong in consumer docs and release notes. ## Verification map -| Contract | Verification | Representative states | Mutation or failure expectation | Audit section | -| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------- | -| FR1, AR1 | `ClickableCard.test.tsx` hidden-control, label, and target tests; `Button.a11y.test.tsx` and `Button.a11y.chromium.spec.ts` ClickableCard states | Action and navigation; `clickable-card` and `clickable-card-as-link` | A missing hidden button or link, a lost `aria-label` or `target`, an unexposed button role or name at the accessibility tree, or a link card losing its computed `link` role fails. Gap: the link card's name at the accessibility tree, and that the root adds no role, have no check. | `audit:ClickableCard/accessibility` | -| FR2, ORD1 | `ClickableCard.test.tsx` surface, hidden-control, keyboard, nested-control, and selection tests | Surface; hidden control; Enter; nested button and input; selection | A missing or duplicate `onClick`, a wrong `currentTarget`, or activation from a nested control or selection fails. Gap: no test cancels navigation from `onClick`. No test covers activating the hidden link of a card given both `href` and `onClick`. No ClickableCard test covers a middle press on a card given `href`. | `audit:ClickableCard/behavior` | -| FR3, ORD2 | `useClickableContainer.test.tsx`; `ClickableCard.test.tsx` link tests | Plain, modified, middle, target, accepted, blocked | A blocked destination reaching a sink, or a lost activation method, fails in the shared hook tests. | `audit:ClickableCard/navigation` | -| FR4, AR2 | `ClickableCard.test.tsx` disabled and touch-press tests; `Button.a11y.chromium.spec.ts` `clickable-card-disabled` state | Disabled action and navigation | A disabled control leaving the tab order, a live `href` or `target`, a callback that runs, a touch-press marker while disabled, or a disabled action card whose unavailable state or inertness (click, Enter, Space) fails at the accessibility tree fails. Gap: the disabled link card has no accessibility-tree check (`spec:AST-085` FR5), and disabled hover and mouse-press paint (`spec:AST-085` FR6) and the half opacity have no check. | `audit:ClickableCard/accessibility` | -| FR5, AR3, AR4 | `ClickableCard.test.tsx` touch-press tests; `CardPress.a11y.chromium.spec.ts` on `core-clickablecard--with-on-click`; stable visual baseline `core-clickablecard--navigation` | Rest; desktop hover and mouse press; touch press | A hover that does not paint over rest, a mouse press that does not paint over hover, a touch press that does not match the desktop press or fade, or a changed rest appearance fails or comes back changed. Gap: the border hover and the focus outline have no automated check. | `audit:ClickableCard/design` | -| FR6 | `ClickableCard.test.tsx` elevation tests; `themingTargets.test.ts` | Elevations; target inventory | A lost elevation class or target fails. Gap: no test covers the ref, DOM passthrough, `onMouseUp` order, or the styling-input merge. | `audit:ClickableCard/api` | -| PR1 | Source review | Enabled and disabled | Gap: no automated check fails if ClickableCard adds its own timer, observer, or measurement. | `audit:ClickableCard/behavior` | -| Theming anatomy map | `scripts/check-knowledge.mjs` | Consumer anatomy and current target | Missing, extra, or stale mappings fail repository validation. | `audit:ClickableCard/theming` | +| Contract | Verification | Representative states | Mutation or failure expectation | Audit section | +| ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------- | +| FR1, AR1 | `ClickableCard.test.tsx` hidden-control, label, and target tests; `Button.a11y.test.tsx` and `Button.a11y.chromium.spec.ts` ClickableCard states | Action and navigation; `clickable-card` and `clickable-card-as-link` | A missing hidden button or link, a lost `aria-label` or `target`, an unexposed button role or name at the accessibility tree, or a link card losing its computed `link` role fails. Gap: the link card's name at the accessibility tree, and that the root adds no role, have no check. | `audit:ClickableCard/accessibility` | +| FR2, ORD1 | `ClickableCard.test.tsx` surface, hidden-control, keyboard, nested-control, and selection tests | Surface; hidden control; Enter; nested button and input; selection | A missing or duplicate `onClick`, a wrong `currentTarget`, or activation from a nested control or selection fails. Gap: no test cancels navigation from `onClick`. No test covers activating the hidden link of a card given both `href` and `onClick`. No ClickableCard test covers a middle press on a card given `href`. | `audit:ClickableCard/behavior` | +| FR3, ORD2 | `useClickableContainer.test.tsx`; `ClickableCard.test.tsx` link tests | Plain, modified, middle, target, accepted, blocked | A blocked destination reaching a sink, or a lost activation method, fails in the shared hook tests. | `audit:ClickableCard/navigation` | +| FR4, AR2 | `ClickableCard.test.tsx` disabled and touch-press tests; `Button.a11y.chromium.spec.ts` `clickable-card-disabled` state | Disabled action and navigation | A disabled control leaving the tab order, a live `href` or `target`, a callback that runs, a touch-press marker while disabled, or a disabled action card whose unavailable state or inertness (click, Enter, Space) fails at the accessibility tree fails. Gap: the disabled link card has no accessibility-tree check (`spec:AST-085` FR5), and disabled hover and mouse-press paint (`spec:AST-085` FR6) and the half opacity have no check. | `audit:ClickableCard/accessibility` | +| FR5, AR3, AR4 | `ClickableCard.test.tsx` touch-press tests; `CardPress.a11y.chromium.spec.ts` on `core-clickablecard--with-on-click`; stable visual baseline `core-clickablecard--navigation`; `nestedControlPress.test.tsx`; `NestedControlPress.a11y.chromium.spec.ts` | Rest; desktop hover and mouse press; touch press; a finger, a pen and a mouse press on a nested control (no card press paint) | A hover that does not paint over rest, a mouse press that does not paint over hover, a touch press that does not match the desktop press or fade, or a changed rest appearance fails or comes back changed. Gap: the border hover and the focus outline have no automated check. A card painted for a press on a nested control fails. | `audit:ClickableCard/design` | +| FR6 | `ClickableCard.test.tsx` elevation tests; `themingTargets.test.ts` | Elevations; target inventory | A lost elevation class or target fails. Gap: no test covers the ref, DOM passthrough, `onMouseUp` order, or the styling-input merge. | `audit:ClickableCard/api` | +| PR1 | Source review | Enabled and disabled | Gap: no automated check fails if ClickableCard adds its own timer, observer, or measurement. | `audit:ClickableCard/behavior` | +| Theming anatomy map | `scripts/check-knowledge.mjs` | Consumer anatomy and current target | Missing, extra, or stale mappings fail repository validation. | `audit:ClickableCard/theming` | ## Decision log diff --git a/docs/specs/components/Item/Item.spec.md b/docs/specs/components/Item/Item.spec.md index 97e278feb8560..9fa7915bfba6d 100644 --- a/docs/specs/components/Item/Item.spec.md +++ b/docs/specs/components/Item/Item.spec.md @@ -45,15 +45,15 @@ claims it. ## Contract at a glance -| Area | Contract | -| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Public contract | `align?: 'center' \| 'start' \| 'first-line'` on Item, ListItem, RadioListItem, and CheckboxListItem; default `center`. | -| Behavior | `first-line` centers each start and end slot on the label's first line, for any slot height; a slot taller than that line moves the text down rather than leaving the row. | -| End-user impact | A small status dot, radio, or age stays level with the first line of a wrapped label instead of drifting to the middle of the row (`center`) or riding above the line (`start`). | -| Builder impact | None by default. A builder opts in per row with `align="first-line"`; theme authors may style the `item` target's `first-line` alignment. | -| Compatibility/readiness | Additive: a new value on an existing closed axis and typed forwarding of an existing runtime pass-through. Rows that omit `align` are unchanged. FR9 gap: outside a RadioList row, a mouse or pen press that starts on a nested control still paints the row. | -| Review checks | Reject a changed default, changed `center`/`start` geometry, JavaScript measurement, a slot pushed outside the row, a second theme target, or a composing row that drops the value. | -| Governing rules | FR1–FR8 below; `architecture:component-theming-surface/INV6`; `spec:AST-017/FR3`. | +| Area | Contract | +| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Public contract | `align?: 'center' \| 'start' \| 'first-line'` on Item, ListItem, RadioListItem, and CheckboxListItem; default `center`. | +| Behavior | `first-line` centers each start and end slot on the label's first line, for any slot height; a slot taller than that line moves the text down rather than leaving the row. | +| End-user impact | A small status dot, radio, or age stays level with the first line of a wrapped label instead of drifting to the middle of the row (`center`) or riding above the line (`start`). | +| Builder impact | None by default. A builder opts in per row with `align="first-line"`; theme authors may style the `item` target's `first-line` alignment. | +| Compatibility/readiness | Additive: a new value on an existing closed axis and typed forwarding of an existing runtime pass-through. Rows that omit `align` are unchanged. | +| Review checks | Reject a changed default, changed `center`/`start` geometry, JavaScript measurement, a slot pushed outside the row, a second theme target, or a composing row that drops the value. | +| Governing rules | FR1–FR8 below; `architecture:component-theming-surface/INV6`; `spec:AST-017/FR3`. | This table is a review projection; the body below is authoritative. @@ -184,15 +184,15 @@ Consumer migration instructions belong in consumer docs and release notes. ## Verification map -| Contract | Verification | Representative states | Mutation or failure expectation | Audit section | -| -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------- | -| FR1, FR7 | `Item.test.tsx` alignment and theme-reflection suites; public type test | Omitted, `center`, `start`, `first-line` | A changed default, a missing `data-align="first-line"`, or a widened type fails. | `audit:Item/api` | -| FR2–FR6 | Real-Chromium geometry assertions over the Item alignment stories | Wrapped label with dot and age; avatar; densities; RTL; theme | A slot center off the first line center by more than 0.5px, or a clipped slot, fails. | `audit:Item/layout` | -| FR8 | `List.test.tsx`, `RadioList.test.tsx`, `CheckboxList.test.tsx` forwarding cases | Each composing row with `align="first-line"` | A row whose Item root lacks `data-align="first-line"` fails. | `audit:Item/api` | -| FR9 | `nestedTouchPress.adopters.test.tsx`; `Item.nestedPress.test.tsx`; the nested-control cases in `CheckboxList.test.tsx`, `RadioList.test.tsx` and `useClickableContainer.test.tsx` | A finger on the delegated control; a finger on another control in the row; a mouse and a pen on another control in a CheckboxList or RadioList row | A row painted for a press on another control, or not painted for a press on its delegated control, fails. Gap: no test yet covers a mouse or pen press on another control in an `onClick`, `href` or delegated row outside CheckboxList and RadioList, or a press on a nested control in a link-root or role row; the `useClickableContainer.test.tsx` mouse-and-pen case asserts the earlier rule. | `audit:Item/behavior` | -| FR10 | `Item.test.tsx` "reflects highlighted, selected, and disabled on the item theme target" | Plain, highlighted only, selected only, disabled only, and all three together | A missing attribute, or an attribute left on a row whose state does not hold, fails. | `audit:Item/theming` | -| AR1, AR2 | Accessibility-tree snapshot of a `first-line` row against a `center` row | Plain and option rows | Any difference in name, role, description, or order fails. | `audit:Item/a11y` | -| PR1 | Source review of Item's alignment styles | All values | A ref, observer, or Effect added for alignment fails review. | `audit:Item/layout` | +| Contract | Verification | Representative states | Mutation or failure expectation | Audit section | +| -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------- | +| FR1, FR7 | `Item.test.tsx` alignment and theme-reflection suites; public type test | Omitted, `center`, `start`, `first-line` | A changed default, a missing `data-align="first-line"`, or a widened type fails. | `audit:Item/api` | +| FR2–FR6 | Real-Chromium geometry assertions over the Item alignment stories | Wrapped label with dot and age; avatar; densities; RTL; theme | A slot center off the first line center by more than 0.5px, or a clipped slot, fails. | `audit:Item/layout` | +| FR8 | `List.test.tsx`, `RadioList.test.tsx`, `CheckboxList.test.tsx` forwarding cases | Each composing row with `align="first-line"` | A row whose Item root lacks `data-align="first-line"` fails. | `audit:Item/api` | +| FR9 | `nestedTouchPress.adopters.test.tsx`; `Item.nestedPress.test.tsx`; the nested-control cases in `CheckboxList.test.tsx`, `RadioList.test.tsx` and `useClickableContainer.test.tsx`; `nestedControlPress.test.tsx`; `NestedControlPress.a11y.chromium.spec.ts` | A finger on the delegated control; a finger on another control in the row; a mouse and a pen on another control in a CheckboxList or RadioList row; a finger, a pen and a mouse on another control in an `onClick`, `href` and delegated row; a mouse on a nested control in a link-root row, which paints the row | A row painted for a press on another control, or not painted for a press on its delegated control, fails. Gap: no test yet covers a press on a nested control in a row with a parent-supplied role. | `audit:Item/behavior` | +| FR10 | `Item.test.tsx` "reflects highlighted, selected, and disabled on the item theme target" | Plain, highlighted only, selected only, disabled only, and all three together | A missing attribute, or an attribute left on a row whose state does not hold, fails. | `audit:Item/theming` | +| AR1, AR2 | Accessibility-tree snapshot of a `first-line` row against a `center` row | Plain and option rows | Any difference in name, role, description, or order fails. | `audit:Item/a11y` | +| PR1 | Source review of Item's alignment styles | All values | A ref, observer, or Effect added for alignment fails review. | `audit:Item/layout` | ## Decision log diff --git a/docs/specs/components/SelectableCard/SelectableCard.spec.md b/docs/specs/components/SelectableCard/SelectableCard.spec.md index 34800bcb8b253..aa1f7e70fcf3e 100644 --- a/docs/specs/components/SelectableCard/SelectableCard.spec.md +++ b/docs/specs/components/SelectableCard/SelectableCard.spec.md @@ -39,15 +39,15 @@ system_specs: [spec:AST-009, spec:AST-020, spec:AST-085] ## Contract at a glance -| Area | Contract | -| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Public contract | A Card that toggles a controlled `isSelected` through `onChange`, named by a required `label`, with `isDisabled` and Card's `variant`, `elevation`, `padding`, and sizing. | -| Behavior | A visually hidden native checkbox carries the role, name, and checked state; the whole surface toggles; selection draws an inset ring without moving layout. | -| End-user impact | Screen-reader users hear a named checkbox and its state; pointer users click anywhere on the card; disabled cards stay discoverable by keyboard. | -| Builder impact | At the next minor, a click inside an open layer inside the card (e.g. a Tooltip or HoverCard surface) no longer reaches the caller's `onClick`; a handler that needs those presses moves to the layer content. A theme's exit duration and easing set the touch press release (FR4). | -| Compatibility/readiness | No API changes. One `[breaking]` behavior change is staged for the next minor and not built: `onClick` stops receiving clicks inside an open layer. Three implementation gaps are listed under Current-state impact. FR4 gap: a mouse or pen press that starts on a nested control still paints the card. The touch press release changes (FR4, `spec:AST-094` FR5). | -| Review checks | Reject a toggle that fires twice for one press, a disabled card that toggles or leaves the tab order, a ring that shifts layout, or a nested control that toggles the card. | -| Governing rules | `spec:AST-085/FR1,FR2,FR5,FR6`; `spec:AST-020/FR9`; `architecture:interaction-modality/INV3`; `architecture:component-theming-surface/INV6,INV14`; `architecture:public-component-api/INV5,INV6,INV7,INV8`; `component:SelectableCard/FR4` (the touch press release); `spec:AST-094/FR5` (the press release's exit tokens). | +| Area | Contract | +| ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Public contract | A Card that toggles a controlled `isSelected` through `onChange`, named by a required `label`, with `isDisabled` and Card's `variant`, `elevation`, `padding`, and sizing. | +| Behavior | A visually hidden native checkbox carries the role, name, and checked state; the whole surface toggles; selection draws an inset ring without moving layout. | +| End-user impact | Screen-reader users hear a named checkbox and its state; pointer users click anywhere on the card; disabled cards stay discoverable by keyboard. | +| Builder impact | At the next minor, a click inside an open layer inside the card (e.g. a Tooltip or HoverCard surface) no longer reaches the caller's `onClick`; a handler that needs those presses moves to the layer content. A theme's exit duration and easing set the touch press release (FR4). | +| Compatibility/readiness | No API changes. One `[breaking]` behavior change is staged for the next minor and not built: `onClick` stops receiving clicks inside an open layer. Three implementation gaps are listed under Current-state impact. The touch press release changes (FR4, `spec:AST-094` FR5). | +| Review checks | Reject a toggle that fires twice for one press, a disabled card that toggles or leaves the tab order, a ring that shifts layout, or a nested control that toggles the card. | +| Governing rules | `spec:AST-085/FR1,FR2,FR5,FR6`; `spec:AST-020/FR9`; `architecture:interaction-modality/INV3`; `architecture:component-theming-surface/INV6,INV14`; `architecture:public-component-api/INV5,INV6,INV7,INV8`; `component:SelectableCard/FR4` (the touch press release); `spec:AST-094/FR5` (the press release's exit tokens). | This table is a review projection; the body below is authoritative. @@ -241,17 +241,17 @@ Consumer migration instructions belong in consumer docs and release notes. ## Verification map -| Contract | Verification | Representative states | Mutation or failure expectation | Audit section | -| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------- | -| FR1, FR2 | `SelectableCard.test.tsx` surface, checkbox, Enter, and Space tests | Unselected, selected | A missed toggle, a wrong `onChange` value, or a doubled toggle from Space fails. Gap: surface-click tests assert only the value, not the call count, and no test asserts the `selectable-card` target or its reflection, or the order of a caller `onClick` or `onMouseUp`. | `audit:SelectableCard/behavior` | -| FR3 | `SelectableCard.test.tsx` elevation tests; stable visual baseline `core-selectablecard--single-select`; `SelectableCard.stories.tsx` | Selected with elevation; one selected default card beside unselected ones | A lost elevation while selected fails; a changed default ring or border comes back changed for review. Gap: palette and theme-added ring colors have no automated check. | `audit:SelectableCard/theming` | -| FR4 | `SelectableCard.test.tsx` touch-press test; `CardPress.a11y.chromium.spec.ts` on `core-selectablecard--single-select` | Rest; desktop hover and mouse press; touch press | A hover that does not paint over rest, a mouse press that does not paint over hover, or a touch press that does not match the desktop press or fade fails. Gap: the focus outline, and the double indicator on nested controls, have no automated check. | `audit:SelectableCard/design` | -| FR5, AR3 | `SelectableCard.test.tsx` disabled tests; `Checkbox.a11y.chromium.spec.ts` `card-disabled` state | Disabled click, Enter, Space | A toggle while disabled, or a disabled card that leaves keyboard reach, fails. Gap: the half opacity, the removed overlays, and the missing disabled reflection on the target have no automated check. | `audit:SelectableCard/a11y` | -| FR2 (nested) | Shared clickable-container hook tests in other components | Card with a nested control or selected text | Gap: no SelectableCard test or story covers nested-control or selection suppression. | `audit:SelectableCard/behavior` | -| Theming anatomy map | `scripts/check-knowledge.mjs` | Consumer anatomy and current target | Missing, extra, or stale mappings fail repository validation. | `audit:SelectableCard/theming` | -| AR1, AR2, AR4 | `SelectableCard.test.tsx` checkbox tests; `Checkbox.a11y.test.tsx` and `Checkbox.a11y.chromium.spec.ts` SelectableCard states | Unchecked, checked, disabled (`card-unchecked`, `card-checked`, `card-disabled`) | A lost checkbox role or name, a wrong checked state, or a disabled card that is not exposed as unavailable or not reachable fails, including at the accessibility tree. Gap: no test asserts that the root adds no role or tab stop, the root focus outline, or the ring winning over hover. | `audit:SelectableCard/a11y` | -| FR6, PR1 | Source review | Ref; caller props | Gap: no test asserts ref or passthrough routing, or fails if SelectableCard adds its own listener or timer. | `audit:SelectableCard/behavior` | -| AR5 | `Checkbox.a11y.chromium.spec.ts` aborted-press check on the SelectableCard states | Press that slides off the card before the lift | A toggle after a slide-off lift fails. | `audit:SelectableCard/a11y` | +| Contract | Verification | Representative states | Mutation or failure expectation | Audit section | +| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------- | +| FR1, FR2 | `SelectableCard.test.tsx` surface, checkbox, Enter, and Space tests | Unselected, selected | A missed toggle, a wrong `onChange` value, or a doubled toggle from Space fails. Gap: surface-click tests assert only the value, not the call count, and no test asserts the `selectable-card` target or its reflection, or the order of a caller `onClick` or `onMouseUp`. | `audit:SelectableCard/behavior` | +| FR3 | `SelectableCard.test.tsx` elevation tests; stable visual baseline `core-selectablecard--single-select`; `SelectableCard.stories.tsx` | Selected with elevation; one selected default card beside unselected ones | A lost elevation while selected fails; a changed default ring or border comes back changed for review. Gap: palette and theme-added ring colors have no automated check. | `audit:SelectableCard/theming` | +| FR4 | `SelectableCard.test.tsx` touch-press test; `CardPress.a11y.chromium.spec.ts` on `core-selectablecard--single-select`; `nestedControlPress.test.tsx`; `NestedControlPress.a11y.chromium.spec.ts` | Rest; desktop hover and mouse press; touch press; a finger, a pen and a mouse press on a nested control (no card press paint) | A hover that does not paint over rest, a mouse press that does not paint over hover, or a touch press that does not match the desktop press or fade fails, as does a card painted for a press on a nested control. Gap: the focus outline, and the double indicator on nested controls, have no automated check. | `audit:SelectableCard/design` | +| FR5, AR3 | `SelectableCard.test.tsx` disabled tests; `Checkbox.a11y.chromium.spec.ts` `card-disabled` state | Disabled click, Enter, Space | A toggle while disabled, or a disabled card that leaves keyboard reach, fails. Gap: the half opacity, the removed overlays, and the missing disabled reflection on the target have no automated check. | `audit:SelectableCard/a11y` | +| FR2 (nested) | Shared clickable-container hook tests in other components | Card with a nested control or selected text | Gap: no SelectableCard test or story covers nested-control or selection suppression. | `audit:SelectableCard/behavior` | +| Theming anatomy map | `scripts/check-knowledge.mjs` | Consumer anatomy and current target | Missing, extra, or stale mappings fail repository validation. | `audit:SelectableCard/theming` | +| AR1, AR2, AR4 | `SelectableCard.test.tsx` checkbox tests; `Checkbox.a11y.test.tsx` and `Checkbox.a11y.chromium.spec.ts` SelectableCard states | Unchecked, checked, disabled (`card-unchecked`, `card-checked`, `card-disabled`) | A lost checkbox role or name, a wrong checked state, or a disabled card that is not exposed as unavailable or not reachable fails, including at the accessibility tree. Gap: no test asserts that the root adds no role or tab stop, the root focus outline, or the ring winning over hover. | `audit:SelectableCard/a11y` | +| FR6, PR1 | Source review | Ref; caller props | Gap: no test asserts ref or passthrough routing, or fails if SelectableCard adds its own listener or timer. | `audit:SelectableCard/behavior` | +| AR5 | `Checkbox.a11y.chromium.spec.ts` aborted-press check on the SelectableCard states | Press that slides off the card before the lift | A toggle after a slide-off lift fails. | `audit:SelectableCard/a11y` | ## Decision log diff --git a/docs/specs/components/Token/Token.spec.md b/docs/specs/components/Token/Token.spec.md index 66dda03dd84f5..ed9eef3f7dc20 100644 --- a/docs/specs/components/Token/Token.spec.md +++ b/docs/specs/components/Token/Token.spec.md @@ -36,15 +36,15 @@ system_specs: [spec:AST-005, spec:AST-009, spec:AST-085] ## Contract at a glance -| Area | Contract | -| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Public contract | An inline chip with a required string `label`, `size`, theme-extensible `color`, optional `icon` and `endContent`, and optional `onClick`, `href`, and `onRemove` interactions. | -| Behavior | `href` renders a link, `onClick` (or an enclosing trigger context) renders a container whose inner button wraps the label, and `onRemove` adds a separate remove button beside, never inside, them. | -| End-user impact | Pointer users can activate the whole chip; keyboard and screen-reader users reach the chip's action and its remove action as separate, named controls. | -| Builder impact | None; the record describes shipped behavior. | -| Compatibility/readiness | Released behavior recorded as current; no API, default, or output changes. Four implementation gaps are listed under Current-state impact. FR6 gap: a mouse or pen press that starts on a nested control still paints the token. | -| Review checks | Reject a remove button nested in the link or the inner button, a remove target smaller than 24 by 24 CSS pixels, a native `disabled` attribute, or a token that navigates around the shared destination rule. | -| Governing rules | `family:navigation-destinations`; `spec:AST-005`; `spec:AST-085/FR1,FR2,FR5`; `architecture:public-component-api/INV5,INV6,INV8`; `architecture:component-theming-surface/INV6,INV14`. | +| Area | Contract | +| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Public contract | An inline chip with a required string `label`, `size`, theme-extensible `color`, optional `icon` and `endContent`, and optional `onClick`, `href`, and `onRemove` interactions. | +| Behavior | `href` renders a link, `onClick` (or an enclosing trigger context) renders a container whose inner button wraps the label, and `onRemove` adds a separate remove button beside, never inside, them. | +| End-user impact | Pointer users can activate the whole chip; keyboard and screen-reader users reach the chip's action and its remove action as separate, named controls. | +| Builder impact | None; the record describes shipped behavior. | +| Compatibility/readiness | Released behavior recorded as current; no API, default, or output changes. Four implementation gaps are listed under Current-state impact. | +| Review checks | Reject a remove button nested in the link or the inner button, a remove target smaller than 24 by 24 CSS pixels, a native `disabled` attribute, or a token that navigates around the shared destination rule. | +| Governing rules | `family:navigation-destinations`; `spec:AST-005`; `spec:AST-085/FR1,FR2,FR5`; `architecture:public-component-api/INV5,INV6,INV8`; `architecture:component-theming-surface/INV6,INV14`. | This table is a review projection; the body below is authoritative. @@ -245,19 +245,19 @@ token's text color. ## Verification map -| Contract | Verification | Representative states | Mutation or failure expectation | Audit section | -| ----------------------------- | --------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------- | -| FR2, FR10 | `Token.test.tsx` render, ref, and pass-through suites | Static, clickable, and link roots; caller props; caller naming on a clickable and a disabled link token | A wrong root element, a detached ref, a dropped caller prop, or a clickable token's `aria-labelledby` left on its root fails DOM assertions. Gap: no test covers the ref on the link-and-remove container. | `audit:Token/behavior` | -| FR1, FR7 | `Token.stories.tsx` size, icon, and end-content fixtures in a browser | Sizes, icon and end content | Gap: the size and overflow unit tests assert presence only, and no story renders a long label; slot order and block size are visible only in the rendered fixtures, and the ellipsis has no check. | `audit:Token/layout` | -| FR3, FR4, FR6, AR1 | `Token.test.tsx` link, clickable, and link-with-remove suites; `nestedTouchPress.adopters.test.tsx` Token cases | Link, clickable, link and remove, modified and middle clicks; a finger press on the Remove button (no token press paint) | Nesting the Remove button, firing the token action from Remove, or losing delegation fails. Gap: no test asserts that `onClick` is dropped with `href`, that a pen or mouse press on the Remove button paints no token press, or that a press on a control in end content paints no token press. | `audit:Token/behavior` | -| FR5, AR5 | `Token.test.tsx` disabled tests | Disabled clickable with remove; disabled static; disabled link with and without remove | A native `disabled`, a lost tab stop, a disabled link with a destination, an unreflected disabled state, or a fired callback fails. | `audit:Token/a11y` | -| AR2, AR3, AR7 | `Token.test.tsx` accessibility suite | Remove name, hidden label, description | A missing remove name, lost hidden label, or missing description fails. Gap: no test asserts the link structure's content-derived name. | `audit:Token/a11y` | -| AR6 | `TokenRemoveTarget.a11y.chromium.spec.ts` | Pre-set filter tokens (default size), LTR and RTL | A remove target that misses its X edge or swallows a label press fails in real Chromium. Gap: the `sm` clipping is not covered. | `audit:Token/a11y` | -| FR8 | `Token.test.tsx` custom-color test; `extensibleAxes.test.ts`; `themingTargets.test.ts` | Theme-added color; map wiring | Dropping the `color` reflection fails. Gap: no test asserts `data-size` or any tone's paint; those are visible only in `Token.stories.tsx`. | `audit:Token/theming` | -| FR9, AR4 | `Token.stories.tsx` clickable and link fixtures in a browser | Hover, press, keyboard focus on the token | Gap: no automated check covers overlays or indicators, and no story renders a clickable or link token with Remove, so the double indicator on Remove has no fixture. | `audit:Token/design` | -| PR1 | Source review | Every structure | Gap: no automated check fails if Token adds a per-token listener, observer, or timer. | `audit:Token/behavior` | -| AR2, AR3, AR5, AR7 | Accessibility-tree evidence (`spec:AST-009` FR3) | Every structure; hidden label; description; disabled | Gap: no accessibility-tree check proves the computed names, the hidden-label name, the description, or the disabled state; the unit tests assert DOM attributes only. | `audit:Token/a11y` | -| `design:bidirectionality` DR2 | `MixedDirectionText.a11y.chromium.spec.ts` | `https://`, `.com`, `+3`, `@alice`, `iPhone جديد` and `example.com موقع` under RTL and LTR (Mixed Direction story) | A label whose weak or neutral characters reorder under RTL (`//:https`, `com.`, `3+`, `alice@`), or right-to-left text with a leading Latin word that lays out left to right, fails on each character's rendered position. | `audit:Token/layout` | +| Contract | Verification | Representative states | Mutation or failure expectation | Audit section | +| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------- | +| FR2, FR10 | `Token.test.tsx` render, ref, and pass-through suites | Static, clickable, and link roots; caller props; caller naming on a clickable and a disabled link token | A wrong root element, a detached ref, a dropped caller prop, or a clickable token's `aria-labelledby` left on its root fails DOM assertions. Gap: no test covers the ref on the link-and-remove container. | `audit:Token/behavior` | +| FR1, FR7 | `Token.stories.tsx` size, icon, and end-content fixtures in a browser | Sizes, icon and end content | Gap: the size and overflow unit tests assert presence only, and no story renders a long label; slot order and block size are visible only in the rendered fixtures, and the ellipsis has no check. | `audit:Token/layout` | +| FR3, FR4, FR6, AR1 | `Token.test.tsx` link, clickable, and link-with-remove suites; `nestedTouchPress.adopters.test.tsx` Token cases; `nestedControlPress.test.tsx`; `NestedControlPress.a11y.chromium.spec.ts` | Link, clickable, link and remove, modified and middle clicks; a finger, a pen and a mouse press on the Remove button (no token press paint); a mouse press on the token's own button (token press paint) | Nesting the Remove button, firing the token action from Remove, or losing delegation fails. Gap: no test asserts that `onClick` is dropped with `href`, that a pen or mouse press on the Remove button paints no token press, or that a press on a control in end content paints no token press. | `audit:Token/behavior` | +| FR5, AR5 | `Token.test.tsx` disabled tests | Disabled clickable with remove; disabled static; disabled link with and without remove | A native `disabled`, a lost tab stop, a disabled link with a destination, an unreflected disabled state, or a fired callback fails. | `audit:Token/a11y` | +| AR2, AR3, AR7 | `Token.test.tsx` accessibility suite | Remove name, hidden label, description | A missing remove name, lost hidden label, or missing description fails. Gap: no test asserts the link structure's content-derived name. | `audit:Token/a11y` | +| AR6 | `TokenRemoveTarget.a11y.chromium.spec.ts` | Pre-set filter tokens (default size), LTR and RTL | A remove target that misses its X edge or swallows a label press fails in real Chromium. Gap: the `sm` clipping is not covered. | `audit:Token/a11y` | +| FR8 | `Token.test.tsx` custom-color test; `extensibleAxes.test.ts`; `themingTargets.test.ts` | Theme-added color; map wiring | Dropping the `color` reflection fails. Gap: no test asserts `data-size` or any tone's paint; those are visible only in `Token.stories.tsx`. | `audit:Token/theming` | +| FR9, AR4 | `Token.stories.tsx` clickable and link fixtures in a browser | Hover, press, keyboard focus on the token | Gap: no automated check covers overlays or indicators, and no story renders a clickable or link token with Remove, so the double indicator on Remove has no fixture. | `audit:Token/design` | +| PR1 | Source review | Every structure | Gap: no automated check fails if Token adds a per-token listener, observer, or timer. | `audit:Token/behavior` | +| AR2, AR3, AR5, AR7 | Accessibility-tree evidence (`spec:AST-009` FR3) | Every structure; hidden label; description; disabled | Gap: no accessibility-tree check proves the computed names, the hidden-label name, the description, or the disabled state; the unit tests assert DOM attributes only. | `audit:Token/a11y` | +| `design:bidirectionality` DR2 | `MixedDirectionText.a11y.chromium.spec.ts` | `https://`, `.com`, `+3`, `@alice`, `iPhone جديد` and `example.com موقع` under RTL and LTR (Mixed Direction story) | A label whose weak or neutral characters reorder under RTL (`//:https`, `com.`, `3+`, `alice@`), or right-to-left text with a leading Latin word that lays out left to right, fails on each character's rendered position. | `audit:Token/layout` | ## Decision log diff --git a/docs/specs/components/TreeList/TreeList.spec.md b/docs/specs/components/TreeList/TreeList.spec.md index 6eda358e01ef9..7a815ca70fc29 100644 --- a/docs/specs/components/TreeList/TreeList.spec.md +++ b/docs/specs/components/TreeList/TreeList.spec.md @@ -37,15 +37,15 @@ system_specs: ## Contract at a glance -| Area | Contract | -| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Public contract | Each `TreeListItemData` may carry the standard `className`, `style`, and `xstyle` styling inputs for its Item row. | -| Behavior | All supplied styling inputs compose on the same Item row box—the element that paints the row, owns its hover state, and contains its visible content. They do not target the outer semantic `
  • `. | -| End-user impact | A builder can reveal or style content for one row without causing every row in the tree to react. | -| Builder impact | The three standard styling mechanisms remain interchangeable parts of one row-styling seam. A builder may use one or combine them; no existing callsite must opt in. | -| Compatibility/readiness | The contract is additive and keeps default output, except FR8's coarse-pointer glide and DD5's Guides. Its authority is current; implementation support may arrive separately, but the durable API is incomplete until all three mechanisms are supported on the same row. FR7 gap: a mouse or pen press that starts on a nested control still paints the row. | -| Review checks | Reject an implementation that omits one mechanism from the durable API, sends the mechanisms to different elements, drops a supplied value, targets the semantic `
  • `, or moves the promised row target without an explicit compatibility decision. | -| Governing rules | [Public component API INV5–INV6](../../../architecture/public-component-api.md) and [AST-002 FR1, FR4, FR7–FR10, FR12, and DEC-1](../../AST-002/spec.md) govern admission, predictability, and composition of the component-local styling seam. | +| Area | Contract | +| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Public contract | Each `TreeListItemData` may carry the standard `className`, `style`, and `xstyle` styling inputs for its Item row. | +| Behavior | All supplied styling inputs compose on the same Item row box—the element that paints the row, owns its hover state, and contains its visible content. They do not target the outer semantic `
  • `. | +| End-user impact | A builder can reveal or style content for one row without causing every row in the tree to react. | +| Builder impact | The three standard styling mechanisms remain interchangeable parts of one row-styling seam. A builder may use one or combine them; no existing callsite must opt in. | +| Compatibility/readiness | The contract is additive and keeps default output, except FR8's coarse-pointer glide and DD5's Guides. Its authority is current; implementation support may arrive separately, but the durable API is incomplete until all three mechanisms are supported on the same row. | +| Review checks | Reject an implementation that omits one mechanism from the durable API, sends the mechanisms to different elements, drops a supplied value, targets the semantic `
  • `, or moves the promised row target without an explicit compatibility decision. | +| Governing rules | [Public component API INV5–INV6](../../../architecture/public-component-api.md) and [AST-002 FR1, FR4, FR7–FR10, FR12, and DEC-1](../../AST-002/spec.md) govern admission, predictability, and composition of the component-local styling seam. | This table is a review projection; the body below is authoritative. @@ -294,7 +294,7 @@ authorize or prohibit a future target. | AR1 | Tree View accessibility contract (`internal/a11y-spec`, pending) bound to TreeList, in jsdom and Chromium; `TreeList.test.tsx` row-naming cases ("names a parent row by its label alone, not the chevron toggle", "names a plain row by its label and describes it with its description", "names and describes link and action rows themselves, not only their inner control", "keeps start and end content, including controls, out of the row name", "typeahead matches the label, not the description or start content") and `TreeListRowNames.a11y.chromium.spec.ts` for the browser-computed names; `TreeList.test.tsx` structural ARIA cases ("sets aria-level, aria-posinset, and aria-setsize at the top level", "sets aria-level/posinset/setsize correctly at deeper levels", "sets aria-level across three depths"); `TreeList.test.tsx` and `useTreeFocus.test.tsx` keyboard suites | Flat and nested trees; expanded/collapsed; selected/unselected; LTR and RTL; typeahead | A row loses its role, label name, state or position, two rows hold a Tab stop, an arrow key stops moving or stops mirroring under RTL, Home/End or typeahead stop working, or the tree claims multi-select | `audit:TreeList/accessibility` | | AR1 (empty header) | `TreeList.test.tsx` "TreeList empty slots" suite: "a header of %s names nothing; the tree keeps its own label" for `''`, `false`, `true`, and `null`, and `0` as a rendered Header | Empty, boolean, and null header with `aria-label`; `0` header | A tree named by an empty Header, or carrying `aria-labelledby` without a rendered Header, fails. | `audit:TreeList/accessibility` | | FR5, FR6, ORD1 | Focused `TreeList.test.tsx` row-identity and styling-composition coverage, required with implementation | One input at a time; all three together; sibling rows | Dropping any mechanism, applying mechanisms to different elements, targeting the `
  • `, changing the merge order, or styling a sibling row fails. | `audit:TreeList/api` | -| FR7 | Focused `TreeList.test.tsx` row-click coverage, required with implementation | Action, parent, link, and disabled rows; clicks in the indent and padding, on the Chevron, and on Start and End content controls; plain, modified, and middle clicks; a finger, a pen and a mouse press on a Start or End content control (no row press paint) | A click outside the label does nothing or runs the wrong action, a link-row click reaches ancestors twice, the Chevron or a Start or End content control activates the row, or a disabled row acts. | `audit:TreeList/behavior` | +| FR7 | Focused `TreeList.test.tsx` row-click coverage, required with implementation; `nestedControlPress.test.tsx`; `NestedControlPress.a11y.chromium.spec.ts` | Action, parent, link, and disabled rows; clicks in the indent and padding, on the Chevron, and on Start and End content controls; plain, modified, and middle clicks; a finger, a pen and a mouse press on a Start or End content control (no row press paint) | A click outside the label does nothing or runs the wrong action, a link-row click reaches ancestors twice, the Chevron or a Start or End content control activates the row, or a disabled row acts. | `audit:TreeList/behavior` | | FR8 | `TreeListExpand.interaction.browser.spec.ts`: per-frame evidence under a finger and a mouse | expand and collapse; reduced motion; the theme's glide token; the rows below and content after the tree, with and without an `animatedLayout` handle | A blank band above the rows below, on any frame, a group that shows at rest before it fades in, rows below that jump, timing other than the theme's glide, motion under a fine pointer without a handle, travel under reduced motion, a collapsed group's rows in the accessibility tree after the tap, or content after the tree moving without a handle fails | `audit:TreeList/behavior` | | FR9 | `animatedLayoutAdopters.test.tsx` (with and without a handle; `isExpanded` changed in `items` glides; the collapsing group kept inert and out of the keyboard order until its exit ends) and `animatedLayoutAdopters.interaction.browser.spec.ts` (the `Core/Animated layout` story through a ScrollableArea ref, expanding and collapsing) | No handle; a handle; click, keyboard, and `items`-driven changes; expanding and collapsing | The rows after a row jump with a handle, an `items` change lands at once, a collapsing group vanishes before its exit or its rows stay focusable during it, or anything changes without a handle | `audit:TreeList/behavior` | | AR2 | `TreeList.test.tsx` collapse-focus suite; `animatedLayoutAdopters.test.tsx` collapse with focus inside during the exit; `TreeListCollapseFocus.a11y.chromium.spec.ts` | Focus on a child row, `items`-driven collapse, with and without a handle; nested outer and inner collapse; a disabled collapsing row; focus on another row or outside | Focus left in the removed or inert group, on the page body, or moved when it was not inside the group fails. | `audit:TreeList/accessibility` | diff --git a/packages/core/src/__tests__/nestedControlPress.test.tsx b/packages/core/src/__tests__/nestedControlPress.test.tsx index 95b1c3f4887ea..fc916d3b5f877 100644 --- a/packages/core/src/__tests__/nestedControlPress.test.tsx +++ b/packages/core/src/__tests__/nestedControlPress.test.tsx @@ -4,9 +4,10 @@ * @file nestedControlPress.test.tsx * @input vitest (jsdom), React Testing Library, ClickableCard, * SelectableCard, Item, TreeList and Token - * @output Checks the press rule of every container, for a mouse and a pen: a - * press that starts on a nested control turns off the container's `:active` - * paint until the press ends; a press on the container's own surface or its + * @output Checks the press rule of every container, for a finger, a pen and + * a mouse: a finger's press that starts on a nested control paints no press + * on the container, and a mouse's or a pen's turns off the container's + * `:active` paint until the press ends; a press on the container's own surface or its * own action leaves it on; a row whose root is a link keeps its press. The * paint itself is checked in a real browser * (__tests__/NestedControlPress.a11y.chromium.spec.ts) @@ -14,9 +15,11 @@ * through each container that composes it */ -import {fireEvent, render, screen} from '@testing-library/react'; +import {act, fireEvent, render, screen} from '@testing-library/react'; import {useRef, type ReactNode} from 'react'; -import {describe, expect, it} from 'vitest'; +import {afterEach, describe, expect, it, vi} from 'vitest'; +import {PRESS_ONSET_MS} from '../utils/pressGesture'; +import {PRESSED_ATTRIBUTE} from '../utils/pressFeedback'; import {ClickableCard} from '../ClickableCard/ClickableCard'; import {SelectableCard} from '../SelectableCard/SelectableCard'; import {Item} from '../Item/Item'; @@ -120,6 +123,10 @@ function nestedOf(name: string): HTMLElement { : 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', @@ -136,6 +143,45 @@ describe.each(CASES)('$name', testCase => { }, ); + 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(); From 8b27ee4a5936d2ce9cd5b291e9d8556e832ed055 Mon Sep 17 00:00:00 2001 From: Cindy Zhang Date: Mon, 16 Nov 2026 21:44:23 -0800 Subject: [PATCH 23/24] docs(press-feedback): record that a held Space on a container's own action 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. --- .../stories/NestedControlPress.stories.tsx | 4 +-- docs/architecture/press-feedback.md | 18 +++++----- .../NestedControlPress.a11y.chromium.spec.ts | 33 ++----------------- 3 files changed, 13 insertions(+), 42 deletions(-) diff --git a/apps/storybook/stories/NestedControlPress.stories.tsx b/apps/storybook/stories/NestedControlPress.stories.tsx index a9657c5eb5cb3..130e24302d6bb 100644 --- a/apps/storybook/stories/NestedControlPress.stories.tsx +++ b/apps/storybook/stories/NestedControlPress.stories.tsx @@ -8,8 +8,8 @@ * 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, or a held - * Space key on its action, paints the container + * only that control; a press on the container's own surface paints the + * container * @position Fixture for __tests__/NestedControlPress.a11y.chromium.spec.ts */ diff --git a/docs/architecture/press-feedback.md b/docs/architecture/press-feedback.md index 377a4f2395cd6..7bc38a150009d 100644 --- a/docs/architecture/press-feedback.md +++ b/docs/architecture/press-feedback.md @@ -36,15 +36,15 @@ deciding_specs: [spec:AST-094/FR5, spec:AST-094/FR11, spec:AST-094/DEC-21] ## Contract at a glance -| Area | Contract | -| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Governing contract | How a press looks and when it shows: `spec:AST-094` FR5, FR8, FR11, FR20 and DEC-21; `design:user-states` DR1–DR5; `design:reduced-motion` DR1–DR2; `architecture:layer-runtime` INV22; `component:Item` FR9. | -| System behavior | One press engine, the page press controller, writes the pressed state of a single press; across a group, the group and menu owners of `architecture:interaction-modality` INV13 write it. Each pressable surface uses one of three recipes: a momentary control, a row-wide target, or a cell or menu row. A press paints and does nothing else: it never changes layout, the hit area, or hit-testing. Every release fades on the theme's exit motion tokens. | -| End-user impact | A person sees the same press on every Astryx surface: the same tint, the same start delay inside scrolling content, the same release fade, and the same cancel when a scroll takes the touch. A press never moves a tap target, so a tap lands where the person aims it. | -| Builder impact | A component picks a recipe and states it in its own record. It adds no press attribute, tracker, timer, or tint variable of its own. A press fix lands once, in the engine or the recipe, and reaches every component that uses it. No public API changes; the recipes are exports of the private press modules. | -| Compatibility/readiness | No public API change. INV1 gap: the touch-runtime press tracker (`PressTracker`, `usePressTracker`), which `architecture:react-component-runtime` INV13 lists for press feedback timing, keeps its current direct users (Switch, Slider, the SegmentedControl lens, Lightbox), and no other component reaches it directly; ClickableCard, SelectableCard, Thumbnail, Tab, Switch, Slider and the Selector-family triggers re-declare press styles (their own press variable, scale, or state) instead of using a recipe's. INV4 gap: Switch, Slider and the SegmentedControl lens release in a fixed 200 ms, and controller controls end a press after 10 px of drift outside scrolling content. INV2 gap: no component record names its recipe, and Table cells paint no press. INV3 and INV9 gap: under a finger, a press makes a control's root the containing block, so a stretched control's tap target shrinks to the control mid-press. INV5 gap: under a mouse or a pen, most surfaces paint CSS `:active`. INV9 gap: a press beside a stretched control paints the control instead of the row. INV8 gap: Selector-family triggers scale under reduced motion. | -| Review checks | Reject a new press attribute, tracker, timer, or tint variable outside the recipes; a press style that changes layout, the containing block, or the hit area; a fixed release duration; a container that paints for a press on a nested control that does not activate it, or a control that paints for a press on its container's own surface; and press engine code moved off first load. | -| Governing rules | `spec:AST-094` FR5, FR8, FR11, FR20, FR27, DEC-14, DEC-21; `family:action-groups` FR2; `design:user-states` DR1–DR5; `design:reduced-motion` DR1–DR2; `architecture:layer-runtime` INV22; `architecture:interaction-modality` INV13; `component:Item` FR9; `component:Button` FR15 and FR17; `module:DropdownMenu/useMenuPress` FR6; `architecture:component-import-boundaries` INV10; `spec:AST-013` FR9. | +| Area | Contract | +| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Governing contract | How a press looks and when it shows: `spec:AST-094` FR5, FR8, FR11, FR20 and DEC-21; `design:user-states` DR1–DR5; `design:reduced-motion` DR1–DR2; `architecture:layer-runtime` INV22; `component:Item` FR9. | +| System behavior | One press engine, the page press controller, writes the pressed state of a single press; across a group, the group and menu owners of `architecture:interaction-modality` INV13 write it. Each pressable surface uses one of three recipes: a momentary control, a row-wide target, or a cell or menu row. A press paints and does nothing else: it never changes layout, the hit area, or hit-testing. Every release fades on the theme's exit motion tokens. | +| End-user impact | A person sees the same press on every Astryx surface: the same tint, the same start delay inside scrolling content, the same release fade, and the same cancel when a scroll takes the touch. A press never moves a tap target, so a tap lands where the person aims it. | +| Builder impact | A component picks a recipe and states it in its own record. It adds no press attribute, tracker, timer, or tint variable of its own. A press fix lands once, in the engine or the recipe, and reaches every component that uses it. No public API changes; the recipes are exports of the private press modules. | +| Compatibility/readiness | No public API change. INV1 gap: the touch-runtime press tracker (`PressTracker`, `usePressTracker`), which `architecture:react-component-runtime` INV13 lists for press feedback timing, keeps its current direct users (Switch, Slider, the SegmentedControl lens, Lightbox), and no other component reaches it directly; ClickableCard, SelectableCard, Thumbnail, Tab, Switch, Slider and the Selector-family triggers re-declare press styles (their own press variable, scale, or state) instead of using a recipe's. INV4 gap: Switch, Slider and the SegmentedControl lens release in a fixed 200 ms, and controller controls end a press after 10 px of drift outside scrolling content. INV2 gap: no component record names its recipe, and Table cells paint no press. INV3 and INV9 gap: under a finger, a press makes a control's root the containing block, so a stretched control's tap target shrinks to the control mid-press. INV5 gap: under a mouse or a pen, most surfaces paint CSS `:active`. INV5 gap: a held Space on a container's own action (ClickableCard, SelectableCard, Item, TreeList row, Token) paints no press on the container. INV9 gap: a press beside a stretched control paints the control instead of the row. INV8 gap: Selector-family triggers scale under reduced motion. | +| Review checks | Reject a new press attribute, tracker, timer, or tint variable outside the recipes; a press style that changes layout, the containing block, or the hit area; a fixed release duration; a container that paints for a press on a nested control that does not activate it, or a control that paints for a press on its container's own surface; and press engine code moved off first load. | +| Governing rules | `spec:AST-094` FR5, FR8, FR11, FR20, FR27, DEC-14, DEC-21; `family:action-groups` FR2; `design:user-states` DR1–DR5; `design:reduced-motion` DR1–DR2; `architecture:layer-runtime` INV22; `architecture:interaction-modality` INV13; `component:Item` FR9; `component:Button` FR15 and FR17; `module:DropdownMenu/useMenuPress` FR6; `architecture:component-import-boundaries` INV10; `spec:AST-013` FR9. | ## Purpose diff --git a/packages/core/src/__tests__/NestedControlPress.a11y.chromium.spec.ts b/packages/core/src/__tests__/NestedControlPress.a11y.chromium.spec.ts index bb8ca8294a340..6cddc7473dba7 100644 --- a/packages/core/src/__tests__/NestedControlPress.a11y.chromium.spec.ts +++ b/packages/core/src/__tests__/NestedControlPress.a11y.chromium.spec.ts @@ -8,8 +8,8 @@ * @output Real-engine proof of the press rule for every container: a press on * a nested control leaves the container as it was under the pointer, for a * mouse, a pen and a finger; a mouse press on the container's own surface - * paints the container; a held Space key on a control or on a container's - * action paints its press until the key is released + * paints the container; a held Space key on a Button paints its press + * until the key is released * @position Run with `pnpm test:a11y-contract`. Browser layer of * cancelNestedPress (hooks/useClickableContainer.ts); the jsdom layer is * __tests__/nestedControlPress.test.tsx. @@ -72,8 +72,6 @@ interface Container { selector: string; /** The nested control's accessible name. */ nested: RegExp; - /** The container's own action, which takes keyboard focus. */ - action: {role: 'button' | 'checkbox' | 'radio'; name: RegExp}; /** Where to read the container's paint: clear of its content. */ sample: (box: Box) => Point; } @@ -81,7 +79,6 @@ interface Container { const CONTAINERS: Container[] = [ { name: 'ClickableCard', - action: {role: 'button', name: /^Open billing$/}, id: 'clickable-card', selector: '[data-pressable-container]', nested: /^Nested$/, @@ -89,7 +86,6 @@ const CONTAINERS: Container[] = [ }, { name: 'SelectableCard', - action: {role: 'checkbox', name: /^Plan$/}, id: 'selectable-card', selector: '[data-pressable-container]', nested: /^Nested$/, @@ -97,7 +93,6 @@ const CONTAINERS: Container[] = [ }, { name: 'Item', - action: {role: 'button', name: /^Open row$/}, id: 'item', selector: '.astryx-item', nested: /^Nested$/, @@ -105,7 +100,6 @@ const CONTAINERS: Container[] = [ }, { name: 'TreeList row', - action: {role: 'button', name: /Open tree row/}, id: 'tree-list', selector: '.astryx-tree-list-item', nested: /^Nested$/, @@ -113,7 +107,6 @@ const CONTAINERS: Container[] = [ }, { name: 'Token', - action: {role: 'button', name: /^Filter token$/}, id: 'token', selector: '.astryx-token', nested: /remove/i, @@ -123,8 +116,6 @@ const CONTAINERS: Container[] = [ interface Opened { page: Page; - /** The container's own action. */ - action: ReturnType; cdp: CDPSession; close: () => Promise; nested: Point; @@ -160,9 +151,6 @@ async function open( await page.mouse.move(1, 1); return { page, - action: scope.getByRole(container.action.role, { - name: container.action.name, - }), cdp: await context.newCDPSession(page), close: async () => context.close(), nested: { @@ -313,23 +301,6 @@ for (const container of CONTAINERS) { await opened.close(); } }); - - test(`${container.name}: a held Space key on its action paints the container until the release`, async ({ - browser, - }) => { - const opened = await open(browser, DESKTOP, container); - try { - const {page} = opened; - await opened.action.focus(); - const rest = await steadyPixel(page, opened.sample); - await page.keyboard.down('Space'); - expectOtherColour(await steadyPixel(page, opened.sample), rest); - await page.keyboard.up('Space'); - expectSameColour(await steadyPixel(page, opened.sample), rest); - } finally { - await opened.close(); - } - }); } test('Button: a held Space key paints its press until the release', async ({ From 62e8b70560e5f1ea48973ce5d205a46154744d43 Mon Sep 17 00:00:00 2001 From: Cindy Zhang Date: Tue, 17 Nov 2026 03:33:53 -0800 Subject: [PATCH 24/24] docs(useClickableContainer, Token): the onPointerDown docs and Token's gap match the shipped nested press --- docs/specs/components/Token/Token.spec.md | 26 ++--- .../src/hooks/useClickableContainer.doc.mjs | 96 +++++++++++++++---- 2 files changed, 88 insertions(+), 34 deletions(-) diff --git a/docs/specs/components/Token/Token.spec.md b/docs/specs/components/Token/Token.spec.md index ed9eef3f7dc20..495e6ccb26987 100644 --- a/docs/specs/components/Token/Token.spec.md +++ b/docs/specs/components/Token/Token.spec.md @@ -245,19 +245,19 @@ token's text color. ## Verification map -| Contract | Verification | Representative states | Mutation or failure expectation | Audit section | -| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------- | -| FR2, FR10 | `Token.test.tsx` render, ref, and pass-through suites | Static, clickable, and link roots; caller props; caller naming on a clickable and a disabled link token | A wrong root element, a detached ref, a dropped caller prop, or a clickable token's `aria-labelledby` left on its root fails DOM assertions. Gap: no test covers the ref on the link-and-remove container. | `audit:Token/behavior` | -| FR1, FR7 | `Token.stories.tsx` size, icon, and end-content fixtures in a browser | Sizes, icon and end content | Gap: the size and overflow unit tests assert presence only, and no story renders a long label; slot order and block size are visible only in the rendered fixtures, and the ellipsis has no check. | `audit:Token/layout` | -| FR3, FR4, FR6, AR1 | `Token.test.tsx` link, clickable, and link-with-remove suites; `nestedTouchPress.adopters.test.tsx` Token cases; `nestedControlPress.test.tsx`; `NestedControlPress.a11y.chromium.spec.ts` | Link, clickable, link and remove, modified and middle clicks; a finger, a pen and a mouse press on the Remove button (no token press paint); a mouse press on the token's own button (token press paint) | Nesting the Remove button, firing the token action from Remove, or losing delegation fails. Gap: no test asserts that `onClick` is dropped with `href`, that a pen or mouse press on the Remove button paints no token press, or that a press on a control in end content paints no token press. | `audit:Token/behavior` | -| FR5, AR5 | `Token.test.tsx` disabled tests | Disabled clickable with remove; disabled static; disabled link with and without remove | A native `disabled`, a lost tab stop, a disabled link with a destination, an unreflected disabled state, or a fired callback fails. | `audit:Token/a11y` | -| AR2, AR3, AR7 | `Token.test.tsx` accessibility suite | Remove name, hidden label, description | A missing remove name, lost hidden label, or missing description fails. Gap: no test asserts the link structure's content-derived name. | `audit:Token/a11y` | -| AR6 | `TokenRemoveTarget.a11y.chromium.spec.ts` | Pre-set filter tokens (default size), LTR and RTL | A remove target that misses its X edge or swallows a label press fails in real Chromium. Gap: the `sm` clipping is not covered. | `audit:Token/a11y` | -| FR8 | `Token.test.tsx` custom-color test; `extensibleAxes.test.ts`; `themingTargets.test.ts` | Theme-added color; map wiring | Dropping the `color` reflection fails. Gap: no test asserts `data-size` or any tone's paint; those are visible only in `Token.stories.tsx`. | `audit:Token/theming` | -| FR9, AR4 | `Token.stories.tsx` clickable and link fixtures in a browser | Hover, press, keyboard focus on the token | Gap: no automated check covers overlays or indicators, and no story renders a clickable or link token with Remove, so the double indicator on Remove has no fixture. | `audit:Token/design` | -| PR1 | Source review | Every structure | Gap: no automated check fails if Token adds a per-token listener, observer, or timer. | `audit:Token/behavior` | -| AR2, AR3, AR5, AR7 | Accessibility-tree evidence (`spec:AST-009` FR3) | Every structure; hidden label; description; disabled | Gap: no accessibility-tree check proves the computed names, the hidden-label name, the description, or the disabled state; the unit tests assert DOM attributes only. | `audit:Token/a11y` | -| `design:bidirectionality` DR2 | `MixedDirectionText.a11y.chromium.spec.ts` | `https://`, `.com`, `+3`, `@alice`, `iPhone جديد` and `example.com موقع` under RTL and LTR (Mixed Direction story) | A label whose weak or neutral characters reorder under RTL (`//:https`, `com.`, `3+`, `alice@`), or right-to-left text with a leading Latin word that lays out left to right, fails on each character's rendered position. | `audit:Token/layout` | +| Contract | Verification | Representative states | Mutation or failure expectation | Audit section | +| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------- | +| FR2, FR10 | `Token.test.tsx` render, ref, and pass-through suites | Static, clickable, and link roots; caller props; caller naming on a clickable and a disabled link token | A wrong root element, a detached ref, a dropped caller prop, or a clickable token's `aria-labelledby` left on its root fails DOM assertions. Gap: no test covers the ref on the link-and-remove container. | `audit:Token/behavior` | +| FR1, FR7 | `Token.stories.tsx` size, icon, and end-content fixtures in a browser | Sizes, icon and end content | Gap: the size and overflow unit tests assert presence only, and no story renders a long label; slot order and block size are visible only in the rendered fixtures, and the ellipsis has no check. | `audit:Token/layout` | +| FR3, FR4, FR6, AR1 | `Token.test.tsx` link, clickable, and link-with-remove suites; `nestedTouchPress.adopters.test.tsx` Token cases; `nestedControlPress.test.tsx`; `NestedControlPress.a11y.chromium.spec.ts` | Link, clickable, link and remove, modified and middle clicks; a finger, a pen and a mouse press on the Remove button (no token press paint); a mouse press on the token's own button (token press paint) | Nesting the Remove button, firing the token action from Remove, or losing delegation fails. Gap: no test asserts that `onClick` is dropped with `href`, or that a press on a control in end content paints no token press. | `audit:Token/behavior` | +| FR5, AR5 | `Token.test.tsx` disabled tests | Disabled clickable with remove; disabled static; disabled link with and without remove | A native `disabled`, a lost tab stop, a disabled link with a destination, an unreflected disabled state, or a fired callback fails. | `audit:Token/a11y` | +| AR2, AR3, AR7 | `Token.test.tsx` accessibility suite | Remove name, hidden label, description | A missing remove name, lost hidden label, or missing description fails. Gap: no test asserts the link structure's content-derived name. | `audit:Token/a11y` | +| AR6 | `TokenRemoveTarget.a11y.chromium.spec.ts` | Pre-set filter tokens (default size), LTR and RTL | A remove target that misses its X edge or swallows a label press fails in real Chromium. Gap: the `sm` clipping is not covered. | `audit:Token/a11y` | +| FR8 | `Token.test.tsx` custom-color test; `extensibleAxes.test.ts`; `themingTargets.test.ts` | Theme-added color; map wiring | Dropping the `color` reflection fails. Gap: no test asserts `data-size` or any tone's paint; those are visible only in `Token.stories.tsx`. | `audit:Token/theming` | +| FR9, AR4 | `Token.stories.tsx` clickable and link fixtures in a browser | Hover, press, keyboard focus on the token | Gap: no automated check covers overlays or indicators, and no story renders a clickable or link token with Remove, so the double indicator on Remove has no fixture. | `audit:Token/design` | +| PR1 | Source review | Every structure | Gap: no automated check fails if Token adds a per-token listener, observer, or timer. | `audit:Token/behavior` | +| AR2, AR3, AR5, AR7 | Accessibility-tree evidence (`spec:AST-009` FR3) | Every structure; hidden label; description; disabled | Gap: no accessibility-tree check proves the computed names, the hidden-label name, the description, or the disabled state; the unit tests assert DOM attributes only. | `audit:Token/a11y` | +| `design:bidirectionality` DR2 | `MixedDirectionText.a11y.chromium.spec.ts` | `https://`, `.com`, `+3`, `@alice`, `iPhone جديد` and `example.com موقع` under RTL and LTR (Mixed Direction story) | A label whose weak or neutral characters reorder under RTL (`//:https`, `com.`, `3+`, `alice@`), or right-to-left text with a leading Latin word that lays out left to right, fails on each character's rendered position. | `audit:Token/layout` | ## Decision log 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 `