An open source design system that's fully customizable and agent ready
TypeScript
fix(HoverCard): only put aria-expanded on a trigger whose role supports it (#5501)
Cindy Zhang780938e40a3b
diff --git a/.changeset/hovercard-aria-expanded-role-gate.md b/.changeset/hovercard-aria-expanded-role-gate.mdnew file mode 100644index 0000000000..bcd0a6628a--- /dev/null+++ b/.changeset/hovercard-aria-expanded-role-gate.md@@ -0,0 +1,11 @@+---+'@astryxdesign/core': patch+---++[fix] HoverCard: a labelled card no longer puts `aria-expanded` on a trigger whose role cannot carry it++Since the dialog-popup contract landed, a labelled HoverCard set `aria-haspopup`, `aria-controls` and `aria-expanded` on its trigger whatever that trigger was. The first two are global ARIA attributes and are valid anywhere; `aria-expanded` is supported on a fixed set of roles, and a role-less trigger is not one of them. Every Timestamp with a hover card is a role-less trigger, so nine Timestamp stories reported a critical axe `aria-allowed-attr` violation across twenty-nine nodes.++`aria-expanded` is now emitted only when the trigger's role supports it. A role-less trigger keeps `aria-haspopup="dialog"` and `aria-controls`, so the popup relationship is still advertised — only the state the element could never have expressed is dropped, and if it carried its own `aria-expanded` that value is left alone. On a trigger whose role does support the attribute nothing changes: the card drives it, overwriting the trigger's own value exactly as before.++@cixzhangdiff --git a/packages/core/src/HoverCard/HoverCard.test.tsx b/packages/core/src/HoverCard/HoverCard.test.tsxindex 20ff3e9d8f..4dbfaa5523 100644--- a/packages/core/src/HoverCard/HoverCard.test.tsx+++ b/packages/core/src/HoverCard/HoverCard.test.tsx@@ -400,6 +400,58 @@ describe('HoverCard', () => {expect(trigger).toHaveAttribute('aria-expanded', 'false');});+ it('omits aria-expanded on a trigger whose role does not support it', () => {+ render(+ <HoverCard content={<span>Card content</span>} label="Timestamp details">+ <time dateTime="2026-08-25" tabIndex={0}>+ 2 hours ago+ </time>+ </HoverCard>,+ );+ const trigger = screen.getByText('2 hours ago');+ expect(trigger.tagName).toBe('TIME');+ // Global attributes are valid on any element, so the popup relationship is+ // still advertised.+ expect(trigger).toHaveAttribute('aria-haspopup', 'dialog');+ // aria-expanded is not: <time> has no role that supports it, and emitting+ // it is a critical axe aria-allowed-attr violation.+ expect(trigger).not.toHaveAttribute('aria-expanded');+ });++ it('keeps aria-expanded on a role-less trigger that declares a supporting role', () => {+ render(+ <HoverCard content={<span>Card content</span>} label="Profile actions">+ <span role="button" tabIndex={0}>+ Trigger+ </span>+ </HoverCard>,+ );+ const trigger = screen.getByRole('button', {name: 'Trigger'});+ expect(trigger).toHaveAttribute('aria-expanded', 'false');+ });++ it('leaves a role-less trigger own aria-expanded untouched', () => {+ render(+ <HoverCard content={<span>Card content</span>} label="Profile actions">+ <span aria-expanded="true">Trigger</span>+ </HoverCard>,+ );+ const trigger = screen.getByText('Trigger');+ expect(trigger).toHaveAttribute('aria-expanded', 'true');+ });++ it('keeps aria-expanded on triggers whose implicit role supports it', () => {+ render(+ <HoverCard content={<span>Card content</span>} label="Profile actions">+ <input type="button" value="Trigger" />+ </HoverCard>,+ );+ expect(screen.getByRole('button')).toHaveAttribute(+ 'aria-expanded',+ 'false',+ );+ });+it('keeps aria-describedby on the trigger when no label is provided', () => {render(<HoverCard content={<span>Card content</span>}>@@ -503,7 +555,8 @@ describe('HoverCard', () => {const wrapper = screen.getByText('Just text, no element');expect(wrapper.tagName).toBe('SPAN');expect(wrapper).toHaveAttribute('aria-haspopup', 'dialog');- expect(wrapper).toHaveAttribute('aria-expanded', 'false');+ // The wrapper is a role-less <span>; aria-expanded is invalid there.+ expect(wrapper).not.toHaveAttribute('aria-expanded');// While closed, the layer is not in the DOM, so aria-controls is unset.expect(wrapper).not.toHaveAttribute('aria-controls');expect(wrapper).not.toHaveAttribute('aria-describedby');diff --git a/packages/core/src/HoverCard/HoverCard.tsx b/packages/core/src/HoverCard/HoverCard.tsxindex 5e0e5979bd..4316875cdf 100644--- a/packages/core/src/HoverCard/HoverCard.tsx+++ b/packages/core/src/HoverCard/HoverCard.tsx@@ -32,6 +32,66 @@ export type {HoverCardTouchTrigger,} from './useHoverCard';+// `aria-haspopup` and `aria-controls` are global, so any trigger may carry+// them. `aria-expanded` is not. This is the ARIA 1.2 "Supported States and+// Properties" list for it — deliberately the narrow reading: axe accepts the+// attribute on rather more roles, since it also allows every subclass of these,+// so a role outside this set is not necessarily a violation. Widening it is+// safe; the set is a floor, not the spec's ceiling. The same rule is applied in+// Chat/useTriggerMenu.tsx, which only emits the combobox attributes once the+// element is actually a combobox.+const EXPANDABLE_ROLES = new Set([+ 'application',+ 'button',+ 'checkbox',+ 'columnheader',+ 'combobox',+ 'gridcell',+ 'link',+ 'listbox',+ 'menuitem',+ 'menuitemcheckbox',+ 'menuitemradio',+ 'row',+ 'rowheader',+ 'switch',+ 'tab',+ 'treeitem',+]);++const BUTTON_INPUT_TYPES = new Set(['button', 'submit', 'reset', 'image']);++// Deliberately partial, and unlisted elements are read as role-less: dropping+// aria-expanded where it might have been legal costs an AT user a state they+// can still infer, whereas emitting it where it is illegal is a critical+// aria-allowed-attr defect.+function supportsAriaExpanded(el: HTMLElement): boolean {+ const explicit = el.getAttribute('role')?.trim().split(/\s+/)[0];+ if (explicit) {+ return EXPANDABLE_ROLES.has(explicit);+ }+ switch (el.tagName) {+ case 'BUTTON':+ case 'SUMMARY':+ return true;+ case 'A':+ case 'AREA':+ return el.hasAttribute('href');+ case 'INPUT':+ // The button-flavoured input types map to role="button"; every other+ // type maps to a textbox-family role, which does not take it.+ return BUTTON_INPUT_TYPES.has(+ (el as HTMLInputElement).type?.toLowerCase(),+ );+ case 'SELECT':+ // combobox when it is a single-line picker, listbox otherwise; both+ // support aria-expanded.+ return true;+ default:+ return false;+ }+}+const styles = stylex.create({wrapperContents: {display: 'contents',@@ -265,12 +325,17 @@ export function HoverCard({// trigger with the dialog's content (aria-describedby is for plain-text// descriptions, not navigable regions). See #5049.//+ // aria-expanded only goes on a trigger whose role permits it. A role-less+ // trigger (Timestamp's <time>/<span>) gets haspopup + controls, which are+ // global, and no expanded state.+ //// Merge rather than overwrite: the trigger may already carry its own// popup semantics (e.g. a menu button wrapped in a labelled HoverCard),// so preserve the existing values and restore them on cleanup.const existingHaspopup = firstChild.getAttribute('aria-haspopup');const existingControls = firstChild.getAttribute('aria-controls');const existingExpanded = firstChild.getAttribute('aria-expanded');+ const canExpand = supportsAriaExpanded(firstChild);firstChild.setAttribute('aria-haspopup', 'dialog');// Only point aria-controls at the layer while it is open and in the DOM.@@ -287,7 +352,13 @@ export function HoverCard({} else {firstChild.removeAttribute('aria-controls');}- firstChild.setAttribute('aria-expanded', String(hoverCard.isOpen));+ if (canExpand) {+ firstChild.setAttribute('aria-expanded', String(hoverCard.isOpen));+ } else if (existingExpanded) {+ firstChild.setAttribute('aria-expanded', existingExpanded);+ } else {+ firstChild.removeAttribute('aria-expanded');+ }return () => {hoverCard.ref(null);@@ -354,7 +425,8 @@ export function HoverCard({tabIndex={0}aria-haspopup={label ? 'dialog' : undefined}aria-controls={label && hoverCard.isOpen ? hoverCard.id : undefined}- aria-expanded={label ? hoverCard.isOpen : undefined}+ // No aria-expanded: this wrapper is a role-less <span>, and+ // aria-expanded is invalid on it (see EXPANDABLE_ROLES above).aria-describedby={label ? undefined : hoverCard.describedBy}{...stylex.props(styles.wrapperInline,diff --git a/packages/core/src/HoverCard/useHoverCard.tsx b/packages/core/src/HoverCard/useHoverCard.tsxindex 8eafbe147e..7eadf5fbc1 100644--- a/packages/core/src/HoverCard/useHoverCard.tsx+++ b/packages/core/src/HoverCard/useHoverCard.tsx@@ -202,7 +202,10 @@ export interface HoverCardReturn {/*** Whether the hover card is currently open.- * Useful for driving `aria-expanded` on the trigger.+ * Useful for driving `aria-expanded` on the trigger — but only when the+ * trigger's role permits it (`button`, `link`, `combobox`, …). On a role-less+ * trigger `aria-expanded` is invalid; use `aria-haspopup`/`aria-controls`+ * alone there.*/isOpen: boolean;diff --git a/packages/core/src/Timestamp/Timestamp.test.tsx b/packages/core/src/Timestamp/Timestamp.test.tsxindex 595d0b265b..cf337bb40f 100644--- a/packages/core/src/Timestamp/Timestamp.test.tsx+++ b/packages/core/src/Timestamp/Timestamp.test.tsx@@ -673,6 +673,24 @@ describe('Timestamp', () => {expect(screen.getByTestId('ts')).toHaveAttribute('tabindex', '0');});+ it('does not put aria-expanded on the role-less hover-card trigger', async () => {+ render(+ <Timestamp+ value={Date.now() / 1000 - 3600}+ format="relative"+ data-testid="ts"+ />,+ );+ const trigger = screen.getByTestId('ts').parentElement;+ // The trigger is Text's <span>, which has no role, so aria-expanded is+ // invalid on it (axe aria-allowed-attr, critical). aria-haspopup is+ // global and still advertises the dialog.+ await waitFor(() => {+ expect(trigger).toHaveAttribute('aria-haspopup', 'dialog');+ });+ expect(trigger).not.toHaveAttribute('aria-expanded');+ });+it('shows the hover card when the timestamp receives keyboard focus', async () => {const user = userEvent.setup();render(