Skip to content

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

TypeScript

fix(core): give HoverCard popup an accessible name or group semantics (#3988)

Baraa Hamodi6c922bc3e4a0
diff --git a/.changeset/hovercard-dialog-label.md b/.changeset/hovercard-dialog-label.md
new file mode 100644
index 0000000000..7ec244c713
--- /dev/null
+++ b/.changeset/hovercard-dialog-label.md
@@ -0,0 +1,6 @@
+---
+'@astryxdesign/core': patch
+---
+
+[fix] HoverCard: popups now expose a named dialog when the new label prop is set, and honest group semantics otherwise. Previously every hover card announced as an unnamed dialog.
+@bhamodi
diff --git a/packages/core/src/HoverCard/HoverCard.doc.mjs b/packages/core/src/HoverCard/HoverCard.doc.mjs
index 5069330c35..be0f856c2d 100644
--- a/packages/core/src/HoverCard/HoverCard.doc.mjs
+++ b/packages/core/src/HoverCard/HoverCard.doc.mjs
@@ -79,6 +79,12 @@ export const docs = {
description: 'Enables or disables the hover and focus triggers.',
default: 'true',
},
+ {
+ name: 'label',
+ type: 'string',
+ description:
+ 'Accessible name for the hover card popup. When provided, the popup is exposed as a named role="dialog"; when omitted, it falls back to role="group" (a group may validly be unnamed).',
+ },
{
name: 'onOpenChange',
type: '(isOpen: boolean) => void',
@@ -188,6 +194,12 @@ export const docsZh = {
description: '启用或禁用悬停和聚焦触发器。',
default: 'true',
},
+ {
+ name: 'label',
+ type: 'string',
+ description:
+ '悬浮卡片弹出层的无障碍名称。提供时,弹出层以具名的 role="dialog" 暴露;省略时,回退为 role="group"(group 可以合法地没有名称)。',
+ },
{
name: 'onOpenChange',
type: '(isOpen: boolean) => void',
@@ -252,6 +264,7 @@ export const docsDense = {
hideDelay: 'Hide delay in ms.',
focusTrigger: 'Controls when focus events trigger hover card.',
isEnabled: 'Enable/disable hover + focus triggers.',
+ label: 'Accessible name for the popup. With label: named role="dialog"; without: role="group".',
onOpenChange: 'Callback when visibility changes; true=shown, false=hidden.',
hasHoverIndication: 'Dashed underline on trigger element.',
isDefaultOpen: 'Show hover card on mount. Still dismissible.',
diff --git a/packages/core/src/HoverCard/HoverCard.test.tsx b/packages/core/src/HoverCard/HoverCard.test.tsx
index 7b22faa540..c0d88f3b31 100644
--- a/packages/core/src/HoverCard/HoverCard.test.tsx
+++ b/packages/core/src/HoverCard/HoverCard.test.tsx
@@ -58,15 +58,34 @@ describe('HoverCard', () => {
expect(screen.getByRole('button', {name: 'Trigger'})).toBeInTheDocument();
});
- it('gives the floating layer role="dialog"', () => {
+ it('exposes the floating layer as role="group" when no label is provided', () => {
render(
<HoverCard content={<span>Card content</span>}>
<button type="button">Trigger</button>
</HoverCard>,
);
- expect(screen.getByRole('dialog', {hidden: true})).toHaveTextContent(
+ // A group may validly be unnamed; an unnamed dialog may not. Without a
+ // label the layer must not claim the dialog role.
+ expect(screen.getByRole('group', {hidden: true})).toHaveTextContent(
'Card content',
);
+ expect(screen.queryByRole('dialog', {hidden: true})).toBeNull();
+ });
+
+ it('exposes the floating layer as a named dialog when label is provided', () => {
+ render(
+ <HoverCard content={<span>Card content</span>} label="Profile preview">
+ <button type="button">Trigger</button>
+ </HoverCard>,
+ );
+ // The layer is hidden while closed, so assert the accessible name via the
+ // aria-label attribute on the role-carrying element (same pattern as the
+ // Popover dialogLabel test) — accname computation returns '' for hidden
+ // elements.
+ const dialog = screen.getByRole('dialog', {hidden: true});
+ expect(dialog).toHaveAttribute('aria-label', 'Profile preview');
+ expect(dialog).toHaveTextContent('Card content');
+ expect(screen.queryByRole('group', {hidden: true})).toBeNull();
});
it('wraps element children in an inline-safe span', () => {
diff --git a/packages/core/src/HoverCard/HoverCard.tsx b/packages/core/src/HoverCard/HoverCard.tsx
index d1fa4e71e5..099b325e4e 100644
--- a/packages/core/src/HoverCard/HoverCard.tsx
+++ b/packages/core/src/HoverCard/HoverCard.tsx
@@ -96,6 +96,15 @@ export interface HoverCardProps extends Pick<
*/
isEnabled?: boolean;
+ /**
+ * Accessible name for the hover card popup.
+ *
+ * When provided, the popup is exposed to assistive technology as a named
+ * `role="dialog"`. When omitted, the popup falls back to `role="group"` —
+ * a group may validly be unnamed, an unnamed dialog may not.
+ */
+ label?: string;
+
/**
* Callback fired when hover card visibility changes.
* Called with `true` when shown and `false` when hidden.
@@ -166,6 +175,7 @@ export function HoverCard({
hideDelay = 200,
focusTrigger = 'auto',
isEnabled = true,
+ label,
onOpenChange,
hasHoverIndication = 'auto',
isOpen,
@@ -197,6 +207,7 @@ export function HoverCard({
hideDelay,
focusTrigger,
isEnabled,
+ label,
isOpen,
isDefaultOpen,
onShow: handleShow,
diff --git a/packages/core/src/HoverCard/useHoverCard.doc.mjs b/packages/core/src/HoverCard/useHoverCard.doc.mjs
index e0f7e0c845..5578933234 100644
--- a/packages/core/src/HoverCard/useHoverCard.doc.mjs
+++ b/packages/core/src/HoverCard/useHoverCard.doc.mjs
@@ -13,6 +13,7 @@ export const docs = {
{name: 'hideDelay', type: 'number', description: 'Delay before hiding after mouse or focus leaves, in milliseconds.', default: '200'},
{name: 'focusTrigger', type: "'auto' | 'always' | 'never'", description: 'When focus should open the hover card. auto only attaches focus listeners to naturally focusable elements.', default: "'auto'"},
{name: 'isEnabled', type: 'boolean', description: 'Whether hover and focus triggers are enabled.', default: 'true'},
+ {name: 'label', type: 'string', description: 'Accessible name for the hover card popup. When provided, the popup is exposed as a named role="dialog"; when omitted, it falls back to role="group" (a group may validly be unnamed).'},
{name: 'isOpen', type: 'boolean', description: 'Controlled open state. true force-shows, false force-hides, undefined lets hover/focus manage visibility.'},
{name: 'isDefaultOpen', type: 'boolean', description: 'Whether the hover card should be shown on mount.', default: 'false'},
{name: 'onShow', type: '() => void', description: 'Callback fired when the hover card becomes visible.'},
@@ -52,6 +53,7 @@ export const docsDense = {
hideDelay: 'hide delay after mouse/focus leave in ms.',
focusTrigger: 'when focus opens hover card; auto = naturally focusable elements only.',
isEnabled: 'whether hover/focus triggers are enabled.',
+ label: 'accessible name for popup. with label: named role="dialog"; without: role="group".',
isOpen: 'controlled open state: true force-show, false force-hide, undefined unmanaged.',
isDefaultOpen: 'show on mount.',
onShow: 'fires when hover card becomes visible.',
diff --git a/packages/core/src/HoverCard/useHoverCard.tsx b/packages/core/src/HoverCard/useHoverCard.tsx
index 423487f5c1..6942d0abb3 100644
--- a/packages/core/src/HoverCard/useHoverCard.tsx
+++ b/packages/core/src/HoverCard/useHoverCard.tsx
@@ -119,6 +119,15 @@ export interface HoverCardOptions {
*/
isEnabled?: boolean;
+ /**
+ * Accessible name for the hover card popup.
+ *
+ * When provided, the popup is exposed to assistive technology as a named
+ * `role="dialog"`. When omitted, the popup falls back to `role="group"` —
+ * a group may validly be unnamed, an unnamed dialog may not.
+ */
+ label?: string;
+
/**
* Controlled open state. When provided, overrides hover/focus triggers:
* - `true`: force-show the hover card (hover/focus hide is suppressed)
@@ -250,6 +259,7 @@ export function useHoverCard(options: HoverCardOptions = {}): HoverCardReturn {
hideDelay = 200,
focusTrigger = 'auto',
isEnabled = true,
+ label,
isOpen,
isDefaultOpen = false,
onShow,
@@ -462,7 +472,11 @@ export function useHoverCard(options: HoverCardOptions = {}): HoverCardReturn {
const renderProps = {
placement: renderPlacement,
alignment: props?.alignment ?? alignment,
- role: 'dialog',
+ // A named dialog when a label is provided; otherwise a group. A group
+ // may validly be unnamed, an unnamed dialog may not — and hover cards
+ // are non-modal, so group is honest semantics without a name.
+ role: label ? 'dialog' : 'group',
+ 'aria-label': label || undefined,
xstyle: [popoverXstyle, layerAnimations[renderPlacement]],
// Render the layer as inline-safe phrasing markup so HoverCard stays
// valid (and hydration-stable) inside inline contexts like a `<p>`.
@@ -516,7 +530,15 @@ export function useHoverCard(options: HoverCardOptions = {}): HoverCardReturn {
renderProps,
);
},
- [layer, placement, alignment, clearTimeouts, scheduleHide, popoverXstyle],
+ [
+ layer,
+ placement,
+ alignment,
+ label,
+ clearTimeouts,
+ scheduleHide,
+ popoverXstyle,
+ ],
);
return {
diff --git a/packages/core/src/Layer/useLayer.tsx b/packages/core/src/Layer/useLayer.tsx
index a45a7e3c3a..024f62894f 100644
--- a/packages/core/src/Layer/useLayer.tsx
+++ b/packages/core/src/Layer/useLayer.tsx
@@ -100,6 +100,12 @@ export interface ContextRenderProps {
* non-hashed selector for the layer.
*/
role?: string;
+ /**
+ * Accessible name applied to the popover container via `aria-label`.
+ * Pair with `role` so layers with a named role (e.g. `'dialog'`) expose a
+ * proper name to assistive technology.
+ */
+ 'aria-label'?: string;
/**
* StyleX styles for the popover container.
*/
@@ -525,6 +531,7 @@ export function useLayer(
alignment = 'center',
positioning = 'anchor',
role,
+ 'aria-label': ariaLabel,
xstyle,
className: extraClassName,
style: extraStyle,
@@ -561,6 +568,7 @@ export function useLayer(
ref={popoverRefCallback}
id={id}
role={role}
+ aria-label={ariaLabel}
popover={lightDismiss ? 'auto' : 'manual'}
className={combinedClassName}
style={{...stylexResult.style, ...anchorStyle, ...extraStyle}}