Skip to content

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.md
new file mode 100644
index 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.ts
index 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.tsx
index 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.tsx
index 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.tsx
index 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 fallback
const 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 mount
useEffect(() => {
diff --git a/packages/core/src/Dialog/Dialog.doc.mjs b/packages/core/src/Dialog/Dialog.doc.mjs
index 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.ts
new file mode 100644
index 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.tsx
index 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 jsdom
beforeEach(() => {
@@ -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.tsx
index 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.tsx
index 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 && (