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.tsxindex 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 breakpointreturn (<>@@ -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 ? (<SampleTopNavdiff --git a/apps/storybook/stories/AppShell.stories.tsx b/apps/storybook/stories/AppShell.stories.tsxindex 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.mjsindex 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.tsxindex 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.tsxindex 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 propconst 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 hamburgerconst 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.tsxindex 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({<XDSButtonvariant="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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsxindex 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 bartopbar: {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.tsxindex 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.tsxindex 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 handlersconst 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.tsxindex 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.tsxindex 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.tsxindex 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 popoverconst 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.tsindex 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.cssindex 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;+ }+ }}