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.mdnew file mode 100644index 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.+@bhamodidiff --git a/packages/core/src/HoverCard/HoverCard.doc.mjs b/packages/core/src/HoverCard/HoverCard.doc.mjsindex 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.tsxindex 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.tsxindex 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.mjsindex 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.tsxindex 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.tsxindex 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}}