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.tsxindex 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() {<Buttonlabel="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.tsxindex 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 renderedexpect(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.tsxindex 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 + interactionhoverCard.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({<spanref={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.tsxindex 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,