An open source design system that's fully customizable and agent ready
TypeScript
fix(dialog): suppress inline autofocus (#2774)
Cindy Zhangc054be615c6e
diff --git a/.changeset/docsite-autofocus-suppression.md b/.changeset/docsite-autofocus-suppression.mdnew file mode 100644index 0000000000..e451fdc105--- /dev/null+++ b/.changeset/docsite-autofocus-suppression.md@@ -0,0 +1,5 @@+---+'@xds/core': patch+---++Suppress documentation-preview autofocus for inline dialogs. `XDSDialogHeader` now skips its title autofocus when rendered inside `XDSDialog isInline`, preventing component examples from stealing page scroll. `XDSCommandPaletteInput` now reads the same dialog inline context instead of carrying a duplicate inline flag in CommandPalette context.diff --git a/packages/core/src/CommandPalette/CommandPaletteContext.ts b/packages/core/src/CommandPalette/CommandPaletteContext.tsindex e69ad5bfc7..862da94e58 100644--- a/packages/core/src/CommandPalette/CommandPaletteContext.ts+++ b/packages/core/src/CommandPalette/CommandPaletteContext.ts@@ -42,8 +42,6 @@ export interface CommandPaletteContextValue {isOpen: boolean;/** Whether an async search is in flight. */isBusy: boolean;- /** Whether the palette is rendered inline (no modal behavior). */- isInline: boolean;}export const CommandPaletteContext =diff --git a/packages/core/src/CommandPalette/XDSCommandPalette.tsx b/packages/core/src/CommandPalette/XDSCommandPalette.tsxindex 0941336182..ee9c7bb31f 100644--- a/packages/core/src/CommandPalette/XDSCommandPalette.tsx+++ b/packages/core/src/CommandPalette/XDSCommandPalette.tsx@@ -466,7 +466,6 @@ export function XDSCommandPalette<onClose: handleClose,isOpen,isBusy,- isInline: isInline ?? false,}),[optimisticSearch,@@ -485,7 +484,6 @@ export function XDSCommandPalette<handleClose,isOpen,isBusy,- isInline,],);diff --git a/packages/core/src/CommandPalette/XDSCommandPaletteInput.test.tsx b/packages/core/src/CommandPalette/XDSCommandPaletteInput.test.tsxindex 7bad339641..69e2154a0c 100644--- a/packages/core/src/CommandPalette/XDSCommandPaletteInput.test.tsx+++ b/packages/core/src/CommandPalette/XDSCommandPaletteInput.test.tsx@@ -2,7 +2,7 @@/*** @file XDSCommandPaletteInput.test.tsx- * @input Uses vitest, @testing-library/react, XDSCommandPaletteInput+ * @input Uses vitest, @testing-library/react, XDSCommandPaletteInput, XDSDialog* @output Unit tests for XDSCommandPaletteInput component* @position Testing; validates XDSCommandPaletteInput.tsx implementation*/@@ -11,6 +11,7 @@ import {describe, it, expect, vi} from 'vitest';import {render, screen, fireEvent} from '@testing-library/react';import {XDSCommandPaletteInput} from './XDSCommandPaletteInput';import {CommandPaletteContext} from './CommandPaletteContext';+import {XDSDialog} from '../Dialog';import type {CommandPaletteContextValue} from './CommandPaletteContext';describe('XDSCommandPaletteInput', () => {@@ -72,7 +73,7 @@ describe('XDSCommandPaletteInput', () => {});});-describe('XDSCommandPaletteInput inline context', () => {+describe('XDSCommandPaletteInput dialog context', () => {function makeContext(overrides: Partial<CommandPaletteContextValue> = {},): CommandPaletteContextValue {@@ -92,17 +93,18 @@ describe('XDSCommandPaletteInput inline context', () => {onClose: vi.fn(),isOpen: true,isBusy: false,- isInline: false,...overrides,};}- it('does not auto-focus when context isInline is true', () => {+ it('does not auto-focus inside an inline dialog', () => {const focusSpy = vi.spyOn(HTMLElement.prototype, 'focus');render(- <CommandPaletteContext value={makeContext({isInline: true})}>- <XDSCommandPaletteInput />- </CommandPaletteContext>,+ <XDSDialog isOpen isInline onOpenChange={() => {}}>+ <CommandPaletteContext value={makeContext()}>+ <XDSCommandPaletteInput />+ </CommandPaletteContext>+ </XDSDialog>,);const input = screen.getByRole('combobox');@@ -113,9 +115,9 @@ describe('XDSCommandPaletteInput inline context', () => {focusSpy.mockRestore();});- it('auto-focuses when context isInline is false', async () => {+ it('auto-focuses outside an inline dialog', async () => {render(- <CommandPaletteContext value={makeContext({isInline: false})}>+ <CommandPaletteContext value={makeContext()}><XDSCommandPaletteInput /></CommandPaletteContext>,);diff --git a/packages/core/src/CommandPalette/XDSCommandPaletteInput.tsx b/packages/core/src/CommandPalette/XDSCommandPaletteInput.tsxindex edeee851ce..50d4d9156e 100644--- a/packages/core/src/CommandPalette/XDSCommandPaletteInput.tsx+++ b/packages/core/src/CommandPalette/XDSCommandPaletteInput.tsx@@ -3,7 +3,7 @@'use client';/*** @file XDSCommandPaletteInput.tsx- * @input Uses React, StyleX, XDSIcon, CommandPaletteContext+ * @input Uses React, StyleX, XDSIcon, CommandPaletteContext, DialogContext* @output Exports XDSCommandPaletteInput component and props* @position Search input for the command palette*@@ -24,6 +24,7 @@ import {typographyVars,} from '../theme/tokens.stylex';import {useCommandPaletteContext} from './CommandPaletteContext';+import {useDialogContext} from '../Dialog/DialogContext';import type {XDSBaseProps} from '../XDSBaseProps';const styles = stylex.create({@@ -155,15 +156,16 @@ export function XDSCommandPaletteInput({...props}: XDSCommandPaletteInputProps) {const ctx = useCommandPaletteContext();+ const dialogContext = useDialogContext();const inputRef = useRef<HTMLInputElement>(null);// Use context values as fallbackconst value = controlledValue ?? ctx?.search;const handleValueChange = onValueChange ?? ctx?.setSearch;- // When inside an inline CommandPalette, disable auto-focus by default+ // When rendered inside an inline dialog, disable auto-focus by default// to avoid stealing focus from the surrounding page.- const effectiveAutoFocus = hasAutoFocus && !(ctx?.isInline ?? false);+ const effectiveAutoFocus = hasAutoFocus && dialogContext?.isInline !== true;// Auto-focus on mountuseEffect(() => {diff --git a/packages/core/src/Dialog/Dialog.doc.mjs b/packages/core/src/Dialog/Dialog.doc.mjsindex 9e04007617..713bce237b 100644--- a/packages/core/src/Dialog/Dialog.doc.mjs+++ b/packages/core/src/Dialog/Dialog.doc.mjs@@ -95,7 +95,7 @@ export const docs = {name: 'isInline',type: 'boolean',description:- 'Renders dialog content inline without the <dialog> element, backdrop, or modal behavior. For documentation previews and showcases only.',+ 'Renders dialog content inline without the <dialog> element, backdrop, modal behavior, or dialog autofocus. For documentation previews and showcases only.',default: 'false',},], },@@ -109,7 +109,7 @@ export const docs = {{name: 'title',type: 'string',- description: 'Dialog title (receives focus on open).',+ description: 'Dialog title (receives focus on open in modal dialogs; suppressed for inline previews).',},{name: 'subtitle',@@ -350,6 +350,7 @@ export const docsDense = {position: 'static position; centered by default',variant: 'standard or fullscreen (fills viewport)',purpose: 'dismissal behavior: required=no dismiss; form=no backdrop after interaction; info=both allowed',+ isInline: 'inline docs/showcase rendering; no <dialog>, backdrop, modal behavior, or dialog autofocus',},},{@@ -358,7 +359,7 @@ export const docsDense = {displayName: 'Dialog Header',description: 'dialog header w/ title, optional subtitle, close button, start/end content slots',propDescriptions: {- title: 'dialog title (receives focus on open)',+ title: 'dialog title (receives focus on open in modal dialogs; suppressed inline)',subtitle: 'subtitle below title',onOpenChange: 'close button callback (omit=no button)',startContent: 'content before title (e.g. back button)',diff --git a/packages/core/src/Dialog/DialogContext.ts b/packages/core/src/Dialog/DialogContext.tsnew file mode 100644index 0000000000..8392062ea7--- /dev/null+++ b/packages/core/src/Dialog/DialogContext.ts@@ -0,0 +1,24 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++'use client';++/**+ * @file DialogContext.ts+ * @input React context+ * @output Internal dialog context for child focus behavior+ * @position Dialog internals; consumed by focus-managing children+ */++import {createContext, use} from 'react';++export interface DialogContextValue {+ /** Whether the dialog is rendered inline for docs/showcases. */+ isInline: boolean;+}++export const DialogContext = createContext<DialogContextValue | null>(null);+DialogContext.displayName = 'DialogContext';++export function useDialogContext(): DialogContextValue | null {+ return use(DialogContext);+}diff --git a/packages/core/src/Dialog/XDSDialog.test.tsx b/packages/core/src/Dialog/XDSDialog.test.tsxindex 63e59f5598..0a51de74b3 100644--- a/packages/core/src/Dialog/XDSDialog.test.tsx+++ b/packages/core/src/Dialog/XDSDialog.test.tsx@@ -12,6 +12,7 @@import {describe, it, expect, vi, beforeEach} from 'vitest';import {render, screen} from '@testing-library/react';import {XDSDialog} from './XDSDialog';+import {XDSDialogHeader} from './XDSDialogHeader';// Mock showModal and close methods since they're not fully implemented in jsdombeforeEach(() => {@@ -327,5 +328,21 @@ describe('XDSDialog', () => {);expect(HTMLDialogElement.prototype.showModal).not.toHaveBeenCalled();});++ it('suppresses DialogHeader auto-focus', () => {+ const before = document.createElement('button');+ before.type = 'button';+ document.body.appendChild(before);+ before.focus();++ render(+ <XDSDialog isOpen={true} isInline onOpenChange={() => {}}>+ <XDSDialogHeader title="Inline title" />+ </XDSDialog>,+ );++ expect(before).toHaveFocus();+ before.remove();+ });});});diff --git a/packages/core/src/Dialog/XDSDialog.tsx b/packages/core/src/Dialog/XDSDialog.tsxindex 4e7eb4511f..c7f402b8c1 100644--- a/packages/core/src/Dialog/XDSDialog.tsx+++ b/packages/core/src/Dialog/XDSDialog.tsx@@ -4,7 +4,7 @@/*** @file XDSDialog.tsx- * @input Uses React, DialogHTMLAttributes, ReactNode, container (Layout)+ * @input Uses React, DialogHTMLAttributes, ReactNode, container (Layout), DialogContext* @output Exports XDSDialog component, XDSDialogProps, XDSDialogVariant, XDSDialogPurpose types* @position Core implementation; consumed by index.ts, tested by XDSDialog.test.tsx*@@ -16,7 +16,7 @@* - /packages/cli/templates/blocks/components/Dialog/ (showcase blocks)*/-import {useEffect, useRef, type ReactNode} from 'react';+import {useEffect, useMemo, useRef, type ReactNode} from 'react';import type {XDSBaseProps} from '../XDSBaseProps';import * as stylex from '@stylexjs/stylex';import {useScrollLock} from '../hooks/useScrollLock';@@ -38,6 +38,7 @@ import {} from '../Layout/padding.stylex';import type {SpacingStep} from '../utils/types';import {xdsClassName, mergeProps, mergeRefs} from '../utils';+import {DialogContext} from './DialogContext';/*** Calculate a directional translate offset for dialog entry animation.@@ -231,9 +232,10 @@ export interface XDSDialogProps extends XDSBaseProps<HTMLDialogElement> {isOpen: boolean;/**- * Renders dialog content inline without the <dialog> element, backdrop, or- * modal behavior. Intended for documentation previews and showcases only —- * not for production UIs. The dialog will not trap focus or respond to Escape.+ * Renders dialog content inline without the <dialog> element, backdrop,+ * modal behavior, or dialog-managed autofocus. Intended for documentation+ * previews and showcases only — not for production UIs. The dialog will not+ * trap focus or respond to Escape.* @default false*/isInline?: boolean;@@ -344,6 +346,7 @@ export function XDSDialog({const paddingToken = spacingStepToToken[effectivePadding] as SpacingToken;const isFullscreen = variant === 'fullscreen';+ const dialogContextValue = useMemo(() => ({isInline}), [isInline]);const dialogRef = useRef<HTMLDialogElement>(null);@@ -488,7 +491,7 @@ export function XDSDialog({effectivePadding !== 4 &&containerPaddingBlockEndVarStyles[effectivePadding],)}>- {children}+ <DialogContext value={dialogContextValue}>{children}</DialogContext></div>);diff --git a/packages/core/src/Dialog/XDSDialogHeader.tsx b/packages/core/src/Dialog/XDSDialogHeader.tsxindex a795a6c7b7..bd25a3ec5e 100644--- a/packages/core/src/Dialog/XDSDialogHeader.tsx+++ b/packages/core/src/Dialog/XDSDialogHeader.tsx@@ -4,7 +4,7 @@/*** @file XDSDialogHeader.tsx- * @input Uses React, useEffect, useRef, XDSLayoutHeader, XDSButton, XDSIcon, XDSHeading, XDSText+ * @input Uses React, useEffect, useRef, XDSLayoutHeader, XDSButton, XDSIcon, XDSHeading, XDSText, DialogContext* @output Exports XDSDialogHeader component and XDSDialogHeaderProps* @position Dialog header component; used with XDSDialog and XDSLayout*@@ -25,6 +25,7 @@ import {XDSIcon} from '../Icon';import {XDSHeading} from '../Heading/XDSHeading';import {XDSText} from '../Text/XDSText';import type {XDSBaseProps} from '../XDSBaseProps';+import {useDialogContext} from './DialogContext';const styles = stylex.create({container: {@@ -100,9 +101,10 @@ export interface XDSDialogHeaderProps extends XDSBaseProps<HTMLDivElement> {/*** Header component designed specifically for XDSDialog.*- * Renders a title that receives focus when the dialog opens (for screen reader accessibility)- * and an optional close button. The title is an h2 element with tabIndex={-1} so it can be- * programmatically focused but doesn't appear in the tab order.+ * Renders a title that receives focus when a modal dialog opens (for screen reader accessibility)+ * and an optional close button. Inline documentation previews suppress this autofocus.+ * The title is an h2 element with tabIndex={-1} so it can be programmatically focused but+ * doesn't appear in the tab order.** Uses XDSLayoutHeader internally for consistent styling with other layout headers.*@@ -127,14 +129,17 @@ export function XDSDialogHeader({ref,}: XDSDialogHeaderProps) {const titleRef = useRef<HTMLHeadingElement>(null);+ const dialogContext = useDialogContext();+ const shouldAutoFocus = dialogContext?.isInline !== true;- // Auto-focus the title when mounted for screen reader accessibility+ // Auto-focus the title when mounted for screen reader accessibility.+ // Inline dialogs are documentation/showcase previews, so suppress focus to+ // avoid stealing scroll position from the surrounding page.useEffect(() => {- if (titleRef.current) {- titleRef.current.tabIndex = -1;+ if (shouldAutoFocus && titleRef.current) {titleRef.current.focus();}- }, []);+ }, [shouldAutoFocus]);return (<XDSLayoutHeader ref={ref} hasDivider={hasDivider}>@@ -143,7 +148,11 @@ export function XDSDialogHeader({<div {...stylex.props(styles.actions)}>{startContent}</div>)}<div {...stylex.props(styles.titleWrapper)}>- <XDSHeading ref={titleRef} level={2} xstyle={styles.titleFocusable}>+ <XDSHeading+ ref={titleRef}+ level={2}+ tabIndex={-1}+ xstyle={styles.titleFocusable}>{title}</XDSHeading>{subtitle && (