An open source design system that's fully customizable and agent ready
TypeScript
fix(SideNavItem): a disabled item keeps its Tab stop (spec:AST-085 FR1) (#9102)
홍규진7958bd2b1774
diff --git a/.changeset/side-nav-item-focusable-disabled.md b/.changeset/side-nav-item-focusable-disabled.mdnew file mode 100644index 0000000000..63c1d7e1a4--- /dev/null+++ b/.changeset/side-nav-item-focusable-disabled.md@@ -0,0 +1,7 @@+---+'@astryxdesign/core': patch+---++[fix] A disabled `SideNavItem` stays focusable. Before, it rendered a `<button>` with the native `disabled` attribute, so Tab skipped it and keyboard and screen-reader users could not reach it, and an item that became disabled while focused dropped focus to the page. Now it exposes `aria-disabled="true"` and keeps its Tab stop, while a click, Enter or Space still runs no `onClick`, does not navigate, and does not close the mobile drawer. In a collapsed rail, a disabled item's label tooltip now opens when Tab focuses it and describes the focusable control rather than its row. This meets the focusable-disabled requirement in spec:AST-085 (FR1, FR2, FR4, FR5). No API changes.++@kyu-rongdiff --git a/packages/core/src/SideNav/SideNav.test.tsx b/packages/core/src/SideNav/SideNav.test.tsxindex cf0b0f5bed..86d2702b07 100644--- a/packages/core/src/SideNav/SideNav.test.tsx+++ b/packages/core/src/SideNav/SideNav.test.tsx@@ -964,10 +964,71 @@ describe('SideNavItem', () => {expect(button).not.toHaveAttribute('aria-current');});- it('disables the button when isDisabled', () => {+ // spec:AST-085 FR1, FR2: a disabled item stays focusable but is inert.+ it('keeps a disabled item focusable and exposes aria-disabled', () => {render(<SideNavItem label="Dashboard" isDisabled />);- const button = screen.getByRole('button');- expect(button).toBeDisabled();+ const button = screen.getByRole('button', {name: 'Dashboard'});+ expect(button).not.toHaveAttribute('disabled');+ expect(button).toHaveAttribute('aria-disabled', 'true');+ button.focus();+ expect(button).toHaveFocus();+ });++ it('does not run onClick on a disabled item from a click, Enter or Space', async () => {+ const user = userEvent.setup();+ const handleClick = vi.fn();+ render(<SideNavItem label="Dashboard" onClick={handleClick} isDisabled />);+ const button = screen.getByRole('button', {name: 'Dashboard'});+ fireEvent.click(button);+ button.focus();+ await user.keyboard('{Enter}');+ await user.keyboard(' ');+ expect(handleClick).not.toHaveBeenCalled();+ });++ it('renders a disabled item with href as a focusable button that does not navigate', () => {+ const handleClick = vi.fn();+ render(+ <SideNavItem+ label="Dashboard"+ href="/dashboard"+ onClick={handleClick}+ isDisabled+ />,+ );+ expect(screen.queryByRole('link')).toBeNull();+ const button = screen.getByRole('button', {name: 'Dashboard'});+ expect(button).not.toHaveAttribute('disabled');+ expect(button).not.toHaveAttribute('href');+ expect(button).toHaveAttribute('aria-disabled', 'true');+ fireEvent.click(button);+ expect(handleClick).not.toHaveBeenCalled();+ });++ it('exposes aria-disabled on the primary of a disabled split row', () => {+ render(+ <SideNavItem label="Settings" href="/settings" collapsible isDisabled>+ <SideNavItem label="General" href="/settings/general" />+ </SideNavItem>,+ );+ const primary = screen.getByRole('button', {name: 'Settings'});+ expect(primary).not.toHaveAttribute('disabled');+ expect(primary).toHaveAttribute('aria-disabled', 'true');+ });++ it('keeps focus on an item that becomes disabled while focused', () => {+ const item = (isDisabled: boolean) => (+ <SideNavItem+ label="Dashboard"+ onClick={() => {}}+ isDisabled={isDisabled}+ />+ );+ const {rerender} = render(item(false));+ const button = screen.getByRole('button', {name: 'Dashboard'});+ button.focus();+ rerender(item(true));+ expect(screen.getByRole('button', {name: 'Dashboard'})).toHaveFocus();});it('calls onClick handler', async () => {@@ -2447,6 +2508,18 @@ describe('SideNavItem — mobile drawer close-on-activate', () => {expect(closeMobileNav).not.toHaveBeenCalled();});+ it('does not close the mobile nav when a disabled item is activated', async () => {+ const user = userEvent.setup();+ const {closeMobileNav} = renderInDrawer(+ <SideNavItem label="Home" href="/" isDisabled data-testid="item" />,+ );+ const item = screen.getByTestId('item');+ fireEvent.click(item);+ item.focus();+ await user.keyboard('{Enter}');+ expect(closeMobileNav).not.toHaveBeenCalled();+ });+it('does not close the mobile nav when a row action is clicked', async () => {const user = userEvent.setup();const onActionClick = vi.fn();@@ -2495,7 +2568,7 @@ describe('SideNav keyboard operation', () => {expect(screen.getByRole('button', {name: 'Settings'})).toHaveFocus();});- it('skips a disabled item in the tab order', async () => {+ it('keeps a disabled item in the tab order', async () => {const user = userEvent.setup();render(<SideNav>@@ -2508,6 +2581,8 @@ describe('SideNav keyboard operation', () => {await user.tab();expect(screen.getByRole('button', {name: 'Dashboard'})).toHaveFocus();await user.tab();+ expect(screen.getByRole('button', {name: 'Archived'})).toHaveFocus();+ await user.tab();expect(screen.getByRole('button', {name: 'Settings'})).toHaveFocus();});@@ -4001,6 +4076,51 @@ describe('SideNavItem collapsed-from-mount rail tooltip', () => {expect(spy.mock.contexts).toContain(layer);});+ it('describes a disabled rail item on the control that takes focus', async () => {+ // spec:AST-085 FR5: the disabled control keeps its tab stop, so the label+ // tooltip has to describe it, not the row around it.+ renderRail(+ <SideNavItem+ label="Analytics (Coming Soon)"+ icon={StubIcon}+ href="/analytics"+ isDisabled+ />,+ );+ await act(async () => {});+ const button = screen.getByRole('button', {+ name: 'Analytics (Coming Soon)',+ });+ expect(button).not.toHaveAttribute('disabled');+ expect(button).toHaveAttribute('aria-disabled', 'true');+ expect(railTooltipFor(button)).toHaveTextContent('Analytics (Coming Soon)');+ expect(button.parentElement).not.toHaveAttribute('aria-describedby');+ });++ it('shows a disabled rail item its label when Tab focuses it', async () => {+ // The row listens for the tooltip, but it is not focusable itself, so it+ // has to hear the focus that bubbles up from the control.+ const user = userEvent.setup();+ const spy = vi.spyOn(HTMLElement.prototype, 'showPopover');+ showPopover = spy;+ renderRail(+ <SideNavItem+ label="Analytics (Coming Soon)"+ icon={StubIcon}+ href="/analytics"+ isDisabled+ />,+ );+ await act(async () => {});+ const button = screen.getByRole('button', {+ name: 'Analytics (Coming Soon)',+ });++ await user.tab();+ expect(button).toHaveFocus();+ expect(spy.mock.contexts).toContain(railTooltipFor(button));+ });+it('describes the link once a disabled item is enabled in the rail', () => {const item = (isDisabled: boolean) => (<SideNavItemdiff --git a/packages/core/src/SideNav/SideNavItem.spec.md b/packages/core/src/SideNav/SideNavItem.spec.mdindex dd925aedc5..8812ce6ce7 100644--- a/packages/core/src/SideNav/SideNavItem.spec.md+++ b/packages/core/src/SideNav/SideNavItem.spec.md@@ -39,7 +39,7 @@ system_specs: [spec:AST-085]| Behavior | One SideNav row: a link or button with optional icon and passive end content, optional row-level actions beside it, and optional nested children that can expand and collapse. In a collapsed rail it is icon-only with a tooltip or a flyout. || End-user impact | Users see and hear the current page, reach row actions before nested items, expand or collapse groups without navigating, and return to the page after choosing a destination in the mobile drawer. || Builder impact | None. |-| Compatibility/readiness | Records shipped behavior; no public change. Four implementation gaps (see Current-state impact). |+| Compatibility/readiness | Records shipped behavior; no public change. Three implementation gaps (see Current-state impact). || Review checks | Reject an interactive control rendered inside the primary element, a link that also toggles collapse, a toggle or action that activates the row, collapsed children that stay reachable, or a drawer activation that leaves the drawer open after navigating. || Governing rules | `component:SideNav` FR1–FR5, DD1 (nesting and row geometry); `family:navigation-destinations`; `architecture:interaction-modality`; `architecture:public-component-api`. |@@ -68,10 +68,6 @@ Consumer migration instructions belong in consumer docs and release notes.## Current-state impact-- **A disabled item leaves the tab order.** A disabled item renders a- `<button>` with the native `disabled` attribute, so it is skipped by Tab and- exposes no focusable disabled state. `spec:AST-085` FR1 has a disabled control- expose `aria-disabled="true"` and keep its tab stop.- **A disabled parent stays operable in a collapsed rail.** In a collapsed rail,a disabled item with children renders its flyout trigger with neither`disabled` nor `aria-disabled`, so it keeps its tab stop and announces no@@ -125,7 +121,7 @@ Consumer migration instructions belong in consumer docs and release notes.| ID | Invariant | Basis || ---- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------ |-| FR1 | The primary element is the `as` component, else the `LinkProvider` link, else `<a>`, when `href` is set and the item is enabled; otherwise a `<button type="button">`. A disabled item MUST stay focusable with `aria-disabled="true"` and keep its tab stop (`spec:AST-085` FR1). Implementation gap: a disabled item renders native `disabled` instead, which removes it from the tab order. It shows the icon (`selectedIcon` when selected and given), the label, `endContent`, and, for a whole-row collapsible item, a chevron. `endContent` is passive and renders inside the primary element. | Current source and tests |+| FR1 | The primary element is the `as` component, else the `LinkProvider` link, else `<a>`, when `href` is set and the item is enabled; otherwise a `<button type="button">`. A disabled item stays focusable with `aria-disabled="true"`, keeps its tab stop, and keeps focus when it becomes disabled (`spec:AST-085` FR1, FR4). It shows the icon (`selectedIcon` when selected and given), the label, `endContent`, and, for a whole-row collapsible item, a chevron. `endContent` is passive and renders inside the primary element. | Current source and tests || FR2 | In an expanded rail and on a collapsed leaf, `isSelected` sets `aria-current="page"` on the primary element, never on a row wrapper. A collapsed parent's flyout trigger carries no `aria-current`. | Current source and tests || FR3 | A disabled item does not fire `onClick` or navigate. Its row actions stay operable. | Current source and tests || FR4 | `actions` render as siblings of the primary element at the row's trailing edge, after the toggle and before nested children in DOM and focus order, at the row's control size (`sm`) unless a control sets its own (`architecture:component-size-cascade`). Clicking an action neither activates nor toggles the row. A row wrapper exists only when there are actions or an independent toggle; a falsy `actions` adds none. | Current source and tests |@@ -146,16 +142,16 @@ Consumer migration instructions belong in consumer docs and release notes.### Representative states-| State | Required invariant | Allowed variation |-| -------------------------- | -------------------------------------------------------------------------------------- | ----------------- |-| Link, selected | `aria-current="page"` on the link; selected icon if given. | Fill. |-| Disabled button | `aria-disabled`; focusable; no `onClick`. Implementation gap: native `disabled` (FR1). | Muted styling. |-| Collapsible without action | Whole row toggles; chevron turns. | — |-| Collapsible with `href` | Link navigates; separate toggle button collapses. | — |-| Actions | Actions after toggle, before children; never activate the row. | Action content. |-| Collapsed rail leaf | Icon-only; tooltip with label. | — |-| Collapsed rail parent | Icon-only trigger; flyout with header and children. | Delay. |-| Mobile drawer | Activation closes the drawer. | — |+| State | Required invariant | Allowed variation |+| -------------------------- | -------------------------------------------------------------- | ----------------- |+| Link, selected | `aria-current="page"` on the link; selected icon if given. | Fill. |+| Disabled button | `aria-disabled`; focusable; no `onClick`. | Muted styling. |+| Collapsible without action | Whole row toggles; chevron turns. | — |+| Collapsible with `href` | Link navigates; separate toggle button collapses. | — |+| Actions | Actions after toggle, before children; never activate the row. | Action content. |+| Collapsed rail leaf | Icon-only; tooltip with label. | — |+| Collapsed rail parent | Icon-only trigger; flyout with header and children. | Delay. |+| Mobile drawer | Activation closes the drawer. | — |### Transformation and precedence order@@ -211,16 +207,10 @@ is recorded. Row geometry visual intent is `component:SideNav` DD1.| FR11 | `SideNav.test.tsx` focus ring suite | Plain, split, actions rows | Missing shared ring classes fail. | `audit:SideNavItem/accessibility` || FR3, FR7, FR9 | `SideNav.test.tsx` keyboard operation and focus management suites | Tab order, Enter/Space toggle, flyout Escape | Lost order, a stranded focus, or no focus return fails. | `audit:SideNavItem/accessibility` |-Pending conformance: the SideNavItem suite's native-`disabled` assertion and-the keyboard suite's disabled Tab-skip assertion pin FR1's implementation gap;-they change when disabled items follow `spec:AST-085`.-Read from source, with no focused test yet:-- FR1 and ORD1–ORD2: a disabled item with `href` rendering a button, the- required focusable `aria-disabled` shape (no item renders it yet), the- button's `type="button"`, the icon, the selected-icon swap, and the whole-row- chevron.+- FR1 and ORD1–ORD2: the button's `type="button"`, the icon, the+ selected-icon swap, and the whole-row chevron.- FR4: the actions' trailing-edge placement and the wrapper for an independenttoggle without actions.- FR5: the forwarded `ref` and `xstyle` on the outer box.diff --git a/packages/core/src/SideNav/SideNavItem.tsx b/packages/core/src/SideNav/SideNavItem.tsxindex 02ee513331..2bbebc6490 100644--- a/packages/core/src/SideNav/SideNavItem.tsx+++ b/packages/core/src/SideNav/SideNavItem.tsx@@ -13,8 +13,8 @@* provided and fall back to `label` when it is missing or blank. Their label* tooltip binds to the interactive control through a callback ref, so hover,* keyboard focus, and `aria-describedby` follow the control from the first- * collapsed render. A disabled control takes neither pointer nor focus, so its- * row is the tooltip's trigger instead.+ * collapsed render. A disabled control takes no pointer, so its row listens+ * for the tooltip instead, while the control keeps focus and the description.** Collapsed items with children open their submenu flyout through* `useMenuHover`, the shared hover-intent hook (same one `SideNavHeading` and@@ -74,6 +74,7 @@ import {import {useSideNavRenderMode} from './SideNavRenderContext';import {useAppShellMobile} from '../AppShell/AppShellMobileContext';import {themeProps} from '../utils/themeProps';+import {disabledInteractionProps} from '../utils/disabledInteraction';import {useTranslator} from '../i18n';import {useMergedRefs} from '../hooks/useMergedRefs';@@ -324,6 +325,8 @@ interface NavItemElementProps {/*** Renders `<a>` (via LinkComponent) when `href` is set, otherwise `<button>`.* Centralizes the link-vs-button decision used across all SideNavItem paths.+ * A disabled item is a `<button>` that keeps its tab stop and exposes+ * `aria-disabled`, but is inert (spec:AST-085 FR1, FR2).*/function NavItemElement({href,@@ -351,8 +354,16 @@ function NavItemElement({ref={ref as React.Ref<HTMLButtonElement>}type="button"onClick={onClick}- disabled={isDisabled}- {...rest}>+ {...rest}+ {...(isDisabled+ ? {+ 'aria-disabled': true,+ ...disabledInteractionProps(+ rest.onKeyDown as+ React.KeyboardEventHandler<HTMLButtonElement> | undefined,+ ),+ }+ : null)}>{children}</button>);@@ -539,6 +550,10 @@ export function SideNavItem({const isRailLeaf = isCollapsed && !hasChildren;const railTooltip = useTooltip({placement: 'end',+ // A disabled leaf's row is the trigger (see the collapsed path). It is not+ // focusable itself, so `auto` would never hear the focus that bubbles up+ // from its control.+ focusTrigger: 'always',isEnabled: isRailLeaf,isOpen: isRailLeaf ? undefined : false,});@@ -702,14 +717,17 @@ export function SideNavItem({// Items without children: icon-only link or button, its label in a// tooltip. The control is the trigger, so the element that takes focus is- // the one described. A disabled control takes neither pointer- // (`navItemStyles.disabled`) nor focus, so its row is the trigger instead.+ // the one described. A disabled control takes no pointer+ // (`navItemStyles.disabled`), so its row listens for the tooltip instead;+ // the control still takes focus (focusin reaches the row) and stays the+ // element described (spec:AST-085 FR5).const isRowTrigger = isDisabled;const collapsedAriaProps = {'aria-current': isSelected ? ('page' as const) : undefined,- 'aria-describedby': isRowTrigger- ? rest['aria-describedby']- : joinIds(rest['aria-describedby'], railTooltip.describedBy),+ 'aria-describedby': joinIds(+ rest['aria-describedby'],+ railTooltip.describedBy,+ ),'aria-disabled': isDisabled || undefined,'aria-label': collapsedAccessibleLabel,'data-testid': testId,@@ -732,7 +750,6 @@ export function SideNavItem({return (<divref={isRowTrigger ? railTooltip.ref : undefined}- aria-describedby={isRowTrigger ? railTooltip.describedBy : undefined}{...stylex.props(styles.root, xstyle)}>{collapsedElement}{railTooltip.renderTooltip(label)}