Skip to content

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

TypeScript

fix(HoverCard): expose rich cards as dialog popups, not descriptions (#5419)

Gonzalo Blascof4d494c48274
diff --git a/packages/cli/assets/templates/blocks/components/HoverCard/HoverCardHookUsage.tsx b/packages/cli/assets/templates/blocks/components/HoverCard/HoverCardHookUsage.tsx
index b8ca836d08..15b562835d 100644
--- a/packages/cli/assets/templates/blocks/components/HoverCard/HoverCardHookUsage.tsx
+++ b/packages/cli/assets/templates/blocks/components/HoverCard/HoverCardHookUsage.tsx
@@ -13,6 +13,7 @@ export default function HoverCardHookUsage() {
placement: 'below',
delay: 100,
isDefaultOpen: true,
+ label: 'Alex Morgan',
});
return (
@@ -20,7 +21,9 @@ export default function HoverCardHookUsage() {
<Button
label="Hover profile"
ref={hoverCard.ref}
- aria-describedby={hoverCard.describedBy}
+ aria-haspopup="dialog"
+ aria-controls={hoverCard.isOpen ? hoverCard.id : undefined}
+ aria-expanded={hoverCard.isOpen}
/>
{hoverCard.renderHoverCard(
<VStack gap={1}>
diff --git a/packages/core/src/HoverCard/HoverCard.test.tsx b/packages/core/src/HoverCard/HoverCard.test.tsx
index 204a299ccd..3bbda14c71 100644
--- a/packages/core/src/HoverCard/HoverCard.test.tsx
+++ b/packages/core/src/HoverCard/HoverCard.test.tsx
@@ -365,7 +365,42 @@ describe('HoverCard', () => {
);
});
- it('injects aria-describedby on trigger', () => {
+ it('advertises a dialog popup on the trigger when labelled', () => {
+ render(
+ <HoverCard content={<span>Card content</span>} label="Profile actions">
+ <button type="button">Trigger</button>
+ </HoverCard>,
+ );
+ const trigger = screen.getByRole('button', {name: 'Trigger'});
+ expect(trigger).toHaveAttribute('aria-haspopup', 'dialog');
+ // While closed, the layer is not in the DOM, so aria-controls must not
+ // point at a missing id (see DateInput). It is set once the card opens.
+ expect(trigger).not.toHaveAttribute('aria-controls');
+ expect(trigger).toHaveAttribute('aria-expanded', 'false');
+ expect(trigger).not.toHaveAttribute('aria-describedby');
+ });
+
+ it('merges existing popup attributes on the trigger when labelled', () => {
+ render(
+ <HoverCard content={<span>Card content</span>} label="Profile actions">
+ <button
+ type="button"
+ aria-haspopup="menu"
+ aria-controls="menu-id"
+ aria-expanded="true">
+ Trigger
+ </button>
+ </HoverCard>,
+ );
+ const trigger = screen.getByRole('button', {name: 'Trigger'});
+ // The hover card's dialog popup is advertised, but the trigger's own
+ // popup semantics are preserved rather than overwritten.
+ expect(trigger).toHaveAttribute('aria-haspopup', 'dialog');
+ expect(trigger.getAttribute('aria-controls')).toContain('menu-id');
+ expect(trigger).toHaveAttribute('aria-expanded', 'false');
+ });
+
+ it('keeps aria-describedby on the trigger when no label is provided', () => {
render(
<HoverCard content={<span>Card content</span>}>
<button type="button">Trigger</button>
@@ -373,9 +408,10 @@ describe('HoverCard', () => {
);
const trigger = screen.getByRole('button', {name: 'Trigger'});
expect(trigger).toHaveAttribute('aria-describedby');
+ expect(trigger).not.toHaveAttribute('aria-haspopup');
});
- it('merges existing aria-describedby', () => {
+ it('preserves existing aria-describedby when no label is provided', () => {
render(
<HoverCard content={<span>Card content</span>}>
<button type="button" aria-describedby="existing-id">
@@ -388,6 +424,34 @@ describe('HoverCard', () => {
expect(describedBy).toContain('existing-id');
});
+ it('updates aria-expanded when the labelled hover card opens and closes', async () => {
+ render(
+ <HoverCard
+ content={<span>Card content</span>}
+ label="Profile actions"
+ delay={0}>
+ <button type="button">Trigger</button>
+ </HoverCard>,
+ );
+ const trigger = screen.getByRole('button', {name: 'Trigger'});
+ expect(trigger).toHaveAttribute('aria-expanded', 'false');
+ expect(trigger).not.toHaveAttribute('aria-controls');
+
+ fireEvent.mouseEnter(trigger);
+ await waitFor(() => {
+ expect(trigger).toHaveAttribute('aria-expanded', 'true');
+ // The layer is in the DOM now, so aria-controls points at it.
+ expect(trigger).toHaveAttribute('aria-controls');
+ });
+
+ fireEvent.mouseLeave(trigger);
+ await waitFor(() => {
+ expect(trigger).toHaveAttribute('aria-expanded', 'false');
+ // The layer is gone from the DOM, so aria-controls is cleared.
+ expect(trigger).not.toHaveAttribute('aria-controls');
+ });
+ });
+
it('calls onOpenChange(true) when shown', async () => {
const onOpenChange = vi.fn();
render(
@@ -429,16 +493,32 @@ describe('HoverCard', () => {
it('supports text-only children with inline wrapper', () => {
render(
- <HoverCard content={<span>Card content</span>}>
+ <HoverCard content={<span>Card content</span>} label="Profile actions">
Just text, no element
</HoverCard>,
);
// Text should be rendered
expect(screen.getByText('Just text, no element')).toBeInTheDocument();
- // Should have aria-describedby on the wrapper span
+ // When labelled, the wrapper advertises a dialog popup.
+ 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');
+ // 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');
+ });
+
+ it('keeps aria-describedby on text-only children when no label is provided', () => {
+ render(
+ <HoverCard content={<span>Card content</span>}>
+ Just text, no element
+ </HoverCard>,
+ );
const wrapper = screen.getByText('Just text, no element');
expect(wrapper.tagName).toBe('SPAN');
expect(wrapper).toHaveAttribute('aria-describedby');
+ expect(wrapper).not.toHaveAttribute('aria-haspopup');
});
describe('isDefaultOpen', () => {
diff --git a/packages/core/src/HoverCard/HoverCard.tsx b/packages/core/src/HoverCard/HoverCard.tsx
index f2cf8ae93b..5e0e5979bd 100644
--- a/packages/core/src/HoverCard/HoverCard.tsx
+++ b/packages/core/src/HoverCard/HoverCard.tsx
@@ -259,7 +259,59 @@ export function HoverCard({
// Use combined ref for position + interaction
hoverCard.ref(firstChild);
- // Set aria-describedby, merging with existing
+ if (label) {
+ // When named, the hover card is a dialog. The trigger should advertise the
+ // popup relationship with aria-haspopup/aria-expanded, not describe the
+ // trigger with the dialog's content (aria-describedby is for plain-text
+ // descriptions, not navigable regions). See #5049.
+ //
+ // 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');
+
+ firstChild.setAttribute('aria-haspopup', 'dialog');
+ // Only point aria-controls at the layer while it is open and in the DOM.
+ // While closed, useLayer leaves only an inert <template> marker, so the
+ // id would reference nothing. DateInput gates it the same way. The
+ // trigger's own aria-controls (if any) is preserved either way.
+ if (hoverCard.isOpen) {
+ firstChild.setAttribute(
+ 'aria-controls',
+ mergeIds(existingControls, hoverCard.id) ?? '',
+ );
+ } else if (existingControls) {
+ firstChild.setAttribute('aria-controls', existingControls);
+ } else {
+ firstChild.removeAttribute('aria-controls');
+ }
+ firstChild.setAttribute('aria-expanded', String(hoverCard.isOpen));
+
+ return () => {
+ hoverCard.ref(null);
+ if (existingHaspopup) {
+ firstChild.setAttribute('aria-haspopup', existingHaspopup);
+ } else {
+ firstChild.removeAttribute('aria-haspopup');
+ }
+ if (existingControls) {
+ firstChild.setAttribute('aria-controls', existingControls);
+ } else {
+ firstChild.removeAttribute('aria-controls');
+ }
+ if (existingExpanded) {
+ firstChild.setAttribute('aria-expanded', existingExpanded);
+ } else {
+ firstChild.removeAttribute('aria-expanded');
+ }
+ };
+ }
+
+ // Unnamed fallback: the popup remains role="group", which is not a dialog,
+ // so keep the previous description relationship until a naming decision is
+ // made for the no-label case (tracked in #5049).
const existingDescribedBy = firstChild.getAttribute('aria-describedby');
firstChild.setAttribute(
'aria-describedby',
@@ -274,7 +326,14 @@ export function HoverCard({
firstChild.removeAttribute('aria-describedby');
}
};
- }, [textOnly, hoverCard.ref, hoverCard.describedBy]);
+ }, [
+ textOnly,
+ label,
+ hoverCard.ref,
+ hoverCard.id,
+ hoverCard.isOpen,
+ hoverCard.describedBy,
+ ]);
// While closed, useLayer leaves only an inert <template> marker at this JSX
// position. When the card needs to open, it uses that marker to keep the
@@ -293,7 +352,10 @@ export function HoverCard({
<span
ref={hoverCard.ref}
tabIndex={0}
- aria-describedby={hoverCard.describedBy}
+ aria-haspopup={label ? 'dialog' : undefined}
+ aria-controls={label && hoverCard.isOpen ? hoverCard.id : undefined}
+ aria-expanded={label ? hoverCard.isOpen : undefined}
+ aria-describedby={label ? undefined : hoverCard.describedBy}
{...stylex.props(
styles.wrapperInline,
showHoverIndication && styles.hoverIndication,
diff --git a/packages/core/src/HoverCard/useHoverCard.tsx b/packages/core/src/HoverCard/useHoverCard.tsx
index 17b1b33741..3ab90eccb5 100644
--- a/packages/core/src/HoverCard/useHoverCard.tsx
+++ b/packages/core/src/HoverCard/useHoverCard.tsx
@@ -190,11 +190,22 @@ export interface HoverCardReturn {
anchorId: string;
/**
- * ID for aria-describedby on the trigger element.
- * Caller should compose with other IDs using mergeIds utility.
+ * Unique ID for the hover card container.
+ * Useful for `aria-controls` or `aria-owns` on the trigger.
+ */
+ id: string;
+
+ /**
+ * Deprecated alias of `id`. Kept for backwards compatibility; prefer `id`.
*/
describedBy: string;
+ /**
+ * Whether the hover card is currently open.
+ * Useful for driving `aria-expanded` on the trigger.
+ */
+ isOpen: boolean;
+
/**
* Render function for hover card content.
* Returns anchor-positioned popover element.
@@ -681,7 +692,9 @@ export function useHoverCard(options: HoverCardOptions = {}): HoverCardReturn {
positionRef: layer.ref,
interactionRef,
anchorId: layer.anchorId,
+ id: layer.id,
describedBy: layer.id,
+ isOpen: layer.isOpen,
renderHoverCard,
show: layer.show,
hide: layer.hide,