An open source design system that's fully customizable and agent ready
TypeScript
feat(Dialog): useXDSImperativeDialog — show/hide without state management (#1239)
Cindy Zhanga87f5fb2edf6
diff --git a/packages/core/src/Dialog/index.ts b/packages/core/src/Dialog/index.tsindex aa9d59c9a3..ec37fd240f 100644--- a/packages/core/src/Dialog/index.ts+++ b/packages/core/src/Dialog/index.ts@@ -20,3 +20,6 @@ export type {export {XDSDialogHeader} from './XDSDialogHeader';export type {XDSDialogHeaderProps} from './XDSDialogHeader';++export {useXDSImperativeDialog} from './useXDSImperativeDialog';+export type {XDSImperativeDialogReturn} from './useXDSImperativeDialog';diff --git a/packages/core/src/Dialog/useXDSImperativeDialog.test.tsx b/packages/core/src/Dialog/useXDSImperativeDialog.test.tsxnew file mode 100644index 0000000000..ba841a1144--- /dev/null+++ b/packages/core/src/Dialog/useXDSImperativeDialog.test.tsx@@ -0,0 +1,70 @@+import {describe, it, expect, vi, beforeAll} from 'vitest';+import {render, screen, fireEvent} from '@testing-library/react';+import {useXDSImperativeDialog} from './useXDSImperativeDialog';++// jsdom doesn't support dialog.showModal/close+beforeAll(() => {+ HTMLDialogElement.prototype.showModal = vi.fn();+ HTMLDialogElement.prototype.close = vi.fn();+});++function TestHarness() {+ const dialog = useXDSImperativeDialog({width: 400});++ return (+ <div>+ <button onClick={() => dialog.show(<div>Dialog content</div>)}>+ Open+ </button>+ <button onClick={() => dialog.hide()}>Close</button>+ <span data-testid="status">{dialog.isOpen ? 'open' : 'closed'}</span>+ {dialog.element}+ </div>+ );+}++describe('useXDSImperativeDialog', () => {+ it('starts closed', () => {+ render(<TestHarness />);+ expect(screen.getByTestId('status').textContent).toBe('closed');+ });++ it('opens on show()', () => {+ render(<TestHarness />);+ fireEvent.click(screen.getByText('Open'));+ expect(screen.getByTestId('status').textContent).toBe('open');+ });++ it('renders content when open', () => {+ render(<TestHarness />);+ fireEvent.click(screen.getByText('Open'));+ expect(screen.getByText('Dialog content')).toBeInTheDocument();+ });++ it('closes on hide()', () => {+ render(<TestHarness />);+ fireEvent.click(screen.getByText('Open'));+ expect(screen.getByTestId('status').textContent).toBe('open');+ fireEvent.click(screen.getByText('Close'));+ expect(screen.getByTestId('status').textContent).toBe('closed');+ });++ it('can show with options', () => {+ function OptionsHarness() {+ const dialog = useXDSImperativeDialog();+ return (+ <div>+ <button onClick={() => dialog.show(<div>Wide content</div>, {width: 720})}>+ Open Wide+ </button>+ <span data-testid="status">{dialog.isOpen ? 'open' : 'closed'}</span>+ {dialog.element}+ </div>+ );+ }+ render(<OptionsHarness />);+ fireEvent.click(screen.getByText('Open Wide'));+ expect(screen.getByTestId('status').textContent).toBe('open');+ expect(screen.getByText('Wide content')).toBeInTheDocument();+ });+});diff --git a/packages/core/src/Dialog/useXDSImperativeDialog.tsx b/packages/core/src/Dialog/useXDSImperativeDialog.tsxnew file mode 100644index 0000000000..73523f7ed8--- /dev/null+++ b/packages/core/src/Dialog/useXDSImperativeDialog.tsx@@ -0,0 +1,98 @@+'use client';++/**+ * @file useXDSImperativeDialog.tsx+ * @input Uses React, XDSDialog+ * @output Exports useXDSImperativeDialog hook+ * @position Utility hook; wraps XDSDialog with imperative show/hide API+ *+ * Eliminates boilerplate for dialogs that don't need controlled state.+ * Instead of managing isOpen + content state, call show() with content+ * and the dialog handles the rest.+ *+ * @example+ * ```+ * const dialog = useXDSImperativeDialog();+ *+ * <button onClick={() => dialog.show(<MyContent />)}>Open</button>+ * {dialog.element}+ * ```+ */++import {useState, useCallback, useMemo, type ReactNode} from 'react';+import {XDSDialog, type XDSDialogProps} from './XDSDialog';++type DialogOptions = Omit<+ XDSDialogProps,+ 'isOpen' | 'onOpenChange' | 'children'+>;++export interface XDSImperativeDialogReturn {+ /** Show the dialog with the given content. */+ show: (content: ReactNode, options?: DialogOptions) => void;+ /** Hide the dialog. */+ hide: () => void;+ /** Whether the dialog is currently open. */+ isOpen: boolean;+ /** Render this in your JSX tree. */+ element: ReactNode;+}++/**+ * Imperative dialog — show/hide without managing state.+ *+ * @example+ * ```+ * const dialog = useXDSImperativeDialog();+ *+ * // Fire and forget — no isOpen state needed+ * onClick={() => dialog.show(+ * <XDSCodeBlock code={output} language="bash" />+ * )}+ *+ * // With options+ * onClick={() => dialog.show(content, { width: 720, variant: 'fullscreen' })}+ *+ * // Render the portal+ * return <>{dialog.element}</>;+ * ```+ */+export function useXDSImperativeDialog(+ defaultOptions?: DialogOptions,+): XDSImperativeDialogReturn {+ const [isOpen, setIsOpen] = useState(false);+ const [content, setContent] = useState<ReactNode>(null);+ const [options, setOptions] = useState<DialogOptions | undefined>(+ defaultOptions,+ );++ const show = useCallback(+ (newContent: ReactNode, newOptions?: DialogOptions) => {+ setContent(newContent);+ if (newOptions) setOptions(prev => ({...prev, ...newOptions}));+ setIsOpen(true);+ },+ [],+ );++ const hide = useCallback(() => {+ setIsOpen(false);+ }, []);++ const element = useMemo(+ () => (+ <XDSDialog+ isOpen={isOpen}+ onOpenChange={open => {+ if (!open) setIsOpen(false);+ }}+ {...(defaultOptions ?? {})}+ {...(options ?? {})}>+ {content}+ </XDSDialog>+ ),+ [isOpen, content, options, defaultOptions],+ );++ return {show, hide, isOpen, element};+}