Skip to content

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

TypeScript

feat(MobileNav): auto-detect drawer side from trigger position (#1395)

Cindy Zhangf4eebe739881
diff --git a/apps/sandbox/src/app/(raw)/pages/shell-lab/page.tsx b/apps/sandbox/src/app/(raw)/pages/shell-lab/page.tsx
index ca401c7284..05ba36550a 100644
--- a/apps/sandbox/src/app/(raw)/pages/shell-lab/page.tsx
+++ b/apps/sandbox/src/app/(raw)/pages/shell-lab/page.tsx
@@ -130,7 +130,7 @@ interface ShellConfig {
isResizable: boolean;
collapseToggleLocation: 'sidenav' | 'topnav';
mobileNavMode: 'auto' | 'customContent' | 'customToggle' | 'disabled';
- mobileNavSide: 'start' | 'end';
+ mobileNavSide: 'auto' | 'start' | 'end';
topNavAlignment: 'none' | 'start' | 'center' | 'end';
topNavStyle: 'items' | 'menus' | 'mega';
showTopNavHeading: boolean;
@@ -159,7 +159,7 @@ const DEFAULT_CONFIG: ShellConfig = {
isResizable: false,
collapseToggleLocation: 'sidenav',
mobileNavMode: 'auto',
- mobileNavSide: 'start',
+ mobileNavSide: 'auto',
topNavAlignment: 'start',
topNavStyle: 'items',
showTopNavHeading: true,
@@ -462,8 +462,11 @@ function ConfigPanel({
<SelectorRow
label="Side"
value={config.mobileNavSide}
- onChange={v => onChange({mobileNavSide: v as 'start' | 'end'})}
+ onChange={v =>
+ onChange({mobileNavSide: v as 'auto' | 'start' | 'end'})
+ }
options={[
+ {value: 'auto', label: 'Auto'},
{value: 'start', label: 'Start'},
{value: 'end', label: 'End'},
]}
diff --git a/packages/core/src/AppShell/XDSAppShell.tsx b/packages/core/src/AppShell/XDSAppShell.tsx
index 38dc631dae..e1a491a321 100644
--- a/packages/core/src/AppShell/XDSAppShell.tsx
+++ b/packages/core/src/AppShell/XDSAppShell.tsx
@@ -618,12 +618,6 @@ export function XDSAppShell({
// 2. Config with custom content
const shouldRenderConfigContent =
mobileNavEnabled && mobileNavConfigContent != null && isBelowBreakpoint;
- // 3. Auto — mount drawer structure when props exist, use presence for path selection
- const shouldRenderAutoMobileNav =
- !mobileNavDisabled &&
- mobileNavReactNode == null &&
- !mobileNavConfigContent &&
- isBelowBreakpoint;
// =========================================================================
// Mobile context — shared with XDSMobileNavToggle and future TopNav mobile
@@ -632,10 +626,12 @@ export function XDSAppShell({
() => ({
isMobile: isBelowBreakpoint,
isMobileNavOpen,
- toggleMobileNav: () => setMobileNavOpen(!isMobileNavOpen),
- openMobileNav: () => setMobileNavOpen(true),
+ toggleMobileNav: () =>
+ mobileNavEnabled && setMobileNavOpen(!isMobileNavOpen),
+ openMobileNav: () => mobileNavEnabled && setMobileNavOpen(true),
closeMobileNav: () => setMobileNavOpen(false),
isMobileNavEnabled: mobileNavEnabled,
+ hasAutoToggle: mobileNavHasToggle,
}),
[isBelowBreakpoint, isMobileNavOpen, setMobileNavOpen, mobileNavEnabled],
);
@@ -654,7 +650,7 @@ export function XDSAppShell({
isBelowBreakpoint && !mobileNavDisabled && mobileNavReactNode == null ? (
<XDSTopNavMobileContentContext
value={
- hasSideNavContent ? (
+ hasSideNavContent && mobileNavHasToggle ? (
<XDSSideNavRenderContext value="drawer-content">
<div ref={sideNavRef} style={{display: 'contents'}}>
{sideNav}
@@ -845,36 +841,39 @@ export function XDSAppShell({
presence detection works. Hidden until the drawer opens. */}
{shouldRenderMobileNavReactNode && mobileNavReactNode}
{shouldRenderConfigContent && mobileNavConfigContent}
- {shouldRenderAutoMobileNav && (
- <ActivityWrapper mode={isMobileNavOpen ? 'visible' : 'hidden'}>
- {/* SideNav detection — always mounted so presence is known.
- Hidden when TopNav owns the drawer (combined mode renders
- sideNav via TopNav's mobile content context instead). */}
- {hasSideNav && (
- <div
- ref={sideNavRef}
- style={{display: hasTopNavContent ? 'none' : 'contents'}}>
- <XDSSideNavRenderContext value="drawer">
- {sideNav}
- </XDSSideNavRenderContext>
- </div>
- )}
- {hasTopNav && hasTopNavContent && (
- <XDSTopNavMobileContentContext
- value={
- hasSideNavContent ? (
- <XDSSideNavRenderContext value="drawer-content">
- {sideNav}
- </XDSSideNavRenderContext>
- ) : null
- }>
- <XDSTopNavRenderContext value="drawer">
- {topNav}
- </XDSTopNavRenderContext>
- </XDSTopNavMobileContentContext>
- )}
- </ActivityWrapper>
- )}
+ {isBelowBreakpoint &&
+ !mobileNavDisabled &&
+ mobileNavReactNode == null &&
+ !mobileNavConfigContent && (
+ <ActivityWrapper mode={isMobileNavOpen ? 'visible' : 'hidden'}>
+ {/* SideNav drawer — always mounted so presence detection works.
+ Hidden when TopNav owns the drawer (combined mode passes
+ sideNav via TopNav's mobile content context instead). */}
+ {hasSideNav && (
+ <div
+ ref={sideNavRef}
+ style={{display: hasTopNavContent ? 'none' : 'contents'}}>
+ <XDSSideNavRenderContext value="drawer">
+ {sideNav}
+ </XDSSideNavRenderContext>
+ </div>
+ )}
+ {hasTopNav && hasTopNavContent && (
+ <XDSTopNavMobileContentContext
+ value={
+ hasSideNavContent ? (
+ <XDSSideNavRenderContext value="drawer-content">
+ {sideNav}
+ </XDSSideNavRenderContext>
+ ) : null
+ }>
+ <XDSTopNavRenderContext value="drawer">
+ {topNav}
+ </XDSTopNavRenderContext>
+ </XDSTopNavMobileContentContext>
+ )}
+ </ActivityWrapper>
+ )}
</div>
</XDSAppShellMobileContext.Provider>
);
diff --git a/packages/core/src/AppShell/XDSAppShellMobileContext.tsx b/packages/core/src/AppShell/XDSAppShellMobileContext.tsx
index 97d33fef6c..2403fe8eb0 100644
--- a/packages/core/src/AppShell/XDSAppShellMobileContext.tsx
+++ b/packages/core/src/AppShell/XDSAppShellMobileContext.tsx
@@ -11,7 +11,6 @@
* to adapt rendering based on mobile context.
*/
-
import {createContext, useContext} from 'react';
export interface XDSAppShellMobileContextValue {
@@ -27,6 +26,8 @@ export interface XDSAppShellMobileContextValue {
closeMobileNav: () => void;
/** Whether mobile nav is enabled at all */
isMobileNavEnabled: boolean;
+ /** Whether auto-placed toggles should render (false in customToggle mode) */
+ hasAutoToggle: boolean;
}
const defaultValue: XDSAppShellMobileContextValue = {
@@ -36,6 +37,7 @@ const defaultValue: XDSAppShellMobileContextValue = {
openMobileNav: () => {},
closeMobileNav: () => {},
isMobileNavEnabled: false,
+ hasAutoToggle: true,
};
export const XDSAppShellMobileContext =
diff --git a/packages/core/src/AppShell/XDSAppShellSlotPresence.tsx b/packages/core/src/AppShell/XDSAppShellSlotPresence.tsx
index c28077032c..7dea30fe96 100644
--- a/packages/core/src/AppShell/XDSAppShellSlotPresence.tsx
+++ b/packages/core/src/AppShell/XDSAppShellSlotPresence.tsx
@@ -63,6 +63,11 @@ export function useXDSSlotPresence(initialValue = false) {
elementRef.current = node;
+ if (!node) {
+ setHasContent(false);
+ return;
+ }
+
if (node) {
// Check immediately
setHasContent(hasChildContent(node));
diff --git a/packages/core/src/MobileNav/XDSMobileNav.tsx b/packages/core/src/MobileNav/XDSMobileNav.tsx
index 34cdae62ee..43cf626a43 100644
--- a/packages/core/src/MobileNav/XDSMobileNav.tsx
+++ b/packages/core/src/MobileNav/XDSMobileNav.tsx
@@ -23,7 +23,7 @@
* - /packages/core/src/MobileNav/index.ts (exports if types change)
*/
-import {useCallback, useEffect, useRef, type ReactNode} from 'react';
+import {useCallback, useEffect, useRef, useState, type ReactNode} from 'react';
import * as stylex from '@stylexjs/stylex';
import {
borderVars,
@@ -214,9 +214,14 @@ export interface XDSMobileNavProps extends Omit<XDSBaseProps, 'title'> {
/**
* Which side the drawer slides from.
- * @default 'end'
+ * - `'start'` — slides from the inline-start edge (left in LTR)
+ * - `'end'` — slides from the inline-end edge (right in LTR)
+ * - `'auto'` — determined by the trigger element's position: if the
+ * toggle is in the start half of the viewport the drawer opens from
+ * start, otherwise from end.
+ * @default 'auto'
*/
- side?: 'start' | 'end';
+ side?: 'start' | 'end' | 'auto';
/**
* Accessible label for the drawer. Falls back to header string, then 'Navigation'.
@@ -265,7 +270,7 @@ export function XDSMobileNav({
children,
header,
width = 320,
- side = 'end',
+ side = 'auto',
label,
'data-testid': testId,
xstyle,
@@ -288,6 +293,10 @@ export function XDSMobileNav({
const dialogRef = useRef<HTMLDialogElement>(null);
const closeTimeoutRef = useRef<ReturnType<typeof setTimeout>>(null);
+ // Resolved side — computed from trigger position when side='auto'
+ const [resolvedSide, setResolvedSide] = useState<'start' | 'end'>(
+ side === 'auto' ? 'end' : side,
+ );
// Merge refs
const setRefs = useCallback(
@@ -315,6 +324,20 @@ export function XDSMobileNav({
}
if (isOpen) {
+ // Determine drawer side from trigger position when auto
+ if (side === 'auto') {
+ const trigger = document.activeElement as HTMLElement | null;
+ if (trigger && trigger !== document.body) {
+ const rect = trigger.getBoundingClientRect();
+ const triggerCenter = rect.left + rect.width / 2;
+ setResolvedSide(
+ triggerCenter < window.innerWidth / 2 ? 'start' : 'end',
+ );
+ }
+ } else {
+ setResolvedSide(side);
+ }
+
if (!dialog.open) {
dialog.showModal();
}
@@ -363,7 +386,7 @@ export function XDSMobileNav({
[onOpenChange],
);
- const isStart = side === 'start';
+ const isStart = resolvedSide === 'start';
return (
<dialog
@@ -373,7 +396,7 @@ export function XDSMobileNav({
onClick={handleDialogClick}
onCancel={handleCancel}
{...mergeProps(
- xdsClassName('mobile-nav', {side}),
+ xdsClassName('mobile-nav', {side: resolvedSide}),
stylex.props(
styles.dialog,
styles.backdrop,
diff --git a/packages/core/src/TopNav/XDSTopNav.tsx b/packages/core/src/TopNav/XDSTopNav.tsx
index 601cb42b75..7186e7bc38 100644
--- a/packages/core/src/TopNav/XDSTopNav.tsx
+++ b/packages/core/src/TopNav/XDSTopNav.tsx
@@ -25,6 +25,7 @@ import {useXDSTopNavMobileContent} from './XDSTopNavMobileContentContext';
import {XDSDivider} from '../Divider/XDSDivider';
import {XDSMobileNav} from '../MobileNav/XDSMobileNav';
import {XDSMobileNavToggle} from '../MobileNav/XDSMobileNavToggle';
+import {useXDSAppShellMobile} from '../AppShell/XDSAppShellMobileContext';
/**
* Base TopNav styles
@@ -172,6 +173,7 @@ export function XDSTopNav({
}: XDSTopNavProps) {
const renderMode = useXDSTopNavRenderMode();
const mobileContent = useXDSTopNavMobileContent();
+ const {hasAutoToggle} = useXDSAppShellMobile();
const hasCenterContent = centerContent != null;
const hasCollapsibleContent = startContent != null || centerContent != null;
// Show mobile toggle when there's ANY drawer content — own items OR SideNav via context
@@ -182,7 +184,7 @@ export function XDSTopNav({
// Falls through to default when there's no drawer content — no reason
// to strip down the TopNav if there's nothing to put in the drawer.
// =========================================================================
- if (renderMode === 'mobile-bar' && hasMobileDrawerContent) {
+ if (renderMode === 'mobile-bar') {
return (
<nav
ref={ref}
@@ -198,7 +200,7 @@ export function XDSTopNav({
{heading && <div {...stylex.props(styles.heading)}>{heading}</div>}
<div {...stylex.props(styles.mobileBarEnd)}>
{endContent}
- <XDSMobileNavToggle />
+ {hasMobileDrawerContent && hasAutoToggle && <XDSMobileNavToggle />}
</div>
</nav>
);