Skip to content

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

TypeScript

fix(core): correct TopNavMegaMenu popup semantics and trigger wiring (#3992)

Baraa Hamodi49cd09464910
diff --git a/.changeset/topnavmegamenu-popup-semantics.md b/.changeset/topnavmegamenu-popup-semantics.md
new file mode 100644
index 0000000000..ee956eb70b
--- /dev/null
+++ b/.changeset/topnavmegamenu-popup-semantics.md
@@ -0,0 +1,6 @@
+---
+'@astryxdesign/core': patch
+---
+
+[fix] TopNav: TopNavMegaMenu triggers now expose aria-controls, and the panel is a labeled group instead of an invalid modal-dialog-wrapped menu.
+@bhamodi
diff --git a/packages/core/src/TopNav/TopNavMegaMenu.test.tsx b/packages/core/src/TopNav/TopNavMegaMenu.test.tsx
index b87ef26b6a..e0aae0aec6 100644
--- a/packages/core/src/TopNav/TopNavMegaMenu.test.tsx
+++ b/packages/core/src/TopNav/TopNavMegaMenu.test.tsx
@@ -9,7 +9,7 @@
* SYNC: When TopNavMegaMenu changes, update tests to match new behavior
*/
-import {describe, it, expect, vi} from 'vitest';
+import {describe, it, expect, vi, beforeAll, afterAll} from 'vitest';
import {render, screen} from '@testing-library/react';
import userEvent from '@testing-library/user-event';
import {TopNavMegaMenu} from './TopNavMegaMenu';
@@ -75,6 +75,154 @@ describe('TopNavMegaMenu — default mode', () => {
});
});
+// =============================================================================
+// Popup semantics (default mode)
+// =============================================================================
+
+describe('TopNavMegaMenu — popup semantics', () => {
+ // Mock the Popover API (not implemented in jsdom).
+ const originalMatches = HTMLElement.prototype.matches;
+
+ beforeAll(() => {
+ HTMLElement.prototype.showPopover = vi.fn(function (this: HTMLElement) {
+ this.setAttribute('popover-open', '');
+ const event = new Event('toggle', {bubbles: false});
+ Object.defineProperty(event, 'newState', {value: 'open'});
+ this.dispatchEvent(event);
+ });
+ HTMLElement.prototype.hidePopover = vi.fn(function (this: HTMLElement) {
+ this.removeAttribute('popover-open');
+ const event = new Event('toggle', {bubbles: false});
+ Object.defineProperty(event, 'newState', {value: 'closed'});
+ this.dispatchEvent(event);
+ });
+ // eslint-disable-next-line @typescript-eslint/no-explicit-any
+ (HTMLElement.prototype as any).matches = function (
+ selector: string,
+ ): boolean {
+ if (selector === ':popover-open') {
+ return this.hasAttribute('popover-open');
+ }
+ return originalMatches.call(this, selector);
+ };
+ });
+
+ afterAll(() => {
+ // eslint-disable-next-line @typescript-eslint/no-explicit-any
+ (HTMLElement.prototype as any).matches = originalMatches;
+ });
+
+ it('trigger aria-controls resolves to the popup element', async () => {
+ const user = userEvent.setup();
+ render(
+ <TopNavMegaMenu
+ label="Products"
+ items={<TopNavMegaMenuItem title="Analytics" href="/analytics" />}
+ />,
+ );
+
+ const trigger = screen.getByRole('button', {name: 'Products'});
+ expect(trigger).toHaveAttribute('aria-expanded', 'false');
+
+ // aria-controls must be present and point at the real popup element.
+ const controlsId = trigger.getAttribute('aria-controls');
+ expect(controlsId).toBeTruthy();
+ const popup = document.getElementById(controlsId as string);
+ expect(popup).not.toBeNull();
+
+ await user.click(trigger);
+
+ expect(trigger).toHaveAttribute('aria-expanded', 'true');
+ // The referenced element is the popup that contains the panel content.
+ expect(popup).toContainElement(
+ screen.getByRole('group', {name: 'Products', hidden: true}),
+ );
+ });
+
+ it('does not wrap the panel in a role="dialog" aria-modal element', async () => {
+ const user = userEvent.setup();
+ render(
+ <TopNavMegaMenu
+ label="Products"
+ items={<TopNavMegaMenuItem title="Analytics" href="/analytics" />}
+ />,
+ );
+
+ await user.click(screen.getByRole('button', {name: 'Products'}));
+
+ // Focus stays on the trigger while the panel is open, so a modal dialog
+ // wrapper would tell assistive tech the focused control is inert.
+ expect(
+ screen.queryByRole('dialog', {hidden: true}),
+ ).not.toBeInTheDocument();
+ expect(document.querySelector('[aria-modal="true"]')).toBeNull();
+ });
+
+ it('does not expose role="menu" — a link grid is not an ARIA menu', async () => {
+ const user = userEvent.setup();
+ render(
+ <TopNavMegaMenu
+ label="Products"
+ items={
+ <>
+ <TopNavMegaMenuItem title="Analytics" href="/analytics" />
+ <TopNavMegaMenuItem title="Reports" href="/reports" />
+ </>
+ }
+ />,
+ );
+
+ await user.click(screen.getByRole('button', {name: 'Products'}));
+
+ // Per the WAI-ARIA APG, mega menu panels of navigation links must not use
+ // the menu role (reserved for action menus with menuitem children).
+ expect(screen.queryByRole('menu', {hidden: true})).not.toBeInTheDocument();
+ expect(screen.queryAllByRole('menuitem', {hidden: true})).toHaveLength(0);
+ });
+
+ it('exposes the panel as a labeled group', async () => {
+ const user = userEvent.setup();
+ render(
+ <TopNavMegaMenu
+ label="Products"
+ items={<TopNavMegaMenuItem title="Analytics" href="/analytics" />}
+ />,
+ );
+
+ await user.click(screen.getByRole('button', {name: 'Products'}));
+
+ expect(
+ screen.getByRole('group', {name: 'Products', hidden: true}),
+ ).toBeInTheDocument();
+ });
+
+ it('keeps item links with accessible names inside the panel', async () => {
+ const user = userEvent.setup();
+ render(
+ <TopNavMegaMenu
+ label="Products"
+ items={
+ <>
+ <TopNavMegaMenuItem title="Analytics" href="/analytics" />
+ <TopNavMegaMenuItem title="Reports" href="/reports" />
+ </>
+ }
+ />,
+ );
+
+ await user.click(screen.getByRole('button', {name: 'Products'}));
+
+ const analytics = screen.getByRole('link', {
+ name: /Analytics/,
+ hidden: true,
+ });
+ expect(analytics).toHaveAttribute('href', '/analytics');
+ expect(
+ screen.getByRole('link', {name: /Reports/, hidden: true}),
+ ).toHaveAttribute('href', '/reports');
+ });
+});
+
// =============================================================================
// Mobile-bar mode — should be hidden
// =============================================================================
diff --git a/packages/core/src/TopNav/TopNavMegaMenu.tsx b/packages/core/src/TopNav/TopNavMegaMenu.tsx
index 3efb91ccc7..6c8cbc8184 100644
--- a/packages/core/src/TopNav/TopNavMegaMenu.tsx
+++ b/packages/core/src/TopNav/TopNavMegaMenu.tsx
@@ -354,7 +354,11 @@ function DefaultMegaMenu({
}, [onOpenChange]);
const popover = usePopover({
- dialogLabel: label,
+ // role: 'none' — the panel exposes its own role="group" labeled by
+ // `label`. Focus stays on the trigger while the panel is open, so a
+ // role="dialog" aria-modal="true" wrapper would announce an unnamed
+ // modal dialog around a grid of links.
+ role: 'none',
// hasSurface: false — mega menu provides its own surface (panelContainer)
// with border-top and custom overflow. Animation is applied via the
// render() call's xstyle prop (panelAnimation), not the hook options.
@@ -434,8 +438,7 @@ function DefaultMegaMenu({
<button
ref={mergeRefs(triggerButtonRef, ref)}
type="button"
- aria-haspopup="true"
- aria-expanded={popover.isOpen}
+ {...popover.triggerProps}
onClick={handleClick}
onMouseEnter={handleMouseEnter}
onMouseLeave={handleMouseLeave}
@@ -454,7 +457,10 @@ function DefaultMegaMenu({
</button>
{popover.render(
<div
- role="menu"
+ // role="group" — a mega menu is a browsing grid of links, not an
+ // ARIA menu of menuitems (per the WAI-ARIA APG, the menu role is
+ // for action menus; link mega menus are the documented anti-case).
+ role="group"
aria-label={label}
onMouseEnter={handleMouseEnter}
onMouseLeave={handleMouseLeave}