Skip to content

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

TypeScript

fix(popover): expose wrapper role options (#4661)

Cindy Zhang11b423e960e0
diff --git a/.changeset/popover-role-option.md b/.changeset/popover-role-option.md
new file mode 100644
index 0000000000..0f37af1af7
--- /dev/null
+++ b/.changeset/popover-role-option.md
@@ -0,0 +1,6 @@
+---
+'@astryxdesign/core': patch
+---
+
+[fix] Popover: expose wrapper role and modal options so non-dialog popup content can own its semantics.
+@cixzhang
diff --git a/packages/core/src/Popover/Popover.doc.mjs b/packages/core/src/Popover/Popover.doc.mjs
index f5537d2ff1..7d1db3e034 100644
--- a/packages/core/src/Popover/Popover.doc.mjs
+++ b/packages/core/src/Popover/Popover.doc.mjs
@@ -72,6 +72,20 @@ export const docs = {
type: 'string',
description: 'Accessible label for the popover dialog.',
},
+ {
+ name: 'role',
+ type: "'dialog' | 'none'",
+ description:
+ 'ARIA role for the popover wrapper. Use dialog for dialog-style popovers; use none when content provides its own role, like menu or listbox.',
+ default: "'dialog'",
+ },
+ {
+ name: 'isModal',
+ type: 'boolean',
+ description:
+ 'Whether a dialog-style popover sets aria-modal. Only applies when role is dialog.',
+ default: 'true',
+ },
{
name: 'hasCloseButton',
type: 'boolean',
@@ -213,6 +227,20 @@ export const docsZh = {
type: 'string',
description: '弹出框对话框的无障碍标签。',
},
+ {
+ name: 'role',
+ type: "'dialog' | 'none'",
+ description:
+ '弹出框包装器的 ARIA 角色。对话框式弹出框使用 dialog;当内容提供自己的角色(如 menu 或 listbox)时使用 none。',
+ default: "'dialog'",
+ },
+ {
+ name: 'isModal',
+ type: 'boolean',
+ description:
+ '对话框式弹出框是否设置 aria-modal。仅在 role 为 dialog 时适用。',
+ default: 'true',
+ },
{
name: 'hasCloseButton',
type: 'boolean',
diff --git a/packages/core/src/Popover/Popover.test.tsx b/packages/core/src/Popover/Popover.test.tsx
index 7713741a42..23cab1e62f 100644
--- a/packages/core/src/Popover/Popover.test.tsx
+++ b/packages/core/src/Popover/Popover.test.tsx
@@ -107,6 +107,47 @@ describe('Popover', () => {
expect(dialog).toHaveAttribute('aria-label', 'Greeting');
});
+ it('can render a neutral wrapper when content owns its role', () => {
+ render(
+ <Popover
+ role="none"
+ content={
+ <div role="menu" aria-label="Actions">
+ Menu content
+ </div>
+ }
+ label="Actions">
+ <button type="button">Open</button>
+ </Popover>,
+ );
+
+ const trigger = screen.getByRole('button', {name: 'Open'});
+ expect(trigger).toHaveAttribute('aria-haspopup', 'true');
+ expect(
+ screen.queryByRole('dialog', {hidden: true}),
+ ).not.toBeInTheDocument();
+ expect(screen.getByRole('menu', {hidden: true})).toHaveAttribute(
+ 'aria-label',
+ 'Actions',
+ );
+ });
+
+ it('can render a non-modal dialog wrapper', () => {
+ render(
+ <Popover
+ role="dialog"
+ isModal={false}
+ content={<span>Hello</span>}
+ label="Greeting">
+ <button type="button">Open</button>
+ </Popover>,
+ );
+
+ const dialog = screen.getByRole('dialog', {hidden: true});
+ expect(dialog).toBeInTheDocument();
+ expect(dialog).not.toHaveAttribute('aria-modal');
+ });
+
it('calls onOpenChange when opened', () => {
const onOpenChange = vi.fn();
render(
diff --git a/packages/core/src/Popover/Popover.tsx b/packages/core/src/Popover/Popover.tsx
index aedefaf312..eb2fda32e1 100644
--- a/packages/core/src/Popover/Popover.tsx
+++ b/packages/core/src/Popover/Popover.tsx
@@ -163,10 +163,29 @@ export interface PopoverProps extends Pick<
/**
* Accessible label for the popover dialog.
- * Recommended for accessibility (used as aria-label on the dialog).
+ * Recommended for accessibility when `role` is `'dialog'`.
*/
label?: string;
+ /**
+ * ARIA role stamped on the popover content wrapper.
+ *
+ * Use `'dialog'` for dialog-style popovers. Use `'none'` when the popup
+ * content owns its own role, such as a child `role="menu"` or
+ * `role="listbox"`.
+ *
+ * @default 'dialog'
+ */
+ role?: 'dialog' | 'none';
+
+ /**
+ * Whether a dialog-style popover is modal (`aria-modal`). Only applies when
+ * `role` is `'dialog'`.
+ *
+ * @default true
+ */
+ isModal?: boolean;
+
/**
* Whether to include a hidden close button for accessibility.
* The button appears when keyboard users tab past the last element.
@@ -293,6 +312,8 @@ export function Popover({
isEnabled = true,
width,
label,
+ role = 'dialog',
+ isModal,
hasCloseButton,
closeButtonLabel,
hasAutoFocus,
@@ -320,6 +341,8 @@ export function Popover({
const popover = usePopover({
dialogLabel: label,
+ role,
+ isModal,
hasLightDismiss,
hasEscapeDismiss,
hasCloseButton,