An open source design system that's fully customizable and agent ready
TypeScript
Fix external SideNav collapse button (#2351)
Andrey Goder729c4a60cb4f
diff --git a/packages/core/src/Lightbox/XDSLightbox.tsx b/packages/core/src/Lightbox/XDSLightbox.tsxindex 9785e8510a..f81aeac0df 100644--- a/packages/core/src/Lightbox/XDSLightbox.tsx+++ b/packages/core/src/Lightbox/XDSLightbox.tsx@@ -30,7 +30,7 @@ import {XDSIcon} from '../Icon';import {XDSIconButton} from '../IconButton';import {useScrollLock} from '../hooks/useScrollLock';import {useIsomorphicLayoutEffect} from '../hooks/useIsomorphicLayoutEffect';-import {xdsClassName, mergeProps} from '../utils';+import {xdsClassName, mergeProps, mergeRefs} from '../utils';import type {XDSBaseProps} from '../XDSBaseProps';/**@@ -291,7 +291,7 @@ export function XDSLightbox({}onIndexChange?.(value);},- [isControlled, onIndexChange],+ [isControlled, onIndexChange, setUncontrolledIndex],);// Zoom/pan state@@ -314,7 +314,10 @@ export function XDSLightbox({// Reset zoom on image changeuseEffect(() => {+ // Reset image view state when the active media item changes.+ // eslint-disable-next-line @eslint-react/set-state-in-effectsetZoom(1);+ // eslint-disable-next-line @eslint-react/set-state-in-effectsetPan({x: 0, y: 0});}, [index, currentItem.src]);@@ -443,21 +446,6 @@ export function XDSLightbox({};}, [isDragging]);- // Merge refs- const setRef = useCallback(- (node: HTMLDialogElement | null) => {- (dialogRef as React.MutableRefObject<HTMLDialogElement | null>).current =- node;- if (typeof ref === 'function') {- ref(node);- } else if (ref) {- (ref as React.MutableRefObject<HTMLDialogElement | null>).current =- node;- }- },- [ref],- );-const isZoomed = zoom > 1;const imageTransform =zoom === 1@@ -466,7 +454,7 @@ export function XDSLightbox({return (<dialog- ref={setRef}+ ref={mergeRefs(ref, dialogRef)}onCancel={handleCancel}onClick={handleBackdropClick}onKeyDown={handleKeyDown}diff --git a/packages/core/src/SideNav/SideNav.doc.mjs b/packages/core/src/SideNav/SideNav.doc.mjsindex 8feaf6b8e9..35baed337b 100644--- a/packages/core/src/SideNav/SideNav.doc.mjs+++ b/packages/core/src/SideNav/SideNav.doc.mjs@@ -66,6 +66,12 @@ export const docs = {'Enables collapse behavior. true for uncontrolled with default toggle button, or an object for controlled mode and advanced config (defaultIsCollapsed, isCollapsed + onCollapsedChange, hasButton, buttonLabel).',default: 'false',},+ {+ name: 'handleRef',+ type: 'Ref<XDSSideNavImperativeCollapseHandle>',+ description:+ 'Imperative collapse handle for XDSSideNavCollapseButton instances rendered outside this SideNav. Separate from `ref`, which continues to expose the root HTMLElement.',+ },{name: 'xstyle',type: 'StyleXStyles',@@ -250,13 +256,13 @@ export const docs = {{name: 'XDSSideNavCollapseButton',description:- 'Toggle button for sidenav collapse. Place inside XDSSideNav (reads context automatically) or outside (pass sideNavRef). Renders as an icon-only ghost button by default.',+ 'Toggle button for sidenav collapse. Place inside XDSSideNav (reads context automatically) or outside (pass handleRef). Renders as an icon-only ghost button by default.',props: [{- name: 'sideNavRef',- type: 'RefObject<HTMLElement | null>',+ name: 'handleRef',+ type: 'RefObject<XDSSideNavImperativeCollapseHandle | null>',description:- 'Ref to the XDSSideNav element. Only needed when the button is rendered outside the sidenav.',+ 'Imperative collapse handle from XDSSideNav. Only needed when the button is rendered outside the sidenav.',},{name: 'label',@@ -339,6 +345,12 @@ export const docsZh = {'启用折叠行为。true 表示非受控模式并带默认切换按钮,或传入对象进行受控模式和高级配置(defaultIsCollapsed、isCollapsed + onCollapsedChange、hasButton、buttonLabel)。',default: 'false',},+ {+ name: 'handleRef',+ type: 'Ref<XDSSideNavImperativeCollapseHandle>',+ description:+ '供渲染在 SideNav 外部的 XDSSideNavCollapseButton 使用的命令式折叠句柄。与 `ref` 分离,`ref` 仍然指向根 HTMLElement。',+ },{name: 'xstyle',type: 'StyleXStyles',@@ -505,13 +517,13 @@ export const docsZh = {{name: 'XDSSideNavCollapseButton',description:- '侧边栏折叠切换按钮。放置在 XDSSideNav 内部(自动读取上下文)或外部(传入 sideNavRef)。默认渲染为仅图标的 ghost 按钮。',+ '侧边栏折叠切换按钮。放置在 XDSSideNav 内部(自动读取上下文)或外部(传入 handleRef)。默认渲染为仅图标的 ghost 按钮。',props: [{- name: 'sideNavRef',- type: 'RefObject<HTMLElement | null>',+ name: 'handleRef',+ type: 'RefObject<XDSSideNavImperativeCollapseHandle | null>',description:- 'XDSSideNav 元素的引用。仅在按钮渲染在侧边栏外部时需要。',+ '来自 XDSSideNav 的命令式折叠句柄。仅在按钮渲染在侧边栏外部时需要。',},{name: 'label',@@ -574,6 +586,7 @@ export const docsDense = {footer: 'Footer area above icon bar.',footerIcons: 'Footer icon bar.',collapsible: 'Enables collapse behavior. true for uncontrolled w/ default toggle, or object for controlled mode (defaultIsCollapsed, isCollapsed+onCollapsedChange, hasButton, buttonLabel).',+ handleRef: 'Imperative collapse handle for XDSSideNavCollapseButton outside this SideNav. `ref` still exposes the root HTMLElement.',xstyle: 'StyleX styles for layout customization. Must be stylex.create() value.',},},@@ -627,9 +640,9 @@ export const docsDense = {{name: 'XDSSideNavCollapseButton',description:- 'Toggle button for sidenav collapse. Place inside XDSSideNav (reads context) or outside (pass sideNavRef). Icon-only ghost button by default.',+ 'Toggle button for sidenav collapse. Place inside XDSSideNav (reads context) or outside (pass handleRef). Icon-only ghost button by default.',propDescriptions: {- sideNavRef: 'Ref to XDSSideNav element. Only needed when button rendered outside sidenav.',+ handleRef: 'Imperative collapse handle from XDSSideNav. Only needed when button rendered outside sidenav.',label: 'Custom label. Text button w/ chevron when provided, icon-only when omitted.',children: 'Custom content. Overrides default chevron icon + label.',},diff --git a/packages/core/src/SideNav/XDSSideNav.test.tsx b/packages/core/src/SideNav/XDSSideNav.test.tsxindex 000fe5c37a..68c5b70a81 100644--- a/packages/core/src/SideNav/XDSSideNav.test.tsx+++ b/packages/core/src/SideNav/XDSSideNav.test.tsx@@ -13,13 +13,17 @@ import React from 'react';import {describe, it, expect, vi} from 'vitest';import {render, screen, act, fireEvent} from '@testing-library/react';import userEvent from '@testing-library/user-event';-import type {ReactNode} from 'react';+import {useRef, useState, type ReactNode} from 'react';import {XDSSideNav} from './XDSSideNav';+import {XDSSideNavCollapseButton} from './XDSSideNavCollapseButton';import {XDSSideNavHeading} from './XDSSideNavHeading';import {XDSSideNavItem} from './XDSSideNavItem';import {XDSSideNavSection} from './XDSSideNavSection';import {XDSLinkProvider} from '../Link/XDSLinkProvider';-import {XDSSideNavCollapseContext} from './XDSSideNavCollapseContext';+import {+ XDSSideNavCollapseContext,+ type XDSSideNavImperativeCollapseHandle,+} from './XDSSideNavCollapseContext';function CustomLink({children,@@ -123,6 +127,41 @@ describe('XDSSideNav', () => {render(<XDSSideNav data-testid="page-nav">Content</XDSSideNav>);expect(screen.getByTestId('page-nav')).toBeInTheDocument();});++ it('renders and toggles from outside SideNav when handleRef is provided', async () => {+ const user = userEvent.setup();++ function Example() {+ const [isCollapsed, setIsCollapsed] = useState(false);+ const handleRef = useRef<XDSSideNavImperativeCollapseHandle>(null);++ return (+ <>+ <XDSSideNavCollapseButton handleRef={handleRef} />+ <XDSSideNav+ handleRef={handleRef}+ collapsible={{+ isCollapsed,+ onCollapsedChange: setIsCollapsed,+ hasButton: false,+ }}>+ <XDSSideNavSection title="Main">+ <XDSSideNavItem label="Dashboard" icon={StubIcon} />+ </XDSSideNavSection>+ </XDSSideNav>+ </>+ );+ }++ render(<Example />);++ const button = screen.getByRole('button', {name: 'Collapse sidebar'});+ await user.click(button);++ expect(+ screen.getByRole('button', {name: 'Expand sidebar'}),+ ).toBeInTheDocument();+ });});// =============================================================================diff --git a/packages/core/src/SideNav/XDSSideNav.tsx b/packages/core/src/SideNav/XDSSideNav.tsxindex 75ed4dae1c..cfb7d82278 100644--- a/packages/core/src/SideNav/XDSSideNav.tsx+++ b/packages/core/src/SideNav/XDSSideNav.tsx@@ -21,13 +21,23 @@* - /packages/cli/templates/blocks/components/SideNav/ (showcase blocks)*/-import {useCallback, useRef, useState, type ReactNode} from 'react';+import {+ useCallback,+ useImperativeHandle,+ 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, spacingVars} from '../theme/tokens.stylex';import {xdsClassName, mergeProps, mergeRefs} from '../utils';-import {XDSSideNavCollapseContext} from './XDSSideNavCollapseContext';+import {+ XDSSideNavCollapseContext,+ type XDSSideNavCollapseState,+ type XDSSideNavImperativeCollapseHandle,+} from './XDSSideNavCollapseContext';import {XDSSideNavCollapseButton} from './XDSSideNavCollapseButton';import {useXDSSideNavRenderMode} from './XDSSideNavRenderContext';import {XDSMobileNav} from '../MobileNav/XDSMobileNav';@@ -186,6 +196,14 @@ const styles = stylex.create({export interface XDSSideNavProps extends XDSBaseProps<HTMLElement> {/** Ref forwarded to the root element */ref?: React.Ref<HTMLElement>;++ /**+ * Imperative collapse handle for XDSSideNavCollapseButton instances rendered+ * outside this SideNav. This intentionally stays separate from `ref`, which+ * continues to expose the root HTMLElement.+ */+ handleRef?: React.Ref<XDSSideNavImperativeCollapseHandle>;+/*** Header area — typically XDSSideNavHeading. Sticky at top.*/@@ -308,6 +326,7 @@ export function XDSSideNav({style,'data-testid': testId,ref,+ handleRef,...props}: XDSSideNavProps) {// Parse collapsible prop@@ -327,6 +346,12 @@ export function XDSSideNav({const [uncontrolledCollapsed, setUncontrolledCollapsed] =useState(defaultIsCollapsed);const collapsed = isControlled ? controlledCollapsed : uncontrolledCollapsed;+ const navRef = useRef<HTMLElement>(null);+ const collapseStateRef = useRef<XDSSideNavCollapseState>({+ isCollapsed: collapsed,+ toggle: () => {},+ isCollapsible,+ });const setCollapsedState = useCallback((value: boolean) => {@@ -352,6 +377,12 @@ export function XDSSideNav({const toggle = useCallback(() => {const next = !collapsed;++ collapseStateRef.current = {+ ...collapseStateRef.current,+ isCollapsed: next,+ };+setCollapsedState(next);if (isResizable) {if (next) {@@ -364,13 +395,25 @@ export function XDSSideNav({const showResizeHandle = isResizable && !collapsed;+ collapseStateRef.current = {+ isCollapsed: collapsed,+ toggle,+ isCollapsible,+ };+const collapseContext = {isCollapsed: collapsed,toggle,isCollapsible,};- const navRef = useRef<HTMLElement>(null);+ useImperativeHandle(+ handleRef,+ () => ({+ getCollapseState: () => collapseStateRef.current,+ }),+ [],+ );// Render mode — when inside AppShell mobile layout, render subsetsconst renderMode = useXDSSideNavRenderMode();diff --git a/packages/core/src/SideNav/XDSSideNavCollapseButton.tsx b/packages/core/src/SideNav/XDSSideNavCollapseButton.tsxindex 283e627859..860acc6860 100644--- a/packages/core/src/SideNav/XDSSideNavCollapseButton.tsx+++ b/packages/core/src/SideNav/XDSSideNavCollapseButton.tsx@@ -9,7 +9,7 @@* @position Composable toggle button for sidenav collapse** Place inside XDSSideNav (reads context automatically) or outside- * (pass sideNavRef to connect). Customizable via label/children.+ * (pass handleRef to connect). Customizable via label/children.** SYNC: When modified, update:* - /packages/core/src/SideNav/SideNav.doc.mjs@@ -17,13 +17,17 @@* - /packages/cli/templates/blocks/components/SideNav/ (showcase blocks)*/-import React, {useCallback, type ReactNode} from 'react';+import React, {type ReactNode} from 'react';import * as stylex from '@stylexjs/stylex';import {durationVars, easeVars} from '../theme/tokens.stylex';import {getIcon} from '../Icon/globalIconRegistry';import {XDSButton} from '../Button';import type {XDSBaseProps} from '../XDSBaseProps';-import {useXDSSideNavCollapse} from './XDSSideNavCollapseContext';+import {+ useXDSSideNavCollapse,+ type XDSSideNavCollapseState,+ type XDSSideNavImperativeCollapseHandle,+} from './XDSSideNavCollapseContext';import {useXDSAppShellMobile} from '../AppShell/XDSAppShellMobileContext';// =============================================================================@@ -50,11 +54,10 @@ const styles = stylex.create({export interface XDSSideNavCollapseButtonProps extends XDSBaseProps<HTMLButtonElement> {ref?: React.Ref<HTMLButtonElement>;/**- * Ref to the XDSSideNav element. Only needed when the button is- * rendered outside the sidenav (reads collapse state via ref instead- * of context).+ * Imperative handle from XDSSideNav. Only needed when the button is rendered+ * outside the sidenav, where collapse context is unavailable.*/- sideNavRef?: React.RefObject<HTMLElement | null>;+ handleRef?: React.RefObject<XDSSideNavImperativeCollapseHandle | null>;/*** Custom button label text. When provided, renders as a text button@@ -77,7 +80,7 @@ export interface XDSSideNavCollapseButtonProps extends XDSBaseProps<HTMLButtonEl** Place anywhere inside XDSSideNav (header, topContent, footer, footerIcons)* and it reads collapse state from context automatically. For placement- * outside the sidenav (e.g. in TopNav or content area), pass sideNavRef.+ * outside the sidenav (e.g. in TopNav or content area), pass handleRef.** @example* ```@@ -89,27 +92,21 @@ export interface XDSSideNavCollapseButtonProps extends XDSBaseProps<HTMLButtonEl* @example* ```* const ref = useRef(null);- * <XDSTopNav endContent={<XDSSideNavCollapseButton sideNavRef={ref} />} />- * <XDSSideNav ref={ref} isCollapsible>...</XDSSideNav>+ * <XDSTopNav endContent={<XDSSideNavCollapseButton handleRef={ref} />} />+ * <XDSSideNav handleRef={ref} collapsible>...</XDSSideNav>* ```*/export function XDSSideNavCollapseButton({ref,- sideNavRef: _sideNavRef,+ handleRef,label,children,+ ...props}: XDSSideNavCollapseButtonProps) {- const {isCollapsed, toggle, isCollapsible} = useXDSSideNavCollapse();+ const {isCollapsed, toggle, isCollapsible} =+ useXDSSideNavCollapseState(handleRef);const {isMobile} = useXDSAppShellMobile();- const handleClick = useCallback(() => {- toggle();- }, [toggle]);-- // TODO: sideNavRef-based wiring for outside-sidenav usage- // For now, the button only works via context (inside sidenav or- // when AppShell provides the context at the shell level).-// Hide when not collapsible, or when in mobile mode (sidenav is in// the mobile drawer — collapse doesn't apply there)if (!isCollapsible || isMobile) {@@ -121,7 +118,8 @@ export function XDSSideNavCollapseButton({ref={ref}label={label ?? (isCollapsed ? 'Expand sidebar' : 'Collapse sidebar')}variant="ghost"- onClick={handleClick}+ {...props}+ onClick={toggle}icon={children ?? (<span@@ -139,3 +137,25 @@ export function XDSSideNavCollapseButton({}XDSSideNavCollapseButton.displayName = 'XDSSideNavCollapseButton';++function useXDSSideNavCollapseState(+ handleRef:+ | React.RefObject<XDSSideNavImperativeCollapseHandle | null>+ | undefined,+): XDSSideNavCollapseState {+ const contextCollapseState = useXDSSideNavCollapse();++ if (handleRef == null) {+ return contextCollapseState;+ }++ const externalCollapseState = handleRef.current?.getCollapseState() ?? null;++ return {+ isCollapsed: externalCollapseState?.isCollapsed ?? false,+ toggle: () => {+ handleRef.current?.getCollapseState()?.toggle();+ },+ isCollapsible: externalCollapseState?.isCollapsible ?? true,+ };+}diff --git a/packages/core/src/SideNav/XDSSideNavCollapseContext.ts b/packages/core/src/SideNav/XDSSideNavCollapseContext.tsindex 8abb917023..cf6a433baf 100644--- a/packages/core/src/SideNav/XDSSideNavCollapseContext.ts+++ b/packages/core/src/SideNav/XDSSideNavCollapseContext.ts@@ -10,6 +10,8 @@** Provides collapse state to XDSSideNavCollapseButton and other* sidenav children. Set by XDSSideNav when isCollapsible is true.+ * Also provides a small imperative handle for ref-based collapse buttons+ * rendered outside the XDSSideNav tree.*/import {createContext, use} from 'react';@@ -28,6 +30,10 @@ export interface XDSSideNavCollapseState {*/export type SideNavCollapseState = XDSSideNavCollapseState;+export interface XDSSideNavImperativeCollapseHandle {+ getCollapseState: () => XDSSideNavCollapseState | null;+}+export const XDSSideNavCollapseContext = createContext<XDSSideNavCollapseState>({isCollapsed: false,diff --git a/packages/core/src/SideNav/index.ts b/packages/core/src/SideNav/index.tsindex e47195a632..338902a4db 100644--- a/packages/core/src/SideNav/index.ts+++ b/packages/core/src/SideNav/index.ts@@ -27,7 +27,10 @@ export {XDSSideNavCollapseButton} from './XDSSideNavCollapseButton';export type {XDSSideNavCollapseButtonProps} from './XDSSideNavCollapseButton';export {useXDSSideNavCollapse} from './XDSSideNavCollapseContext';-export type {XDSSideNavCollapseState} from './XDSSideNavCollapseContext';+export type {+ XDSSideNavCollapseState,+ XDSSideNavImperativeCollapseHandle,+} from './XDSSideNavCollapseContext';export {XDSSideNavRenderContext,