Skip to content

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

TypeScript

feat: shell hardening batch — entry animation, TopNavMenu mobile, collapsible items (#565) (#657)

Cindy Zhang774afadb959e
diff --git a/apps/sandbox/src/app/(fullscreen)/pages/shell-lab/page.tsx b/apps/sandbox/src/app/(fullscreen)/pages/shell-lab/page.tsx
index 934deddf32..2851d84e0e 100644
--- a/apps/sandbox/src/app/(fullscreen)/pages/shell-lab/page.tsx
+++ b/apps/sandbox/src/app/(fullscreen)/pages/shell-lab/page.tsx
@@ -4,6 +4,7 @@ import {useState, useCallback} from 'react';
import * as stylex from '@stylexjs/stylex';
import {XDSAppShell} from '@xds/core/AppShell';
+import type {XDSMobileNavConfig} from '@xds/core/AppShell';
import {
XDSSideNav,
XDSSideNavHeading,
@@ -102,7 +103,6 @@ interface ShellConfig {
variant: 'wash' | 'surface' | 'section' | 'elevated';
height: 'fill' | 'auto';
sideNavBreakpoint: 'sm' | 'md' | 'lg' | 'none';
- sideNavWidth: number;
showSideNav: boolean;
showTopNav: boolean;
showBanner: boolean;
@@ -126,7 +126,6 @@ const DEFAULT_CONFIG: ShellConfig = {
variant: 'section',
height: 'fill',
sideNavBreakpoint: 'md',
- sideNavWidth: 260,
showSideNav: true,
showTopNav: true,
showBanner: false,
@@ -752,15 +751,12 @@ export default function ShellLabPage() {
}, []);
// Build the mobileNav prop based on config
- const mobileNav:
- | false
- | {hasToggle?: boolean; content?: React.ReactNode}
- | React.ReactNode
- | undefined =
+ const mobileNav: false | XDSMobileNavConfig | React.ReactNode | undefined =
config.mobileNavMode === 'disabled'
? false
: config.mobileNavMode === 'customContent'
? {
+ breakpoint: config.sideNavBreakpoint,
content: (
<XDSMobileNav header="Custom Nav" side={config.mobileNavSide}>
<XDSVStack gap={2} xstyle={styles.customSearchBar}>
@@ -804,8 +800,8 @@ export default function ShellLabPage() {
),
}
: config.mobileNavMode === 'customToggle'
- ? {hasToggle: false} // auto drawer content, but no auto toggle
- : undefined; // auto with toggle — full default behavior
+ ? {hasToggle: false, breakpoint: config.sideNavBreakpoint} // auto drawer content, but no auto toggle
+ : {breakpoint: config.sideNavBreakpoint}; // auto with breakpoint
return (
<>
@@ -813,8 +809,6 @@ export default function ShellLabPage() {
variant={config.variant}
height={config.height}
contentPadding={6}
- sideNavBreakpoint={config.sideNavBreakpoint}
- sideNavWidth={config.sideNavWidth}
topNav={
config.showTopNav ? (
<SampleTopNav
diff --git a/apps/storybook/stories/AppShell.stories.tsx b/apps/storybook/stories/AppShell.stories.tsx
index 196a420e16..35f0bec6d5 100644
--- a/apps/storybook/stories/AppShell.stories.tsx
+++ b/apps/storybook/stories/AppShell.stories.tsx
@@ -236,13 +236,7 @@ const meta: Meta<typeof XDSAppShell> = {
control: 'boolean',
description: 'Whether the side nav starts collapsed',
},
- sideNavBreakpoint: {
- control: 'radio',
- options: ['sm', 'md', 'lg', 'none'],
- },
- sideNavWidth: {
- control: 'number',
- },
+
background: {
control: 'radio',
options: ['surface', 'wash'],
diff --git a/packages/core/src/AppShell/AppShell.doc.mjs b/packages/core/src/AppShell/AppShell.doc.mjs
index 7f5bc842d5..d892bd5481 100644
--- a/packages/core/src/AppShell/AppShell.doc.mjs
+++ b/packages/core/src/AppShell/AppShell.doc.mjs
@@ -7,7 +7,7 @@ export const docs = {
features: [
'Two navigation slots: topNav (horizontal bar) and sideNav (vertical sidebar)',
'Two height modes: fill (viewport-height, independent scroll containers) and auto (page-scroll with sticky nav)',
- 'Controlled and uncontrolled sideNav collapse with responsive auto-collapse via sideNavBreakpoint',
+ 'Controlled and uncontrolled sideNav collapse with responsive auto-collapse via mobileNav breakpoint',
'Mobile: collapsed sideNav renders as an overlay with backdrop',
'Composes XDSLayout internally for automatic padding collapse, scroll containment, and slot awareness',
'Semantic HTML: <main> with role="main", SideNav with role="navigation", skip-to-content link',
@@ -213,7 +213,7 @@ const isMobile = useMediaQuery('(max-width: 768px)');
name: 'mobileNav',
type: 'ReactNode',
description:
- 'Mobile navigation slot, typically an XDSMobileNav component. Rendered when the viewport is below the sideNavBreakpoint.',
+ 'Mobile navigation configuration. Accepts false (disable), config object (tune auto behavior), or ReactNode (full custom drawer).',
},
{
name: 'banner',
@@ -244,19 +244,7 @@ const isMobile = useMediaQuery('(max-width: 768px)');
type: '(isCollapsed: boolean) => void',
description: 'Callback fired when the sideNav collapse state changes.',
},
- {
- name: 'sideNavBreakpoint',
- type: "'sm' | 'md' | 'lg' | 'none'",
- description:
- 'Viewport-width breakpoint below which the sideNav auto-collapses. Use "none" to disable responsive collapse.',
- default: "'md'",
- },
- {
- name: 'sideNavWidth',
- type: 'number',
- description: 'Width of the sideNav panel in pixels.',
- default: '260',
- },
+
{
name: 'variant',
type: "'wash' | 'surface' | 'section' | 'elevated'",
@@ -301,7 +289,7 @@ export const docsZh = {
features: [
'两个导航插槽:topNav(水平导航栏)和 sideNav(垂直侧边栏)',
'两种高度模式:fill(视口高度,独立滚动容器)和 auto(页面滚动,导航栏吸顶)',
- '受控和非受控的 sideNav 折叠,通过 sideNavBreakpoint 支持响应式自动折叠',
+ '受控和非受控的 sideNav 折叠,通过 mobileNav breakpoint 支持响应式自动折叠',
'移动端:折叠的 sideNav 以带遮罩层的浮层形式展示',
'内部组合使用 XDSLayout,自动处理内边距折叠、滚动容器和插槽感知',
'语义化 HTML:<main> 带 role="main",SideNav 带 role="navigation",跳转到内容链接',
@@ -470,7 +458,7 @@ const isMobile = useMediaQuery('(max-width: 768px)');
name: 'mobileNav',
type: 'ReactNode',
description:
- '移动端导航插槽,通常为 XDSMobileNav 组件。当视口宽度低于 sideNavBreakpoint 时渲染。',
+ '移动端导航配置。接受 false(禁用)、配置对象(调整自动行为)或 ReactNode(完全自定义抽屉)。',
},
{
name: 'banner',
@@ -557,7 +545,7 @@ export const docsDense = {
features: [
'two nav slots: topNav (horizontal bar) + sideNav (vertical sidebar)',
'two height modes: fill (viewport 100dvh, independent scroll) + auto (page-scroll w/ sticky nav)',
- 'controlled+uncontrolled sideNav collapse w/ responsive auto-collapse via sideNavBreakpoint',
+ 'controlled+uncontrolled sideNav collapse w/ responsive auto-collapse via mobileNav breakpoint',
'mobile: collapsed sideNav renders as overlay w/ backdrop',
'composes XDSLayout internally for auto padding collapse, scroll containment, slot awareness',
'semantic HTML: <main> role="main", SideNav role="navigation", skip-to-content link',
@@ -582,15 +570,13 @@ export const docsDense = {
children: 'main content area, rendered inside <main>',
topNav: 'top nav slot, typically XDSTopNav',
sideNav: 'side nav slot, typically XDSSideNav',
- mobileNav: 'mobile nav slot, typically XDSMobileNav; rendered below sideNavBreakpoint',
+ mobileNav: 'mobile nav config: false | MobileNavConfig | ReactNode',
banner: 'slot for system-wide announcements above topNav',
height:
'fill=viewport 100dvh w/ independent scroll; auto=content-driven w/ sticky nav',
isSideNavCollapsed: 'sideNav collapsed (controlled)',
defaultIsSideNavCollapsed: 'initial collapsed state (uncontrolled)',
onSideNavCollapsedChange: 'callback on sideNav collapse change',
- sideNavBreakpoint: 'auto-collapse breakpoint; "none" disables responsive collapse',
- sideNavWidth: 'sideNav panel width in px',
variant:
'nav bg style: wash=wash bg, surface=surface bg, section=dividers, elevated=wash nav w/ elevated surface content+radius',
contentPadding:
diff --git a/packages/core/src/AppShell/XDSAppShell.test.tsx b/packages/core/src/AppShell/XDSAppShell.test.tsx
index eb9367bd08..75f1fa173e 100644
--- a/packages/core/src/AppShell/XDSAppShell.test.tsx
+++ b/packages/core/src/AppShell/XDSAppShell.test.tsx
@@ -238,7 +238,7 @@ describe('XDSAppShell', () => {
it('tracks breakpoint changes', () => {
render(
- <XDSAppShell sideNav={<TestSideNav />} sideNavBreakpoint="md">
+ <XDSAppShell sideNav={<TestSideNav />} mobileNav={{breakpoint: 'md'}}>
<div>Content</div>
</XDSAppShell>,
);
@@ -247,9 +247,9 @@ describe('XDSAppShell', () => {
expect(window.matchMedia).toHaveBeenCalled();
});
- it('does not track breakpoint when sideNavBreakpoint is none', () => {
+ it('does not track breakpoint when mobileNav breakpoint is none', () => {
render(
- <XDSAppShell sideNav={<TestSideNav />} sideNavBreakpoint="none">
+ <XDSAppShell sideNav={<TestSideNav />} mobileNav={{breakpoint: 'none'}}>
<div>Content</div>
</XDSAppShell>,
);
diff --git a/packages/core/src/AppShell/XDSAppShell.tsx b/packages/core/src/AppShell/XDSAppShell.tsx
index 2d88cd672c..a2fdfa6a36 100644
--- a/packages/core/src/AppShell/XDSAppShell.tsx
+++ b/packages/core/src/AppShell/XDSAppShell.tsx
@@ -51,8 +51,6 @@ import {xdsClassName, mergeProps} from '../utils';
// Constants
// =============================================================================
-const DEFAULT_SIDENAV_WIDTH = 260;
-
const BREAKPOINT_VALUES: Record<XDSAppShellBreakpoint, number> = {
sm: 640,
md: 768,
@@ -114,6 +112,12 @@ export interface XDSMobileNavConfig {
* or raw children.
*/
content?: ReactNode;
+
+ /**
+ * Breakpoint below which mobile nav activates.
+ * @default 'md'
+ */
+ breakpoint?: XDSAppShellBreakpoint;
}
export interface XDSAppShellProps {
@@ -201,18 +205,6 @@ export interface XDSAppShellProps {
*/
sideNav?: ReactNode;
- /**
- * Breakpoint below which side nav auto-collapses.
- * @default 'md'
- */
- sideNavBreakpoint?: XDSAppShellBreakpoint;
-
- /**
- * Width of side nav when expanded (in pixels).
- * @default 260
- */
- sideNavWidth?: number;
-
/**
* Top navigation — typically an XDSTopNav.
*/
@@ -428,8 +420,6 @@ export function XDSAppShell({
height = 'fill',
mobileNav,
sideNav,
- sideNavBreakpoint = 'md',
- sideNavWidth = DEFAULT_SIDENAV_WIDTH,
topNav,
xstyle,
className,
@@ -447,6 +437,8 @@ export function XDSAppShell({
!isValidElement(mobileNav)
? (mobileNav as XDSMobileNavConfig)
: null;
+ const sideNavBreakpoint: XDSAppShellBreakpoint =
+ mobileNavConfig?.breakpoint ?? 'md';
// ReactNode shorthand — user provides <XDSMobileNav> directly as the prop
const mobileNavReactNode: ReactNode | null =
mobileNav != null &&
@@ -499,7 +491,7 @@ export function XDSAppShell({
const contentAreaStyle =
variant === 'wash'
? styles.contentBgWash
- : variant === 'elevated' && hasTopNav && hasSideNav
+ : variant === 'elevated' && hasTopNav && hasSideNav && !isBelowBreakpoint
? styles.contentBgTransparent
: variant === 'surface' || variant === 'elevated'
? styles.contentBgSurface
@@ -726,20 +718,26 @@ export function XDSAppShell({
// mode — it shows heading + footer icons horizontally, with the hamburger
const autoMobileTopBar =
shouldShowAutoToggle && !hasTopNav && hasSideNav ? (
- <XDSLayoutHeader
- padding={0}
- hasDivider={navHasDividers}
- xstyle={navAreaStyle}>
- <div
- {...stylex.props(styles.autoMobileTopBar)}
- role="navigation"
- aria-label="Mobile navigation">
- <XDSSideNavRenderContext value="topbar">
- {sideNav}
- </XDSSideNavRenderContext>
- <XDSMobileNavToggle />
- </div>
- </XDSLayoutHeader>
+ <div
+ {...stylex.props(
+ isAuto && styles.headerSticky,
+ isAuto && stickyBgStyle,
+ )}>
+ <XDSLayoutHeader
+ padding={0}
+ hasDivider={navHasDividers}
+ xstyle={navAreaStyle}>
+ <div
+ {...stylex.props(styles.autoMobileTopBar)}
+ role="navigation"
+ aria-label="Mobile navigation">
+ <XDSSideNavRenderContext value="topbar">
+ {sideNav}
+ </XDSSideNavRenderContext>
+ <XDSMobileNavToggle />
+ </div>
+ </XDSLayoutHeader>
+ </div>
) : undefined;
return (
diff --git a/packages/core/src/MobileNav/XDSMobileNav.tsx b/packages/core/src/MobileNav/XDSMobileNav.tsx
index ce1a97a3e7..450e689e24 100644
--- a/packages/core/src/MobileNav/XDSMobileNav.tsx
+++ b/packages/core/src/MobileNav/XDSMobileNav.tsx
@@ -55,6 +55,9 @@ const styles = stylex.create({
height: '100dvh',
backgroundColor: 'transparent',
overflow: 'hidden',
+ overscrollBehavior: 'contain',
+ // Prevent touch gestures (pull-to-refresh, background scroll) passing through
+ touchAction: 'none',
outline: 'none',
// Native <dialog> uses display:none when closed — we preserve that
// by only setting display when [open] via :where() selector.
@@ -68,6 +71,7 @@ const styles = stylex.create({
backdrop: {
'::backdrop': {
backgroundColor: colorVars['--color-overlay'],
+ backdropFilter: 'blur(2px)',
opacity: 0,
transition: `opacity ${SLIDE_DURATION} ${SLIDE_EASING}`,
},
@@ -145,8 +149,11 @@ const styles = stylex.create({
overflowY: 'auto',
overflowX: 'hidden',
overscrollBehavior: 'contain',
+ // Re-enable vertical touch scrolling inside the drawer content
+ // (dialog root has touch-action: none to block pull-to-refresh)
+ touchAction: 'pan-y',
paddingInline: spacingVars['--spacing-2'],
- paddingBlock: spacingVars['--spacing-1'],
+ paddingBlock: spacingVars['--spacing-2'],
},
});
@@ -307,7 +314,13 @@ export function XDSMobileNav({
if (!dialog.open) {
dialog.showModal();
}
+ // Prevent background scrolling and iOS pull-to-refresh.
+ // overflow: clip avoids creating a scroll container (unlike hidden),
+ // so there's no scroll bounce and no need to save/restore scroll position.
+ document.documentElement.style.overflow = 'clip';
} else if (dialog.open) {
+ document.documentElement.style.overflow = '';
+
const duration = window.matchMedia('(prefers-reduced-motion: reduce)')
.matches
? 10
@@ -321,6 +334,7 @@ export function XDSMobileNav({
if (closeTimeoutRef.current) {
clearTimeout(closeTimeoutRef.current);
}
+ document.documentElement.style.overflow = '';
};
}, [isOpen]);
@@ -363,8 +377,9 @@ export function XDSMobileNav({
xstyle,
),
)}>
- {/* Drawer panel */}
+ {/* Drawer panel — tabIndex so showModal() focuses the drawer, not the close button */}
<div
+ tabIndex={-1}
{...stylex.props(
styles.drawer,
dynamicStyles.width(width),
@@ -385,7 +400,6 @@ export function XDSMobileNav({
<XDSButton
variant="ghost"
label="Close navigation"
- tooltip="Close"
icon={<XDSIcon icon="close" color="inherit" />}
onClick={() => onOpenChange(false)}
/>
diff --git a/packages/core/src/NavItem/index.ts b/packages/core/src/NavItem/index.ts
new file mode 100644
index 0000000000..a41d71770e
--- /dev/null
+++ b/packages/core/src/NavItem/index.ts
@@ -0,0 +1 @@
+export {navItemStyles} from './navItemStyles.stylex';
diff --git a/packages/core/src/NavItem/navItemStyles.stylex.ts b/packages/core/src/NavItem/navItemStyles.stylex.ts
new file mode 100644
index 0000000000..abcb79324c
--- /dev/null
+++ b/packages/core/src/NavItem/navItemStyles.stylex.ts
@@ -0,0 +1,95 @@
+/**
+ * @file navItemStyles.stylex.ts
+ * @input Uses theme tokens (color, spacing, radius, typography, transition)
+ * @output Exports shared nav item appearance styles
+ * @position Shared styles consumed by SideNavItem, TopNavItem (drawer mode),
+ * TopNavMenu (drawer mode), and any custom nav items that need to match.
+ *
+ * Centralizes the nav item appearance (layout, colors, hover/active/selected states,
+ * disabled state) so all nav-like components stay in sync — especially important
+ * when TopNav items render inside MobileNav drawers alongside SideNav items.
+ *
+ * Individual components layer their own overrides (e.g. collapsed mode, indentation,
+ * focus outlines) via stylex.props composition.
+ */
+
+import * as stylex from '@stylexjs/stylex';
+import {
+ colorVars,
+ spacingVars,
+ radiusVars,
+ textSizeVars,
+ fontWeightVars,
+ lineHeightVars,
+} from '../theme/tokens.stylex';
+
+/**
+ * Base styles shared by all nav item components.
+ * Apply as a foundation and override specific properties as needed.
+ *
+ * @example
+ * ```
+ * import {navItemStyles} from '@xds/core/navItemStyles';
+ *
+ * const styles = stylex.create({
+ * indented: { paddingInlineStart: spacingVars['--spacing-6'] },
+ * });
+ *
+ * <a {...stylex.props(navItemStyles.item, styles.indented)}>
+ * Dashboard
+ * </a>
+ * ```
+ */
+export const navItemStyles = stylex.create({
+ /** Base interactive nav item — layout, typography, hover/active states */
+ item: {
+ display: 'flex',
+ alignItems: 'center',
+ gap: spacingVars['--spacing-2'],
+ width: '100%',
+ paddingInline: spacingVars['--spacing-2'],
+ paddingBlock: spacingVars['--spacing-2'],
+ borderRadius: radiusVars['--radius-element'],
+ borderWidth: 0,
+ borderStyle: 'none',
+ backgroundColor: 'transparent',
+ color: colorVars['--color-text-primary'],
+ textDecoration: 'none',
+ cursor: 'pointer',
+ fontFamily: 'inherit',
+ fontSize: textSizeVars['--text-base'],
+ fontWeight: fontWeightVars['--font-weight-normal'],
+ lineHeight: lineHeightVars['--leading-base'],
+ textAlign: 'start',
+ boxSizing: 'border-box',
+ ':hover': {
+ '@media (hover: hover)': {
+ backgroundColor: colorVars['--color-hover-overlay'],
+ },
+ },
+ ':active': {
+ backgroundColor: colorVars['--color-pressed-overlay'],
+ },
+ },
+
+ /** Selected/active page indicator — deemphasized background, medium weight */
+ selected: {
+ backgroundColor: colorVars['--color-deemphasized'],
+ fontWeight: fontWeightVars['--font-weight-medium'],
+ ':hover': {
+ '@media (hover: hover)': {
+ backgroundColor: colorVars['--color-deemphasized'],
+ },
+ },
+ ':active': {
+ backgroundColor: colorVars['--color-deemphasized'],
+ },
+ },
+
+ /** Disabled state — muted color, no interaction */
+ disabled: {
+ color: colorVars['--color-text-disabled'],
+ cursor: 'not-allowed',
+ pointerEvents: 'none' as const,
+ },
+});
diff --git a/packages/core/src/SideNav/XDSSideNav.tsx b/packages/core/src/SideNav/XDSSideNav.tsx
index aa60181aed..8891a45fc2 100644
--- a/packages/core/src/SideNav/XDSSideNav.tsx
+++ b/packages/core/src/SideNav/XDSSideNav.tsx
@@ -111,6 +111,20 @@ const styles = stylex.create({
borderBlockStart: 'none',
paddingBlockStart: 0,
},
+ // Drawer footer — pushed to bottom of the scrollable content area
+ drawerFooter: {
+ display: 'flex',
+ flexDirection: 'column',
+ marginBlockStart: 'auto',
+ gap: spacingVars['--spacing-2'],
+ paddingBlockStart: spacingVars['--spacing-2'],
+ borderBlockStart: `1px solid ${colorVars['--color-divider']}`,
+ },
+ drawerFooterIcons: {
+ display: 'flex',
+ alignItems: 'center',
+ gap: spacingVars['--spacing-1'],
+ },
// Topbar mode — horizontal layout for mobile top bar
topbar: {
display: 'flex',
@@ -119,7 +133,6 @@ const styles = stylex.create({
justifyContent: 'space-between',
height: 48,
width: '100%',
- paddingInline: spacingVars['--spacing-2'],
backgroundColor: 'inherit',
boxSizing: 'border-box',
overflow: 'hidden',
@@ -298,12 +311,23 @@ export function XDSSideNav({
// =========================================================================
// Drawer mode — render inside XDSMobileNav with heading as header
// =========================================================================
+ const hasDrawerFooter = !!(footer || footerIcons);
+
if (renderMode === 'drawer') {
return (
<XDSMobileNav header={header} data-testid={testId}>
{topContent}
{children}
- {footer}
+ {hasDrawerFooter && (
+ <div {...stylex.props(styles.drawerFooter)}>
+ {footer}
+ {footerIcons && (
+ <div {...stylex.props(styles.drawerFooterIcons)}>
+ {footerIcons}
+ </div>
+ )}
+ </div>
+ )}
</XDSMobileNav>
);
}
@@ -317,7 +341,16 @@ export function XDSSideNav({
<>
{topContent}
{children}
- {footer}
+ {hasDrawerFooter && (
+ <div {...stylex.props(styles.drawerFooter)}>
+ {footer}
+ {footerIcons && (
+ <div {...stylex.props(styles.drawerFooterIcons)}>
+ {footerIcons}
+ </div>
+ )}
+ </div>
+ )}
</>
);
}
diff --git a/packages/core/src/SideNav/XDSSideNavItem.tsx b/packages/core/src/SideNav/XDSSideNavItem.tsx
index 92369589aa..3f9518b4f1 100644
--- a/packages/core/src/SideNav/XDSSideNavItem.tsx
+++ b/packages/core/src/SideNav/XDSSideNavItem.tsx
@@ -15,7 +15,7 @@
'use client';
-import {useId, useRef, type ReactNode} from 'react';
+import {useCallback, useId, useRef, useState, type ReactNode} from 'react';
import * as stylex from '@stylexjs/stylex';
import {
colorVars,
@@ -24,6 +24,7 @@ import {
textSizeVars,
fontWeightVars,
lineHeightVars,
+ transitionVars,
} from '../theme/tokens.stylex';
import {XDSIcon} from '../Icon';
import type {XDSIconType} from '../Icon';
@@ -31,7 +32,9 @@ import {useXDSLinkComponent} from '../Link/useXDSLinkComponent';
import type {XDSLinkComponentType} from '../Link/types';
import {xdsClassName, mergeProps} from '../utils';
import {XDSTooltip} from '../Tooltip';
+import {navItemStyles} from '../NavItem/navItemStyles.stylex';
import {useXDSSideNavCollapse} from './XDSSideNavCollapseContext';
+import {getIcon} from '../Icon/globalIconRegistry';
// =============================================================================
// Styles
@@ -43,50 +46,10 @@ const styles = stylex.create({
flexDirection: 'column',
width: '100%',
},
- item: {
- display: 'flex',
- alignItems: 'center',
- gap: spacingVars['--spacing-2'],
- width: '100%',
- paddingInline: spacingVars['--spacing-2'],
- paddingBlock: spacingVars['--spacing-2'],
- borderRadius: radiusVars['--radius-element'],
- borderWidth: 0,
- borderStyle: 'none',
- backgroundColor: 'transparent',
- color: colorVars['--color-text-primary'],
- textDecoration: 'none',
- cursor: 'pointer',
- fontFamily: 'inherit',
- fontSize: textSizeVars['--text-base'],
- fontWeight: fontWeightVars['--font-weight-normal'],
- lineHeight: lineHeightVars['--leading-base'],
- textAlign: 'start',
- boxSizing: 'border-box',
- ':hover': {
- '@media (hover: hover)': {
- backgroundColor: colorVars['--color-hover-overlay'],
- },
- },
- },
itemCollapsed: {
justifyContent: 'center',
paddingInline: spacingVars['--spacing-1'],
},
- selected: {
- backgroundColor: colorVars['--color-deemphasized'],
- fontWeight: fontWeightVars['--font-weight-medium'],
- ':hover': {
- '@media (hover: hover)': {
- backgroundColor: colorVars['--color-deemphasized'],
- },
- },
- },
- disabled: {
- color: colorVars['--color-text-disabled'],
- cursor: 'not-allowed',
- pointerEvents: 'none',
- },
label: {
flex: 1,
minWidth: 0,
@@ -102,6 +65,30 @@ const styles = stylex.create({
children: {
paddingInlineStart: spacingVars['--spacing-6'],
},
+ childrenCollapsible: {
+ display: 'grid',
+ gridTemplateRows: '1fr',
+ transitionProperty: 'grid-template-rows',
+ transitionDuration: transitionVars['--transition-normal'],
+ },
+ childrenCollapsed: {
+ gridTemplateRows: '0fr',
+ },
+ childrenInner: {
+ overflow: 'hidden',
+ minHeight: 0,
+ paddingInlineStart: spacingVars['--spacing-6'],
+ },
+ expandChevron: {
+ display: 'inline-flex',
+ alignItems: 'center',
+ transitionProperty: 'transform',
+ transitionDuration: transitionVars['--transition-fast'],
+ flexShrink: 0,
+ },
+ expandChevronCollapsed: {
+ transform: 'rotate(180deg)',
+ },
});
// =============================================================================
@@ -155,6 +142,24 @@ export interface XDSSideNavItemProps {
* Sub-items for nesting.
*/
children?: ReactNode;
+ /**
+ * Enables collapse behavior for items with children.
+ * When true, clicking the item toggles visibility of sub-items.
+ *
+ * - `true` — collapsible with defaults (starts expanded)
+ * - Object — controlled/configured:
+ * - `defaultIsCollapsed` — start collapsed (default: false)
+ * - `isCollapsed` + `onCollapsedChange` — controlled mode
+ *
+ * @default false
+ */
+ collapsible?:
+ | boolean
+ | {
+ defaultIsCollapsed?: boolean;
+ isCollapsed?: boolean;
+ onCollapsedChange?: (isCollapsed: boolean) => void;
+ };
/**
* Test ID for the item element.
*/
@@ -196,6 +201,7 @@ export function XDSSideNavItem({
onClick,
endContent,
children,
+ collapsible: itemCollapsible,
'data-testid': testId,
ref,
}: XDSSideNavItemProps) {
@@ -205,6 +211,27 @@ export function XDSSideNavItem({
const LinkComponent = useXDSLinkComponent(as);
const itemRef = useRef<HTMLDivElement>(null);
+ // Collapse state for items with children
+ const itemCollapsibleConfig =
+ typeof itemCollapsible === 'object' ? itemCollapsible : {};
+ const isItemCollapsible = hasChildren && itemCollapsible !== false;
+ const itemControlledCollapsed = itemCollapsibleConfig.isCollapsed;
+ const isItemControlled = itemControlledCollapsed !== undefined;
+ const [uncontrolledCollapsed, setUncontrolledCollapsed] = useState(
+ itemCollapsibleConfig.defaultIsCollapsed ?? false,
+ );
+ const isItemCollapsed = isItemControlled
+ ? itemControlledCollapsed
+ : uncontrolledCollapsed;
+
+ const toggleItemCollapse = useCallback(() => {
+ const next = !isItemCollapsed;
+ if (!isItemControlled) {
+ setUncontrolledCollapsed(next);
+ }
+ itemCollapsibleConfig.onCollapsedChange?.(next);
+ }, [isItemCollapsed, isItemControlled, itemCollapsibleConfig]);
+
const displayIcon = isSelected && selectedIcon ? selectedIcon : icon;
// In collapsed mode: hide items without icons
@@ -217,6 +244,11 @@ export function XDSSideNavItem({
e.preventDefault();
return;
}
+ if (isItemCollapsible && !isCollapsed) {
+ e.preventDefault();
+ toggleItemCollapse();
+ return;
+ }
onClick?.(e);
};
@@ -233,12 +265,23 @@ export function XDSSideNavItem({
{!isCollapsed && endContent && (
<span {...stylex.props(styles.endContent)}>{endContent}</span>
)}
+ {!isCollapsed && isItemCollapsible && (
+ <span
+ {...stylex.props(
+ styles.expandChevron,
+ isItemCollapsed && styles.expandChevronCollapsed,
+ )}>
+ {getIcon('chevronDown')}
+ </span>
+ )}
</>
);
const ariaProps = {
'aria-current': isSelected ? ('page' as const) : undefined,
'aria-disabled': isDisabled || undefined,
+ 'aria-expanded': isItemCollapsible ? !isItemCollapsed : undefined,
+ 'aria-controls': isItemCollapsible ? `${id}-children` : undefined,
'data-testid': testId,
};
@@ -250,10 +293,10 @@ export function XDSSideNavItem({
onClick={handleClick}
{...ariaProps}
{...stylex.props(
- styles.item,
+ navItemStyles.item,
isCollapsed && styles.itemCollapsed,
- isSelected && styles.selected,
- isDisabled && styles.disabled,
+ isSelected && navItemStyles.selected,
+ isDisabled && navItemStyles.disabled,
)}>
{itemContent}
</LinkComponent>
@@ -265,10 +308,10 @@ export function XDSSideNavItem({
disabled={isDisabled}
{...ariaProps}
{...stylex.props(
- styles.item,
+ navItemStyles.item,
isCollapsed && styles.itemCollapsed,
- isSelected && styles.selected,
- isDisabled && styles.disabled,
+ isSelected && navItemStyles.selected,
+ isDisabled && navItemStyles.disabled,
)}>
{itemContent}
</button>
@@ -281,13 +324,20 @@ export function XDSSideNavItem({
{itemElement}
{hasChildren && !isCollapsed && (
<div
+ id={`${id}-children`}
role="group"
aria-labelledby={`${id}-label`}
- {...stylex.props(styles.children)}>
- <span id={`${id}-label`} hidden>
- {label}
- </span>
- {children}
+ aria-hidden={isItemCollapsed}
+ {...stylex.props(
+ styles.childrenCollapsible,
+ isItemCollapsed && styles.childrenCollapsed,
+ )}>
+ <div {...stylex.props(styles.childrenInner)}>
+ <span id={`${id}-label`} hidden>
+ {label}
+ </span>
+ {children}
+ </div>
</div>
)}
</div>
diff --git a/packages/core/src/Tooltip/useXDSTooltip.tsx b/packages/core/src/Tooltip/useXDSTooltip.tsx
index 71fe960e85..ca678ec284 100644
--- a/packages/core/src/Tooltip/useXDSTooltip.tsx
+++ b/packages/core/src/Tooltip/useXDSTooltip.tsx
@@ -299,6 +299,14 @@ export function useXDSTooltip(
// Event handlers
const handleMouseEnter = useCallback(() => {
+ // Suppress tooltips on touch devices — hover is simulated and eats a tap
+ if (
+ typeof window !== 'undefined' &&
+ typeof window.matchMedia === 'function' &&
+ window.matchMedia('(hover: none)').matches
+ ) {
+ return;
+ }
scheduleShow();
}, [scheduleShow]);
@@ -306,11 +314,18 @@ export function useXDSTooltip(
scheduleHide();
}, [scheduleHide]);
- const handleFocusIn = useCallback(() => {
- if (!isEnabled) return;
- clearTimeouts();
- layer.show();
- }, [isEnabled, clearTimeouts, layer]);
+ const handleFocusIn = useCallback(
+ (e: Event) => {
+ if (!isEnabled) return;
+ // Only show tooltip for keyboard focus (:focus-visible),
+ // not programmatic focus (e.g. dialog auto-focus, touch tap)
+ const target = e.target as HTMLElement;
+ if (!target.matches(':focus-visible')) return;
+ clearTimeouts();
+ layer.show();
+ },
+ [isEnabled, clearTimeouts, layer],
+ );
const handleFocusOut = useCallback(() => {
scheduleHide();
diff --git a/packages/core/src/TopNav/XDSTopNav.tsx b/packages/core/src/TopNav/XDSTopNav.tsx
index 81313b9381..32390b26ca 100644
--- a/packages/core/src/TopNav/XDSTopNav.tsx
+++ b/packages/core/src/TopNav/XDSTopNav.tsx
@@ -22,6 +22,7 @@ import {xdsClassName, mergeProps} from '../utils';
import {TopNavSlotContext} from './TopNavContext';
import {useXDSTopNavRenderMode} from './XDSTopNavRenderContext';
import {useXDSTopNavMobileContent} from './XDSTopNavMobileContentContext';
+import {XDSDivider} from '../Divider/XDSDivider';
import {XDSMobileNav} from '../MobileNav/XDSMobileNav';
import {XDSMobileNavToggle} from '../MobileNav/XDSMobileNavToggle';
@@ -106,9 +107,10 @@ const styles = stylex.create({
flexDirection: 'column',
gap: spacingVars['--spacing-0-5'],
},
- drawerExtraContent: {
- marginBlockStart: spacingVars['--spacing-4'],
+ drawerDivider: {
+ marginBlock: spacingVars['--spacing-2'],
},
+ drawerExtraContent: {},
});
export interface XDSTopNavProps extends XDSBaseProps<HTMLElement> {
@@ -218,6 +220,11 @@ export function XDSTopNav({
{centerContent}
</div>
)}
+ {hasCollapsibleContent && mobileContent && (
+ <div {...stylex.props(styles.drawerDivider)}>
+ <XDSDivider />
+ </div>
+ )}
{mobileContent && (
<div {...stylex.props(styles.drawerExtraContent)}>
{mobileContent}
diff --git a/packages/core/src/TopNav/XDSTopNavItem.tsx b/packages/core/src/TopNav/XDSTopNavItem.tsx
index d947e6f2e6..ed2697b78d 100644
--- a/packages/core/src/TopNav/XDSTopNavItem.tsx
+++ b/packages/core/src/TopNav/XDSTopNavItem.tsx
@@ -28,6 +28,7 @@ import {
import {useXDSLinkComponent} from '../Link/useXDSLinkComponent';
import type {XDSLinkComponentType} from '../Link/types';
import {useXDSTopNavRenderMode} from './XDSTopNavRenderContext';
+import {navItemStyles} from '../NavItem/navItemStyles.stylex';
import {xdsClassName, mergeProps} from '../utils';
/**
@@ -76,50 +77,18 @@ const styles = stylex.create({
':active': colorVars['--color-deemphasized'],
},
},
- disabled: {
- color: colorVars['--color-text-disabled'],
- cursor: 'not-allowed',
- pointerEvents: 'none',
- },
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'],
- },
+ // Drawer mode — focus outline (base item + selected come from navItemStyles)
+ drawerFocus: {
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'],
- },
+ outlineOffset: {
+ default: '0',
+ ':focus-visible': '2px',
},
},
});
@@ -220,9 +189,10 @@ export function XDSTopNavItem({
{...mergeProps(
xdsClassName('top-nav-item', {mode: 'drawer'}),
stylex.props(
- styles.drawerItem,
- isSelected && styles.drawerItemSelected,
- isDisabled && styles.disabled,
+ navItemStyles.item,
+ styles.drawerFocus,
+ isSelected && navItemStyles.selected,
+ isDisabled && navItemStyles.disabled,
xstyle,
),
className,
@@ -251,7 +221,7 @@ export function XDSTopNavItem({
stylex.props(
styles.base,
isSelected && styles.selected,
- isDisabled && styles.disabled,
+ isDisabled && navItemStyles.disabled,
isIconOnly && styles.iconOnly,
xstyle,
),
diff --git a/packages/core/src/TopNav/XDSTopNavMenu.tsx b/packages/core/src/TopNav/XDSTopNavMenu.tsx
index b40e6e9bb0..326cf825b7 100644
--- a/packages/core/src/TopNav/XDSTopNavMenu.tsx
+++ b/packages/core/src/TopNav/XDSTopNavMenu.tsx
@@ -10,13 +10,22 @@
* - /packages/core/src/TopNav/index.ts
*/
-import {useCallback, useEffect, useRef, type ReactNode} from 'react';
+import {
+ useCallback,
+ useEffect,
+ useId,
+ useRef,
+ useState,
+ type ReactNode,
+} from 'react';
import * as stylex from '@stylexjs/stylex';
import {useXDSPopover} from '../Popover/useXDSPopover';
import {useListFocus} from '../hooks/useListFocus';
import {getIcon} from '../Icon/globalIconRegistry';
import {xdsClassName, mergeProps} from '../utils';
+import {navItemStyles} from '../NavItem/navItemStyles.stylex';
import {useTopNavSlot} from './TopNavContext';
+import {useXDSTopNavRenderMode} from './XDSTopNavRenderContext';
import {
colorVars,
spacingVars,
@@ -149,6 +158,58 @@ const styles = stylex.create({
},
});
+const drawerStyles = stylex.create({
+ section: {
+ display: 'flex',
+ flexDirection: 'column',
+ },
+ header: {
+ justifyContent: 'space-between',
+ border: 'none',
+ background: 'none',
+ },
+ chevron: {
+ display: 'inline-flex',
+ transitionProperty: 'transform',
+ transitionDuration: transitionVars['--transition-fast'],
+ },
+ chevronExpanded: {
+ transform: 'rotate(180deg)',
+ },
+ items: {
+ display: 'grid',
+ gridTemplateRows: '0fr',
+ transitionProperty: 'grid-template-rows',
+ transitionDuration: transitionVars['--transition-normal'],
+ },
+ itemsExpanded: {
+ gridTemplateRows: '1fr',
+ },
+ itemsInner: {
+ overflow: 'hidden',
+ minHeight: 0,
+ },
+ item: {
+ paddingInlineStart: spacingVars['--spacing-6'],
+ textDecoration: 'none',
+ },
+ itemIcon: {
+ flexShrink: 0,
+ width: 20,
+ height: 20,
+ },
+ itemText: {
+ display: 'flex',
+ flexDirection: 'column',
+ gap: spacingVars['--spacing-0-5'],
+ },
+ itemDescription: {
+ fontSize: textSizeVars['--text-sm'],
+ color: colorVars['--color-text-secondary'],
+ fontWeight: fontWeightVars['--font-weight-normal'],
+ },
+});
+
// =============================================================================
// Types
// =============================================================================
@@ -253,6 +314,69 @@ export function XDSTopNavMenu({
delay = 150,
hideDelay = 200,
}: XDSTopNavMenuProps) {
+ const renderMode = useXDSTopNavRenderMode();
+ const [drawerExpanded, setDrawerExpanded] = useState(false);
+ const menuId = useId();
+
+ // Mobile bar: hide menus entirely
+ if (renderMode === 'mobile-bar') {
+ return null;
+ }
+
+ // Drawer mode: collapsible section
+ if (renderMode === 'drawer') {
+ return (
+ <div {...stylex.props(drawerStyles.section)}>
+ <button
+ type="button"
+ onClick={() => setDrawerExpanded(v => !v)}
+ aria-expanded={drawerExpanded}
+ aria-controls={`${menuId}-items`}
+ {...stylex.props(navItemStyles.item, drawerStyles.header)}>
+ {label}
+ <span
+ {...stylex.props(
+ drawerStyles.chevron,
+ drawerExpanded && drawerStyles.chevronExpanded,
+ )}>
+ {getIcon('chevronDown')}
+ </span>
+ </button>
+ <div
+ id={`${menuId}-items`}
+ {...stylex.props(
+ drawerStyles.items,
+ drawerExpanded && drawerStyles.itemsExpanded,
+ )}>
+ <div {...stylex.props(drawerStyles.itemsInner)}>
+ {items.map((item, i) => (
+ <a
+ key={i}
+ href={item.href}
+ onClick={item.onClick}
+ {...stylex.props(navItemStyles.item, drawerStyles.item)}>
+ {item.icon && (
+ <span {...stylex.props(drawerStyles.itemIcon)}>
+ {item.icon}
+ </span>
+ )}
+ <span {...stylex.props(drawerStyles.itemText)}>
+ {item.title}
+ {item.description && (
+ <span {...stylex.props(drawerStyles.itemDescription)}>
+ {item.description}
+ </span>
+ )}
+ </span>
+ </a>
+ ))}
+ </div>
+ </div>
+ </div>
+ );
+ }
+
+ // Default: desktop popover
const slot = useTopNavSlot();
const showTimeoutRef = useRef<ReturnType<typeof setTimeout> | null>(null);
const hideTimeoutRef = useRef<ReturnType<typeof setTimeout> | null>(null);
diff --git a/packages/core/src/index.ts b/packages/core/src/index.ts
index ef0ddbdc23..2f45343a92 100644
--- a/packages/core/src/index.ts
+++ b/packages/core/src/index.ts
@@ -28,6 +28,7 @@ export * from './EmptyState';
export * from './Link';
export * from './List';
export * from './NavIcon';
+export * from './NavItem';
export * from './Slider';
export * from './Stack';
export * from './Switch';
diff --git a/packages/core/src/reset.css b/packages/core/src/reset.css
index d90eca4563..b3c140451a 100644
--- a/packages/core/src/reset.css
+++ b/packages/core/src/reset.css
@@ -328,4 +328,30 @@
:where(html) {
-webkit-tap-highlight-color: transparent;
}
+
+ /* ===========================================================================
+ Touch Devices
+ =========================================================================== */
+
+ /*
+ * Suppress focus-visible outlines on touch-only devices.
+ *
+ * Focus rings exist to show keyboard users where focus is. On devices
+ * with no hover capability and a coarse pointer (phones, tablets),
+ * there's no keyboard navigation — focus rings are visual noise that
+ * can flash on tap, on dialog open (showModal auto-focus), or on
+ * programmatic focus.
+ *
+ * This targets touch-only devices specifically:
+ * - (hover: none) — no hover capability (not a mouse)
+ * - (pointer: coarse) — imprecise pointer (finger, not stylus)
+ *
+ * Hybrid devices (laptop with touchscreen) are NOT affected because
+ * their primary pointer is fine (trackpad/mouse) and hover is available.
+ */
+ @media (hover: none) and (pointer: coarse) {
+ :where(:focus-visible) {
+ outline: none;
+ }
+ }
}