An open source design system that's fully customizable and agent ready
TypeScript
spec(HoverCard, Stack): verification maps name the audit tests and browser evidence (#9582)
Cindy Zhang2227dcbf6f44
diff --git a/docs/specs/components/HoverCard/HoverCard.spec.md b/docs/specs/components/HoverCard/HoverCard.spec.mdindex 7c76b3929d..0a1a183479 100644--- a/docs/specs/components/HoverCard/HoverCard.spec.md+++ b/docs/specs/components/HoverCard/HoverCard.spec.md@@ -17,6 +17,8 @@ verified_by:packages/core/src/Layer/useTouchTrigger.test.ts,packages/core/src/Layer/touchTriggerTargets.test.tsx,apps/storybook/stories/HoverCard.stories.tsx,+ packages/core/src/HoverCard/__tests__/HoverCardAudit.a11y.chromium.spec.ts,+ .github/a11y-audit-axe.json,scripts/check-knowledge.mjs,]modules: []@@ -255,26 +257,27 @@ Consumer migration instructions belong in consumer docs and release notes.## Verification map-| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |-| ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------- |-| FR1, FR2, FR8 | `HoverCard.test.tsx` render, wrapper, portal, theme font, and SSR tests | Text and element triggers; default open | A stray target, lost font, or hydration mismatch fails. | `audit:HoverCard/anatomy` |-| FR3, AR1 | `HoverCard.test.tsx` role and trigger-attribute tests | Labelled and unlabelled; supported and unsupported roles | Wrong role, or trigger attributes that are not replaced and restored as stated, fail. | `audit:HoverCard/accessibility` |-| FR4–FR6, AR2 | `HoverCard.test.tsx` hover, Escape, refocus, and touch tests; `useTouchTrigger.test.ts` and `touchTriggerTargets.test.tsx` disabled-control cases; tap-destination cases an evidence gap until built | Hover, focus, tap, Escape from trigger and content; a trigger inside a link or a clickable card; a disabled control inside a clickable row | A card that cannot be reached or dismissed, or that opens on a tap that already acts, fails. | `audit:HoverCard/behavior` |-| FR7 | `HoverCard.test.tsx` isEnabled, isDefaultOpen, and onOpenChange tests; `layerDismissalFamilies.test.tsx` controlled HoverCard case | Disabled, default open | Wrong state reporting fails. | `audit:HoverCard/behavior` |-| FR9, FR10, AR3 | Evidence gap until built: a press-toggle suite in `HoverCard.test.tsx` and a controlled pinned case in `layerDismissalFamilies.test.tsx` | Click, Enter, Space, and tap pin; second press, press outside, focus leaving, and Escape close; pointer leave and presses on the card keep the pin; labelled and unlabelled; non-button trigger; a toggle trigger inside a ClickableCard, an Item row, and a `<label>` | A press that does not pin or close as stated, a pin lost on pointer leave, a missing or stale `aria-expanded` or `aria-controls`, a second announcement, a non-button trigger without the warning or its tap fallback, or a pinning press that also activates the card, row, or labelled control around the trigger, fails. | `audit:HoverCard/behavior` |-| FR5, FR9 (`triggerBehavior`) | Evidence gap until built: a trigger-behavior suite in `HoverCard.test.tsx` | `adaptive` by default and explicitly, `hover`, and `toggle`, each with mouse hover, focus, and touch; `touchTrigger` beside each value | Under any value, a lost hover or focus preview; under `adaptive`, an info-only tap that leaves the card shut or a press that pins it; under `hover`, a tap that opens it or a press that pins it; under `toggle`, a click, tap, Enter, or Space that does not pin or close it as FR9 states; or a `touchTrigger` that changes `hover` or `toggle`, fails. | `audit:HoverCard/behavior` |-| FR11 | `HoverCard.test.tsx` surface-press suite | A card inside a clickable container and inside a `<label>`; a button inside the card | A click on card content that runs the container's click handler or activates a labelled control, or a card button that stops working, fails. | — |-| Theming anatomy map | `scripts/check-knowledge.mjs` | Consumer anatomy and current target | Missing, extra, or stale mappings fail validation. | `audit:HoverCard/theming` |+| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |+| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------- |+| FR1, FR2, FR8 | `HoverCard.test.tsx` render, wrapper, portal, theme font, SSR, and card `xstyle`/`className`/`style` tests; `HoverCardAudit` Chromium frames of `HoverCard / Open States` for the single target, equal padding on every logical edge, and the text trigger's dashed hover cue | Text and element triggers; default open | A stray target, lost font, or hydration mismatch fails, and so do card `xstyle`, `className`, or `style` that do not reach the card, missing or unequal card padding, or a lost dashed cue on a text trigger. | `audit:HoverCard/anatomy` |+| FR3, AR1 | `HoverCard.test.tsx` role, trigger-attribute, and attribute-restore tests; `HoverCardAudit` frames and the audit axe pass on `HoverCard / Open States` | Labelled and unlabelled; supported and unsupported roles | Wrong role, trigger attributes that are not replaced and restored as stated, or a new axe violation on an open card, fail. | `audit:HoverCard/accessibility` |+| FR4–FR6, AR2 | `HoverCard.test.tsx` hover, delay and hide-delay timing, trigger-to-card hold, Escape, refocus, and touch tests; `HoverCardAudit` hover-and-keyboard pass in Chromium; `useTouchTrigger.test.ts` and `touchTriggerTargets.test.tsx` disabled-control cases; tap-destination cases an evidence gap until built | Hover, focus, tap, Escape from trigger and content; a trigger inside a link or a clickable card; a disabled control inside a clickable row | A card that cannot be reached or dismissed, that opens before `delay` or closes before `hideDelay`, that closes while the pointer moves from the trigger into it, or that opens on a tap that already acts, fails. | `audit:HoverCard/behavior` |+| FR7 | `HoverCard.test.tsx` isEnabled, isDefaultOpen, onOpenChange, `isOpen` forcing, and controlled-close focus-return tests; `layerDismissalFamilies.test.tsx` controlled HoverCard case | Disabled, default open, held open, held closed, closed by the caller with focus inside | Wrong state reporting, a hover that hides a card held open or opens one held closed, or focus left inside a card the caller closes, fails. | `audit:HoverCard/behavior` |+| FR9, FR10, AR3 | Evidence gap until built: a press-toggle suite in `HoverCard.test.tsx` and a controlled pinned case in `layerDismissalFamilies.test.tsx` | Click, Enter, Space, and tap pin; second press, press outside, focus leaving, and Escape close; pointer leave and presses on the card keep the pin; labelled and unlabelled; non-button trigger; a toggle trigger inside a ClickableCard, an Item row, and a `<label>` | A press that does not pin or close as stated, a pin lost on pointer leave, a missing or stale `aria-expanded` or `aria-controls`, a second announcement, a non-button trigger without the warning or its tap fallback, or a pinning press that also activates the card, row, or labelled control around the trigger, fails. | `audit:HoverCard/behavior` |+| FR5, FR9 (`triggerBehavior`) | Evidence gap until built: a trigger-behavior suite in `HoverCard.test.tsx` | `adaptive` by default and explicitly, `hover`, and `toggle`, each with mouse hover, focus, and touch; `touchTrigger` beside each value | Under any value, a lost hover or focus preview; under `adaptive`, an info-only tap that leaves the card shut or a press that pins it; under `hover`, a tap that opens it or a press that pins it; under `toggle`, a click, tap, Enter, or Space that does not pin or close it as FR9 states; or a `touchTrigger` that changes `hover` or `toggle`, fails. | `audit:HoverCard/behavior` |+| FR11 | `HoverCard.test.tsx` surface-press suite | A card inside a clickable container and inside a `<label>`; a button inside the card | A click on card content that runs the container's click handler or activates a labelled control, or a card button that stops working, fails. | — |+| Theming anatomy map | `scripts/check-knowledge.mjs` | Consumer anatomy and current target | Missing, extra, or stale mappings fail validation. | `audit:HoverCard/theming` |Read from source, with no focused test yet:-- FR1: the card's padding, and `xstyle`, `className`, and `style` reaching it.- FR3: restoring the trigger's own attributes on unmount.-- FR4: the `delay` and `hideDelay` timing, and moving between the trigger and- the card keeping it open.-- FR7: `isOpen` forcing the card, and the focus return after a controlled- close.-- FR8: `hasHoverIndication`.+- FR7: `isOpen={true}` keeping the card open when focus leaves the trigger.+- FR8: `hasHoverIndication={true}` and `{false}`.++Checked only in a browser, with no unit test:++- FR1: the card's padding.+- FR8: the default `hasHoverIndication` cue on a text trigger.## Decision logdiff --git a/docs/specs/components/Stack/Stack.spec.md b/docs/specs/components/Stack/Stack.spec.mdindex 29e3ff0ffe..e3667534d6 100644--- a/docs/specs/components/Stack/Stack.spec.md+++ b/docs/specs/components/Stack/Stack.spec.md@@ -20,6 +20,8 @@ verified_by:packages/core/src/VStack/VStack.test.tsx,packages/core/src/theme/themingTargets.test.ts,apps/storybook/stories/Stack.stories.tsx,+ apps/storybook/stories/HStack.stories.tsx,+ packages/core/src/HStack/__tests__/HStackAudit.a11y.chromium.spec.ts,scripts/check-knowledge.mjs,apps/storybook/rtl-audit/targets.json,]@@ -179,17 +181,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 | `Stack.test.tsx`, `HStack.test.tsx`, `VStack.test.tsx` element tests; stable visual baseline `core-stack--default` | Default and `as` elements; default stack | A wrong default or `as` element fails; a changed default direction, gap, or alignment comes back changed for review. Gap: the direction, alignment, and alias tests assert only that content renders, so direction, `hAlign`/`vAlign` mapping, alias precedence, the `stack` target, and its reflection have no unit check. | `audit:Stack/layout` |-| FR3 | `Stack.test.tsx` padding-precedence tests; `@astryx/no-physical-properties` lint rule | Uniform, axis, edge, all four edges | A missing padding class, edge over axis on the end edges, edge over uniform on the edges the tests pair, or a physical left/right padding property fails. Gap: edge over axis on the start edges, axis over uniform, any untested edge-over-uniform pairing, and the gap value (the gap test asserts only that content renders) have no check, and no browser right-to-left check covers the edges. | `audit:Stack/layout` |-| FR5 | `Stack.test.tsx` sizing and scrolling tests | Numeric and string sizes; scrollable | A wrong computed width or height, or no class change for `isScrollable`, fails. Gap: `wrap`, `maxWidth`, `minHeight`, and size winning over caller `style` have no check. | `audit:Stack/layout` |-| FR6 | `StackItem.test.tsx` element, scroll, and passthrough tests | Default and `as` elements; scrollable; `size="fill"` with scroll | A wrong element, or no class change for `isScrollable`, fails. Gap: the size and `crossAlignSelf` tests assert only that content renders, so the minimum-size reset, `static`, `fill`, cross alignment, and the `stack-item` target have no check. | `audit:Stack/layout` |-| FR7 | Ref and pass-through tests in all four suites | Default and `as` elements | A dropped ref fails in all four suites, and a dropped `aria-label` in the Stack and StackItem suites (the HStack and VStack pass-through tests assert `data-testid` only). Gap: the ref tests accept any element, so a ref on a wrapper passes, and the styling-input merge order has no check. | `audit:Stack/behavior` |-| FR4 | Source review against `architecture:container-padding` | Padded stack | Gap: no automated check fails if Stack publishes container-padding variables. | `audit:Stack/layout` |-| Theming anatomy map | `scripts/check-knowledge.mjs` | Consumer anatomy and current targets | Missing, extra, or stale mappings fail repository validation. | `audit:Stack/theming` |-| AR1, PR1 | `serverSafeComponents.test.ts`; source review | Every form | A client API (state, an effect, a context read) added without a client directive fails `serverSafeComponents.test.ts`. Gap: a client API added together with a client directive passes, and no automated check fails if Stack or StackItem adds a role. | `audit:Stack/behavior` |-| RTL relation | RTL audit curated targets (`apps/storybook/rtl-audit/targets.json`): Stack and StackItem D2 on `Stack / Horizontal` and `Stack / StackItem fill size`, HStack D2 on `AspectRatio / Height driven`, VStack D4 on `Spinner / Narrow flex host` | Horizontal stacks, static and fill items, and a start-aligned vertical stack; LTR and RTL | A horizontal stack whose first child is not at the inline start, or a start-aligned vertical stack child that does not move to the mirrored side, fails D2 or D4. | `audit:Stack/i18n-rtl` |+| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |+| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------- |+| FR1, FR2 | `Stack.test.tsx`, `HStack.test.tsx`, `VStack.test.tsx` element tests; `HStack.test.tsx` target, reflection, axis, alias, and precedence tests; `HStackAudit` Chromium frames of `HStack / Alignment Matrix`; stable visual baseline `core-stack--default` | Default and `as` elements; default stack | A wrong default or `as` element fails; a changed default direction, gap, or alignment comes back changed for review. `HStack.test.tsx` fails if HStack loses its horizontal direction, the `stack` target, or its reflection, sends an alignment prop or alias to the wrong Stack prop, or loses alias precedence; the `HStackAudit` frames fail if the resulting horizontal geometry is wrong, mirrored in right-to-left. Gap: the Stack and VStack direction, alignment, and alias tests assert only that content renders, so the vertical `data-direction` reflection and Stack's own axis mapping have no unit check. | `audit:Stack/layout` |+| FR3 | `Stack.test.tsx` padding-precedence tests; `@astryx/no-physical-properties` lint rule | Uniform, axis, edge, all four edges | A missing padding class, edge over axis on the end edges, edge over uniform on the edges the tests pair, or a physical left/right padding property fails. Gap: edge over axis on the start edges, axis over uniform, any untested edge-over-uniform pairing, and the gap value (the gap test asserts only that content renders) have no check, and no browser right-to-left check covers the edges. | `audit:Stack/layout` |+| FR5 | `Stack.test.tsx` sizing and scrolling tests; `HStack.test.tsx` merge test; `HStackAudit` wrap frames | Numeric and string sizes; scrollable | A wrong computed width or height, or no class change for `isScrollable`, fails. `HStack.test.tsx` fails if `width` does not win over caller `style`, and the `HStackAudit` frames fail if `wrap` does not break a row. Gap: `height`, `maxWidth`, and `minHeight` winning over caller `style`, `maxWidth` and `minHeight` themselves, and `wrap` on Stack and VStack have no check. | `audit:Stack/layout` |+| FR6 | `StackItem.test.tsx` element, scroll, and passthrough tests | Default and `as` elements; scrollable; `size="fill"` with scroll | A wrong element, or no class change for `isScrollable`, fails. Gap: the size and `crossAlignSelf` tests assert only that content renders, so the minimum-size reset, `static`, `fill`, cross alignment, and the `stack-item` target have no check. | `audit:Stack/layout` |+| FR7 | Ref and pass-through tests in all four suites; `HStack.test.tsx` exact-ref and merge tests | Default and `as` elements | A dropped ref fails in all four suites, and a dropped `aria-label` in the Stack, HStack, and StackItem suites (the VStack pass-through test asserts `data-testid` only). `HStack.test.tsx` fails if the ref reaches any element but the rendered one, or if `className` and `style` do not merge. Gap: the Stack, VStack, and StackItem ref tests accept any element, so a ref on a wrapper passes there, and the `xstyle`, `className`, `style` order has no check. | `audit:Stack/behavior` |+| FR4 | Source review against `architecture:container-padding` | Padded stack | Gap: no automated check fails if Stack publishes container-padding variables. | `audit:Stack/layout` |+| Theming anatomy map | `scripts/check-knowledge.mjs` | Consumer anatomy and current targets | Missing, extra, or stale mappings fail repository validation. | `audit:Stack/theming` |+| AR1, PR1 | `serverSafeComponents.test.ts`; `HStack.test.tsx` no-role test; `HStackAudit` frames; source review | Every form | A client API (state, an effect, a context read) added without a client directive fails `serverSafeComponents.test.ts`. `HStack.test.tsx` and the `HStackAudit` frames fail if Stack adds a role or tab stop on its horizontal path. Gap: a client API added together with a client directive passes, and no automated check fails if Stack adds a role or tab stop on its vertical path, or StackItem adds either. | `audit:Stack/behavior` |+| RTL relation | RTL audit curated targets (`apps/storybook/rtl-audit/targets.json`): Stack and StackItem D2 on `Stack / Horizontal` and `Stack / StackItem fill size`, HStack D2 on `AspectRatio / Height driven` and `HStack / Alignment Matrix`, VStack D4 on `Spinner / Narrow flex host` | Horizontal stacks, static and fill items, and a start-aligned vertical stack; LTR and RTL | A horizontal stack whose first child is not at the inline start, or a start-aligned vertical stack child that does not move to the mirrored side, fails D2 or D4. | `audit:Stack/i18n-rtl` |## Decision log