An open source design system that's fully customizable and agent ready
TypeScript
spec(SideNavHeading, TopNavHeading): record the heading in the menu button name (backfill) (#9385)
Cindy Zhangb8ee12e34713
diff --git a/docs/specs/components/SideNav/SideNavHeading.spec.md b/docs/specs/components/SideNav/SideNavHeading.spec.mdindex f2ff635ba0..17b7ce1431 100644--- a/docs/specs/components/SideNav/SideNavHeading.spec.md+++ b/docs/specs/components/SideNav/SideNavHeading.spec.md@@ -107,7 +107,8 @@ Consumer migration instructions belong in consumer docs and release notes.**Owns**-- The identity block and its link and trigger configurations (FR1–FR4).+- The identity block and its link and trigger configurations (FR1–FR4,+ FR11).- The product menu popover (FR5–FR7).- The collapsed-rail form (FR8) and the focus outline (FR9).@@ -138,6 +139,7 @@ Consumer migration instructions belong in consumer docs and release notes.| FR8 | In a collapsed rail, without `icon` it renders nothing. With `icon`: `headingHref` makes an icon-only link named by `heading`; else `menu` makes an icon-only button named by `heading` that is the native invoker of its menu popover; else the icon renders alone. Each form shows a tooltip with `heading` at the inline end; `headerEndContent` and the chevron are hidden. | Current source and tests || FR9 | Every focusable part paints the shared focus outline. | Current source and tests || FR10 | In the product menu's `role="menu"` region, a press (finger, pen or mouse) that lands on an enabled item and slides across the items acts on the one it lifts on, once, through that item's own activation, with the highlight following the pointer; a lift outside acts on nothing, and a mouse released outside closes the menu. The menu adopts `module:DropdownMenu/useMenuPress` for this (`family:action-groups` FR1–FR5; `module:DropdownMenu/useMenuPress` DEC-7). A press on caller content that is not an item, and a Ctrl-, Cmd- or Shift-click or a middle click on a link item, stays that content's or the browser's own, and keyboard and assistive-technology behavior is unchanged. | Current source and tests |+| FR11 | In both menu configurations, the chevron button's accessible name contains the visible `heading`, so a person who identifies the control by the product or workspace name they see hears that name (`family:buttons` FR1; WCAG 2.2 Label in Name). The name is one translated message, `@astryx.sideNav.heading.openMenu`, that takes `heading`: "Acme, Open menu" in English for the heading "Acme". Every shipped locale's message carries `{heading}` unchanged. | Current source and tests |### Allowed variation@@ -191,15 +193,16 @@ map is recorded.## Verification map-| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |-| ------------ | ---------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------ |-| FR1–FR4, AR1 | `SideNav.test.tsx` SideNavHeading and headerEndContent suites | Each configuration | Wrong element, unnamed link, or misplaced end content fails. | `audit:SideNavHeading/behavior` |-| FR5 | `SideNav.test.tsx` SideNavHeading hover/click guard suite | Hover, click, late click, Escape | Lost guard or focus return fails. | `audit:SideNavHeading/behavior` |-| FR6, AR2 | `SideNav.test.tsx` menu popover semantics suite | Whole trigger; mixed; collapsed | A dialog wrapper or misplaced menu role fails. | `audit:SideNavHeading/accessibility` |-| FR8 | `SideNav.test.tsx` SideNavHeading collapsed suite | Link, menu, plain, no icon | Missing name, tooltip, or invoker fails. | `audit:SideNavHeading/behavior` |-| FR9 | `SideNav.test.tsx` focus ring suite | Whole-heading link, collapsed link, menu trigger | A missing shared ring class fails. | `audit:SideNavHeading/accessibility` |-| FR10 | `SideNav.test.tsx` SideNavHeading menu-popover suite (touch and mouse slides) | Touch and mouse slides across items; a caller button and link; a release outside | Removing the adoption fails the slide tests. | — |-| RTL relation | RTL audit curated D2 and D8 targets (`apps/storybook/rtl-audit/targets.json`) on `SideNav / Default` | Heading icon and title, with 0px start and 8px end padding; LTR and RTL | An icon that is not at the inline start of the title, or an end padding that stays on the same physical side in RTL, fails D2 or D8. | `audit:SideNavHeading/i18n-rtl` |+| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |+| ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------ |+| FR1–FR4, AR1 | `SideNav.test.tsx` SideNavHeading and headerEndContent suites | Each configuration | Wrong element, unnamed link, or misplaced end content fails. | `audit:SideNavHeading/behavior` |+| FR5 | `SideNav.test.tsx` SideNavHeading hover/click guard suite | Hover, click, late click, Escape | Lost guard or focus return fails. | `audit:SideNavHeading/behavior` |+| FR6, AR2 | `SideNav.test.tsx` menu popover semantics suite | Whole trigger; mixed; collapsed | A dialog wrapper or misplaced menu role fails. | `audit:SideNavHeading/accessibility` |+| FR8 | `SideNav.test.tsx` SideNavHeading collapsed suite | Link, menu, plain, no icon | Missing name, tooltip, or invoker fails. | `audit:SideNavHeading/behavior` |+| FR9 | `SideNav.test.tsx` focus ring suite | Whole-heading link, collapsed link, menu trigger | A missing shared ring class fails. | `audit:SideNavHeading/accessibility` |+| FR10 | `SideNav.test.tsx` SideNavHeading menu-popover suite (touch and mouse slides) | Touch and mouse slides across items; a caller button and link; a release outside | Removing the adoption fails the slide tests. | — |+| FR11 | `SideNav.test.tsx` SideNavHeading cases "includes the visible heading in the menu trigger name without hrefs", "includes the heading in the translated menu trigger name" (Korean catalog), and "renders chevron as separate trigger when menu and hrefs are provided" | Whole trigger; links plus trigger; a translated locale | A name without the heading, or a translated name that drops it, fails. | `audit:SideNavHeading/accessibility` |+| RTL relation | RTL audit curated D2 and D8 targets (`apps/storybook/rtl-audit/targets.json`) on `SideNav / Default` | Heading icon and title, with 0px start and 8px end padding; LTR and RTL | An icon that is not at the inline start of the title, or an end padding that stays on the same physical side in RTL, fails D2 or D8. | `audit:SideNavHeading/i18n-rtl` |Read from source, with no focused test yet:diff --git a/docs/specs/components/TopNav/TopNavHeading.spec.md b/docs/specs/components/TopNav/TopNavHeading.spec.mdindex 94ee3921fd..957b152309 100644--- a/docs/specs/components/TopNav/TopNavHeading.spec.md+++ b/docs/specs/components/TopNav/TopNavHeading.spec.md@@ -98,7 +98,8 @@ Consumer migration instructions belong in consumer docs and release notes.**Owns**-- The identity block layout and its link and trigger configurations (FR1–FR6).+- The identity block layout and its link and trigger configurations (FR1–FR6,+ FR11).- The product menu popover and its close behavior (FR7–FR9).**Does not own / non-goals**@@ -132,6 +133,7 @@ Consumer migration instructions belong in consumer docs and release notes.| FR8 | Escape closes the menu and returns focus to the trigger. | Current source and tests || FR9 | Descendants of `menu` receive a close action, which NavHeadingMenu items call on selection. | Current source || FR10 | In the product menu's `role="menu"` region, a press (finger, pen or mouse) that lands on an enabled item and slides across the items acts on the one it lifts on, once, through that item's own activation, with the highlight following the pointer; a lift outside acts on nothing, and a mouse released outside closes the menu. The menu adopts `module:DropdownMenu/useMenuPress` for this (`family:action-groups` FR1–FR5; `module:DropdownMenu/useMenuPress` DEC-7). A press on caller content that is not an item, and a Ctrl-, Cmd- or Shift-click or a middle click on a link item, stays that content's or the browser's own, and keyboard and assistive-technology behavior is unchanged. | Current source and tests |+| FR11 | In both menu configurations, the chevron button's accessible name contains the visible `heading` when one is set, so a person who identifies the control by the product or workspace name they see hears that name (`family:buttons` FR1; WCAG 2.2 Label in Name). The name is one translated message, `@astryx.topNav.heading.openMenu`: "Acme, Open menu" in English for the heading "Acme". With no `heading`, or an empty one, it is the translated generic action, "Open menu", with no separator. Every shipped locale's message carries `{heading}` unchanged. | Current source and tests |### Allowed variation@@ -189,13 +191,14 @@ is recorded.## Verification map-| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |-| ----------------- | ------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------- |-| FR1–FR3, AR1 | `TopNav.test.tsx` TopNavHeading render and logo-name tests | Each configuration | A wrong element or unnamed logo link fails. | `audit:TopNavHeading/behavior` |-| FR4, FR7, AR2–AR3 | `TopNav.test.tsx` menu popover semantics tests | Whole trigger; links plus trigger | A modal wrapper or misplaced menu role fails. | `audit:TopNavHeading/accessibility` |-| FR5, FR8 | `TopNav.test.tsx` hover/click guard tests | Hover-open, click, late click, Escape | Losing the guard or focus return fails. | `audit:TopNavHeading/behavior` |-| FR10 | `TopNav.test.tsx` TopNavHeading menu-popover suite (touch and mouse slides) | Touch and mouse slides across items | Removing the adoption fails the slide tests. | — |-| RTL relation | RTL audit curated D2 and D8 target (`apps/storybook/rtl-audit/targets.json`) on `TopNav / Full example` | Heading logo and title, with 0px start and 8px end padding; LTR and RTL | A logo that is not at the inline start of the title, or an end padding that stays on the same physical side in RTL, fails D2 or D8. | `audit:TopNavHeading/i18n-rtl` |+| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |+| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------- |+| FR1–FR3, AR1 | `TopNav.test.tsx` TopNavHeading render and logo-name tests | Each configuration | A wrong element or unnamed logo link fails. | `audit:TopNavHeading/behavior` |+| FR4, FR7, AR2–AR3 | `TopNav.test.tsx` menu popover semantics tests | Whole trigger; links plus trigger | A modal wrapper or misplaced menu role fails. | `audit:TopNavHeading/accessibility` |+| FR5, FR8 | `TopNav.test.tsx` hover/click guard tests | Hover-open, click, late click, Escape | Losing the guard or focus return fails. | `audit:TopNavHeading/behavior` |+| FR10 | `TopNav.test.tsx` TopNavHeading menu-popover suite (touch and mouse slides) | Touch and mouse slides across items | Removing the adoption fails the slide tests. | — |+| FR11 | `TopNav.test.tsx` TopNavHeading cases "includes the visible heading in the menu trigger name without hrefs", "includes the heading in the translated menu trigger name with independent links", and "keeps the translated generic menu trigger name when the optional heading is absent or empty" (Korean catalog) | Whole trigger; links plus trigger; no heading; empty heading | A name without the heading, a translated name that drops it, or a dangling separator without a heading fails. | `audit:TopNavHeading/accessibility` |+| RTL relation | RTL audit curated D2 and D8 target (`apps/storybook/rtl-audit/targets.json`) on `TopNav / Full example` | Heading logo and title, with 0px start and 8px end padding; LTR and RTL | A logo that is not at the inline start of the title, or an end padding that stays on the same physical side in RTL, fails D2 or D8. | `audit:TopNavHeading/i18n-rtl` |Read from source, with no focused test yet: that clicking the block itself opens the menu in the menu-without-hrefs configuration (FR2); the `dialogLabel` fallback name of the menu (FR7); that the rest of the block opens the menu in the links-plus-trigger configuration (FR2); the `top-nav-heading` target (FR1); line truncation, part order, and `headerEndContent` (FR1); `as` and `LinkProvider` rendering (FR3); the chevron button's size (FR4); FR6; the popover's placement (FR7); and FR9.