An open source design system that's fully customizable and agent ready
TypeScript
feat(SideNav): integrate useXDSResizable for built-in resize (#1877)
Ernesta27bb83a60b2
diff --git a/apps/sandbox/src/app/(raw)/pages/shell-lab/page.tsx b/apps/sandbox/src/app/(raw)/pages/shell-lab/page.tsxindex 6a5623b6c1..5f98f53a6b 100644--- a/apps/sandbox/src/app/(raw)/pages/shell-lab/page.tsx+++ b/apps/sandbox/src/app/(raw)/pages/shell-lab/page.tsx@@ -34,7 +34,6 @@ import {XDSNavIcon} from '@xds/core/NavIcon';import {XDSBanner} from '@xds/core/Banner';import {XDSList, XDSListItem} from '@xds/core/List';import {XDSNavMenuItem} from '@xds/core/NavMenu';-import {useXDSResizable} from '@xds/core/Resizable';// =============================================================================// Configuration types@@ -544,12 +543,6 @@ function SampleSideNav({externalCollapsed?: boolean;setExternalCollapsed?: (v: boolean) => void;}) {- const sidebar = useXDSResizable({- defaultSize: 260,- minSizePx: 180,- maxSizePx: 480,- });-const appNavIcon = (<XDSNavIconicon={@@ -633,7 +626,7 @@ function SampleSideNav({: true: false}- resizable={config.isResizable ? sidebar.props : false}+ resizable={config.isResizable}header={heading}topContent={config.showTopContent ? (diff --git a/packages/core/src/Resizable/XDSResizeHandle.tsx b/packages/core/src/Resizable/XDSResizeHandle.tsxindex 7392ac5b8f..9453a27a44 100644--- a/packages/core/src/Resizable/XDSResizeHandle.tsx+++ b/packages/core/src/Resizable/XDSResizeHandle.tsx@@ -77,6 +77,26 @@ const styles = stylex.create({':focus-visible': spacingVars['--spacing-0-5'],},},+ // Overlay mode — absolutely positioned inside the parent panel+ // instead of being a sibling in flex flow. Used when the handle+ // must stay within a parent's overflow: clip bounds.+ overlay: {+ position: 'absolute',+ zIndex: 2,+ backgroundColor: 'transparent',+ },+ overlayHorizontal: {+ insetInlineEnd: 0,+ top: 0,+ bottom: 0,+ width: 'var(--resize-handle-hit-area, 16px)',+ },+ overlayVertical: {+ insetBlockEnd: 0,+ left: 0,+ right: 0,+ height: 'var(--resize-handle-hit-area, 16px)',+ },horizontal: {width: 1,height: '100%',@@ -195,6 +215,16 @@ export interface XDSResizeHandleProps extends Omit<*/direction?: 'horizontal' | 'vertical';+ /**+ * Positioning mode. `'inline'` (default) puts the handle in normal+ * flex flow between siblings. `'overlay'` uses absolute positioning+ * so the handle sits inside a parent panel's bounds — useful when+ * the parent has `overflow: clip`.+ * @default 'inline'+ */+ position?: 'inline' | 'overlay';++ /**/*** Reverse the drag direction. Use when the handle controls a panel* on the end/right/bottom side.@@ -211,6 +241,7 @@ export interface XDSResizeHandleProps extends Omit</*** Show a 1px divider line. The line IS the handle — it takes only* 1px in the layout with a wider invisible hit area for interaction.+ * Ignored in overlay mode.* @default false*/hasDivider?: boolean;@@ -265,6 +296,7 @@ export interface XDSResizeHandleProps extends Omit<*/export function XDSResizeHandle({direction = 'horizontal',+ position: positionMode = 'inline',isReversed = false,isDisabled = false,hasDivider = false,@@ -282,6 +314,7 @@ export function XDSResizeHandle({const [isHovered, setIsHovered] = useState(false);const [isFocused, setIsFocused] = useState(false);const isHorizontal = direction === 'horizontal';+ const isOverlay = positionMode === 'overlay';const sign = isReversed ? -1 : 1;const effectiveSide = resolveEffectiveSide(pillPlacement,@@ -449,13 +482,21 @@ export function XDSResizeHandle({xdsClassName('resize-handle'),stylex.props(styles.handle,- isHorizontal ? styles.horizontal : styles.vertical,- !hasDivider &&+ isOverlay && styles.overlay,+ isOverlay &&+ (isHorizontal ? styles.overlayHorizontal : styles.overlayVertical),+ !isOverlay && (isHorizontal ? styles.horizontal : styles.vertical),+ !isOverlay &&+ !hasDivider &&(isHorizontal? styles.noDividerHorizontal: styles.noDividerVertical),- hasDivider && isInteracting && !isDragging && styles.handleHover,- hasDivider && isDragging && styles.handleActive,+ !isOverlay &&+ hasDivider &&+ isInteracting &&+ !isDragging &&+ styles.handleHover,+ !isOverlay && hasDivider && isDragging && styles.handleActive,isDisabled && styles.disabled,xstyle,),diff --git a/packages/core/src/Resizable/index.ts b/packages/core/src/Resizable/index.tsindex ef272cfa9c..b61704a67d 100644--- a/packages/core/src/Resizable/index.ts+++ b/packages/core/src/Resizable/index.ts@@ -12,6 +12,7 @@ export type {ResizableRegion,ResizableRegionConfig,ResizableProps,+ XDSResizableConfig,UseXDSResizableSingleConfig,UseXDSResizableMultiConfig,} from './useXDSResizable';diff --git a/packages/core/src/Resizable/useXDSResizable.ts b/packages/core/src/Resizable/useXDSResizable.tsindex 11c4d32adc..02b587b0ea 100644--- a/packages/core/src/Resizable/useXDSResizable.ts+++ b/packages/core/src/Resizable/useXDSResizable.ts@@ -30,9 +30,31 @@ export interface ResizableRegionConfig {shrinkOrder?: number;}+/**+ * Shared config shape for any component that integrates built-in resize+ * (e.g. XDSSideNav `resizable` prop). Provides a simplified API surface+ * over the full ResizableRegionConfig.+ */+export interface XDSResizableConfig {+ /** Initial width in pixels. @default 260 */+ defaultWidth?: number;+ /** Minimum width in pixels. @default 180 */+ minWidth?: number;+ /** Maximum width in pixels. @default 480 */+ maxWidth?: number;+ /** localStorage key for persisting width. */+ autoSaveId?: string;+ /** Called when the width changes (on drag end). */+ onWidthChange?: (width: number) => void;+}+export interface UseXDSResizableSingleConfig extends ResizableRegionConfig {/** Unique key for localStorage persistence. */autoSaveId?: string;+ /** Called when size changes during drag. */+ onSizeChange?: (size: number) => void;+ /** Called when collapse state changes (via drag or programmatic). */+ onCollapseChange?: (isCollapsed: boolean) => void;}export interface UseXDSResizableMultiConfig {@@ -165,6 +187,8 @@ function useSingleResizable(collapsedSize = DEFAULT_COLLAPSED_SIZE,snaps = [],autoSaveId,+ onSizeChange,+ onCollapseChange,} = config;const resolvedDefault = resolveDefaultSize(defaultSize);@@ -191,20 +215,34 @@ function useSingleResizable(preCollapseSize.current = size;setIsCollapsed(true);setSize(0);- }, [collapsible, size]);+ onCollapseChange?.(true);+ onSizeChange?.(0);+ }, [collapsible, size, onCollapseChange, onSizeChange]);const expand = useCallback(() => {setIsCollapsed(false);const restored = preCollapseSize.current || resolvedDefault;- setSize(clampSize(restored, minSizePx, maxSizePx, snaps));- }, [resolvedDefault, minSizePx, maxSizePx, snaps]);+ const newSize = clampSize(restored, minSizePx, maxSizePx, snaps);+ setSize(newSize);+ onCollapseChange?.(false);+ onSizeChange?.(newSize);+ }, [+ resolvedDefault,+ minSizePx,+ maxSizePx,+ snaps,+ onCollapseChange,+ onSizeChange,+ ]);const resize = useCallback((newSize: number) => {- setSize(clampSize(newSize, minSizePx, maxSizePx, snaps));+ const clamped = clampSize(newSize, minSizePx, maxSizePx, snaps);+ setSize(clamped);setIsCollapsed(false);+ onSizeChange?.(clamped);},- [minSizePx, maxSizePx, snaps],+ [minSizePx, maxSizePx, snaps, onSizeChange],);const onResizeStart = useCallback(() => {@@ -215,15 +253,22 @@ function useSingleResizable((delta: number) => {const raw = dragStartSize.current + delta;if (collapsible && raw < collapsedSize) {- if (!isCollapsed) preCollapseSize.current = size;+ if (!isCollapsed) {+ preCollapseSize.current = size;+ onCollapseChange?.(true);+ }setIsCollapsed(true);setSize(0);+ onSizeChange?.(0);return;}if (isCollapsed && raw >= collapsedSize) {setIsCollapsed(false);+ onCollapseChange?.(false);}- setSize(clampSize(raw, minSizePx, maxSizePx, snaps));+ const clamped = clampSize(raw, minSizePx, maxSizePx, snaps);+ setSize(clamped);+ onSizeChange?.(clamped);},[collapsible,@@ -233,6 +278,8 @@ function useSingleResizable(minSizePx,maxSizePx,snaps,+ onSizeChange,+ onCollapseChange,],);diff --git a/packages/core/src/SideNav/XDSSideNav.test.tsx b/packages/core/src/SideNav/XDSSideNav.test.tsxindex 49901ebe06..29a3cd5a16 100644--- a/packages/core/src/SideNav/XDSSideNav.test.tsx+++ b/packages/core/src/SideNav/XDSSideNav.test.tsx@@ -9,7 +9,7 @@import React from 'react';import {describe, it, expect, vi} from 'vitest';-import {render, screen, act} from '@testing-library/react';+import {render, screen, act, fireEvent} from '@testing-library/react';import userEvent from '@testing-library/user-event';import {forwardRef, type ComponentPropsWithoutRef, type ReactNode} from 'react';import {XDSSideNav} from './XDSSideNav';@@ -685,21 +685,13 @@ describe('XDSSideNav resizable', () => {</XDSSideNav>,);const handle = screen.getByTestId('xds-sidenav-resize-handle');+ // The pointer event handler is on the hit area child inside the handle.+ const hitArea = handle.firstElementChild as HTMLElement;- // Simulate pointer drag sequenceact(() => {- 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}),- );+ fireEvent.pointerDown(hitArea, {clientX: 260});+ fireEvent.pointerMove(document, {clientX: 310});+ fireEvent.pointerUp(document, {clientX: 310});});expect(handleWidthChange).toHaveBeenCalledTimes(1);diff --git a/packages/core/src/SideNav/XDSSideNav.tsx b/packages/core/src/SideNav/XDSSideNav.tsxindex ffdb63e878..ca75314a11 100644--- a/packages/core/src/SideNav/XDSSideNav.tsx+++ b/packages/core/src/SideNav/XDSSideNav.tsx@@ -19,26 +19,27 @@* - /packages/cli/templates/blocks/components/SideNav/ (showcase blocks)*/-import {useCallback, useState, type ReactNode} from 'react';+import {useCallback, useRef, useState, type ReactNode} from 'react';import type {XDSBaseProps} from '../XDSBaseProps';import * as stylex from '@stylexjs/stylex';import type {StyleXStyles} from '@stylexjs/stylex';-import {- borderVars,- colorVars,- durationVars,- easeVars,- spacingVars,-} from '../theme/tokens.stylex';+import {borderVars, colorVars, spacingVars} from '../theme/tokens.stylex';import {xdsClassName, mergeProps} from '../utils';import {XDSSideNavCollapseContext} from './XDSSideNavCollapseContext';import {XDSSideNavCollapseButton} from './XDSSideNavCollapseButton';import {useXDSSideNavRenderMode} from './XDSSideNavRenderContext';import {XDSMobileNav} from '../MobileNav/XDSMobileNav';-import {useResizable} from './useResizable';-import type {ResizableProps} from '../Resizable/useXDSResizable';+import {useXDSResizable} from '../Resizable/useXDSResizable';+import type {XDSResizableConfig} from '../Resizable/useXDSResizable';import {XDSResizeHandle} from '../Resizable/XDSResizeHandle';+// =============================================================================+// Constants+// =============================================================================++/** Width below which dragging collapses the sidebar (when collapsible). */+const COLLAPSE_THRESHOLD = 160;+// =============================================================================// Styles// =============================================================================@@ -152,26 +153,6 @@ const styles = stylex.create({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',- transitionProperty: 'background-color',- transitionDuration: durationVars['--duration-fast'],- transitionTimingFunction: easeVars['--ease-standard'],- touchAction: 'none',- },- dragHandleHover: {- // Applied via @media (hover: hover) in the component- backgroundColor: colorVars['--color-border'],- },// Topbar mode — horizontal layout for mobile top bartopbar: {display: 'flex',@@ -246,24 +227,21 @@ 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.+ * Enables a resize handle at the inline-end edge for resizing the sidebar.+ * Uses `useXDSResizable` internally and renders `XDSResizeHandle` in+ * overlay mode. When collapsed, the handle is hidden.*- * - `true` — resizable with defaults (260px initial width)- * - Object — configured:+ * - `true` — resizable with defaults (260px initial, 180–480px range)+ * - Object — configured via `XDSResizableConfig`:* - `defaultWidth` — initial width in pixels (default: 260)- * - `onWidthChange` — called when user finishes resizing- * - `ResizableProps` — driven by `useXDSResizable()` hook from `@xds/core/Resizable`+ * - `minWidth` — minimum width in pixels (default: 180)+ * - `maxWidth` — maximum width in pixels (default: 480)+ * - `autoSaveId` — localStorage key for persisting width+ * - `onWidthChange` — called when the width changes** @default false*/- resizable?:- | boolean- | {- defaultWidth?: number;- onWidthChange?: (width: number) => void;- }- | ResizableProps;+ resizable?: boolean | XDSResizableConfig;/*** Enables collapse behavior. The sidebar can be collapsed to a narrow@@ -334,13 +312,8 @@ export function XDSSideNav({const controlledCollapsed = collapsibleConfig.isCollapsed;const onCollapsedChange = collapsibleConfig.onCollapsedChange;- // Resizable config — detect if using new useXDSResizable() hook props- const isResizableHook =- typeof resizable === 'object' &&- resizable !== null &&- '_isResizableProps' in resizable;- const resizableConfig =- !isResizableHook && typeof resizable === 'object' ? resizable : {};+ // Resizable config+ const resizableConfig = typeof resizable === 'object' ? resizable : {};const isResizable = !!resizable;// Collapse state (controlled + uncontrolled)@@ -349,13 +322,41 @@ export function XDSSideNav({useState(defaultIsCollapsed);const collapsed = isControlled ? controlledCollapsed : uncontrolledCollapsed;+ const setCollapsedState = useCallback(+ (value: boolean) => {+ if (!isControlled) {+ setUncontrolledCollapsed(value);+ }+ onCollapsedChange?.(value);+ },+ [isControlled, onCollapsedChange],+ );++ // Resize hook — callbacks keep SideNav in sync without effects.+ const resizableHook = useXDSResizable({+ defaultSize: resizableConfig.defaultWidth ?? 260,+ minSizePx: resizableConfig.minWidth ?? 180,+ maxSizePx: resizableConfig.maxWidth ?? 480,+ collapsible: isCollapsible,+ collapsedSize: COLLAPSE_THRESHOLD,+ autoSaveId: resizableConfig.autoSaveId,+ onSizeChange: resizableConfig.onWidthChange,+ onCollapseChange: isCollapsible ? setCollapsedState : undefined,+ });+const toggle = useCallback(() => {- const newValue = !collapsed;- if (!isControlled) {- setUncontrolledCollapsed(newValue);+ const next = !collapsed;+ setCollapsedState(next);+ if (isResizable) {+ if (next) {+ resizableHook.collapse();+ } else {+ resizableHook.expand();+ }}- onCollapsedChange?.(newValue);- }, [collapsed, isControlled, onCollapsedChange]);+ }, [collapsed, setCollapsedState, isResizable, resizableHook]);++ const showResizeHandle = isResizable && !collapsed;const collapseContext = {isCollapsed: collapsed,@@ -363,32 +364,7 @@ export function XDSSideNav({isCollapsible,};- // =========================================================================- // Resize — use new ResizableProps when available, else legacy hook- // =========================================================================- const legacyResize = useResizable({- enabled: isResizable && !isResizableHook,- config: resizableConfig,- collapsed,- });-- // When using the new hook, derive width/handle state from ResizableProps- const resizableHookProps = isResizableHook- ? (resizable as ResizableProps)- : null;- const width = resizableHookProps- ? resizableHookProps._size- : legacyResize.width;- const showResizeHandle = resizableHookProps- ? !collapsed- : legacyResize.showHandle;- const resizeHandleProps = resizableHookProps- ? null- : legacyResize.handleProps;- const isHandleHovered = resizableHookProps- ? false- : legacyResize.isHandleHovered;- const containerRef = resizableHookProps ? null : legacyResize.containerRef;+ const navRef = useRef<HTMLElement>(null);// Render mode — when inside AppShell mobile layout, render subsetsconst renderMode = useXDSSideNavRenderMode();@@ -467,12 +443,17 @@ export function XDSSideNav({// When resizable, override the nav width via inline styleconst resizableNavStyle: React.CSSProperties | undefined = isResizable- ? {...(style ?? {}), width: collapsed ? undefined : width}+ ? {...(style ?? {}), width: collapsed ? undefined : resizableHook.size}: style;const navElement = (<nav- ref={ref}+ ref={node => {+ navRef.current = node;+ if (typeof ref === 'function') ref(node);+ else if (ref)+ (ref as React.MutableRefObject<HTMLElement | null>).current = node;+ }}role="navigation"aria-label="Side navigation"data-testid={testId}@@ -526,43 +507,20 @@ export function XDSSideNav({</nav>);- // Wrap in resizable container when using legacy resize (with built-in handle).- // When using new ResizableProps, wrap in a flex container with the new- // XDSResizeHandle. The container ensures the handle sits outside the nav's- // overflow boundary (AppShell wraps sideNav in a LayoutPanel with overflow:clip).- // When using legacy resize, use the old built-in drag handle.- const content = resizableHookProps ? (- <div- {...mergeProps(stylex.props(styles.resizableContainer), undefined, {- width: collapsed ? undefined : width,- })}>- {navElement}- {!collapsed && (- <XDSResizeHandle- direction="horizontal"- hasDivider- resizable={resizableHookProps}- label="Resize sidebar"- />- )}- </div>- ) : showResizeHandle ? (- <div- ref={containerRef}- {...mergeProps(stylex.props(styles.resizableContainer), {- style: {width},- })}>+ // Overlay drag handle inside the nav when resizable.+ // Uses XDSResizeHandle in overlay mode so the handle sits inside+ // the panel's overflow: clip bounds.+ const content = showResizeHandle ? (+ <div {...stylex.props(styles.resizableContainer)}>{navElement}- <div+ <XDSResizeHandledata-testid="xds-sidenav-resize-handle"- role="separator"- aria-orientation="vertical"- aria-label="Resize sidebar"- {...stylex.props(- styles.dragHandle,- isHandleHovered && styles.dragHandleHover,- )}- {...resizeHandleProps}+ direction="horizontal"+ position="overlay"+ pillPlacement="end"+ isAlwaysVisible={false}+ resizable={resizableHook.props}+ label="Resize sidebar"/></div>) : (diff --git a/packages/core/src/SideNav/useResizable.ts b/packages/core/src/SideNav/useResizable.tsdeleted file mode 100644index 2a62688121..0000000000--- a/packages/core/src/SideNav/useResizable.ts+++ /dev/null@@ -1,135 +0,0 @@-'use client';--/**- * @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,- };-}