An open source design system that's fully customizable and agent ready
TypeScript
fix(core): disabled links, tokens and cards stay focusable (#7842)
Cindy Zhang29ead988571c
diff --git a/.changeset/nav-items-focusable-disabled.md b/.changeset/nav-items-focusable-disabled.mdnew file mode 100644index 0000000000..cfecb860bb--- /dev/null+++ b/.changeset/nav-items-focusable-disabled.md@@ -0,0 +1,7 @@+---+'@astryxdesign/core': patch+---++[fix] Disabled Link and ClickableCard, and the buttons of a disabled Token, stay focusable. Before, they rendered the native `disabled` attribute or `tabIndex={-1}`, so keyboard and screen-reader users could not reach them. Now each disabled control exposes `aria-disabled="true"` and keeps the Tab stop it has when enabled, while activation by click, Enter or Space, `onClick`, removal and navigation stay blocked; a disabled Link keeps no live destination and is exposed with the link role. A `Popover` no longer opens from a wrapped or `anchorRef` trigger marked `aria-disabled="true"` (for example a disabled `Button` with a `tooltip`), including for a click dispatched straight on the trigger; before, such a click opened it. This meets the focusable-disabled requirement in spec:AST-085 (FR1, FR2, FR5). No API changes.++@cixzhangdiff --git a/apps/storybook/stories/ClickableCard.stories.tsx b/apps/storybook/stories/ClickableCard.stories.tsxindex 1cb13719db..b5cf6ae4c5 100644--- a/apps/storybook/stories/ClickableCard.stories.tsx+++ b/apps/storybook/stories/ClickableCard.stories.tsx@@ -154,7 +154,7 @@ export const Disabled: Story = {docs: {description: {story:- '`isDisabled` suppresses click, hover, and focus, removes any live link destination, sets `aria-disabled`, and leaves the card out of the tab order.',+ '`isDisabled` suppresses click and hover, removes any live link destination, sets `aria-disabled`, and keeps the card in the tab order so it is announced as disabled.',},},},diff --git a/apps/storybook/stories/Link.stories.tsx b/apps/storybook/stories/Link.stories.tsxindex 4e301ab5cd..506f9c387d 100644--- a/apps/storybook/stories/Link.stories.tsx+++ b/apps/storybook/stories/Link.stories.tsx@@ -250,7 +250,7 @@ export const ButtonFallbackDisabled: Story = {docs: {description: {story:- 'The button fallback supports the `isDisabled` prop with native `disabled` attribute.',+ 'The button fallback supports the `isDisabled` prop: it stays focusable with `aria-disabled` and ignores clicks, Enter and Space.',},},},diff --git a/packages/core/src/ClickableCard/ClickableCard.doc.mjs b/packages/core/src/ClickableCard/ClickableCard.doc.mjsindex 7417c34169..9a164ebee9 100644--- a/packages/core/src/ClickableCard/ClickableCard.doc.mjs+++ b/packages/core/src/ClickableCard/ClickableCard.doc.mjs@@ -24,7 +24,7 @@ export const docs = {{name: 'onClick', type: '(event: MouseEvent) => void', description: 'Click handler: fires on card surface only.'},{name: 'href', type: 'string', description: 'Navigation URL. Plain, new-tab, Cmd/Ctrl-click, and middle-click activation all follow the shared navigation rule described on the Link `href` prop.'},{name: 'target', type: 'string', description: 'Link target.', default: "'_self'"},- {name: 'isDisabled', type: 'boolean', description: 'Disables the card, removes a link destination, and leaves the card out of the tab order.', default: 'false'},+ {name: 'isDisabled', type: 'boolean', description: 'Disables the card and removes a link destination; the card keeps its tab stop and is announced as disabled.', default: 'false'},{name: 'children', type: 'ReactNode', description: 'Card content.'},{name: 'padding', type: '0 | 0.5 | 1 | 1.5 | 2 | 3 | 4 | 5 | 6 | 8 | 10', description: 'Inner padding.', default: '4'},{name: 'variant', type: "'default' | 'transparent' | 'muted' | 'blue' | 'cyan' | 'gray' | 'green' | 'orange' | 'pink' | 'purple' | 'red' | 'teal' | 'yellow'", description: 'Background color variant.', default: "'default'"},@@ -75,7 +75,7 @@ export const docsDense = {onClick: 'click handler: fires on card surface only',href: 'navigation URL; every activation follows the shared navigation rule (see Link href)',target: 'link target',- isDisabled: 'disables card, removes link destination, and leaves tab order',+ isDisabled: 'disables card, removes link destination, keeps tab stop',padding: 'inner padding',variant: 'background color variant',elevation: 'resting shadow depth: none|low|med|high; often raised to signal clickability',diff --git a/packages/core/src/ClickableCard/ClickableCard.test.tsx b/packages/core/src/ClickableCard/ClickableCard.test.tsxindex e71db24338..ffa4877812 100644--- a/packages/core/src/ClickableCard/ClickableCard.test.tsx+++ b/packages/core/src/ClickableCard/ClickableCard.test.tsx@@ -129,7 +129,7 @@ describe('ClickableCard', () => {expect(link).toHaveAttribute('target', '_blank');});- it('disabled button is disabled and the surface runs nothing', () => {+ it('disabled button stays focusable and the surface runs nothing', () => {const handleClick = vi.fn();render(<ClickableCard label="Disabled" onClick={handleClick} isDisabled>@@ -137,13 +137,14 @@ describe('ClickableCard', () => {</ClickableCard>,);const button = screen.getByRole('button', {name: 'Disabled'});- expect(button).toBeDisabled();+ expect(button).not.toHaveAttribute('disabled');+ expect(button).toHaveAttribute('aria-disabled', 'true');fireEvent.click(screen.getByText('Content'));fireEvent.click(button);expect(handleClick).not.toHaveBeenCalled();});- it('disabled link has no live destination, leaves the tab order, and runs nothing', () => {+ it('disabled link has no live destination, keeps its tab stop, and runs nothing', () => {const handleClick = vi.fn();render(<ClickableCard@@ -157,7 +158,7 @@ describe('ClickableCard', () => {);const link = screen.getByRole('link', {name: 'Disabled link'});expect(link).toHaveAttribute('aria-disabled', 'true');- expect(link).toHaveAttribute('tabindex', '-1');+ expect(link).toHaveAttribute('tabindex', '0');expect(link).not.toHaveAttribute('href');expect(link).not.toHaveAttribute('target');expect(fireEvent.click(link)).toBe(false);diff --git a/packages/core/src/ClickableCard/ClickableCard.tsx b/packages/core/src/ClickableCard/ClickableCard.tsxindex 51716e1979..0a63ec80b0 100644--- a/packages/core/src/ClickableCard/ClickableCard.tsx+++ b/packages/core/src/ClickableCard/ClickableCard.tsx@@ -51,6 +51,7 @@ import {interactionOverlayStyles} from '../utils/interactionOverlay.stylex';import {usePressFeedback} from '../hooks/usePressFeedback';import {useMergedRefs} from '../hooks/useMergedRefs';+import {disabledInteractionProps} from '../utils/disabledInteraction';// =============================================================================// Styles — only the interactive layer, Card handles everything else// =============================================================================@@ -210,8 +211,8 @@ export interface ClickableCardProps extends BaseProps {/*** Set to true to disable the card.- * Disabled action cards use a native disabled button. Disabled link cards- * render no live destination, leave the tab order, and expose aria-disabled.+ * Disabled cards keep their tab stop and expose aria-disabled; activation is+ * blocked, and disabled link cards render no live destination.*/isDisabled?: boolean;@@ -255,10 +256,6 @@ export interface ClickableCardProps extends BaseProps {// Component// =============================================================================-function preventDisabledLinkClick(event: MouseEvent<HTMLAnchorElement>): void {- event.preventDefault();-}-/*** An interactive card that acts as a single navigation or action target.*@@ -376,11 +373,12 @@ export function ClickableCard({ref={interactiveRef as React.Ref<HTMLAnchorElement>}href={isDisabled ? undefined : href}target={isDisabled ? undefined : target}- onClick={isDisabled ? preventDisabledLinkClick : undefined}role={isDisabled ? 'link' : undefined}+ {...(isDisabled ? disabledInteractionProps() : null)}aria-label={label}aria-disabled={isDisabled || undefined}- tabIndex={isDisabled ? -1 : 0}+ // A disabled card keeps its Tab stop (spec:AST-085 FR1).+ tabIndex={0}{...stylex.props(styles.srOnly)}/>) : (@@ -388,8 +386,10 @@ export function ClickableCard({ref={interactiveRef as React.Ref<HTMLButtonElement>}type="button"aria-label={label}- disabled={isDisabled}+ aria-disabled={isDisabled || undefined}onClick={onClickProp}+ // Focusable while disabled (FR1), but inert (FR2).+ {...(isDisabled ? disabledInteractionProps() : null)}{...stylex.props(styles.srOnly)}/>)}diff --git a/packages/core/src/Link/Link.test.tsx b/packages/core/src/Link/Link.test.tsxindex 826c931cb6..ebd2bc7cc8 100644--- a/packages/core/src/Link/Link.test.tsx+++ b/packages/core/src/Link/Link.test.tsx@@ -58,10 +58,25 @@ describe('Link', () => {expect(handleClick).toHaveBeenCalledTimes(1);});- it('button fallback supports isDisabled', () => {- render(<Link isDisabled>Disabled Action</Link>);+ it('button fallback stays focusable and inert when isDisabled', async () => {+ const user = userEvent.setup();+ const onClick = vi.fn();+ render(+ <Link isDisabled onClick={onClick}>+ Disabled Action+ </Link>,+ );const button = screen.getByRole('button');- expect(button).toBeDisabled();+ expect(button).not.toHaveAttribute('disabled');+ expect(button).toHaveAttribute('aria-disabled', 'true');+ const nativeClick = vi.fn();+ button.addEventListener('click', nativeClick);+ await user.tab();+ expect(button).toHaveFocus();+ await user.keyboard('{Enter} ');+ expect(nativeClick).not.toHaveBeenCalled();+ fireEvent.click(button);+ expect(onClick).not.toHaveBeenCalled();});it('button fallback has type="button"', () => {@@ -156,11 +171,10 @@ describe('Link', () => {Disabled Link</Link>,);- // An href-less anchor has no implicit `link` role, so query by text.- const link = screen.getByText('Disabled Link').closest('a');- expect(link).not.toBeNull();+ // The href-less anchor keeps a Tab stop and an explicit link role.+ const link = screen.getByRole('link', {name: 'Disabled Link'});expect(link).toHaveAttribute('aria-disabled', 'true');- expect(link).toHaveAttribute('tabIndex', '-1');+ expect(link).toHaveAttribute('tabIndex', '0');// Visual classes are preserved in the disabled state.expect(link?.className).toContain('astryx-link');});diff --git a/packages/core/src/Link/Link.tsx b/packages/core/src/Link/Link.tsxindex 3dde606b92..963910ec09 100644--- a/packages/core/src/Link/Link.tsx+++ b/packages/core/src/Link/Link.tsx@@ -48,6 +48,7 @@ import {focusOutlineProps} from '../utils/focusOutline.stylex';import {interactionOverlayStyles} from '../utils/interactionOverlay.stylex';import {usePressFeedback} from '../hooks/usePressFeedback';import {useTranslator} from '../i18n';+import {disabledInteractionProps} from '../utils/disabledInteraction';/*** Base link styles@@ -174,9 +175,8 @@ export interface LinkProps extends BaseProps</*** Whether the link is disabled.* A disabled link renders as a plain anchor without an href (and without- * target/rel/onClick), so it cannot be focused or activated — no- * navigation and no onClick, even via programmatic focus or assistive- * technology activation.+ * target/rel/onClick), so it cannot navigate or run onClick. It keeps a tab+ * stop and is announced as a disabled link.* @default false*/isDisabled?: boolean;@@ -264,15 +264,6 @@ export interface LinkProps extends BaseProps<children: ReactNode;}-/**- * Click handler for disabled links. The disabled anchor renders without an- * href, so there is no navigation to block in practice; preventDefault is a- * defensive guard against synthetic/programmatic clicks.- */-function preventDefaultClick(event: React.MouseEvent<HTMLAnchorElement>): void {- event.preventDefault();-}-/*** A styled anchor link component.*@@ -367,8 +358,6 @@ export function Link({{...(isDisabled ? undefined : pressable)}aria-label={label || undefined}aria-disabled={isDisabled || undefined}- tabIndex={isDisabled ? -1 : undefined}- disabled={isDisabled}{...mergeProps(themeProps('link', {color}),focusOutlineProps.focusVisible(@@ -386,24 +375,26 @@ export function Link({className,style,)}- {...props}>+ {...props}+ // Focusable while disabled (spec:AST-085 FR1), but inert (FR2).+ {...(isDisabled ? disabledInteractionProps(props.onKeyDown) : null)}>{sharedContent}</button>);} else if (isDisabled) {- // A disabled link 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 link performs no navigation, and custom router- // links may require a live href. target/rel are omitted with the href.+ // A disabled link renders as an <a> with no href, so nothing can navigate+ // and the consumer onClick never fires. It keeps a Tab stop and the link+ // role so keyboard and screen-reader users still find it (spec:AST-085+ // FR1, FR5). The router LinkComponent is deliberately skipped — a disabled+ // link performs no navigation, and custom router links may require a live+ // href. target/rel are omitted with the href.linkElement = (<aref={ref as React.Ref<HTMLAnchorElement>}- onClick={preventDefaultClick}+ role="link"aria-label={label || undefined}aria-disabled={true}- tabIndex={-1}+ tabIndex={0}{...mergeProps(themeProps('link', {color}),focusOutlineProps.focusVisible(@@ -417,7 +408,8 @@ export function Link({className,style,)}- {...props}>+ {...props}+ {...disabledInteractionProps(props.onKeyDown)}>{sharedContent}</a>);diff --git a/packages/core/src/Link/__tests__/Link.a11y.states.ts b/packages/core/src/Link/__tests__/Link.a11y.states.tsindex a661a91d18..dc5643d888 100644--- a/packages/core/src/Link/__tests__/Link.a11y.states.ts+++ b/packages/core/src/Link/__tests__/Link.a11y.states.ts@@ -73,7 +73,7 @@ export const LINK_A11Y_EXCLUSIONS = [{owner: 'Link component tests and family:navigation-destinations FR7',reason:- 'A disabled Link renders an href-less anchor that is neither a link nor focusable. That disabled semantics is member-owned, so disabled states are not bound to this available-link contract.',+ 'A disabled Link renders a focusable, href-less anchor with an explicit link role and aria-disabled, so it cannot navigate. That disabled semantics is member-owned, so disabled states are not bound to this available-link contract.',},{owner: 'Link component tests (button rendering)',diff --git a/packages/core/src/Popover/Popover.test.tsx b/packages/core/src/Popover/Popover.test.tsxindex c4a16cd555..7b9c20729e 100644--- a/packages/core/src/Popover/Popover.test.tsx+++ b/packages/core/src/Popover/Popover.test.tsx@@ -124,6 +124,21 @@ describe('Popover', () => {expect(screen.getByRole('button', {name: 'Open'})).toBeInTheDocument();});+ it('does not open from an aria-disabled trigger', () => {+ render(+ <Popover content={<span>Content</span>} label="Test">+ <button type="button" aria-disabled="true">+ Trigger+ </button>+ </Popover>,+ );+ const trigger = screen.getByRole('button', {name: 'Trigger'});+ // A click dispatched straight on the trigger, as element.click() or an+ // assistive-technology activate command does (spec:AST-085 FR2).+ act(() => trigger.click());+ expect(trigger).toHaveAttribute('aria-expanded', 'false');+ });+it('sets aria-haspopup on trigger', () => {render(<Popover content={<span>Content</span>} label="Test">diff --git a/packages/core/src/Popover/Popover.tsx b/packages/core/src/Popover/Popover.tsxindex 9a21038de9..66d77713de 100644--- a/packages/core/src/Popover/Popover.tsx+++ b/packages/core/src/Popover/Popover.tsx@@ -481,12 +481,22 @@ export function Popover({}, [content, popover.isOpen, scheduleOverflowMeasurement]);// Shared handler for click events on the trigger button.- const handleTriggerClick = useCallback(() => {- if (!isEnabled) {- return;- }- popover.toggle();- }, [isEnabled, popover]);+ const handleTriggerClick = useCallback(+ (event?: {currentTarget: EventTarget | null}) => {+ // An aria-disabled trigger stays focusable but opens nothing+ // (spec:AST-085 FR2), even for a click dispatched straight on it.+ const trigger = event?.currentTarget;+ if (+ !isEnabled ||+ (trigger instanceof Element &&+ trigger.getAttribute('aria-disabled') === 'true')+ ) {+ return;+ }+ popover.toggle();+ },+ [isEnabled, popover],+ );// Shared handler for keydown events on role="button" elements.// Native <button> synthesizes click on Enter/Space, but role="button"@@ -495,7 +505,7 @@ export function Popover({(e: KeyboardEvent) => {if (e.key === 'Enter' || e.key === ' ') {e.preventDefault();- handleTriggerClick();+ handleTriggerClick(e);}},[handleTriggerClick],@@ -662,7 +672,8 @@ export function Popover({if (isRenderProp) {const triggerProps: PopoverTriggerRenderProps = {ref: popover.triggerRef,- onClick: handleTriggerClick,+ // The caller renders and owns this trigger element.+ onClick: () => handleTriggerClick(),'aria-haspopup': 'dialog','aria-expanded': popover.isOpen,'aria-controls': popover.id,diff --git a/packages/core/src/PowerSearch/PowerSearchToken.test.tsx b/packages/core/src/PowerSearch/PowerSearchToken.test.tsxindex f702649d64..d1ab8527f7 100644--- a/packages/core/src/PowerSearch/PowerSearchToken.test.tsx+++ b/packages/core/src/PowerSearch/PowerSearchToken.test.tsx@@ -218,11 +218,13 @@ describe('PowerSearchToken', () => {expect(onRemove).toHaveBeenCalledTimes(1);});- it('disables both the activation and remove buttons when isDisabled is set', () => {+ it('marks both the activation and remove buttons disabled when isDisabled is set', () => {renderToken({onClick: vi.fn(), onRemove: vi.fn(), isDisabled: true});- expect(screen.getByRole('button', {name: 'Status: is'})).toBeDisabled();- expect(- screen.getByRole('button', {name: 'Remove Status: is'}),- ).toBeDisabled();+ // spec:AST-085 FR1: focusable, exposed through aria-disabled.+ for (const name of ['Status: is', 'Remove Status: is']) {+ const button = screen.getByRole('button', {name});+ expect(button).not.toHaveAttribute('disabled');+ expect(button).toHaveAttribute('aria-disabled', 'true');+ }});});diff --git a/packages/core/src/Token/Token.test.tsx b/packages/core/src/Token/Token.test.tsxindex c5846d003e..4426fc3867 100644--- a/packages/core/src/Token/Token.test.tsx+++ b/packages/core/src/Token/Token.test.tsx@@ -134,8 +134,10 @@ describe('Token', () => {/>,);const button = screen.getByRole('button', {name: 'Disabled'});- expect(button).toBeDisabled();+ expect(button).not.toHaveAttribute('disabled');+ expect(button).toHaveAttribute('aria-disabled', 'true');expect(button.tagName).toBe('BUTTON');+ fireEvent.click(button);// Container click is also disabledconst container = screen.getByTestId('token');fireEvent.click(container);@@ -254,14 +256,34 @@ describe('Token accessibility', () => {).toBeInTheDocument();});- it('disables both buttons when isDisabled is true', () => {+ it('keeps both buttons focusable and inert when isDisabled is true', async () => {+ const user = userEvent.setup();+ const handleClick = vi.fn();+ const handleRemove = vi.fn();render(- <Token label="Token" onClick={() => {}} onRemove={() => {}} isDisabled />,+ <Token+ label="Token"+ onClick={handleClick}+ onRemove={handleRemove}+ isDisabled+ />,);const buttons = screen.getAllByRole('button');+ expect(buttons).toHaveLength(2);for (const button of buttons) {- expect(button).toBeDisabled();+ expect(button).not.toHaveAttribute('disabled');+ expect(button).toHaveAttribute('aria-disabled', 'true');+ // A wrapping Popover listens for clicks on the button itself.+ const nativeClick = vi.fn();+ button.addEventListener('click', nativeClick);+ await user.tab();+ expect(button).toHaveFocus();+ await user.keyboard('{Enter} ');+ expect(nativeClick).not.toHaveBeenCalled();+ fireEvent.click(button);}+ expect(handleClick).not.toHaveBeenCalled();+ expect(handleRemove).not.toHaveBeenCalled();});it('does not fire onClick or onRemove when disabled', () => {diff --git a/packages/core/src/Token/Token.tsx b/packages/core/src/Token/Token.tsxindex 780e3b8597..57c5b3d6f3 100644--- a/packages/core/src/Token/Token.tsx+++ b/packages/core/src/Token/Token.tsx@@ -41,6 +41,7 @@ import {interactionOverlayStyles} from '../utils/interactionOverlay.stylex';import {usePressFeedback} from '../hooks/usePressFeedback';import {useTranslator} from '../i18n';import type {TokenColorMap} from './index';+import {disabledInteractionProps} from '../utils/disabledInteraction';// =============================================================================// Types@@ -321,7 +322,9 @@ export function Token({e.stopPropagation();onRemove(e);}}- disabled={isDisabled}+ // Focusable while disabled (spec:AST-085 FR1), but inert (FR2).+ aria-disabled={isDisabled || undefined}+ {...(isDisabled ? disabledInteractionProps() : null)}{...focusOutlineProps.focusVisible(styles.removeButton)}><Icon icon="close" size="xsm" color="inherit" /></button>@@ -455,7 +458,8 @@ export function Token({<buttontype="button"onClick={effectiveOnClick}- disabled={isDisabled}+ aria-disabled={isDisabled || undefined}+ {...(isDisabled ? disabledInteractionProps() : null)}{...stylex.props(styles.invisibleButton)}><span{...stylex.props(diff --git a/packages/core/src/utils/disabledInteraction.ts b/packages/core/src/utils/disabledInteraction.tsnew file mode 100644index 0000000000..6de990ce04--- /dev/null+++ b/packages/core/src/utils/disabledInteraction.ts@@ -0,0 +1,40 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/**+ * @file disabledInteraction.ts+ * @input An optional caller keydown handler+ * @output Event props that keep a focusable, aria-disabled control inert+ * @position Shared by controls that replace native `disabled` with+ * `aria-disabled` under spec:AST-085 (FR1, FR2)+ */++import type {KeyboardEvent, KeyboardEventHandler, MouseEvent} from 'react';++/**+ * Event props for a disabled control that stays focusable. Native `disabled`+ * dispatched no click at all; without it, Enter and Space still synthesize a+ * click that native listeners on the element (a wrapping Popover's trigger)+ * receive. Cancelling those keys keeps the click from existing, and the click+ * handler cancels pointer clicks and keeps them from reaching ancestors. Other+ * keys still reach the caller's handler.+ */+export function disabledInteractionProps<T extends HTMLElement>(+ onKeyDown?: KeyboardEventHandler<T>,+): {+ onClick: (event: MouseEvent<T>) => void;+ onKeyDown: (event: KeyboardEvent<T>) => void;+} {+ return {+ onClick: event => {+ event.preventDefault();+ event.stopPropagation();+ },+ onKeyDown: event => {+ if (event.key === 'Enter' || event.key === ' ') {+ event.preventDefault();+ } else {+ onKeyDown?.(event);+ }+ },+ };+}