Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

fix(core): a disabled TopNavItem keeps its tab stop (#9208)

Parinith6a02057ada6d
diff --git a/.changeset/top-nav-item-focusable-disabled.md b/.changeset/top-nav-item-focusable-disabled.md
new file mode 100644
index 0000000000..9ae68540f3
--- /dev/null
+++ b/.changeset/top-nav-item-focusable-disabled.md
@@ -0,0 +1,7 @@
+---
+'@astryxdesign/core': patch
+---
+
+[fix] A disabled `TopNavItem` now keeps its Tab stop, in both the bar and the drawer. Before, it rendered with `tabIndex={-1}`, so Tab skipped it and keyboard and screen-reader users could not reach it. Now it is a focusable `link` that exposes `aria-disabled="true"`, while a click, Enter or Space still runs no `onClick` or `onKeyDown`, does not navigate, and does not close the mobile drawer (`spec:AST-085` FR1, FR2, FR5, `TopNavItem` FR3). No API changes.
+
+@parinith-web
diff --git a/docs/specs/components/TopNav/TopNavItem.spec.md b/docs/specs/components/TopNav/TopNavItem.spec.md
index b1726cfd5a..5bdcae4b9a 100644
--- a/docs/specs/components/TopNav/TopNavItem.spec.md
+++ b/docs/specs/components/TopNav/TopNavItem.spec.md
@@ -39,7 +39,7 @@ system_specs: [spec:AST-085]
| Behavior | A link in the TopNav bar or drawer. Selected marks the current page; disabled drops the destination; in the drawer, activating it closes the drawer. |
| End-user impact | Users see and hear which destination is current; a disabled item cannot navigate by any input; drawer users return to the page after choosing a destination. |
| Builder impact | None. |
-| Compatibility/readiness | Records shipped behavior; no prop, default, target, or export changes. Three implementation gaps (see Current-state impact). |
+| Compatibility/readiness | Records shipped behavior; no prop, default, target, or export changes. Two implementation gaps (see Current-state impact). |
| Review checks | Reject a disabled item that keeps an `href` or fires `onClick`, a selected item without `aria-current="page"`, an icon-only item without an accessible name, or a drawer item that leaves the drawer open after navigating. |
| Governing rules | `component:TopNav` render modes; `spec:AST-085` (disabled items); `architecture:interaction-modality` (shared focus indicator); `architecture:component-theming-surface`. |
@@ -70,10 +70,6 @@ Consumer migration instructions belong in consumer docs and release notes.
- **Color transition under reduced motion.** The bar link's background and text
color still animate when reduced motion is requested; `design:reduced-motion`
DR3 allows no animated property for a fine pointer.
-- **A disabled item leaves the tab order.** A disabled item is an `<a>` without
- `href` carrying `tabIndex=-1`, so keyboard users cannot reach it or learn that
- it is disabled. `spec:AST-085` FR1 has a disabled control keep the tab stop it has
- when enabled.
## Ownership boundary
@@ -102,15 +98,15 @@ Consumer migration instructions belong in consumer docs and release notes.
## Behavioral and layout contract
-| ID | Invariant | Basis |
-| --- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------ |
-| FR1 | An enabled item renders the `as` component, else the `LinkProvider` link component, else `<a>`, with `href` and `target`, the forwarded `ref`, and other DOM props. It shows `icon`, then `children` if given, else `label`. | Current source and tests |
-| FR2 | `isSelected` sets `aria-current="page"` and the selected treatment; the selected fill stays under hover and touch press with no overlay. | Current source and tests |
-| FR3 | `isDisabled` renders a plain `<a>` with no `href` and no `target` and `aria-disabled="true"`, and suppresses clicks, so no input can navigate or fire `onClick`. A disabled item MUST keep the tab stop it has when enabled (`spec:AST-085` FR1). Implementation gap: it is an `<a>` without `href` carrying `tabIndex=-1`, so it is not a tab stop. | Current source and tests |
-| FR4 | `isIconOnly` hides the text and sets `aria-label` to `label`. | Current source and tests |
-| FR5 | In `default` and `mobile-bar` modes the item is a horizontal bar link with `top-nav-item`. In `drawer` mode it is a full-width row sized by `size`, carries `data-mode="drawer"`, and on activation calls `onClick` and then closes the AppShell drawer. | Current source and tests |
-| FR6 | Both renderings paint the shared focus outline on keyboard focus and use the shared press feedback. | Current source |
-| FR7 | `className`, `style`, and `xstyle` merge after component styles. | Current source |
+| ID | Invariant | Basis |
+| --- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------ |
+| FR1 | An enabled item renders the `as` component, else the `LinkProvider` link component, else `<a>`, with `href` and `target`, the forwarded `ref`, and other DOM props. It shows `icon`, then `children` if given, else `label`. | Current source and tests |
+| FR2 | `isSelected` sets `aria-current="page"` and the selected treatment; the selected fill stays under hover and touch press with no overlay. | Current source and tests |
+| FR3 | `isDisabled` renders a plain `<a>` with no `href` and no `target` and `aria-disabled="true"`, and suppresses clicks, so no input can navigate or fire `onClick`. A disabled item MUST keep the tab stop it has when enabled (`spec:AST-085` FR1). | Current source and tests |
+| FR4 | `isIconOnly` hides the text and sets `aria-label` to `label`. | Current source and tests |
+| FR5 | In `default` and `mobile-bar` modes the item is a horizontal bar link with `top-nav-item`. In `drawer` mode it is a full-width row sized by `size`, carries `data-mode="drawer"`, and on activation calls `onClick` and then closes the AppShell drawer. | Current source and tests |
+| FR6 | Both renderings paint the shared focus outline on keyboard focus and use the shared press feedback. | Current source |
+| FR7 | `className`, `style`, and `xstyle` merge after component styles. | Current source |
### Allowed variation
@@ -119,13 +115,13 @@ Consumer migration instructions belong in consumer docs and release notes.
### Representative states
-| State | Required invariant | Allowed variation |
-| --------- | --------------------------------------------------------------------------------- | ----------------- |
-| Rest | Link with label. | Theme styling. |
-| Selected | `aria-current="page"`; selected fill. | Fill color. |
-| Disabled | No `href`, no click; keeps its tab stop. Implementation gap: `tabIndex=-1` (FR3). | Muted styling. |
-| Icon only | `aria-label` from `label`; no visible text. | Icon. |
-| Drawer | Full-width row; activation closes the drawer. | Row size. |
+| State | Required invariant | Allowed variation |
+| --------- | --------------------------------------------- | ----------------- |
+| Rest | Link with label. | Theme styling. |
+| Selected | `aria-current="page"`; selected fill. | Fill color. |
+| Disabled | No `href`, no click; keeps its tab stop. | Muted styling. |
+| Icon only | `aria-label` from `label`; no visible text. | Icon. |
+| Drawer | Full-width row; activation closes the drawer. | Row size. |
### Transformation and precedence order
@@ -141,7 +137,7 @@ Consumer migration instructions belong in consumer docs and release notes.
- **AR1 — Current page.** The selected item exposes `aria-current="page"`.
- **AR2 — Disabled.** A disabled item is exposed as disabled and keeps its tab
- stop (`spec:AST-085` FR1, FR5); see FR3's implementation gap.
+ stop (`spec:AST-085` FR1, FR5).
- **AR3 — Name.** An icon-only item is named by `label`.
## Design relationships
@@ -171,10 +167,6 @@ is recorded.
| FR5 | `TopNav.test.tsx` disabled-navigation tests in both modes | Default and drawer | Lost click forwarding or href handling fails. | `audit:TopNavItem/behavior` |
| RTL relation (FR1) | RTL audit curated D2 target (`apps/storybook/rtl-audit/targets.json`) on `TopNav / Full example` | The `Dashboard` item's leading icon; LTR and RTL | A leading icon that is not at the inline start of its item fails D2. | `audit:TopNavItem/i18n-rtl` |
-Pending conformance: the TopNavItem state test and the two disabled-navigation
-tests assert `tabIndex=-1` on a disabled item, pinning FR3's implementation
-gap; they change when disabled items follow `spec:AST-085`.
-
Read from source, with no focused test yet: the disabled plain `<a>` taking precedence over `as` and `LinkProvider` (ORD1, FR3); other DOM props reaching the link (FR1); the `top-nav-item` target and its `mode` and `selected` states (FR5); the selected fill under hover and press (FR2); the drawer row size, `data-mode="drawer"`, and closing the drawer on activation (FR5); FR6; and FR7.
## Decision log
diff --git a/packages/core/src/TopNav/TopNav.test.tsx b/packages/core/src/TopNav/TopNav.test.tsx
index 7ad35e89c2..b95a6aabf9 100644
--- a/packages/core/src/TopNav/TopNav.test.tsx
+++ b/packages/core/src/TopNav/TopNav.test.tsx
@@ -591,12 +591,14 @@ describe('TopNavItem', () => {
);
});
- it('sets tabIndex to -1 when disabled', () => {
+ it('keeps its tab stop and link role when disabled (spec:AST-085 FR1, FR5)', async () => {
+ const user = userEvent.setup();
render(<TopNavItem label="Home" href="#" isDisabled />);
- expect(screen.getByText('Home').closest('a')).toHaveAttribute(
- 'tabIndex',
- '-1',
- );
+ const item = screen.getByRole('link', {name: 'Home'});
+ expect(item).toHaveAttribute('aria-disabled', 'true');
+ expect(item).toHaveAttribute('tabIndex', '0');
+ await user.tab();
+ expect(item).toHaveFocus();
});
describe('disabled items do not navigate', () => {
@@ -611,14 +613,13 @@ describe('TopNavItem', () => {
isDisabled
/>,
);
- // An href-less anchor exposes no link role, so it is not announced
- // with a live destination.
- expect(screen.queryByRole('link')).not.toBeInTheDocument();
- const item = screen.getByText('Home').closest('a') as HTMLAnchorElement;
+ // The href-less anchor keeps the link role and its tab stop, so it is
+ // found and announced as disabled, with no live destination.
+ const item = screen.getByRole('link', {name: 'Home'});
expect(item).not.toHaveAttribute('href');
expect(item).not.toHaveAttribute('target');
expect(item).toHaveAttribute('aria-disabled', 'true');
- expect(item).toHaveAttribute('tabIndex', '-1');
+ expect(item).toHaveAttribute('tabIndex', '0');
// fireEvent bypasses pointer-events: none, simulating programmatic/AT
// activation. It returns false when preventDefault was called, i.e.
@@ -641,12 +642,11 @@ describe('TopNavItem', () => {
/>
</TopNavRenderContext>,
);
- expect(screen.queryByRole('link')).not.toBeInTheDocument();
- const item = screen.getByText('Home').closest('a') as HTMLAnchorElement;
+ const item = screen.getByRole('link', {name: 'Home'});
expect(item).not.toHaveAttribute('href');
expect(item).not.toHaveAttribute('target');
expect(item).toHaveAttribute('aria-disabled', 'true');
- expect(item).toHaveAttribute('tabIndex', '-1');
+ expect(item).toHaveAttribute('tabIndex', '0');
// fireEvent bypasses pointer-events: none, simulating programmatic/AT
// activation. It returns false when preventDefault was called.
@@ -655,6 +655,40 @@ describe('TopNavItem', () => {
expect(handleClick).not.toHaveBeenCalled();
});
+ it.each([
+ ['default', undefined],
+ ['drawer', 'drawer' as const],
+ ])(
+ 'stays inert from the keyboard once focused (%s mode)',
+ async (_name, mode) => {
+ const user = userEvent.setup();
+ const handleClick = vi.fn();
+ const handleKeyDown = vi.fn();
+ const item = (
+ <TopNavItem
+ label="Home"
+ href="/home"
+ onClick={handleClick}
+ onKeyDown={handleKeyDown}
+ isDisabled
+ />
+ );
+ render(
+ mode ? (
+ <TopNavRenderContext value={mode}>{item}</TopNavRenderContext>
+ ) : (
+ item
+ ),
+ );
+ await user.tab();
+ expect(screen.getByRole('link', {name: 'Home'})).toHaveFocus();
+ await user.keyboard('{Enter}');
+ await user.keyboard(' ');
+ expect(handleClick).not.toHaveBeenCalled();
+ expect(handleKeyDown).not.toHaveBeenCalled();
+ },
+ );
+
it.each([
['default', null],
['drawer', 'drawer' as const],
diff --git a/packages/core/src/TopNav/TopNavItem.tsx b/packages/core/src/TopNav/TopNavItem.tsx
index d2241a01c0..cd2557fdaf 100644
--- a/packages/core/src/TopNav/TopNavItem.tsx
+++ b/packages/core/src/TopNav/TopNavItem.tsx
@@ -38,7 +38,10 @@ import {themeProps} from '../utils/themeProps';
import {focusOutlineProps} from '../utils/focusOutline.stylex';
import {interactionOverlayStyles} from '../utils/interactionOverlay.stylex';
import {usePressFeedback} from '../hooks/usePressFeedback';
-import {withholdCallerHandlers} from '../utils/disabledInteraction';
+import {
+ disabledInteractionProps,
+ withholdCallerHandlers,
+} from '../utils/disabledInteraction';
/**
* NavItem styles with hover/selected states
@@ -123,8 +126,9 @@ export interface TopNavItemProps extends BaseProps<HTMLAnchorElement> {
isSelected?: boolean;
/**
* Whether the nav item is disabled.
- * A disabled item renders as a plain anchor without an href (and without
- * target), so it cannot navigate and is removed from the tab order.
+ * A disabled item renders as an anchor without an href (and without
+ * target), so it cannot navigate; it keeps its Tab stop and is exposed as a
+ * disabled link.
* @default false
*/
isDisabled?: boolean;
@@ -204,13 +208,12 @@ export function TopNavItem({
renderMode === 'drawer',
);
- // A disabled item renders as a plain <a> with no href: an href-less anchor
- // is not focusable and exposes no link affordance, so programmatic focus +
- // Enter, AT activation commands, and middle-click cannot navigate or fire
- // the consumer onClick. The router LinkComponent is deliberately skipped —
- // a disabled item performs no navigation, and custom router links may
- // require a live href. target is omitted with the href. (Mirrors the
- // disabled paths of Link and SideNavItem.)
+ // A disabled item renders as an <a> with no href. Enter, assistive
+ // technology commands and a middle click cannot navigate or run the caller's
+ // onClick. The item keeps its Tab stop and the link role, so keyboard and
+ // screen-reader users still find it. It does not navigate, so it skips the
+ // router LinkComponent, which can require a live href. The target goes with
+ // the href.
const Root = isDisabled ? 'a' : LinkComponent;
// A disabled item runs no caller handler except `onFocus` and `onBlur`, as a
@@ -237,8 +240,9 @@ export function TopNavItem({
target={isDisabled ? undefined : target}
aria-label={isIconOnly ? label : undefined}
aria-current={isSelected ? 'page' : undefined}
+ role={isDisabled ? 'link' : undefined}
aria-disabled={isDisabled || undefined}
- tabIndex={isDisabled ? -1 : undefined}
+ tabIndex={isDisabled ? 0 : undefined}
{...pressable}
{...mergeProps(
themeProps('top-nav-item', {
@@ -257,6 +261,7 @@ export function TopNavItem({
style,
)}
{...callerProps}
+ {...(isDisabled ? disabledInteractionProps() : null)}
onClick={handleDrawerClick}>
{icon}
{!isIconOnly && (children ?? label)}
@@ -276,8 +281,9 @@ export function TopNavItem({
onClick={isDisabled ? preventDefaultClick : onClick}
aria-label={isIconOnly ? label : undefined}
aria-current={isSelected ? 'page' : undefined}
+ role={isDisabled ? 'link' : undefined}
aria-disabled={isDisabled || undefined}
- tabIndex={isDisabled ? -1 : undefined}
+ tabIndex={isDisabled ? 0 : undefined}
{...pressable}
{...mergeProps(
themeProps('top-nav-item', {
@@ -294,7 +300,8 @@ export function TopNavItem({
className,
style,
)}
- {...callerProps}>
+ {...callerProps}
+ {...(isDisabled ? disabledInteractionProps() : null)}>
{icon}
{!isIconOnly && (children ?? label)}
</Root>