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.tsxindex 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: () => (<XDSTopNavlabel="Main navigation"- position="sticky"title={<XDSTopNavTitletitle="Enterprise Dashboard"diff --git a/packages/core/src/AppShell/XDSAppShell.test.tsx b/packages/core/src/AppShell/XDSAppShell.test.tsxindex 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.tsxindex 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 ? (<XDSLayoutPanelisFullBleedhasDivider@@ -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.mdindex 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';<XDSTopNavlabel="Main navigation"- position="sticky"title={<XDSTopNavTitletitle="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.```tsximport {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 TopNavdiff --git a/packages/core/src/TopNav/XDSTopNav.tsx b/packages/core/src/TopNav/XDSTopNav.tsxindex 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>}