Skip to content

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.md
new file mode 100644
index 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-rong
diff --git a/packages/core/src/SideNav/SideNav.test.tsx b/packages/core/src/SideNav/SideNav.test.tsx
index 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) => (
<SideNavItem
diff --git a/packages/core/src/SideNav/SideNavItem.spec.md b/packages/core/src/SideNav/SideNavItem.spec.md
index 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 independent
toggle 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.tsx
index 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 (
<div
ref={isRowTrigger ? railTooltip.ref : undefined}
- aria-describedby={isRowTrigger ? railTooltip.describedBy : undefined}
{...stylex.props(styles.root, xstyle)}>
{collapsedElement}
{railTooltip.renderTooltip(label)}