An open source design system that's fully customizable and agent ready
TypeScript
feat(SideNav): resizable sidebar with drag handle (#658)
Cindy Zhang2c50d6ba849f
diff --git a/apps/sandbox/src/app/(fullscreen)/pages/shell-lab/page.tsx b/apps/sandbox/src/app/(fullscreen)/pages/shell-lab/page.tsxindex 47d07111f0..0fec286925 100644--- a/apps/sandbox/src/app/(fullscreen)/pages/shell-lab/page.tsx+++ b/apps/sandbox/src/app/(fullscreen)/pages/shell-lab/page.tsx@@ -116,6 +116,7 @@ interface ShellConfig {showSubheading: boolean;showNestedItems: boolean;isCollapsible: boolean;+ isResizable: boolean;collapseToggleLocation: 'sidenav' | 'topnav';mobileNavMode: 'auto' | 'customContent' | 'customToggle' | 'disabled';mobileNavSide: 'start' | 'end';@@ -139,6 +140,7 @@ const DEFAULT_CONFIG: ShellConfig = {showSubheading: false,showNestedItems: true,isCollapsible: true,+ isResizable: false,collapseToggleLocation: 'sidenav',mobileNavMode: 'auto',mobileNavSide: 'start',@@ -271,6 +273,11 @@ function ConfigPanel({]}/>)}+ <ToggleRow+ label="Resizable"+ value={config.isResizable}+ onChange={v => onChange({isResizable: v})}+ /></XDSVStack><XDSDivider />@@ -486,6 +493,7 @@ function SampleSideNav({: true: false}+ resizable={config.isResizable}header={heading}topContent={config.showTopContent ? (diff --git a/packages/core/src/SideNav/SideNav.doc.mjs b/packages/core/src/SideNav/SideNav.doc.mjsindex 32dce59b02..ba14abce70 100644--- a/packages/core/src/SideNav/SideNav.doc.mjs+++ b/packages/core/src/SideNav/SideNav.doc.mjs@@ -13,6 +13,7 @@ export const docs = {'Collapsible sidebar via collapsible prop — collapses to icon-only toolbar, uncontrolled or controlled','Accessible — nav landmark, aria-current="page", role="group" with aria-labelledby on sections','Keyboard navigable — Tab through items, Enter/Space to activate',+ 'Resizable sidebar via resizable prop — drag handle at inline-end edge, pointer-based resize with min/max constraints',],accessibility: ['<nav aria-label="Side navigation"> wraps the entire component',diff --git a/packages/core/src/SideNav/XDSSideNav.test.tsx b/packages/core/src/SideNav/XDSSideNav.test.tsxindex 1478165605..91b42b66dc 100644--- a/packages/core/src/SideNav/XDSSideNav.test.tsx+++ b/packages/core/src/SideNav/XDSSideNav.test.tsx@@ -8,7 +8,7 @@*/import {describe, it, expect, vi} from 'vitest';-import {render, screen} from '@testing-library/react';+import {render, screen, act} from '@testing-library/react';import userEvent from '@testing-library/user-event';import {forwardRef, type ComponentPropsWithoutRef} from 'react';import {XDSSideNav} from './XDSSideNav';@@ -395,6 +395,77 @@ describe('XDSSideNavSection', () => {});});+// =============================================================================+// Resizable+// =============================================================================++describe('XDSSideNav resizable', () => {+ it('renders drag handle when resizable', () => {+ render(<XDSSideNav resizable>Content</XDSSideNav>);+ expect(screen.getByTestId('xds-sidenav-resize-handle')).toBeInTheDocument();+ });++ it('does not render drag handle without resizable', () => {+ render(<XDSSideNav>Content</XDSSideNav>);+ expect(+ screen.queryByTestId('xds-sidenav-resize-handle'),+ ).not.toBeInTheDocument();+ });++ it('does not render drag handle when collapsed', () => {+ render(+ <XDSSideNav+ resizable+ collapsible={{isCollapsed: true, onCollapsedChange: () => {}}}>+ Content+ </XDSSideNav>,+ );+ expect(+ screen.queryByTestId('xds-sidenav-resize-handle'),+ ).not.toBeInTheDocument();+ });++ it('calls onWidthChange after drag', () => {+ const handleWidthChange = vi.fn();+ render(+ <XDSSideNav resizable={{onWidthChange: handleWidthChange}}>+ Content+ </XDSSideNav>,+ );+ const handle = screen.getByTestId('xds-sidenav-resize-handle');++ // Simulate pointer drag sequence+ act(() => {+ handle.dispatchEvent(+ new PointerEvent('pointerdown', {+ clientX: 260,+ bubbles: true,+ }),+ );+ document.dispatchEvent(+ new PointerEvent('pointermove', {clientX: 310, bubbles: true}),+ );+ document.dispatchEvent(+ new PointerEvent('pointerup', {clientX: 310, bubbles: true}),+ );+ });++ expect(handleWidthChange).toHaveBeenCalledTimes(1);+ expect(handleWidthChange).toHaveBeenCalledWith(expect.any(Number));+ });++ it('respects defaultWidth', () => {+ render(<XDSSideNav resizable={{defaultWidth: 300}}>Content</XDSSideNav>);+ const nav = screen.getByRole('navigation');+ expect(nav.style.width).toBe('300px');+ });++ it('drag handle has separator role', () => {+ render(<XDSSideNav resizable>Content</XDSSideNav>);+ expect(screen.getByRole('separator')).toBeInTheDocument();+ });+});+// =============================================================================// Integration// =============================================================================diff --git a/packages/core/src/SideNav/XDSSideNav.tsx b/packages/core/src/SideNav/XDSSideNav.tsxindex 8891a45fc2..bc4df6371f 100644--- a/packages/core/src/SideNav/XDSSideNav.tsx+++ b/packages/core/src/SideNav/XDSSideNav.tsx@@ -7,6 +7,8 @@* Sidebar navigation container with five zones: header + topContent (sticky together),* children (scrollable), footer, and footerIcons (sticky bottom).*+ * Supports optional resize via drag handle at the inline-end edge.+ ** SYNC: When modified, update these files to stay in sync:* - /packages/core/src/SideNav/SideNav.doc.mjs* - /packages/core/src/SideNav/XDSSideNav.test.tsx@@ -26,6 +28,7 @@ import {XDSSideNavCollapseContext} from './XDSSideNavCollapseContext';import {XDSSideNavCollapseButton} from './XDSSideNavCollapseButton';import {useXDSSideNavRenderMode} from './XDSSideNavRenderContext';import {XDSMobileNav} from '../MobileNav/XDSMobileNav';+import {useResizable} from './useResizable';// =============================================================================// Styles@@ -125,6 +128,31 @@ const styles = stylex.create({alignItems: 'center',gap: spacingVars['--spacing-1'],},+ // Resizable container — wraps the nav and the drag handle+ resizableContainer: {+ position: 'relative',+ display: 'flex',+ flexShrink: 0,+ height: '100%',+ },+ // Drag handle at the inline-end edge+ dragHandle: {+ position: 'absolute',+ insetInlineEnd: 0,+ top: 0,+ bottom: 0,+ width: 6,+ cursor: 'col-resize',+ zIndex: 2,+ // Invisible by default; visible on hover+ backgroundColor: 'transparent',+ transition: 'background-color 0.15s ease',+ touchAction: 'none',+ },+ dragHandleHover: {+ // Applied via @media (hover: hover) in the component+ backgroundColor: colorVars['--color-divider'],+ },// Topbar mode — horizontal layout for mobile top bartopbar: {display: 'flex',@@ -198,6 +226,24 @@ export interface XDSSideNavProps extends XDSBaseProps<HTMLElement> {*/'data-testid'?: string;+ /**+ * Enables a drag handle at the inline-end edge for resizing the sidebar.+ * When collapsed, the drag handle is hidden.+ *+ * - `true` — resizable with defaults (260px initial width)+ * - Object — configured:+ * - `defaultWidth` — initial width in pixels (default: 260)+ * - `onWidthChange` — called when user finishes resizing+ *+ * @default false+ */+ resizable?:+ | boolean+ | {+ defaultWidth?: number;+ onWidthChange?: (width: number) => void;+ };+/*** Enables collapse behavior. The sidebar can be collapsed to a narrow* icon-only toolbar.@@ -251,6 +297,7 @@ export function XDSSideNav({footer,footerIcons,collapsible = false,+ resizable = false,xstyle,className,style,@@ -266,6 +313,10 @@ export function XDSSideNav({const controlledCollapsed = collapsibleConfig.isCollapsed;const onCollapsedChange = collapsibleConfig.onCollapsedChange;+ // Resizable config+ const resizableConfig = typeof resizable === 'object' ? resizable : {};+ const isResizable = !!resizable;+// Collapse state (controlled + uncontrolled)const isControlled = controlledCollapsed !== undefined;const [uncontrolledCollapsed, setUncontrolledCollapsed] =@@ -286,6 +337,21 @@ export function XDSSideNav({isCollapsible,};+ // =========================================================================+ // Resize — extracted into useResizable hook+ // =========================================================================+ const {+ width,+ containerRef,+ showHandle: showResizeHandle,+ handleProps: resizeHandleProps,+ isHandleHovered,+ } = useResizable({+ enabled: isResizable,+ config: resizableConfig,+ collapsed,+ });+// Render mode — when inside AppShell mobile layout, render subsetsconst renderMode = useXDSSideNavRenderMode();@@ -361,7 +427,12 @@ export function XDSSideNav({const hasStickyTop = !!(header || topContent);const hasStickyBottom = !!(footer || footerIcons);- const content = (+ // When resizable, override the nav width via inline style+ const resizableNavStyle: React.CSSProperties | undefined = isResizable+ ? {...(style ?? {}), width: collapsed ? undefined : width}+ : style;++ const navElement = (<navref={ref}role="navigation"@@ -371,7 +442,7 @@ export function XDSSideNav({xdsClassName('side-nav'),stylex.props(styles.root, collapsed && styles.rootCollapsed, xstyle),className,- style,+ resizableNavStyle,)}{...props}>{hasStickyTop && (@@ -412,6 +483,29 @@ export function XDSSideNav({</nav>);+ // Wrap in resizable container when isResizable+ const content = showResizeHandle ? (+ <div+ ref={containerRef}+ {...stylex.props(styles.resizableContainer)}+ style={{width}}>+ {navElement}+ <div+ data-testid="xds-sidenav-resize-handle"+ role="separator"+ aria-orientation="vertical"+ aria-label="Resize sidebar"+ {...stylex.props(+ styles.dragHandle,+ isHandleHovered && styles.dragHandleHover,+ )}+ {...resizeHandleProps}+ />+ </div>+ ) : (+ navElement+ );+if (isCollapsible) {return (<XDSSideNavCollapseContext value={collapseContext}>diff --git a/packages/core/src/SideNav/useResizable.ts b/packages/core/src/SideNav/useResizable.tsnew file mode 100644index 0000000000..2959096347--- /dev/null+++ b/packages/core/src/SideNav/useResizable.ts@@ -0,0 +1,133 @@+/**+ * @file useResizable.ts+ * @input Resizable configuration (enabled, defaultWidth, onWidthChange)+ * @output Hook return: width state, containerRef, drag handle props, showHandle flag+ * @position Internal hook; consumed by XDSSideNav.tsx+ *+ * Extracts all resize-related state and pointer event listeners into a+ * standalone hook so event listeners are only registered when resizable+ * is enabled.+ */++import {useCallback, useEffect, useRef, useState} from 'react';++const MIN_WIDTH = 180;+const MAX_WIDTH = 480;+const DEFAULT_WIDTH = 260;++export interface ResizableConfig {+ defaultWidth?: number;+ onWidthChange?: (width: number) => void;+}++export interface UseResizableOptions {+ /** Whether resizing is enabled */+ enabled: boolean;+ /** Resizable configuration (defaultWidth, onWidthChange) */+ config: ResizableConfig;+ /** Whether the sidebar is collapsed (hides the handle) */+ collapsed: boolean;+}++export interface UseResizableReturn {+ /** Current width in pixels */+ width: number;+ /** Ref to attach to the resizable container div */+ containerRef: React.RefObject<HTMLDivElement | null>;+ /** Whether the drag handle should be rendered */+ showHandle: boolean;+ /** Props to spread onto the drag handle element */+ handleProps: {+ onPointerDown: (e: React.PointerEvent) => void;+ onPointerEnter: () => void;+ onPointerLeave: () => void;+ };+ /** Whether the handle is currently hovered */+ isHandleHovered: boolean;+}++export function useResizable({+ enabled,+ config,+ collapsed,+}: UseResizableOptions): UseResizableReturn {+ const {defaultWidth = DEFAULT_WIDTH, onWidthChange} = config;++ const [width, setWidth] = useState(+ Math.min(MAX_WIDTH, Math.max(MIN_WIDTH, defaultWidth)),+ );+ const containerRef = useRef<HTMLDivElement>(null);+ const isDraggingRef = useRef(false);+ const startXRef = useRef(0);+ const startWidthRef = useRef(0);+ const [isHandleHovered, setIsHandleHovered] = useState(false);++ const handlePointerDown = useCallback(+ (e: React.PointerEvent) => {+ if (!enabled) return;+ e.preventDefault();+ isDraggingRef.current = true;+ startXRef.current = e.clientX;+ startWidthRef.current = width;+ document.body.style.cursor = 'col-resize';++ const onPointerMove = (moveEvent: PointerEvent) => {+ if (!isDraggingRef.current) return;+ const delta = moveEvent.clientX - startXRef.current;+ const newWidth = Math.min(+ MAX_WIDTH,+ Math.max(MIN_WIDTH, startWidthRef.current + delta),+ );+ if (containerRef.current) {+ containerRef.current.style.width = `${newWidth}px`;+ }+ };++ const onPointerUp = (upEvent: PointerEvent) => {+ isDraggingRef.current = false;+ document.body.style.cursor = '';+ document.removeEventListener('pointermove', onPointerMove);+ document.removeEventListener('pointerup', onPointerUp);++ const delta = upEvent.clientX - startXRef.current;+ const finalWidth = Math.min(+ MAX_WIDTH,+ Math.max(MIN_WIDTH, startWidthRef.current + delta),+ );+ setWidth(finalWidth);+ onWidthChange?.(finalWidth);+ };++ document.addEventListener('pointermove', onPointerMove);+ document.addEventListener('pointerup', onPointerUp);+ },+ [enabled, width, onWidthChange],+ );++ // Clean up listeners if component unmounts during drag+ useEffect(() => {+ return () => {+ if (isDraggingRef.current) {+ document.body.style.cursor = '';+ }+ };+ }, []);++ const showHandle = enabled && !collapsed;++ const handleProps = {+ onPointerDown: handlePointerDown,+ onPointerEnter: () => setIsHandleHovered(true),+ onPointerLeave: () => {+ if (!isDraggingRef.current) setIsHandleHovered(false);+ },+ };++ return {+ width,+ containerRef,+ showHandle,+ handleProps,+ isHandleHovered,+ };+}