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.mdnew file mode 100644index 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-webdiff --git a/docs/specs/components/TopNav/TopNavItem.spec.md b/docs/specs/components/TopNav/TopNavItem.spec.mdindex 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 textcolor 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 logdiff --git a/packages/core/src/TopNav/TopNav.test.tsx b/packages/core/src/TopNav/TopNav.test.tsxindex 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.tsxindex 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>