Skip to content

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.md
new file mode 100644
index 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.
+
+@cixzhang
diff --git a/packages/core/src/HoverCard/HoverCard.test.tsx b/packages/core/src/HoverCard/HoverCard.test.tsx
index 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.tsx
index 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.tsx
index 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.tsx
index 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(