Skip to content

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.tsx
index 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 change
useEffect(() => {
+ // Reset image view state when the active media item changes.
+ // eslint-disable-next-line @eslint-react/set-state-in-effect
setZoom(1);
+ // eslint-disable-next-line @eslint-react/set-state-in-effect
setPan({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.mjs
index 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.tsx
index 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.tsx
index 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 subsets
const renderMode = useXDSSideNavRenderMode();
diff --git a/packages/core/src/SideNav/XDSSideNavCollapseButton.tsx b/packages/core/src/SideNav/XDSSideNavCollapseButton.tsx
index 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.ts
index 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.ts
index 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,