Skip to content

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

TypeScript

fix(topnav): use Popover API + CSS anchor positioning for mega menu (#412)

Cindy Zhang0ca39294920e
diff --git a/apps/storybook/stories/TopNavMenu.stories.tsx b/apps/storybook/stories/TopNavMenu.stories.tsx
new file mode 100644
index 0000000000..c9787a4199
--- /dev/null
+++ b/apps/storybook/stories/TopNavMenu.stories.tsx
@@ -0,0 +1,284 @@
+import {useState} from 'react';
+import type {Meta, StoryObj} from '@storybook/react';
+import {
+ XDSTopNav,
+ XDSTopNavTitle,
+ XDSTopNavItem,
+ XDSTopNavMenu,
+ XDSTopNavMegaMenu,
+} from '@xds/core/TopNav';
+import {XDSNavIcon} from '@xds/core/NavIcon';
+import {XDSButton} from '@xds/core/Button';
+import {
+ CubeIcon,
+ ChartBarIcon,
+ ShieldCheckIcon,
+ BoltIcon,
+ CodeBracketIcon,
+ GlobeAltIcon,
+ UserCircleIcon,
+ MagnifyingGlassIcon,
+} from '@heroicons/react/24/outline';
+
+// =============================================================================
+// TopNavMenu Stories
+// =============================================================================
+
+const menuMeta: Meta<typeof XDSTopNavMenu> = {
+ title: 'Navigation/XDSTopNavMenu',
+ component: XDSTopNavMenu,
+ tags: ['autodocs'],
+ parameters: {
+ layout: 'fullscreen',
+ },
+};
+
+export default menuMeta;
+type Story = StoryObj<typeof XDSTopNavMenu>;
+
+/**
+ * Basic hover-triggered nav menu with 4 items, each with icon, title,
+ * and description.
+ */
+export const Default: Story = {
+ render: () => (
+ <XDSTopNav
+ label="Main navigation"
+ title={
+ <XDSTopNavTitle
+ title="My App"
+ logo={
+ <XDSNavIcon icon={<CubeIcon style={{width: 16, height: 16}} />} />
+ }
+ href="#"
+ />
+ }
+ startContent={
+ <>
+ <XDSTopNavItem label="Home" href="#" isSelected />
+ <XDSTopNavMenu
+ label="Products"
+ items={[
+ {
+ title: 'Analytics',
+ description: 'Track and analyze user behavior',
+ icon: <ChartBarIcon style={{width: 20, height: 20}} />,
+ href: '#analytics',
+ },
+ {
+ title: 'Security',
+ description: 'Enterprise-grade protection',
+ icon: <ShieldCheckIcon style={{width: 20, height: 20}} />,
+ href: '#security',
+ },
+ {
+ title: 'Automation',
+ description: 'Streamline your workflows',
+ icon: <BoltIcon style={{width: 20, height: 20}} />,
+ href: '#automation',
+ },
+ {
+ title: 'Developer Tools',
+ description: 'APIs, SDKs, and CLI tools',
+ icon: <CodeBracketIcon style={{width: 20, height: 20}} />,
+ href: '#dev-tools',
+ },
+ ]}
+ />
+ <XDSTopNavItem label="Pricing" href="#" />
+ </>
+ }
+ endContent={
+ <XDSButton
+ label="Profile"
+ variant="ghost"
+ icon={<UserCircleIcon style={{width: 16, height: 16}} />}
+ />
+ }
+ />
+ ),
+};
+
+/**
+ * Multiple nav menus side by side. Hovering one closes the other
+ * (standard hover-menu behavior).
+ */
+export const MultipleMenus: Story = {
+ name: 'Multiple Menus',
+ render: () => (
+ <XDSTopNav
+ label="Main navigation"
+ title={<XDSTopNavTitle title="Platform" href="#" />}
+ startContent={
+ <>
+ <XDSTopNavMenu
+ label="Products"
+ items={[
+ {
+ title: 'Analytics',
+ description: 'Track behavior',
+ icon: <ChartBarIcon style={{width: 20, height: 20}} />,
+ href: '#',
+ },
+ {
+ title: 'Security',
+ description: 'Enterprise protection',
+ icon: <ShieldCheckIcon style={{width: 20, height: 20}} />,
+ href: '#',
+ },
+ ]}
+ />
+ <XDSTopNavMenu
+ label="Resources"
+ items={[
+ {title: 'Documentation', href: '#'},
+ {title: 'API Reference', href: '#'},
+ {title: 'Community Forum', href: '#'},
+ ]}
+ />
+ <XDSTopNavItem label="Pricing" href="#" />
+ </>
+ }
+ />
+ ),
+};
+
+// =============================================================================
+// TopNavMegaMenu Stories
+// =============================================================================
+
+/**
+ * Full-width mega menu with items grid and featured content area.
+ * Wrap XDSTopNav in a container with `position: relative` for
+ * correct full-width panel positioning.
+ */
+export const MegaMenu: Story = {
+ name: 'Mega Menu',
+ render: function MegaMenuStory() {
+ const [menuOpen, setMenuOpen] = useState(false);
+
+ return (
+ <div style={{position: 'relative'}}>
+ <XDSTopNav
+ label="Marketing navigation"
+ title={
+ <XDSTopNavTitle
+ title="Acme"
+ logo={
+ <XDSNavIcon
+ icon={<CubeIcon style={{width: 16, height: 16}} />}
+ />
+ }
+ href="#"
+ />
+ }
+ startContent={
+ <>
+ <XDSTopNavMegaMenu
+ label="Products"
+ onOpenChange={setMenuOpen}
+ items={[
+ {
+ title: 'Analytics',
+ description:
+ 'Track and analyze user behavior across your apps',
+ icon: <ChartBarIcon style={{width: 20, height: 20}} />,
+ href: '#analytics',
+ },
+ {
+ title: 'Security',
+ description: 'Enterprise-grade protection for your data',
+ icon: <ShieldCheckIcon style={{width: 20, height: 20}} />,
+ href: '#security',
+ },
+ {
+ title: 'Automation',
+ description: 'Streamline workflows with intelligent tools',
+ icon: <BoltIcon style={{width: 20, height: 20}} />,
+ href: '#automation',
+ },
+ {
+ title: 'Developer Tools',
+ description: 'APIs, SDKs, and CLI for integration',
+ icon: <CodeBracketIcon style={{width: 20, height: 20}} />,
+ href: '#dev-tools',
+ },
+ {
+ title: 'Global Network',
+ description: 'Low-latency edge infra in 40+ regions',
+ icon: <GlobeAltIcon style={{width: 20, height: 20}} />,
+ href: '#network',
+ },
+ ]}
+ featured={{
+ image:
+ 'https://images.unsplash.com/photo-1551434678-e076c223a692?w=560&h=280&fit=crop',
+ imageAlt: 'Team collaboration',
+ title: 'What\u2019s new in v4.0',
+ description:
+ 'AI-powered analytics and real-time collaboration.',
+ linkText: 'Read the announcement \u2192',
+ linkHref: '#announcement',
+ }}
+ />
+ <XDSTopNavItem label="Pricing" href="#" />
+ <XDSTopNavItem label="Docs" href="#" />
+ </>
+ }
+ endContent={
+ <>
+ <XDSButton label="Sign in" variant="ghost" />
+ <XDSButton label="Get started" variant="primary" />
+ </>
+ }
+ />
+ </div>
+ );
+ },
+};
+
+/**
+ * Mega menu without the featured content area — just the items grid.
+ * Uses single-column layout for fewer items.
+ */
+export const MegaMenuSimple: Story = {
+ name: 'Mega Menu (Simple)',
+ render: () => (
+ <div style={{position: 'relative'}}>
+ <XDSTopNav
+ label="Simple navigation"
+ title={<XDSTopNavTitle title="App" href="#" />}
+ startContent={
+ <>
+ <XDSTopNavItem label="Home" href="#" isSelected />
+ <XDSTopNavMegaMenu
+ label="Features"
+ isSingleColumn
+ items={[
+ {
+ title: 'Dashboard',
+ description: 'Overview of your key metrics',
+ icon: <ChartBarIcon style={{width: 20, height: 20}} />,
+ href: '#',
+ },
+ {
+ title: 'Integrations',
+ description: 'Connect with your favorite tools',
+ icon: <CodeBracketIcon style={{width: 20, height: 20}} />,
+ href: '#',
+ },
+ {
+ title: 'API Access',
+ description: 'Programmatic access to all features',
+ icon: <GlobeAltIcon style={{width: 20, height: 20}} />,
+ href: '#',
+ },
+ ]}
+ />
+ </>
+ }
+ endContent={<XDSButton label="Sign in" variant="primary" />}
+ />
+ </div>
+ ),
+};
diff --git a/packages/core/src/AppShell/XDSAppShell.tsx b/packages/core/src/AppShell/XDSAppShell.tsx
index 3a891d5aa2..cc296679f9 100644
--- a/packages/core/src/AppShell/XDSAppShell.tsx
+++ b/packages/core/src/AppShell/XDSAppShell.tsx
@@ -241,7 +241,7 @@ const styles = stylex.create({
headerSticky: {
position: 'sticky',
top: 0,
- zIndex: 10,
+ zIndex: 1,
},
// Sticky sideNav for auto height mode
sideNavSticky: {
diff --git a/packages/core/src/TopNav/XDSTopNavMegaMenu.tsx b/packages/core/src/TopNav/XDSTopNavMegaMenu.tsx
index 8a46ee1f2e..999f08d12b 100644
--- a/packages/core/src/TopNav/XDSTopNavMegaMenu.tsx
+++ b/packages/core/src/TopNav/XDSTopNavMegaMenu.tsx
@@ -1,9 +1,13 @@
/**
* @file XDSTopNavMegaMenu.tsx
- * @input Uses React, StyleX, custom hover logic
+ * @input Uses React, StyleX, useXDSLayer (Popover API + CSS anchor positioning)
* @output Exports XDSTopNavMegaMenu component and related types
* @position Navigation item with hover-triggered full-width mega menu for XDSTopNav
*
+ * Uses useXDSLayer to promote the panel to the top layer via the Popover API,
+ * eliminating z-index stacking. CSS anchor positioning places the panel below
+ * the nav wrapper.
+ *
* SYNC: When modified, update these files to stay in sync:
* - /packages/core/src/TopNav/README.md
* - /packages/core/src/TopNav/index.ts
@@ -21,7 +25,9 @@ import {
textSizeVars,
fontWeightVars,
lineHeightVars,
+ elevationVars,
} from '../theme/tokens.stylex';
+import {useXDSLayer} from '../Layer';
// =============================================================================
// Styles
@@ -29,8 +35,6 @@ import {
const styles = stylex.create({
wrapper: {
- // position: static so the panel positions relative to the nearest
- // positioned ancestor (the nav bar wrapper), not this div.
position: 'static',
},
trigger: {
@@ -78,35 +82,36 @@ const styles = stylex.create({
chevronOpen: {
transform: 'rotate(180deg)',
},
- panel: {
- position: 'absolute',
- top: '100%',
- left: 0,
- right: 0,
- zIndex: 100,
- backgroundColor: colorVars['--color-surface'],
- // Top border provides a subtle divider between the nav bar and panel
- // while keeping them visually connected as one card.
+ // Animation styles applied to the layer's popover element.
+ // Uses :popover-open for enter and @starting-style for initial state.
+ panelAnimation: {
+ opacity: {
+ default: 0,
+ ':popover-open': 1,
+ },
+ transform: {
+ default: 'translateY(-4px)',
+ ':popover-open': 'translateY(0)',
+ },
+ transitionProperty: 'opacity, transform, overlay, display',
+ transitionDuration: '0.2s',
+ transitionTimingFunction: 'ease-out',
+ transitionBehavior: 'allow-discrete',
+ '@starting-style': {
+ opacity: 0,
+ transform: 'translateY(-4px)',
+ },
+ },
+ // Visual styles for the panel content container.
+ panelContainer: {
+ backgroundColor: colorVars['--color-popover'],
borderTop: `1px solid ${colorVars['--color-divider']}`,
borderTopLeftRadius: 0,
borderTopRightRadius: 0,
borderBottomLeftRadius: radiusVars['--radius-container'],
borderBottomRightRadius: radiusVars['--radius-container'],
- // Shadow wraps the panel; the wrapper handles the nav bar's card chrome.
- // Together they create a unified card appearance without a backdrop overlay.
- boxShadow: `0 8px 24px rgba(0, 0, 0, 0.12), 0 2px 8px rgba(0, 0, 0, 0.08)`,
+ boxShadow: elevationVars['--elevation-menu'],
overflow: 'hidden',
- opacity: 0,
- transform: 'translateY(-4px)',
- transitionProperty: 'opacity, transform',
- transitionDuration: '0.2s',
- transitionTimingFunction: 'ease-out',
- pointerEvents: 'none',
- },
- panelOpen: {
- opacity: 1,
- transform: 'translateY(0)',
- pointerEvents: 'auto',
},
panelContent: {
display: 'flex',
@@ -229,6 +234,11 @@ const styles = stylex.create({
backgroundColor: colorVars['--color-divider'],
flexShrink: 0,
},
+ // Anchor positioning: stretch panel to match the anchor width.
+ anchorStretch: {
+ left: 'anchor(left)' as unknown as string,
+ right: 'anchor(right)' as unknown as string,
+ },
});
// =============================================================================
@@ -324,9 +334,12 @@ function ChevronDown() {
* shows a full-width panel below the nav bar with menu items organized in
* columns and an optional featured content area on the right.
*
- * The panel positions itself relative to the nearest positioned ancestor
- * (typically the nav bar wrapper). For correct full-width behavior, wrap
- * the XDSTopNav in a container with `position: relative`.
+ * The panel is promoted to the top layer via the Popover API (through
+ * useXDSLayer) and positioned via CSS anchor positioning relative to the
+ * nearest positioned ancestor (typically the nav bar wrapper).
+ *
+ * For correct full-width behavior, wrap the XDSTopNav in a container with
+ * `position: relative`.
*
* @example
* ```
@@ -342,7 +355,7 @@ function ChevronDown() {
* featured={{
* title: 'New: AI Features',
* description: 'Explore our latest AI-powered tools.',
- * linkText: 'Learn more →',
+ * linkText: 'Learn more \u2192',
* linkHref: '/ai',
* }}
* />
@@ -365,12 +378,50 @@ export function XDSTopNavMegaMenu({
const hideTimeoutRef = useRef<ReturnType<typeof setTimeout> | null>(null);
const wrapperRef = useRef<HTMLDivElement | null>(null);
+ // useXDSLayer handles: Popover API (top layer), CSS anchor positioning,
+ // toggle event sync, and popover element rendering.
+ const layer = useXDSLayer({
+ mode: 'context',
+ lightDismiss: false, // Hover-driven, not click-to-dismiss
+ onShow: () => onOpenChange?.(true),
+ onHide: () => onOpenChange?.(false),
+ });
+
+ // Set the CSS anchor to the nearest positioned ancestor (the nav wrapper).
+ // The panel spans this element's full width.
+ useEffect(() => {
+ const wrapper = wrapperRef.current;
+ if (!wrapper) return;
+
+ let el: HTMLElement | null = wrapper.parentElement;
+ while (el) {
+ const position = getComputedStyle(el).position;
+ if (
+ position === 'relative' ||
+ position === 'absolute' ||
+ position === 'fixed'
+ ) {
+ layer.ref(el);
+ break;
+ }
+ el = el.parentElement;
+ }
+
+ return () => {
+ layer.ref(null);
+ };
+ }, [layer]);
+
const setOpen = useCallback(
(open: boolean) => {
setIsOpen(open);
- onOpenChange?.(open);
+ if (open) {
+ layer.show();
+ } else {
+ layer.hide();
+ }
},
- [onOpenChange],
+ [layer],
);
const clearTimeouts = useCallback(() => {
@@ -440,89 +491,98 @@ export function XDSTopNavMegaMenu({
<ChevronDown />
</span>
</button>
- <div
- role="menu"
- aria-label={label}
- {...stylex.props(styles.panel, isOpen && styles.panelOpen)}>
- <div {...stylex.props(styles.panelContent)}>
- {/* Menu items section */}
- <div
- {...stylex.props(
- styles.menuSection,
- isSingleColumn && styles.menuSectionSingle,
- )}>
- {items.map((item, index) => {
- const Element = item.href ? 'a' : 'div';
- return (
- <Element
- key={index}
- role="menuitem"
- tabIndex={isOpen ? 0 : -1}
- href={item.href}
- onClick={item.onClick}
- {...stylex.props(styles.menuItem)}>
- {item.icon && (
- <div {...stylex.props(styles.menuItemIcon)}>
- {item.icon}
- </div>
- )}
- <div {...stylex.props(styles.menuItemContent)}>
- <span {...stylex.props(styles.menuItemTitle)}>
- {item.title}
- </span>
- {item.description && (
- <span {...stylex.props(styles.menuItemDescription)}>
- {item.description}
- </span>
+ {layer.render(
+ <div
+ role="menu"
+ aria-label={label}
+ onMouseEnter={handleMouseEnter}
+ onMouseLeave={handleMouseLeave}
+ {...stylex.props(styles.panelContainer)}>
+ <div {...stylex.props(styles.panelContent)}>
+ {/* Menu items section */}
+ <div
+ {...stylex.props(
+ styles.menuSection,
+ isSingleColumn && styles.menuSectionSingle,
+ )}>
+ {items.map((item, index) => {
+ const Element = item.href ? 'a' : 'div';
+ return (
+ <Element
+ key={index}
+ role="menuitem"
+ tabIndex={isOpen ? 0 : -1}
+ href={item.href}
+ onClick={item.onClick}
+ {...stylex.props(styles.menuItem)}>
+ {item.icon && (
+ <div {...stylex.props(styles.menuItemIcon)}>
+ {item.icon}
+ </div>
)}
- </div>
- </Element>
- );
- })}
- </div>
-
- {/* Featured section */}
- {featured && (
- <>
- <div {...stylex.props(styles.divider)} />
- <div {...stylex.props(styles.featured)}>
- {featured.children ? (
- featured.children
- ) : (
- <>
- {featured.image && (
- <img
- src={featured.image}
- alt={featured.imageAlt ?? ''}
- {...stylex.props(styles.featuredImage)}
- />
- )}
- <div {...stylex.props(styles.featuredBody)}>
- <span {...stylex.props(styles.featuredTitle)}>
- {featured.title}
+ <div {...stylex.props(styles.menuItemContent)}>
+ <span {...stylex.props(styles.menuItemTitle)}>
+ {item.title}
</span>
- {featured.description && (
- <span {...stylex.props(styles.featuredDescription)}>
- {featured.description}
+ {item.description && (
+ <span {...stylex.props(styles.menuItemDescription)}>
+ {item.description}
</span>
)}
- {featured.linkText && (
- <a
- href={featured.linkHref}
- onClick={featured.onLinkClick}
- tabIndex={isOpen ? 0 : -1}
- {...stylex.props(styles.featuredLink)}>
- {featured.linkText}
- </a>
- )}
</div>
- </>
- )}
- </div>
- </>
- )}
- </div>
- </div>
+ </Element>
+ );
+ })}
+ </div>
+
+ {/* Featured section */}
+ {featured && (
+ <>
+ <div {...stylex.props(styles.divider)} />
+ <div {...stylex.props(styles.featured)}>
+ {featured.children ? (
+ featured.children
+ ) : (
+ <>
+ {featured.image && (
+ <img
+ src={featured.image}
+ alt={featured.imageAlt ?? ''}
+ {...stylex.props(styles.featuredImage)}
+ />
+ )}
+ <div {...stylex.props(styles.featuredBody)}>
+ <span {...stylex.props(styles.featuredTitle)}>
+ {featured.title}
+ </span>
+ {featured.description && (
+ <span {...stylex.props(styles.featuredDescription)}>
+ {featured.description}
+ </span>
+ )}
+ {featured.linkText && (
+ <a
+ href={featured.linkHref}
+ onClick={featured.onLinkClick}
+ tabIndex={isOpen ? 0 : -1}
+ {...stylex.props(styles.featuredLink)}>
+ {featured.linkText}
+ </a>
+ )}
+ </div>
+ </>
+ )}
+ </div>
+ </>
+ )}
+ </div>
+ </div>,
+ {
+ placement: 'below',
+ alignment: 'center',
+ xstyle: [styles.panelAnimation, styles.anchorStretch],
+ },
+ )}
</div>
);
}