An open source design system that's fully customizable and agent ready
TypeScript
fix(popover): stop announcing listbox/menu popups as modal dialogs (#3350)
Cindy Zhanga478a3dcf46e
diff --git a/.changeset/popover-role-modality.md b/.changeset/popover-role-modality.mdnew file mode 100644index 0000000000..43ebaa8398--- /dev/null+++ b/.changeset/popover-role-modality.md@@ -0,0 +1,6 @@+---+'@astryxdesign/core': patch+---++[fix] usePopover: add a `role` (`'dialog' | 'none'`) and `isModal` option so listbox and menu popups no longer announce a false modal dialog. Selector, MultiSelector, BaseTypeahead, PowerSearch, DropdownMenu, TabMenu, and the Chat mention menu now expose their own `listbox`/`menu` role instead of being wrapped in `role="dialog" aria-modal="true"` while focus stays on the trigger. Genuine dialog popovers are unchanged (#3343).+@cixzhangdiff --git a/packages/core/src/Chat/useTriggerMenu.tsx b/packages/core/src/Chat/useTriggerMenu.tsxindex d9d0427712..b1733078b3 100644--- a/packages/core/src/Chat/useTriggerMenu.tsx+++ b/packages/core/src/Chat/useTriggerMenu.tsx@@ -296,6 +296,9 @@ export function useTriggerMenu(hasLightDismiss: true,hasCloseButton: false,hasAutoFocus: false,+ // The popup's own role="listbox" is the exposed semantics; focus stays in+ // the contenteditable composer, so a modal dialog wrapper is incorrect.+ role: 'none',});// Cleanup on unmountdiff --git a/packages/core/src/DropdownMenu/DropdownMenu.test.tsx b/packages/core/src/DropdownMenu/DropdownMenu.test.tsxindex 266b5e37f6..8093964182 100644--- a/packages/core/src/DropdownMenu/DropdownMenu.test.tsx+++ b/packages/core/src/DropdownMenu/DropdownMenu.test.tsx@@ -63,6 +63,22 @@ describe('DropdownMenu', () => {expect(screen.getByRole('menu', {hidden: true})).toBeInTheDocument();});+ it('does not wrap the menu in a role="dialog" aria-modal element', () => {+ render(+ <DropdownMenu+ button={{label: 'Actions'}}+ items={[{label: 'Item 1'}]}+ />,+ );+ // The popup exposes its own role="menu"; it must not be nested inside a+ // modal dialog, which would announce an unnamed dialog around the menu+ // while focus stays on the trigger.+ expect(screen.queryByRole('dialog', {hidden: true})).not.toBeInTheDocument();+ expect(+ document.querySelector('[aria-modal="true"]'),+ ).not.toBeInTheDocument();+ });+it('defaults menu placement below', () => {render(<DropdownMenudiff --git a/packages/core/src/DropdownMenu/DropdownMenu.tsx b/packages/core/src/DropdownMenu/DropdownMenu.tsxindex 7e8d3ec69e..d26eb8c080 100644--- a/packages/core/src/DropdownMenu/DropdownMenu.tsx+++ b/packages/core/src/DropdownMenu/DropdownMenu.tsx@@ -249,6 +249,9 @@ export function DropdownMenu({hasLightDismiss: true,hasCloseButton: false,hasAutoFocus: false,+ // The popup's own role="menu" is the exposed semantics; wrapping it in a+ // modal dialog would announce an unnamed dialog around the menu.+ role: 'none',});const closeMenu = useCallback(() => {diff --git a/packages/core/src/MultiSelector/MultiSelector.tsx b/packages/core/src/MultiSelector/MultiSelector.tsxindex 0929862acf..31b3ec0c20 100644--- a/packages/core/src/MultiSelector/MultiSelector.tsx+++ b/packages/core/src/MultiSelector/MultiSelector.tsx@@ -696,7 +696,9 @@ export function MultiSelector<T extends MultiSelectorOptionType>({onHide: handleLayerHide,hasCloseButton: false,hasAutoFocus: false,- dialogLabel: `${label} options`,+ // The popup's own role="listbox" is the exposed semantics; the trigger+ // keeps DOM focus, so wrapping it in a modal dialog would misrepresent it.+ role: 'none',});// Open dropdown on mount when isDefaultOpen is truediff --git a/packages/core/src/Popover/usePopover.doc.mjs b/packages/core/src/Popover/usePopover.doc.mjsindex 50fc57fa48..684f7d01c3 100644--- a/packages/core/src/Popover/usePopover.doc.mjs+++ b/packages/core/src/Popover/usePopover.doc.mjs@@ -14,7 +14,9 @@ export const docs = {{name: 'hasAutoFocus', type: 'boolean', description: 'Whether to automatically focus the first focusable element when opened.', default: 'true'},{name: 'hasCloseButton', type: 'boolean', description: 'Whether to include a hidden close button that appears for keyboard users.', default: 'true'},{name: 'closeButtonLabel', type: 'string', description: 'Accessible label for the hidden close button.', default: "'Close popover'"},- {name: 'dialogLabel', type: 'string', description: 'Accessible label for the popover dialog. Provide one when there is no visible title.'},+ {name: 'dialogLabel', type: 'string', description: 'Accessible label for the popover dialog (only applies when role is "dialog"). Provide one when there is no visible title.'},+ {name: 'role', type: "'dialog' | 'none'", description: 'ARIA role on the content wrapper. Use "dialog" for genuine dialog content; use "none" for listbox/menu popups whose own content role should be exposed and whose trigger keeps DOM focus.', default: "'dialog'"},+ {name: 'isModal', type: 'boolean', description: 'Whether a dialog-role popover is modal (aria-modal). Only applies when role is "dialog".', default: 'true'},{name: 'hasSurface', type: 'boolean', description: 'Whether to apply the default popover surface background, radius, and shadow.', default: 'true'},],returns: [@@ -27,7 +29,7 @@ export const docs = {{name: 'isOpen', type: 'boolean', description: 'Whether the popover is currently open.'},{name: 'id', type: 'string', description: 'Unique ID for aria-describedby or aria-controls.'},{name: 'render', type: '(children: ReactNode, props?: ContextRenderProps) => ReactNode', description: 'Render function for anchor-positioned popover content. Pass placement and alignment here.'},- {name: 'triggerProps', type: '{aria-haspopup: "dialog"; aria-expanded: boolean; aria-controls: string}', description: 'ARIA attributes to spread onto the trigger element.'},+ {name: 'triggerProps', type: '{aria-haspopup: "dialog" | "true"; aria-expanded: boolean; aria-controls: string}', description: 'ARIA attributes to spread onto the trigger element. aria-haspopup reflects the popover role.'},],usage: {description: 'Headless hook for click-triggered popovers with focus trapping. Combines useLayer with useFocusTrap, auto-focus, light dismiss, Escape handling, and an optional hidden close button for accessible dialog-like popover behavior. Use for custom interactive floating content that needs keyboard navigation.',@@ -54,7 +56,9 @@ export const docsDense = {hasAutoFocus: 'whether first focusable element receives focus on open.',hasCloseButton: 'whether hidden keyboard close button is included.',closeButtonLabel: 'label for hidden close button.',- dialogLabel: 'accessible label for popover dialog.',+ dialogLabel: 'accessible label for popover dialog (role="dialog" only).',+ role: 'content wrapper ARIA role; "none" for listbox/menu popups.',+ isModal: 'whether a dialog-role popover is modal (aria-modal).',hasSurface: 'apply default surface background/radius/shadow.',},returnDescriptions: {diff --git a/packages/core/src/Popover/usePopover.tsx b/packages/core/src/Popover/usePopover.tsxindex e9a52ff4f1..d0ffd2b668 100644--- a/packages/core/src/Popover/usePopover.tsx+++ b/packages/core/src/Popover/usePopover.tsx@@ -130,10 +130,35 @@ export interface UsePopoverOptions {/*** Accessible label for the dialog.- * Required for screen readers to announce the dialog purpose.+ * Required for screen readers to announce the dialog purpose+ * (only applies when `role` is `'dialog'`).*/dialogLabel?: string;+ /**+ * ARIA role stamped on the popover content wrapper.+ *+ * - `'dialog'` (default): the wrapper is a `role="dialog"` and, when+ * `isModal` is true, carries `aria-modal`. Use for genuine dialog content.+ * - `'none'`: the wrapper carries no role or `aria-modal`, so the popup's own+ * content role (e.g. a child `role="listbox"` or `role="menu"`) is the+ * exposed semantics. Use for comboboxes, listboxes, and menus — their+ * trigger keeps DOM focus, so announcing an unnamed modal dialog around+ * them is incorrect.+ *+ * @default 'dialog'+ */+ role?: 'dialog' | 'none';++ /**+ * Whether the dialog is modal (`aria-modal`). Only applies when `role` is+ * `'dialog'`. Set to `false` for non-modal dialogs that do not inert the rest+ * of the page.+ *+ * @default true+ */+ isModal?: boolean;+/*** Whether to apply the default popover surface (background, border-radius,* box-shadow) to the content wrapper.@@ -215,7 +240,7 @@ export interface UsePopoverReturn {* ARIA attributes to spread on the trigger element*/triggerProps: {- 'aria-haspopup': 'dialog';+ 'aria-haspopup': 'dialog' | 'true';'aria-expanded': boolean;'aria-controls': string;};@@ -274,6 +299,8 @@ export function usePopover(hasCloseButton = true,closeButtonLabel = 'Close popover',dialogLabel,+ role = 'dialog',+ isModal = true,} = options;// Track the trigger element for returning focus@@ -339,20 +366,34 @@ export function usePopover(// ARIA attributes for the triggerconst triggerProps = {- 'aria-haspopup': 'dialog' as const,+ 'aria-haspopup': role === 'dialog' ? ('dialog' as const) : ('true' as const),'aria-expanded': layer.isOpen,'aria-controls': layer.id,};+ // Dev-time guardrail: a dialog popover should always be labeled. Warn once+ // per hook instance (in an effect) rather than on every render.+ const warnedUnnamedDialogRef = useRef(false);+ useEffect(() => {+ if (role === 'dialog' && !dialogLabel && !warnedUnnamedDialogRef.current) {+ warnedUnnamedDialogRef.current = true;+ console.warn(+ 'usePopover: role="dialog" without a `dialogLabel` renders an unnamed ' ++ 'dialog. Pass `dialogLabel`, or use `role: "none"` for listbox/menu ' ++ 'popups whose content already carries its own role.',+ );+ }+ }, [role, dialogLabel]);+// Wrapped render function that includes surface styles and optional hidden close buttonconst render = useCallback((children: ReactNode, props?: ContextRenderProps): ReactNode => {return layer.render(<divref={contentRef}- role="dialog"- aria-modal="true"- aria-label={dialogLabel}+ role={role === 'dialog' ? 'dialog' : undefined}+ aria-modal={role === 'dialog' && isModal ? true : undefined}+ aria-label={role === 'dialog' ? dialogLabel : undefined}{...stylex.props(styles.contentWrapper,hasSurface && styles.surface,@@ -379,6 +420,8 @@ export function usePopover(closeButtonLabel,contentRef,dialogLabel,+ role,+ isModal,xstyle,],);diff --git a/packages/core/src/PowerSearch/PowerSearch.tsx b/packages/core/src/PowerSearch/PowerSearch.tsxindex ee9ec36b09..cf1f208348 100644--- a/packages/core/src/PowerSearch/PowerSearch.tsx+++ b/packages/core/src/PowerSearch/PowerSearch.tsx@@ -546,6 +546,9 @@ export function PowerSearch({hasLightDismiss: true,hasCloseButton: false,hasAutoFocus: false,+ // The popup's own listbox/menu content is the exposed semantics; focus+ // stays on the tokenizer input, so a modal dialog wrapper is incorrect.+ role: 'none',});// Wrapper that manages layer visibility and tokenizer focus alongside statediff --git a/packages/core/src/Selector/Selector.test.tsx b/packages/core/src/Selector/Selector.test.tsxindex 936d586c52..81a70fdaa9 100644--- a/packages/core/src/Selector/Selector.test.tsx+++ b/packages/core/src/Selector/Selector.test.tsx@@ -150,6 +150,25 @@ describe('Selector', () => {expect(screen.getByTestId('option-badge')).toHaveTextContent('Owner');});+ it('exposes the popup as a listbox, not a modal dialog', () => {+ render(+ <Selector+ label="Fruit"+ options={OPTIONS}+ value="Banana"+ onChange={() => {}}+ />,+ );+ // The combobox trigger keeps DOM focus; the popup must expose its own+ // role="listbox" and must not be wrapped in a role="dialog" aria-modal+ // element, which would tell AT the focused trigger is inert.+ expect(screen.getByRole('listbox', {hidden: true})).toBeInTheDocument();+ expect(screen.queryByRole('dialog', {hidden: true})).not.toBeInTheDocument();+ expect(+ document.querySelector('[aria-modal="true"]'),+ ).not.toBeInTheDocument();+ });+it('supports explicit menu placement', () => {render(<Selectordiff --git a/packages/core/src/Selector/Selector.tsx b/packages/core/src/Selector/Selector.tsxindex 43c61963c9..88fb364d0c 100644--- a/packages/core/src/Selector/Selector.tsx+++ b/packages/core/src/Selector/Selector.tsx@@ -618,6 +618,9 @@ export function Selector<T extends SelectorOptionType>(hasLightDismiss: true,hasCloseButton: false,hasAutoFocus: false,+ // The popup's own role="listbox" is the exposed semantics; the trigger+ // keeps DOM focus, so wrapping it in a modal dialog would misrepresent it.+ role: 'none',});// Open dropdown on mount when isDefaultOpen is truediff --git a/packages/core/src/TabList/TabMenu.tsx b/packages/core/src/TabList/TabMenu.tsxindex 89d233f126..19b7e41187 100644--- a/packages/core/src/TabList/TabMenu.tsx+++ b/packages/core/src/TabList/TabMenu.tsx@@ -267,6 +267,9 @@ export function TabMenu({hasLightDismiss: true,hasCloseButton: false,hasAutoFocus: false,+ // The popup's own role="menu" is the exposed semantics; a modal dialog+ // wrapper would announce an unnamed dialog around the menu.+ role: 'none',});const {listRef, handleKeyDown: handleListKeyDown} =diff --git a/packages/core/src/Typeahead/BaseTypeahead.tsx b/packages/core/src/Typeahead/BaseTypeahead.tsxindex e32c40c9ad..eb356b5573 100644--- a/packages/core/src/Typeahead/BaseTypeahead.tsx+++ b/packages/core/src/Typeahead/BaseTypeahead.tsx@@ -352,6 +352,9 @@ export const BaseTypeahead = function BaseTypeahead<T extends SearchableItem>({hasLightDismiss: true,hasCloseButton: false,hasAutoFocus: false,+ // The popup's own role="listbox" is the exposed semantics; the input keeps+ // DOM focus, so wrapping it in a modal dialog would misrepresent it.+ role: 'none',});// Show the layer, deferring past the active click if a pointer is down.