Skip to content

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

TypeScript

feat(AppShell): add sticky nav in auto mode, remove TopNav position prop, fix double dividers (#262)

Cindy Zhangd6d2eaedeef4
diff --git a/apps/storybook/stories/TopNav.stories.tsx b/apps/storybook/stories/TopNav.stories.tsx
index 0031b0fe24..015396f365 100644
--- a/apps/storybook/stories/TopNav.stories.tsx
+++ b/apps/storybook/stories/TopNav.stories.tsx
@@ -25,11 +25,6 @@ const meta: Meta<typeof XDSTopNav> = {
layout: 'fullscreen',
},
argTypes: {
- position: {
- control: 'select',
- options: ['static', 'sticky', 'fixed'],
- description: 'Position behavior',
- },
label: {
control: 'text',
description: 'Accessible label for navigation landmark',
@@ -196,7 +191,6 @@ export const FullExample: Story = {
render: () => (
<XDSTopNav
label="Main navigation"
- position="sticky"
title={
<XDSTopNavTitle
title="Enterprise Dashboard"
diff --git a/packages/core/src/AppShell/XDSAppShell.test.tsx b/packages/core/src/AppShell/XDSAppShell.test.tsx
index 101f05861a..46c02b06cb 100644
--- a/packages/core/src/AppShell/XDSAppShell.test.tsx
+++ b/packages/core/src/AppShell/XDSAppShell.test.tsx
@@ -361,6 +361,104 @@ describe('XDSAppShell', () => {
expect(screen.getByText('Nav')).toBeInTheDocument();
});
+ // ===========================================================================
+ // Sticky navigation in auto mode
+ // ===========================================================================
+
+ it('wraps header in sticky container in auto mode', () => {
+ render(
+ <XDSAppShell
+ height="auto"
+ topNav={<div data-testid="topnav">Nav</div>}
+ data-testid="shell">
+ <div>Content</div>
+ </XDSAppShell>,
+ );
+ const topNav = screen.getByTestId('topnav');
+ // The sticky wrapper is the parent of the XDSLayoutHeader div
+ // topNav -> XDSLayoutHeader div -> sticky wrapper div
+ const headerWrapper = topNav.parentElement?.parentElement;
+ expect(headerWrapper).toBeTruthy();
+ expect(
+ headerWrapper?.style.position ||
+ getComputedStyle(headerWrapper!).position,
+ ).toBeDefined();
+ });
+
+ it('does not apply sticky wrapper in fill mode', () => {
+ render(
+ <XDSAppShell
+ height="fill"
+ topNav={<div data-testid="topnav">Nav</div>}
+ data-testid="shell">
+ <div>Content</div>
+ </XDSAppShell>,
+ );
+ // In fill mode, header still renders but without sticky wrapper styles
+ expect(screen.getByTestId('topnav')).toBeInTheDocument();
+ });
+
+ it('wraps sideNav in sticky container in auto mode', () => {
+ render(
+ <XDSAppShell
+ height="auto"
+ topNav={<div>Nav</div>}
+ sideNav={<div data-testid="sidenav">Side</div>}
+ data-testid="shell">
+ <div>Content</div>
+ </XDSAppShell>,
+ );
+ expect(screen.getByTestId('sidenav')).toBeInTheDocument();
+ // The sideNav should be wrapped in a sticky div in auto mode
+ const sideNav = screen.getByTestId('sidenav');
+ // sideNav -> XDSLayoutPanel div -> sticky wrapper div
+ const stickyWrapper = sideNav.parentElement?.parentElement;
+ expect(stickyWrapper).toBeTruthy();
+ });
+
+ it('sets up ResizeObserver on header in auto mode', () => {
+ const observeSpy = vi.fn();
+ const disconnectSpy = vi.fn();
+ vi.stubGlobal(
+ 'ResizeObserver',
+ class {
+ constructor(public callback: ResizeObserverCallback) {}
+ observe = observeSpy;
+ unobserve = vi.fn();
+ disconnect = disconnectSpy;
+ },
+ );
+
+ render(
+ <XDSAppShell height="auto" topNav={<div>Nav</div>} data-testid="shell">
+ <div>Content</div>
+ </XDSAppShell>,
+ );
+
+ expect(observeSpy).toHaveBeenCalled();
+ });
+
+ it('does not set up ResizeObserver in fill mode', () => {
+ const observeSpy = vi.fn();
+ vi.stubGlobal(
+ 'ResizeObserver',
+ class {
+ constructor(public callback: ResizeObserverCallback) {}
+ observe = observeSpy;
+ unobserve = vi.fn();
+ disconnect = vi.fn();
+ },
+ );
+
+ render(
+ <XDSAppShell height="fill" topNav={<div>Nav</div>} data-testid="shell">
+ <div>Content</div>
+ </XDSAppShell>,
+ );
+
+ expect(observeSpy).not.toHaveBeenCalled();
+ });
+
// ===========================================================================
// Ref forwarding
// ===========================================================================
diff --git a/packages/core/src/AppShell/XDSAppShell.tsx b/packages/core/src/AppShell/XDSAppShell.tsx
index 916f3b3504..2b781f525d 100644
--- a/packages/core/src/AppShell/XDSAppShell.tsx
+++ b/packages/core/src/AppShell/XDSAppShell.tsx
@@ -17,6 +17,7 @@ import {
forwardRef,
useCallback,
useEffect,
+ useRef,
useState,
type ReactNode,
} from 'react';
@@ -143,22 +144,55 @@ const styles = stylex.create({
minHeight: '100dvh',
},
skipLink: {
- position: 'absolute',
- top: 0,
- left: 0,
- padding: '8px 16px',
+ // Visually hidden by default, visible on focus (keyboard navigation)
+ position: {
+ default: 'absolute',
+ ':focus': 'fixed',
+ },
+ width: {
+ default: '1px',
+ ':focus': 'auto',
+ },
+ height: {
+ default: '1px',
+ ':focus': 'auto',
+ },
+ padding: {
+ default: 0,
+ ':focus': '8px 16px',
+ },
+ margin: {
+ default: '-1px',
+ ':focus': 0,
+ },
+ overflow: {
+ default: 'hidden',
+ ':focus': 'visible',
+ },
+ clipPath: {
+ default: 'inset(50%)',
+ ':focus': 'none',
+ },
+ whiteSpace: {
+ default: 'nowrap',
+ ':focus': 'normal',
+ },
+ borderWidth: 0,
+ // Focus styles
+ top: {
+ default: 0,
+ ':focus': '8px',
+ },
+ insetInlineStart: {
+ default: 0,
+ ':focus': '8px',
+ },
backgroundColor: colorVars['--color-surface'],
color: colorVars['--color-accent-text'],
zIndex: 9999,
textDecoration: 'none',
fontWeight: fontWeightVars['--font-weight-semibold'],
fontSize: textSizeVars['--text-base'],
- // Visually hidden by default
- transform: 'translateY(-100%)',
- // Show on focus
- ':focus': {
- transform: 'translateY(0)',
- },
},
banner: {
flexShrink: 0,
@@ -189,6 +223,19 @@ const styles = stylex.create({
hidden: {
display: 'none',
},
+ // Sticky header for auto height mode
+ headerSticky: {
+ position: 'sticky',
+ top: 0,
+ zIndex: 10,
+ },
+ // Sticky sideNav for auto height mode
+ sideNavSticky: {
+ position: 'sticky',
+ top: 'var(--appshell-header-height, 0px)',
+ height: 'calc(100vh - var(--appshell-header-height, 0px))',
+ overflow: 'auto',
+ },
});
const dynamicStyles = stylex.create({
@@ -274,10 +321,49 @@ export const XDSAppShell = forwardRef<HTMLDivElement, XDSAppShellProps>(
const [isBelowBreakpoint, setIsBelowBreakpoint] = useState(false);
const isFill = height === 'fill';
+ const isAuto = height === 'auto';
const hasSideNav = sideNav != null;
const hasTopNav = topNav != null;
const hasBanner = banner != null;
+ // =========================================================================
+ // Header height measurement for sticky sideNav offset (auto mode)
+ // =========================================================================
+ const headerRef = useRef<HTMLDivElement>(null);
+ const shellRef = useRef<HTMLDivElement>(null);
+
+ // Merge forwarded ref with internal shell ref
+ const setShellRef = useCallback(
+ (node: HTMLDivElement | null) => {
+ (shellRef as React.MutableRefObject<HTMLDivElement | null>).current =
+ node;
+ if (typeof ref === 'function') {
+ ref(node);
+ } else if (ref) {
+ (ref as React.MutableRefObject<HTMLDivElement | null>).current = node;
+ }
+ },
+ [ref],
+ );
+
+ useEffect(() => {
+ if (!isAuto || !headerRef.current || !shellRef.current) return;
+
+ const headerEl = headerRef.current;
+ const shellEl = shellRef.current;
+
+ const updateHeight = () => {
+ const height = headerEl.getBoundingClientRect().height;
+ shellEl.style.setProperty('--appshell-header-height', `${height}px`);
+ };
+
+ updateHeight();
+
+ const observer = new ResizeObserver(updateHeight);
+ observer.observe(headerEl);
+ return () => observer.disconnect();
+ }, [isAuto]);
+
// =========================================================================
// Responsive breakpoint handling
//
@@ -347,8 +433,12 @@ export const XDSAppShell = forwardRef<HTMLDivElement, XDSAppShellProps>(
// =========================================================================
// Build header content (topNav + banner)
+ //
+ // In auto mode, the header wrapper gets sticky positioning so the topNav
+ // stays pinned while the page scrolls. The ref is used to measure header
+ // height for the sideNav's sticky offset.
// =========================================================================
- const headerContent =
+ const headerInner =
hasTopNav || hasBanner ? (
<XDSLayoutHeader isFullBleed hasDivider={hasTopNav}>
{hasBanner && <div {...stylex.props(styles.banner)}>{banner}</div>}
@@ -356,10 +446,22 @@ export const XDSAppShell = forwardRef<HTMLDivElement, XDSAppShellProps>(
</XDSLayoutHeader>
) : undefined;
+ const headerContent =
+ headerInner != null ? (
+ <div ref={headerRef} {...stylex.props(isAuto && styles.headerSticky)}>
+ {headerInner}
+ </div>
+ ) : undefined;
+
// =========================================================================
// Build sideNav content
+ //
+ // In auto mode, the sideNav panel is not internally scrollable (the page
+ // scrolls as a whole), but it gets sticky positioning so it stays pinned
+ // below the header while the main content scrolls. A wrapper div applies
+ // the sticky behavior since XDSLayoutPanel doesn't accept style/className.
// =========================================================================
- const sideNavContent = showSideNavInline ? (
+ const sideNavPanel = showSideNavInline ? (
<XDSLayoutPanel
isFullBleed
hasDivider
@@ -371,6 +473,13 @@ export const XDSAppShell = forwardRef<HTMLDivElement, XDSAppShellProps>(
</XDSLayoutPanel>
) : undefined;
+ const sideNavContent =
+ sideNavPanel != null && isAuto ? (
+ <div {...stylex.props(styles.sideNavSticky)}>{sideNavPanel}</div>
+ ) : (
+ sideNavPanel
+ );
+
// =========================================================================
// Build main content
// =========================================================================
@@ -392,7 +501,7 @@ export const XDSAppShell = forwardRef<HTMLDivElement, XDSAppShellProps>(
// =========================================================================
return (
<div
- ref={ref}
+ ref={setShellRef}
data-testid={dataTestId}
{...stylex.props(
styles.root,
diff --git a/packages/core/src/TopNav/README.md b/packages/core/src/TopNav/README.md
index d60c54ba51..10978ea902 100644
--- a/packages/core/src/TopNav/README.md
+++ b/packages/core/src/TopNav/README.md
@@ -7,7 +7,6 @@ Top navigation bar component for application headers.
## Features
- **Slot-based layout**: `title`, `startContent`, `endContent` for flexible organization
-- **Position modes**: Static, sticky, or fixed positioning
- **Companion components**: XDSTopNavTitle, XDSTopNavTitleIcon, XDSTopNavItem
- **Accessible**: Proper ARIA roles and keyboard navigation
- **Themeable**: Uses XDS design tokens for styling
@@ -26,7 +25,6 @@ import {HomeIcon, BellIcon, UserCircleIcon} from '@heroicons/react/24/outline';
<XDSTopNav
label="Main navigation"
- position="sticky"
title={
<XDSTopNavTitle
title="My App"
@@ -74,13 +72,12 @@ import {HomeIcon, BellIcon, UserCircleIcon} from '@heroicons/react/24/outline';
### XDSTopNav
-| Prop | Type | Default | Description |
-| -------------- | --------------------------------- | ---------- | ----------------------------------------------------- |
-| `title` | `ReactNode` | — | Title slot (logo, brand) - left aligned |
-| `startContent` | `ReactNode` | — | Start content (nav items, breadcrumbs) - left aligned |
-| `endContent` | `ReactNode` | — | End content (search, icons, profile) - right aligned |
-| `position` | `'static' \| 'sticky' \| 'fixed'` | `'static'` | Position behavior |
-| `label` | `string` | — | Accessible label for navigation landmark |
+| Prop | Type | Default | Description |
+| -------------- | ----------- | ------- | ----------------------------------------------------- |
+| `title` | `ReactNode` | — | Title slot (logo, brand) - left aligned |
+| `startContent` | `ReactNode` | — | Start content (nav items, breadcrumbs) - left aligned |
+| `endContent` | `ReactNode` | — | End content (search, icons, profile) - right aligned |
+| `label` | `string` | — | Accessible label for navigation landmark |
### XDSTopNavTitle
@@ -164,8 +161,8 @@ const theme: Theme = {
## Layout Structure
-XDSTopNav works directly in XDSLayout's `header` slot — no XDSLayoutHeader
-wrapper needed. TopNav manages its own padding, height, and divider.
+XDSTopNav works in XDSLayout's `header` slot via XDSLayoutHeader (which handles
+the divider) or directly. TopNav manages its own padding and height.
```tsx
import {XDSLayout, XDSLayoutContent, XDSLayoutPanel} from '@xds/core/Layout';
@@ -209,5 +206,6 @@ import {XDSTopNav, XDSTopNavTitle, XDSTopNavItem} from '@xds/core/TopNav';
- XDSTopNavItem supports `aria-current="page"` when `isSelected` is true
- XDSTopNavTitleIcon uses `--color-accent` background with `--color-icon-on-media` for contrast
- Default height is 48px with 16px horizontal padding
-- Always displays a bottom divider using `--color-divider` token
- Uses `--color-navbar` token for background (defaults to white)
+- Positioning (sticky/fixed) is handled by the layout system (e.g. XDSAppShell), not TopNav itself
+- Dividers are controlled by the layout system (e.g. XDSLayoutHeader's `hasDivider`), not TopNav
diff --git a/packages/core/src/TopNav/XDSTopNav.tsx b/packages/core/src/TopNav/XDSTopNav.tsx
index 5167aef3d5..409ed96827 100644
--- a/packages/core/src/TopNav/XDSTopNav.tsx
+++ b/packages/core/src/TopNav/XDSTopNav.tsx
@@ -33,21 +33,8 @@ const styles = stylex.create({
height: spacingVars['--spacing-12'],
paddingInline: spacingVars['--spacing-4'],
backgroundColor: colorVars['--color-navbar'],
- borderBlockEnd: `1px solid ${colorVars['--color-divider']}`,
boxSizing: 'border-box',
},
- sticky: {
- position: 'sticky',
- top: 0,
- zIndex: 100,
- },
- fixed: {
- position: 'fixed',
- top: 0,
- left: 0,
- right: 0,
- zIndex: 100,
- },
leftSection: {
display: 'flex',
alignItems: 'center',
@@ -104,14 +91,6 @@ export interface XDSTopNavProps extends Omit<
* Positioned at the right edge of the nav bar.
*/
endContent?: ReactNode;
- /**
- * Position behavior of the nav bar.
- * - `static`: Normal document flow (default)
- * - `sticky`: Sticks to top on scroll
- * - `fixed`: Fixed to viewport top
- * @default 'static'
- */
- position?: 'static' | 'sticky' | 'fixed';
/**
* Accessible label for the navigation landmark.
* Helps screen readers identify the navigation area.
@@ -126,6 +105,9 @@ export interface XDSTopNavProps extends Omit<
* for flexible layout. Title and startContent are left-aligned, endContent
* is right-aligned.
*
+ * Positioning is handled by the layout system (e.g. XDSAppShell applies sticky
+ * behavior in auto height mode). TopNav itself is a pure content component.
+ *
* @example
* ```tsx
* <XDSTopNav
@@ -147,10 +129,7 @@ export interface XDSTopNavProps extends Omit<
* ```
*/
export const XDSTopNav = forwardRef<HTMLElement, XDSTopNavProps>(
- function XDSTopNav(
- {title, startContent, endContent, position = 'static', label, ...props},
- ref,
- ) {
+ function XDSTopNav({title, startContent, endContent, label, ...props}, ref) {
const themeContext = useContext(ThemeContext);
const rootOverride = themeContext?.theme.components?.topNav?.root;
@@ -159,12 +138,7 @@ export const XDSTopNav = forwardRef<HTMLElement, XDSTopNavProps>(
ref={ref}
role="navigation"
aria-label={label}
- {...stylex.props(
- styles.base,
- position === 'sticky' && styles.sticky,
- position === 'fixed' && styles.fixed,
- rootOverride,
- )}
+ {...stylex.props(styles.base, rootOverride)}
{...props}>
<div {...stylex.props(styles.leftSection)}>
{title && <div {...stylex.props(styles.title)}>{title}</div>}