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.tsxnew file mode 100644index 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.tsxindex 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 modesideNavSticky: {diff --git a/packages/core/src/TopNav/XDSTopNavMegaMenu.tsx b/packages/core/src/TopNav/XDSTopNavMegaMenu.tsxindex 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>);}