Skip to content

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

TypeScript

fix(core): correct nav heading popover menu semantics (#3995)

Baraa Hamodi3bc9c8a07481
diff --git a/.changeset/navheading-popover-semantics.md b/.changeset/navheading-popover-semantics.md
new file mode 100644
index 0000000000..253a111513
--- /dev/null
+++ b/.changeset/navheading-popover-semantics.md
@@ -0,0 +1,7 @@
+---
+'@astryxdesign/core': patch
+---
+
+[fix] SideNav/TopNav: collapsed heading popovers no longer wrap their menus in a modal dialog, and the heading button is no longer an invalid child of the menu.
+
+@bhamodi
diff --git a/packages/core/src/SideNav/SideNav.test.tsx b/packages/core/src/SideNav/SideNav.test.tsx
index b7905e93d9..063aba4a15 100644
--- a/packages/core/src/SideNav/SideNav.test.tsx
+++ b/packages/core/src/SideNav/SideNav.test.tsx
@@ -337,7 +337,9 @@ describe('SideNavHeading', () => {
it('whole heading is popover trigger when menu provided without hrefs', () => {
render(<SideNavHeading heading="My App" menu={<div>Menu</div>} />);
const button = screen.getByRole('button');
- expect(button).toHaveAttribute('aria-haspopup', 'dialog');
+ // The popup is no longer a dialog (role: 'none' on usePopover), so the
+ // trigger advertises a generic popup rather than aria-haspopup="dialog".
+ expect(button).toHaveAttribute('aria-haspopup', 'true');
expect(button).toHaveAttribute('aria-expanded', 'false');
});
@@ -351,7 +353,7 @@ describe('SideNavHeading', () => {
const button = screen.getByRole('button');
// The trigger button uses aria attributes from usePopover and
// an onClick handler from useMenuHover for click-to-lock toggle.
- expect(button).toHaveAttribute('aria-haspopup', 'dialog');
+ expect(button).toHaveAttribute('aria-haspopup', 'true');
expect(button).toHaveAttribute('aria-expanded');
});
@@ -364,13 +366,92 @@ describe('SideNavHeading', () => {
/>,
);
const button = screen.getByRole('button', {name: 'Open menu'});
- expect(button).toHaveAttribute('aria-haspopup', 'dialog');
+ expect(button).toHaveAttribute('aria-haspopup', 'true');
});
it('passes data-testid', () => {
render(<SideNavHeading heading="My App" data-testid="nav-header" />);
expect(screen.getByTestId('nav-header')).toBeInTheDocument();
});
+
+ // ===========================================================================
+ // Menu popover semantics — the popup must not be announced as a modal
+ // dialog, and role="menu" must be scoped to the actual menu items so the
+ // heading button is not an invalid child of the menu.
+ // ===========================================================================
+
+ // The popover layer keeps `popover` content display:none in jsdom even
+ // when open, hiding it from role queries — so these tests assert the
+ // popup's ARIA semantics at the DOM level instead.
+ describe('menu popover semantics', () => {
+ const menuItems = (
+ <>
+ <div role="menuitem">Alpha</div>
+ <div role="menuitem">Beta</div>
+ </>
+ );
+
+ it('does not wrap the heading menu popup in a modal dialog', async () => {
+ const user = userEvent.setup();
+ render(<SideNavHeading heading="My App" menu={menuItems} />);
+ await user.click(screen.getByRole('button', {name: 'Open menu'}));
+ expect(document.querySelector('[role="dialog"]')).toBeNull();
+ expect(document.querySelector('[aria-modal="true"]')).toBeNull();
+ });
+
+ it('scopes role="menu" to only menuitem children with an accessible name', async () => {
+ const user = userEvent.setup();
+ render(<SideNavHeading heading="My App" menu={menuItems} />);
+ await user.click(screen.getByRole('button', {name: 'Open menu'}));
+ const menu = document.querySelector('[role="menu"]');
+ expect(menu).not.toBeNull();
+ expect(menu).toHaveAttribute('aria-label', 'My App');
+ const children = Array.from(menu!.children);
+ expect(children.length).toBeGreaterThan(0);
+ for (const child of children) {
+ expect(child).toHaveAttribute('role', 'menuitem');
+ }
+ });
+
+ it('keeps the popup heading button outside the menu and closes on click', async () => {
+ const user = userEvent.setup();
+ render(<SideNavHeading heading="My App" menu={menuItems} />);
+ const trigger = screen.getByRole('button', {name: 'Open menu'});
+ await user.click(trigger);
+ expect(trigger).toHaveAttribute('aria-expanded', 'true');
+ const menu = document.querySelector('[role="menu"]');
+ expect(menu).not.toBeNull();
+ // The heading replica button in the popup is a sibling of the menu,
+ // not an invalid menu child.
+ const headingButton = Array.from(
+ document.querySelectorAll('button'),
+ ).find(b => b !== trigger && b.textContent?.includes('My App'));
+ expect(headingButton).toBeDefined();
+ expect(menu!.contains(headingButton!)).toBe(false);
+ // Clicking it still closes the popup.
+ fireEvent.click(headingButton!);
+ expect(trigger).toHaveAttribute('aria-expanded', 'false');
+ });
+
+ it('applies the same semantics in mixed mode (menu + hrefs)', async () => {
+ const user = userEvent.setup();
+ render(
+ <SideNavHeading
+ heading="Product"
+ headingHref="/product"
+ menu={menuItems}
+ />,
+ );
+ await user.click(screen.getByRole('button', {name: 'Open menu'}));
+ expect(document.querySelector('[role="dialog"]')).toBeNull();
+ const menu = document.querySelector('[role="menu"]');
+ expect(menu).not.toBeNull();
+ expect(menu).toHaveAttribute('aria-label', 'Product');
+ for (const child of Array.from(menu!.children)) {
+ expect(child).toHaveAttribute('role', 'menuitem');
+ }
+ });
+ });
});
// =============================================================================
@@ -476,6 +557,41 @@ describe('SideNavHeading collapsed', () => {
);
expect(screen.getByTestId('nav-header')).toBeInTheDocument();
});
+
+ it('collapsed menu popup is not a dialog and scopes role="menu" to menu items', async () => {
+ const user = userEvent.setup();
+ render(
+ <CollapsedWrapper>
+ <SideNavHeading
+ heading="My App"
+ icon={<span data-testid="app-icon">🏠</span>}
+ menu={
+ <>
+ <div role="menuitem">Alpha</div>
+ <div role="menuitem">Beta</div>
+ </>
+ }
+ />
+ </CollapsedWrapper>,
+ );
+ await user.click(screen.getByRole('button', {name: 'My App'}));
+ // No modal dialog wrapper around the menu popup.
+ expect(document.querySelector('[role="dialog"]')).toBeNull();
+ expect(document.querySelector('[aria-modal="true"]')).toBeNull();
+ // role="menu" is scoped to the menu items and has a direct name.
+ const menu = document.querySelector('[role="menu"]');
+ expect(menu).not.toBeNull();
+ expect(menu).toHaveAttribute('aria-label', 'My App');
+ const children = Array.from(menu!.children);
+ expect(children.length).toBeGreaterThan(0);
+ for (const child of children) {
+ expect(child).toHaveAttribute('role', 'menuitem');
+ }
+ // No button (trigger or heading replica) lives inside the menu.
+ for (const button of Array.from(document.querySelectorAll('button'))) {
+ expect(menu!.contains(button)).toBe(false);
+ }
+ });
});
// =============================================================================
diff --git a/packages/core/src/SideNav/SideNavHeading.tsx b/packages/core/src/SideNav/SideNavHeading.tsx
index 84943937c1..911c5a8044 100644
--- a/packages/core/src/SideNav/SideNavHeading.tsx
+++ b/packages/core/src/SideNav/SideNavHeading.tsx
@@ -351,6 +351,10 @@ export function SideNavHeading({
const popover = usePopover({
dialogLabel: t('@astryx.sideNav.heading.dialogLabel'),
+ // The popup exposes its own role="menu" semantics; a role="dialog"
+ // aria-modal wrapper would announce "dialog, Navigation menu" around a
+ // menu (the anti-pattern removed in a478a3dcf).
+ role: 'none',
hasCloseButton: false,
});
@@ -428,7 +432,6 @@ export function SideNavHeading({
{popover.render(
<div
ref={menuRef}
- role="menu"
{...stylex.props(styles.popoverContent)}
{...contentProps}>
<button
@@ -461,9 +464,14 @@ export function SideNavHeading({
)}
</span>
</button>
- <NavHeadingCloseContext value={closeMenuCtx}>
- {menu}
- </NavHeadingCloseContext>
+ {/* The menu role is scoped to the actual menu items so the
+ heading button above stays a valid sibling, not an invalid
+ child of a role="menu" element. */}
+ <div role="menu" aria-label={heading}>
+ <NavHeadingCloseContext value={closeMenuCtx}>
+ {menu}
+ </NavHeadingCloseContext>
+ </div>
</div>,
{placement: 'below', alignment: 'start', xstyle: styles.popover},
)}
@@ -620,11 +628,15 @@ export function SideNavHeading({
{popover.render(
<div
ref={menuRef}
- role="menu"
{...stylex.props(styles.popoverContent)}
{...contentProps}>
{popoverHeadingContent}
- {menu}
+ {/* The menu role is scoped to the actual menu items so the
+ heading button above stays a valid sibling, not an invalid
+ child of a role="menu" element. */}
+ <div role="menu" aria-label={heading}>
+ {menu}
+ </div>
</div>,
{
placement: 'below',
@@ -683,11 +695,15 @@ export function SideNavHeading({
{popover.render(
<div
ref={menuRef}
- role="menu"
{...stylex.props(styles.popoverContent)}
{...contentProps}>
{popoverHeadingContent}
- {menu}
+ {/* The menu role is scoped to the actual menu items so the
+ heading button above stays a valid sibling, not an invalid
+ child of a role="menu" element. */}
+ <div role="menu" aria-label={heading}>
+ {menu}
+ </div>
</div>,
{
placement: 'below',
diff --git a/packages/core/src/TopNav/TopNav.test.tsx b/packages/core/src/TopNav/TopNav.test.tsx
index f8d17d67c0..dc8b4e2d93 100644
--- a/packages/core/src/TopNav/TopNav.test.tsx
+++ b/packages/core/src/TopNav/TopNav.test.tsx
@@ -10,7 +10,7 @@
*/
import {describe, it, expect, vi} from 'vitest';
-import {render, screen} from '@testing-library/react';
+import {fireEvent, render, screen} from '@testing-library/react';
import userEvent from '@testing-library/user-event';
import {TopNav} from './TopNav';
import {TopNavRenderContext} from './TopNavRenderContext';
@@ -297,6 +297,85 @@ describe('TopNavHeading', () => {
render(<TopNavHeading heading="Test" ref={ref} />);
expect(ref).toHaveBeenCalledWith(expect.any(HTMLElement));
});
+
+ // ===========================================================================
+ // Menu popover semantics — the popup must not be announced as a modal
+ // dialog, and role="menu" must be scoped to the actual menu items so the
+ // heading button is not an invalid child of the menu.
+ // ===========================================================================
+
+ // The popover layer keeps `popover` content display:none in jsdom even
+ // when open, hiding it from role queries — so these tests assert the
+ // popup's ARIA semantics at the DOM level instead.
+ describe('menu popover semantics', () => {
+ const menuItems = (
+ <>
+ <div role="menuitem">Alpha</div>
+ <div role="menuitem">Beta</div>
+ </>
+ );
+
+ it('does not wrap the heading menu popup in a modal dialog', async () => {
+ const user = userEvent.setup();
+ render(<TopNavHeading heading="My App" menu={menuItems} />);
+ await user.click(screen.getByRole('button', {name: 'Open menu'}));
+ expect(document.querySelector('[role="dialog"]')).toBeNull();
+ expect(document.querySelector('[aria-modal="true"]')).toBeNull();
+ });
+
+ it('scopes role="menu" to only menuitem children with an accessible name', async () => {
+ const user = userEvent.setup();
+ render(<TopNavHeading heading="My App" menu={menuItems} />);
+ await user.click(screen.getByRole('button', {name: 'Open menu'}));
+ const menu = document.querySelector('[role="menu"]');
+ expect(menu).not.toBeNull();
+ expect(menu).toHaveAttribute('aria-label', 'My App');
+ const children = Array.from(menu!.children);
+ expect(children.length).toBeGreaterThan(0);
+ for (const child of children) {
+ expect(child).toHaveAttribute('role', 'menuitem');
+ }
+ });
+
+ it('keeps the popup heading button outside the menu and closes on click', async () => {
+ const user = userEvent.setup();
+ render(<TopNavHeading heading="My App" menu={menuItems} />);
+ const trigger = screen.getByRole('button', {name: 'Open menu'});
+ await user.click(trigger);
+ expect(trigger).toHaveAttribute('aria-expanded', 'true');
+ const menu = document.querySelector('[role="menu"]');
+ expect(menu).not.toBeNull();
+ // The heading replica button in the popup is a sibling of the menu,
+ // not an invalid menu child.
+ const headingButton = Array.from(
+ document.querySelectorAll('button'),
+ ).find(b => b !== trigger && b.textContent?.includes('My App'));
+ expect(headingButton).toBeDefined();
+ expect(menu!.contains(headingButton!)).toBe(false);
+ // Clicking it still closes the popup.
+ fireEvent.click(headingButton!);
+ expect(trigger).toHaveAttribute('aria-expanded', 'false');
+ });
+
+ it('applies the same semantics in mixed mode (menu + hrefs)', async () => {
+ const user = userEvent.setup();
+ render(
+ <TopNavHeading
+ heading="Product"
+ headingHref="/product"
+ menu={menuItems}
+ />,
+ );
+ await user.click(screen.getByRole('button', {name: 'Open menu'}));
+ expect(document.querySelector('[role="dialog"]')).toBeNull();
+ const menu = document.querySelector('[role="menu"]');
+ expect(menu).not.toBeNull();
+ expect(menu).toHaveAttribute('aria-label', 'Product');
+ for (const child of Array.from(menu!.children)) {
+ expect(child).toHaveAttribute('role', 'menuitem');
+ }
+ });
+ });
});
describe('NavIcon', () => {
diff --git a/packages/core/src/TopNav/TopNavHeading.tsx b/packages/core/src/TopNav/TopNavHeading.tsx
index 6247e6b145..7455272023 100644
--- a/packages/core/src/TopNav/TopNavHeading.tsx
+++ b/packages/core/src/TopNav/TopNavHeading.tsx
@@ -332,6 +332,10 @@ export function TopNavHeading({
const popover = usePopover({
dialogLabel: t('@astryx.topNav.heading.dialogLabel'),
+ // The popup exposes its own role="menu" semantics; a role="dialog"
+ // aria-modal wrapper would announce "dialog, Navigation menu" around a
+ // menu (the anti-pattern removed in a478a3dcf).
+ role: 'none',
hasCloseButton: false,
});
@@ -511,13 +515,19 @@ export function TopNavHeading({
{popover.render(
<div
ref={menuRef}
- role="menu"
{...stylex.props(styles.popoverContent)}
{...contentProps}>
{popoverHeadingContent}
- <NavHeadingCloseContext value={closeMenuCtx}>
- {menu}
- </NavHeadingCloseContext>
+ {/* The menu role is scoped to the actual menu items so the
+ heading button above stays a valid sibling, not an invalid
+ child of a role="menu" element. */}
+ <div
+ role="menu"
+ aria-label={heading ?? t('@astryx.topNav.heading.dialogLabel')}>
+ <NavHeadingCloseContext value={closeMenuCtx}>
+ {menu}
+ </NavHeadingCloseContext>
+ </div>
</div>,
{
placement: 'below',
@@ -575,13 +585,19 @@ export function TopNavHeading({
{popover.render(
<div
ref={menuRef}
- role="menu"
{...stylex.props(styles.popoverContent)}
{...contentProps}>
{popoverHeadingContent}
- <NavHeadingCloseContext value={closeMenuCtx}>
- {menu}
- </NavHeadingCloseContext>
+ {/* The menu role is scoped to the actual menu items so the
+ heading button above stays a valid sibling, not an invalid
+ child of a role="menu" element. */}
+ <div
+ role="menu"
+ aria-label={heading ?? t('@astryx.topNav.heading.dialogLabel')}>
+ <NavHeadingCloseContext value={closeMenuCtx}>
+ {menu}
+ </NavHeadingCloseContext>
+ </div>
</div>,
{
placement: 'below',