An open source design system that's fully customizable and agent ready
TypeScript
feat(TopNav): add XDSTopNavMenu with hover-triggered overflow menu (#241)
rubyycheung7255ee044547
diff --git a/apps/sandbox/src/app/Sidebar.tsx b/apps/sandbox/src/app/Sidebar.tsxindex 05e0a965c7..c867de60a7 100644--- a/apps/sandbox/src/app/Sidebar.tsx+++ b/apps/sandbox/src/app/Sidebar.tsx@@ -19,6 +19,7 @@ import {usePathname} from 'next/navigation';const pages = [{name: 'Home', href: '/'},{name: 'Example', href: '/pages/example/'},+ {name: 'TopNav Menu', href: '/pages/topnav-menu/'},];const styles = stylex.create({diff --git a/apps/sandbox/src/app/pages/topnav-menu/page.tsx b/apps/sandbox/src/app/pages/topnav-menu/page.tsxnew file mode 100644index 0000000000..c5cba84605--- /dev/null+++ b/apps/sandbox/src/app/pages/topnav-menu/page.tsx@@ -0,0 +1,174 @@+'use client';++import * as stylex from '@stylexjs/stylex';+import {XDSVStack} from '@xds/core/Layout';+import {XDSText, XDSHeading} from '@xds/core/Text';+import {XDSButton} from '@xds/core/Button';+import {+ XDSTopNav,+ XDSTopNavTitle,+ XDSTopNavTitleIcon,+ XDSTopNavItem,+ XDSTopNavMenu,+} from '@xds/core/TopNav';++const styles = stylex.create({+ container: {+ maxWidth: 960,+ },+ navWrapper: {+ borderRadius: 12,+ overflow: 'hidden',+ boxShadow: '0 1px 3px rgba(0, 0, 0, 0.08)',+ },+});++const LogoIcon = () => (+ <svg+ width="16"+ height="16"+ viewBox="0 0 24 24"+ fill="none"+ stroke="currentColor"+ strokeWidth="2"+ strokeLinecap="round"+ strokeLinejoin="round">+ <circle cx="12" cy="12" r="3" />+ <circle cx="12" cy="5" r="1.5" />+ <circle cx="18.5" cy="8.5" r="1.5" />+ <circle cx="18.5" cy="15.5" r="1.5" />+ <circle cx="12" cy="19" r="1.5" />+ <circle cx="5.5" cy="15.5" r="1.5" />+ <circle cx="5.5" cy="8.5" r="1.5" />+ </svg>+);++const PlaceholderIcon = () => (+ <svg+ width="20"+ height="20"+ viewBox="0 0 24 24"+ fill="none"+ stroke="currentColor"+ strokeWidth="1.5"+ strokeLinecap="round"+ strokeLinejoin="round">+ <rect x="3" y="3" width="18" height="18" rx="4" />+ </svg>+);++const productItems = [+ {+ title: 'Approach',+ description: 'Microbiome science for human health',+ icon: <PlaceholderIcon />,+ href: '#approach',+ },+ {+ title: 'Platform',+ description: 'End-to-end discovery and development',+ icon: <PlaceholderIcon />,+ href: '#platform',+ },+];++const scienceItems = [+ {+ title: 'Research',+ description: 'Published studies and clinical trials',+ icon: <PlaceholderIcon />,+ href: '#research',+ },+ {+ title: 'Publications',+ description: 'Peer-reviewed papers and white papers',+ icon: <PlaceholderIcon />,+ href: '#publications',+ },+ {+ title: 'Team',+ description: 'Meet our scientific advisory board',+ icon: <PlaceholderIcon />,+ href: '#team',+ },+];++/**+ * Demo page for XDSTopNavMenu — a nav item with hover-triggered overflow menu.+ */+export default function TopNavMenuPage() {+ return (+ <div {...stylex.props(styles.container)}>+ <XDSVStack gap="space6">+ <XDSVStack gap="space2">+ <XDSHeading level={1}>TopNav Menu</XDSHeading>+ <XDSText type="body" color="secondary">+ A nav item with a hover-triggered overflow menu. Hover over+ "Products" or "Science" to see the popover.+ </XDSText>+ </XDSVStack>++ {/* Marketing-style nav with overflow menus */}+ <XDSVStack gap="space3">+ <XDSHeading level={2}>Marketing Nav</XDSHeading>+ <div {...stylex.props(styles.navWrapper)}>+ <XDSTopNav+ label="Marketing navigation"+ title={+ <XDSTopNavTitle+ title="Marketing"+ logo={<XDSTopNavTitleIcon icon={<LogoIcon />} size="sm" />}+ href="#"+ />+ }+ startContent={+ <>+ <XDSTopNavMenu label="Products" items={productItems} />+ <XDSTopNavMenu label="Science" items={scienceItems} />+ <XDSTopNavItem label="Learn" href="#" />+ </>+ }+ endContent={+ <>+ <XDSButton label="Login" variant="ghost" />+ <XDSButton label="Get started" variant="primary" />+ </>+ }+ />+ </div>+ </XDSVStack>++ {/* Simple nav with one overflow menu */}+ <XDSVStack gap="space3">+ <XDSHeading level={2}>Simple Nav</XDSHeading>+ <div {...stylex.props(styles.navWrapper)}>+ <XDSTopNav+ label="Simple navigation"+ title={<XDSTopNavTitle title="App" href="#" />}+ startContent={+ <>+ <XDSTopNavItem label="Home" href="#" isSelected />+ <XDSTopNavMenu+ label="More"+ items={[+ {+ title: 'Settings',+ description: 'Configure your preferences',+ href: '#settings',+ },+ {+ title: 'Help',+ description: 'Documentation and support',+ href: '#help',+ },+ ]}+ />+ </>+ }+ />+ </div>+ </XDSVStack>+ </XDSVStack>+ </div>+ );+}diff --git a/packages/core/src/TopNav/README.md b/packages/core/src/TopNav/README.mdindex 68d1a497b7..d60c54ba51 100644--- a/packages/core/src/TopNav/README.md+++ b/packages/core/src/TopNav/README.md@@ -62,6 +62,14 @@ import {HomeIcon, BellIcon, UserCircleIcon} from '@heroicons/react/24/outline';/>;```+## Components++- **XDSTopNav** — Main navigation container+- **XDSTopNavTitle** — Title with logo and text+- **XDSTopNavTitleIcon** — Circular icon container for the title+- **XDSTopNavItem** — Navigation link item+- **XDSTopNavMenu** — Navigation item with hover-triggered overflow menu+## Props### XDSTopNav@@ -100,6 +108,25 @@ import {HomeIcon, BellIcon, UserCircleIcon} from '@heroicons/react/24/outline';| `icon` | `ReactNode` | — | Optional icon element || `children` | `ReactNode` | — | Custom content instead of label |+### XDSTopNavMenu++| Prop | Type | Default | Description |+| ----------- | ------------------------- | ------- | ------------------------------------------- |+| `label` | `string` | — | Visible label for the trigger (required) |+| `items` | `XDSTopNavMenuItemData[]` | — | Menu items to display in the hover popover |+| `delay` | `number` | `150` | Delay before showing on hover (ms) |+| `hideDelay` | `number` | `200` | Delay before hiding after mouse leaves (ms) |++#### XDSTopNavMenuItemData++| Property | Type | Description |+| ------------- | ------------ | -------------------------------- |+| `title` | `string` | Display title (required) |+| `description` | `string` | Optional description below title |+| `icon` | `ReactNode` | Optional icon on the left |+| `href` | `string` | URL to navigate to |+| `onClick` | `() => void` | Callback on click |+## ThemingThemes can override `TopNav` styles via `ComponentStyles`:@@ -124,14 +151,16 @@ const theme: Theme = {## Files-| File | Role | Purpose |-| ------------------------ | ----- | ---------------------------- |-| `index.ts` | Entry | Exports components and types |-| `XDSTopNav.tsx` | Core | Main navigation container |-| `XDSTopNavTitle.tsx` | Core | Title with logo and text |-| `XDSTopNavTitleIcon.tsx` | Core | Circular icon container |-| `XDSTopNavItem.tsx` | Core | Navigation link item |-| `XDSTopNav.test.tsx` | Test | Unit tests |+| File | Role | Purpose |+| ------------------------ | ----- | --------------------------------- |+| `index.ts` | Entry | Exports components and types |+| `XDSTopNav.tsx` | Core | Main navigation container |+| `XDSTopNavTitle.tsx` | Core | Title with logo and text |+| `XDSTopNavTitleIcon.tsx` | Core | Circular icon container |+| `XDSTopNavItem.tsx` | Core | Navigation link item |+| `XDSTopNavMenu.tsx` | Core | Nav item with hover overflow menu |+| `XDSTopNav.test.tsx` | Test | Unit tests for TopNav components |+| `XDSTopNavMenu.test.tsx` | Test | Unit tests for XDSTopNavMenu |## Layout Structurediff --git a/packages/core/src/TopNav/XDSTopNavMenu.test.tsx b/packages/core/src/TopNav/XDSTopNavMenu.test.tsxnew file mode 100644index 0000000000..ba3886e375--- /dev/null+++ b/packages/core/src/TopNav/XDSTopNavMenu.test.tsx@@ -0,0 +1,57 @@+/**+ * @file XDSTopNavMenu.test.tsx+ * @input Uses vitest, @testing-library/react, XDSTopNavMenu+ * @output Unit tests for XDSTopNavMenu component+ * @position Testing; validates XDSTopNavMenu behavior+ *+ * SYNC: When XDSTopNavMenu changes, update tests to match new behavior+ */++import {describe, it, expect} from 'vitest';+import {render, screen} from '@testing-library/react';+import {XDSTopNavMenu} from './XDSTopNavMenu';++const mockItems = [+ {+ title: 'Analytics',+ description: 'Track user behavior',+ href: '/analytics',+ },+ {+ title: 'Messaging',+ description: 'Real-time communication',+ href: '/messaging',+ },+];++describe('XDSTopNavMenu', () => {+ it('renders the trigger button with label', () => {+ render(<XDSTopNavMenu label="Products" items={mockItems} />);+ expect(screen.getByRole('button', {name: 'Products'})).toBeInTheDocument();+ });++ it('trigger has aria-haspopup attribute', () => {+ render(<XDSTopNavMenu label="Products" items={mockItems} />);+ const trigger = screen.getByRole('button', {name: 'Products'});+ expect(trigger).toHaveAttribute('aria-haspopup', 'true');+ });++ it('renders with custom items', () => {+ const items = [{title: 'Custom Item', description: 'A custom description'}];+ render(<XDSTopNavMenu label="Menu" items={items} />);+ expect(screen.getByRole('button', {name: 'Menu'})).toBeInTheDocument();+ });++ it('renders icon when provided in items', () => {+ const items = [+ {+ title: 'With Icon',+ description: 'Has an icon',+ icon: <span data-testid="menu-icon">Icon</span>,+ },+ ];+ render(<XDSTopNavMenu label="Menu" items={items} />);+ // Icon is in the hover card content, which may not be visible initially+ expect(screen.getByRole('button', {name: 'Menu'})).toBeInTheDocument();+ });+});diff --git a/packages/core/src/TopNav/XDSTopNavMenu.tsx b/packages/core/src/TopNav/XDSTopNavMenu.tsxnew file mode 100644index 0000000000..fff938fc9e--- /dev/null+++ b/packages/core/src/TopNav/XDSTopNavMenu.tsx@@ -0,0 +1,278 @@+/**+ * @file XDSTopNavMenu.tsx+ * @input Uses React, StyleX, useXDSHoverCard, XDSTopNavItem tokens+ * @output Exports XDSTopNavMenu component and related types+ * @position Navigation item with hover-triggered overflow menu for XDSTopNav+ *+ * SYNC: When modified, update these files to stay in sync:+ * - /packages/core/src/TopNav/README.md+ * - /packages/core/src/TopNav/XDSTopNavMenu.test.tsx+ * - /packages/core/src/TopNav/index.ts+ */++import {type ReactNode} from 'react';+import * as stylex from '@stylexjs/stylex';+import {useXDSHoverCard} from '../Layer/useXDSHoverCard';+import {+ colorVars,+ spacingVars,+ radiusVars,+ transitionVars,+ textSizeVars,+ fontWeightVars,+ lineHeightVars,+} from '../theme/tokens.stylex';++// =============================================================================+// Styles+// =============================================================================++const styles = stylex.create({+ trigger: {+ display: 'inline-flex',+ alignItems: 'center',+ gap: spacingVars['--spacing-2'],+ paddingBlock: spacingVars['--spacing-2'],+ paddingInline: spacingVars['--spacing-3'],+ borderRadius: radiusVars['--radius-element'],+ fontSize: textSizeVars['--text-base'],+ lineHeight: lineHeightVars['--leading-base'],+ fontWeight: fontWeightVars['--font-weight-medium'],+ color: colorVars['--color-text-secondary'],+ textDecoration: 'none',+ cursor: 'pointer',+ transitionProperty: 'background-color, color',+ transitionDuration: transitionVars['--transition-fast'],+ backgroundColor: {+ default: 'transparent',+ ':hover': colorVars['--color-hover-overlay'],+ },+ outline: {+ default: null,+ ':focus-visible': `2px solid ${colorVars['--color-focus-outline']}`,+ },+ outlineOffset: {+ default: '0',+ ':focus-visible': '2px',+ },+ border: 'none',+ fontFamily: 'inherit',+ },+ menuContainer: {+ display: 'flex',+ flexDirection: 'column',+ gap: spacingVars['--spacing-2'],+ minWidth: 280,+ },+ menuItem: {+ display: 'flex',+ alignItems: 'center',+ gap: spacingVars['--spacing-3'],+ paddingBlock: spacingVars['--spacing-3'],+ paddingInline: spacingVars['--spacing-3'],+ borderRadius: radiusVars['--radius-element'],+ textDecoration: 'none',+ cursor: 'pointer',+ transitionProperty: 'background-color',+ transitionDuration: transitionVars['--transition-fast'],+ backgroundColor: {+ default: 'transparent',+ ':hover': colorVars['--color-hover-overlay'],+ },+ border: 'none',+ outline: {+ default: null,+ ':focus-visible': `2px solid ${colorVars['--color-focus-outline']}`,+ },+ outlineOffset: {+ default: '0',+ ':focus-visible': '2px',+ },+ },+ menuItemIcon: {+ display: 'flex',+ alignItems: 'center',+ justifyContent: 'center',+ width: 40,+ height: 40,+ borderRadius: radiusVars['--radius-element'],+ backgroundColor: colorVars['--color-deemphasized'],+ flexShrink: 0,+ },+ menuItemContent: {+ display: 'flex',+ flexDirection: 'column',+ gap: spacingVars['--spacing-1'],+ minWidth: 0,+ },+ menuItemTitle: {+ fontSize: textSizeVars['--text-base'],+ lineHeight: lineHeightVars['--leading-base'],+ fontWeight: fontWeightVars['--font-weight-semibold'],+ color: colorVars['--color-text-primary'],+ },+ menuItemDescription: {+ fontSize: textSizeVars['--text-sm'],+ lineHeight: lineHeightVars['--leading-snug'],+ fontWeight: fontWeightVars['--font-weight-normal'],+ color: colorVars['--color-text-secondary'],+ },+});++// =============================================================================+// Types+// =============================================================================++/**+ * An item in the TopNav overflow menu.+ */+export interface XDSTopNavMenuItemData {+ /**+ * Display title for the menu item.+ */+ title: string;++ /**+ * Optional description text displayed below the title.+ */+ description?: string;++ /**+ * Optional icon element displayed to the left.+ */+ icon?: ReactNode;++ /**+ * URL to navigate to when clicked.+ */+ href?: string;++ /**+ * Callback when item is clicked.+ */+ onClick?: () => void;+}++export interface XDSTopNavMenuProps {+ /**+ * The visible label for the nav item trigger.+ */+ label: string;++ /**+ * Menu items to display in the hover popover.+ */+ items: XDSTopNavMenuItemData[];++ /**+ * Delay before showing the menu on hover (ms).+ * @default 150+ */+ delay?: number;++ /**+ * Delay before hiding the menu after mouse leaves (ms).+ * @default 200+ */+ hideDelay?: number;+}++// =============================================================================+// XDSTopNavMenu+// =============================================================================++/**+ * A navigation item that displays a hover-triggered overflow menu.+ *+ * Renders as a nav item in XDSTopNav's startContent slot. On hover,+ * shows a popover with rich menu items containing an icon, title,+ * and optional description.+ *+ * @example+ * ```tsx+ * <XDSTopNav+ * startContent={+ * <>+ * <XDSTopNavItem label="Home" href="/" isSelected />+ * <XDSTopNavMenu+ * label="Products"+ * items={[+ * {+ * title: 'Analytics',+ * description: 'Track and analyze user behavior',+ * icon: <ChartBarIcon />,+ * href: '/products/analytics',+ * },+ * {+ * title: 'Messaging',+ * description: 'Real-time communication tools',+ * icon: <ChatBubbleIcon />,+ * href: '/products/messaging',+ * },+ * ]}+ * />+ * </>+ * }+ * />+ * ```+ */+export function XDSTopNavMenu({+ label,+ items,+ delay = 150,+ hideDelay = 200,+}: XDSTopNavMenuProps) {+ const hoverCard = useXDSHoverCard({+ placement: 'below',+ alignment: 'start',+ delay,+ hideDelay,+ focusTrigger: 'always',+ });++ return (+ <>+ <button+ ref={hoverCard.ref}+ type="button"+ aria-haspopup="true"+ aria-describedby={hoverCard.describedBy}+ {...stylex.props(styles.trigger)}>+ {label}+ </button>+ {hoverCard.renderHoverCard(+ <div+ role="menu"+ aria-label={label}+ {...stylex.props(styles.menuContainer)}>+ {items.map((item, index) => {+ const Element = item.href ? 'a' : 'div';+ return (+ <Element+ key={index}+ role="menuitem"+ tabIndex={0}+ href={item.href}+ onClick={item.onClick}+ {...stylex.props(styles.menuItem)}>+ <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>+ )}+ </div>+ </Element>+ );+ })}+ </div>,+ )}+ </>+ );+}++XDSTopNavMenu.displayName = 'XDSTopNavMenu';diff --git a/packages/core/src/TopNav/index.ts b/packages/core/src/TopNav/index.tsindex 4adcc6e240..345db63bcb 100644--- a/packages/core/src/TopNav/index.ts+++ b/packages/core/src/TopNav/index.ts@@ -21,3 +21,6 @@ export type {export {XDSTopNavItem} from './XDSTopNavItem';export type {XDSTopNavItemProps} from './XDSTopNavItem';++export {XDSTopNavMenu} from './XDSTopNavMenu';+export type {XDSTopNavMenuProps, XDSTopNavMenuItemData} from './XDSTopNavMenu';