An open source design system that's fully customizable and agent ready
TypeScript
feat(TopNav): mobile responsive rendering (#565) (#652)
Cindy Zhanga1ff924be6fd
diff --git a/packages/core/src/AppShell/XDSAppShell.tsx b/packages/core/src/AppShell/XDSAppShell.tsxindex 877cd959d6..151af29800 100644--- a/packages/core/src/AppShell/XDSAppShell.tsx+++ b/packages/core/src/AppShell/XDSAppShell.tsx@@ -40,6 +40,8 @@ import {XDSLayoutContent} from '../Layout/XDSLayoutContent';import {XDSMobileNav} from '../MobileNav/XDSMobileNav';import {XDSMobileNavToggle} from '../MobileNav/XDSMobileNavToggle';import {XDSSideNavRenderContext} from '../SideNav/XDSSideNavRenderContext';+import {XDSTopNavRenderContext} from '../TopNav/XDSTopNavRenderContext';+import {XDSTopNavMobileContentContext} from '../TopNav/XDSTopNavMobileContentContext';import {XDSAppShellMobileContext} from './XDSAppShellMobileContext';import type {XDSAppShellMobileContextValue} from './XDSAppShellMobileContext';import type {SpacingStep} from '../utils/types';@@ -553,7 +555,7 @@ export function XDSAppShell({// efficient and does not over-trigger.// =========================================================================useEffect(() => {- if (sideNavBreakpoint === 'none' || !hasSideNav) return;+ if (sideNavBreakpoint === 'none' || !hasNavContent) return;const breakpointPx = BREAKPOINT_VALUES[sideNavBreakpoint];const mql = window.matchMedia(`(max-width: ${breakpointPx}px)`);@@ -568,7 +570,7 @@ export function XDSAppShell({mql.addEventListener('change', handleChange);return () => mql.removeEventListener('change', handleChange);- }, [sideNavBreakpoint, hasSideNav]);+ }, [sideNavBreakpoint, hasNavContent]);// =========================================================================// Determine if sideNav should show as overlay (mobile) or inline@@ -577,16 +579,25 @@ export function XDSAppShell({// Three mobile nav rendering modes:// 1. ReactNode shorthand — render the user's element as-is (they own the drawer)const shouldRenderMobileNavReactNode = mobileNavReactNode != null;- // 2. Config with custom content — render inside AppShell-managed drawer+ // 2. Config with custom content — render directlyconst shouldRenderConfigContent =mobileNavEnabled && mobileNavConfigContent != null && isBelowBreakpoint;- // 3. Auto — wrap sideNav content in a managed drawer+ // 3. Auto — render nav content in drawer modeconst shouldRenderAutoMobileNav =mobileNavEnabled &&!mobileNavReactNode &&!mobileNavConfigContent &&isBelowBreakpoint &&- hasSideNav;+ hasNavContent;+ // TopNav-only auto mobile (no SideNav) — TopNav handles its own drawer+ const shouldRenderTopNavDrawer =+ shouldRenderAutoMobileNav && hasTopNav && !hasSideNav;+ // TopNav + SideNav combined — TopNav owns drawer, SideNav content via context+ const shouldRenderCombinedDrawer =+ shouldRenderAutoMobileNav && hasTopNav && hasSideNav;+ // SideNav-only auto mobile (no TopNav) — SideNav handles its own drawer+ const shouldRenderSideNavDrawer =+ shouldRenderAutoMobileNav && !hasTopNav && hasSideNav;// =========================================================================// Mobile context — shared with XDSMobileNavToggle and future TopNav mobile@@ -610,6 +621,17 @@ export function XDSAppShell({// stays pinned while the page scrolls. The ref is used to measure header// height for the sideNav's sticky offset.// =========================================================================+ // When below breakpoint, TopNav renders in mobile-bar mode (heading + endContent + toggle)+ const topNavContent = hasTopNav ? (+ isBelowBreakpoint && mobileNavEnabled ? (+ <XDSTopNavRenderContext value="mobile-bar">+ {topNav}+ </XDSTopNavRenderContext>+ ) : (+ topNav+ )+ ) : null;+const headerInner =hasTopNav || hasBanner ? (<XDSLayoutHeader@@ -617,7 +639,7 @@ export function XDSAppShell({hasDivider={navHasDividers && hasTopNav}xstyle={navAreaStyle}>{hasBanner && <div {...stylex.props(styles.banner)}>{banner}</div>}- {hasTopNav && topNav}+ {topNavContent}</XDSLayoutHeader>) : undefined;@@ -763,13 +785,32 @@ export function XDSAppShell({content={mainContent}/>- {/* Mobile nav — three modes:+ {/* Mobile nav — rendering modes:1. ReactNode shorthand: render user's element as-is- 2. Config content: render inside AppShell-managed drawer- 3. Auto: wrap sideNav in a managed drawer */}+ 2. Config content: render directly+ 3. TopNav-only: TopNav renders its own drawer+ 4. TopNav+SideNav: TopNav owns drawer, SideNav passed via context+ 5. SideNav-only: SideNav renders its own drawer */}{shouldRenderMobileNavReactNode && mobileNavReactNode}{shouldRenderConfigContent && mobileNavConfigContent}- {shouldRenderAutoMobileNav && (+ {shouldRenderTopNavDrawer && (+ <XDSTopNavRenderContext value="drawer">+ {topNav}+ </XDSTopNavRenderContext>+ )}+ {shouldRenderCombinedDrawer && (+ <XDSTopNavMobileContentContext+ value={+ <XDSSideNavRenderContext value="drawer-content">+ {sideNav}+ </XDSSideNavRenderContext>+ }>+ <XDSTopNavRenderContext value="drawer">+ {topNav}+ </XDSTopNavRenderContext>+ </XDSTopNavMobileContentContext>+ )}+ {shouldRenderSideNavDrawer && (<XDSSideNavRenderContext value="drawer">{sideNav}</XDSSideNavRenderContext>diff --git a/packages/core/src/SideNav/XDSSideNav.tsx b/packages/core/src/SideNav/XDSSideNav.tsxindex 043783d594..aa60181aed 100644--- a/packages/core/src/SideNav/XDSSideNav.tsx+++ b/packages/core/src/SideNav/XDSSideNav.tsx@@ -308,6 +308,20 @@ export function XDSSideNav({);}+ // =========================================================================+ // Drawer-content mode — render just items (no XDSMobileNav wrapper)+ // Used when TopNav owns the drawer and SideNav items are nested inside+ // =========================================================================+ if (renderMode === 'drawer-content') {+ return (+ <>+ {topContent}+ {children}+ {footer}+ </>+ );+ }+// =========================================================================// Default mode — full sidebar// =========================================================================diff --git a/packages/core/src/SideNav/XDSSideNavRenderContext.ts b/packages/core/src/SideNav/XDSSideNavRenderContext.tsindex dd0ca498fd..01e4fdf62c 100644--- a/packages/core/src/SideNav/XDSSideNavRenderContext.ts+++ b/packages/core/src/SideNav/XDSSideNavRenderContext.ts@@ -13,7 +13,11 @@import {createContext, useContext} from 'react';-export type XDSSideNavRenderMode = 'default' | 'topbar' | 'drawer';+export type XDSSideNavRenderMode =+ | 'default'+ | 'topbar'+ | 'drawer'+ | 'drawer-content';export const XDSSideNavRenderContext =createContext<XDSSideNavRenderMode>('default');diff --git a/packages/core/src/TopNav/XDSTopNav.tsx b/packages/core/src/TopNav/XDSTopNav.tsxindex 4880a72b71..81313b9381 100644--- a/packages/core/src/TopNav/XDSTopNav.tsx+++ b/packages/core/src/TopNav/XDSTopNav.tsx@@ -20,6 +20,10 @@ import {colorVars, spacingVars} from '../theme/tokens.stylex';import {edgeSignals} from '../Layout/edgeCompensation.stylex';import {xdsClassName, mergeProps} from '../utils';import {TopNavSlotContext} from './TopNavContext';+import {useXDSTopNavRenderMode} from './XDSTopNavRenderContext';+import {useXDSTopNavMobileContent} from './XDSTopNavMobileContentContext';+import {XDSMobileNav} from '../MobileNav/XDSMobileNav';+import {XDSMobileNavToggle} from '../MobileNav/XDSMobileNavToggle';/*** Base TopNav styles@@ -81,6 +85,30 @@ const styles = stylex.create({flexShrink: 0,marginInlineStart: 'auto',},+ // Mobile bar mode — simplified top bar with heading + toggle + endContent+ mobileBar: {+ display: 'flex',+ alignItems: 'center',+ width: '100%',+ height: spacingVars['--spacing-12'],+ paddingInline: spacingVars['--spacing-4'],+ boxSizing: 'border-box',+ },+ mobileBarEnd: {+ display: 'flex',+ alignItems: 'center',+ gap: spacingVars['--spacing-1'],+ marginInlineStart: 'auto',+ },+ // Drawer mode — vertical list of nav items+ drawerItems: {+ display: 'flex',+ flexDirection: 'column',+ gap: spacingVars['--spacing-0-5'],+ },+ drawerExtraContent: {+ marginBlockStart: spacingVars['--spacing-4'],+ },});export interface XDSTopNavProps extends XDSBaseProps<HTMLElement> {@@ -144,7 +172,64 @@ export function XDSTopNav({ref,...props}: XDSTopNavProps) {+ const renderMode = useXDSTopNavRenderMode();+ const mobileContent = useXDSTopNavMobileContent();const hasCenterContent = centerContent != null;+ const hasCollapsibleContent = startContent != null || centerContent != null;++ // =========================================================================+ // Mobile bar mode — heading + endContent + toggle, hide nav items+ // =========================================================================+ if (renderMode === 'mobile-bar') {+ return (+ <nav+ ref={ref}+ role="navigation"+ aria-label={label}+ {...mergeProps(+ xdsClassName('top-nav', {mode: 'mobile-bar'}),+ stylex.props(styles.mobileBar, xstyle),+ className,+ style,+ )}+ {...props}>+ {heading && <div {...stylex.props(styles.heading)}>{heading}</div>}+ <div {...stylex.props(styles.mobileBarEnd)}>+ {endContent}+ {hasCollapsibleContent && <XDSMobileNavToggle />}+ </div>+ </nav>+ );+ }++ // =========================================================================+ // Drawer mode — render nav items vertically inside a MobileNav,+ // plus any additional content passed via context (e.g. SideNav items)+ // =========================================================================+ if (renderMode === 'drawer') {+ // Only render if there are collapsible items or extra content+ if (!hasCollapsibleContent && !mobileContent) return null;++ return (+ <XDSMobileNav header={heading}>+ {hasCollapsibleContent && (+ <div {...stylex.props(styles.drawerItems)}>+ {startContent}+ {centerContent}+ </div>+ )}+ {mobileContent && (+ <div {...stylex.props(styles.drawerExtraContent)}>+ {mobileContent}+ </div>+ )}+ </XDSMobileNav>+ );+ }++ // =========================================================================+ // Default mode — full top bar+ // =========================================================================return (<navdiff --git a/packages/core/src/TopNav/XDSTopNavItem.tsx b/packages/core/src/TopNav/XDSTopNavItem.tsxindex 923a81027b..d947e6f2e6 100644--- a/packages/core/src/TopNav/XDSTopNavItem.tsx+++ b/packages/core/src/TopNav/XDSTopNavItem.tsx@@ -27,6 +27,7 @@ import {} from '../theme/tokens.stylex';import {useXDSLinkComponent} from '../Link/useXDSLinkComponent';import type {XDSLinkComponentType} from '../Link/types';+import {useXDSTopNavRenderMode} from './XDSTopNavRenderContext';import {xdsClassName, mergeProps} from '../utils';/**@@ -83,6 +84,44 @@ const styles = stylex.create({iconOnly: {paddingInline: spacingVars['--spacing-2'],},+ // Drawer mode — SideNavItem-style vertical list element+ drawerItem: {+ display: 'flex',+ alignItems: 'center',+ gap: spacingVars['--spacing-3'],+ width: '100%',+ 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',+ boxSizing: 'border-box',+ backgroundColor: {+ default: 'transparent',+ ':hover': {+ '@media (hover: hover)': colorVars['--color-hover-overlay'],+ },+ ':active': colorVars['--color-pressed-overlay'],+ },+ outline: {+ default: null,+ ':focus-visible': `2px solid ${colorVars['--color-focus-outline']}`,+ },+ },+ drawerItemSelected: {+ color: colorVars['--color-text-primary'],+ fontWeight: fontWeightVars['--font-weight-semibold'],+ backgroundColor: {+ default: colorVars['--color-deemphasized'],+ ':hover': {+ '@media (hover: hover)': colorVars['--color-deemphasized'],+ },+ },+ },});export interface XDSTopNavItemProps extends XDSBaseProps<HTMLAnchorElement> {@@ -164,9 +203,42 @@ export function XDSTopNavItem({...props}: XDSTopNavItemProps) {const LinkComponent = useXDSLinkComponent(as);+ const renderMode = useXDSTopNavRenderMode();const isIconOnly = icon != null && children == null && !label;const showLabel = !isIconOnly;+ // =========================================================================+ // Drawer mode — render as a SideNavItem-style vertical list element+ // =========================================================================+ if (renderMode === 'drawer') {+ return (+ <LinkComponent+ ref={ref}+ aria-current={isSelected ? 'page' : undefined}+ aria-disabled={isDisabled || undefined}+ tabIndex={isDisabled ? -1 : undefined}+ {...mergeProps(+ xdsClassName('top-nav-item', {mode: 'drawer'}),+ stylex.props(+ styles.drawerItem,+ isSelected && styles.drawerItemSelected,+ isDisabled && styles.disabled,+ xstyle,+ ),+ className,+ style,+ )}+ {...props}>+ {icon}+ {children ?? label}+ </LinkComponent>+ );+ }++ // =========================================================================+ // Default / mobile-bar mode — standard horizontal nav item+ // =========================================================================+return (<LinkComponentref={ref}diff --git a/packages/core/src/TopNav/XDSTopNavMobileContentContext.ts b/packages/core/src/TopNav/XDSTopNavMobileContentContext.tsnew file mode 100644index 0000000000..d72c1de7ce--- /dev/null+++ b/packages/core/src/TopNav/XDSTopNavMobileContentContext.ts@@ -0,0 +1,22 @@+/**+ * @file XDSTopNavMobileContentContext.ts+ * @input React createContext, useContext+ * @output Exports XDSTopNavMobileContentContext and useXDSTopNavMobileContent+ * @position Internal context for passing additional drawer content to TopNav+ *+ * When both TopNav and SideNav exist, AppShell passes the SideNav content+ * to TopNav via this context. TopNav renders it below its own items in the+ * mobile drawer, producing a single combined drawer.+ */++import {createContext, useContext, type ReactNode} from 'react';++export const XDSTopNavMobileContentContext = createContext<ReactNode>(null);++/**+ * Read additional mobile drawer content provided by AppShell.+ * Returns null when no additional content is available.+ */+export function useXDSTopNavMobileContent(): ReactNode {+ return useContext(XDSTopNavMobileContentContext);+}diff --git a/packages/core/src/TopNav/XDSTopNavRenderContext.ts b/packages/core/src/TopNav/XDSTopNavRenderContext.tsnew file mode 100644index 0000000000..d95c190f5e--- /dev/null+++ b/packages/core/src/TopNav/XDSTopNavRenderContext.ts@@ -0,0 +1,26 @@+/**+ * @file XDSTopNavRenderContext.ts+ * @input React createContext, useContext+ * @output Exports XDSTopNavRenderContext and useXDSTopNavRenderMode hook+ * @position Internal context for controlling TopNav rendering mode+ *+ * When AppShell renders TopNav in multiple locations (top bar, mobile drawer),+ * this context tells TopNav and its children which parts to render:+ * - 'default': full top bar (desktop)+ * - 'mobile-bar': heading + endContent + toggle, hide nav items (mobile top bar)+ * - 'drawer': nav items as vertical list elements (mobile drawer)+ */++import {createContext, useContext} from 'react';++export type XDSTopNavRenderMode = 'default' | 'mobile-bar' | 'drawer';++export const XDSTopNavRenderContext =+ createContext<XDSTopNavRenderMode>('default');++/**+ * Read the current TopNav render mode from context.+ */+export function useXDSTopNavRenderMode(): XDSTopNavRenderMode {+ return useContext(XDSTopNavRenderContext);+}diff --git a/packages/core/src/TopNav/index.ts b/packages/core/src/TopNav/index.tsindex 97e2901404..6ef476f07c 100644--- a/packages/core/src/TopNav/index.ts+++ b/packages/core/src/TopNav/index.ts@@ -25,3 +25,9 @@ export type {XDSTopNavMegaMenuItemData,XDSTopNavMegaMenuFeatured,} from './XDSTopNavMegaMenu';++export {+ XDSTopNavRenderContext,+ useXDSTopNavRenderMode,+} from './XDSTopNavRenderContext';+export type {XDSTopNavRenderMode} from './XDSTopNavRenderContext';