An open source design system that's fully customizable and agent ready
TypeScript
fix(command-palette): suppress inline initial item scroll (#2817)
Cindy Zhang231d4d1cebaf
diff --git a/.changeset/command-palette-inline-scroll.md b/.changeset/command-palette-inline-scroll.mdnew file mode 100644index 0000000000..8b4a115497--- /dev/null+++ b/.changeset/command-palette-inline-scroll.md@@ -0,0 +1,5 @@+---+'@xds/core': patch+---++`XDSCommandPaletteItem` no longer scrolls highlighted items into view on initial mount when rendered inside an inline dialog. This prevents inline CommandPalette picker examples from scrolling the surrounding documentation page when their selected value is auto-highlighted on mount, while preserving scroll-into-view after user navigation.diff --git a/packages/core/src/CommandPalette/CommandPalette.doc.mjs b/packages/core/src/CommandPalette/CommandPalette.doc.mjsindex 738cda1c10..8fdeca3a53 100644--- a/packages/core/src/CommandPalette/CommandPalette.doc.mjs+++ b/packages/core/src/CommandPalette/CommandPalette.doc.mjs@@ -124,7 +124,7 @@ export const docs = {{name: 'isInline',type: 'boolean',- description: 'Renders command palette content inline without modal behavior. Automatically disables auto-focus on the input. For documentation previews and showcases only.',+ description: 'Renders command palette content inline without modal behavior. Automatically disables input auto-focus and initial highlighted-item auto-scroll. For documentation previews and showcases only.',default: 'false',},],diff --git a/packages/core/src/CommandPalette/XDSCommandPalette.tsx b/packages/core/src/CommandPalette/XDSCommandPalette.tsxindex ee9c7bb31f..176be5e0b4 100644--- a/packages/core/src/CommandPalette/XDSCommandPalette.tsx+++ b/packages/core/src/CommandPalette/XDSCommandPalette.tsx@@ -51,6 +51,7 @@ export interface XDSCommandPaletteProps</*** Renders command palette content inline without modal behavior.+ * Suppresses input auto-focus and initial highlighted-item auto-scroll.* For documentation previews and showcases only.* @default false*/diff --git a/packages/core/src/CommandPalette/XDSCommandPaletteItem.test.tsx b/packages/core/src/CommandPalette/XDSCommandPaletteItem.test.tsxindex 4c830d6434..311002359b 100644--- a/packages/core/src/CommandPalette/XDSCommandPaletteItem.test.tsx+++ b/packages/core/src/CommandPalette/XDSCommandPaletteItem.test.tsx@@ -6,10 +6,38 @@* @output Unit tests for XDSCommandPaletteItem*/-import {describe, it, expect, vi} from 'vitest';-import {render, screen, fireEvent} from '@testing-library/react';+import {afterEach, describe, it, expect, vi} from 'vitest';+import {render, screen, fireEvent, waitFor} from '@testing-library/react';+import {XDSDialog} from '../Dialog/XDSDialog';import {XDSCommandPaletteItem} from './XDSCommandPaletteItem';+const scrollIntoViewDescriptor = Object.getOwnPropertyDescriptor(+ HTMLElement.prototype,+ 'scrollIntoView',+);++function mockScrollIntoView() {+ const scrollIntoView = vi.fn();+ Object.defineProperty(HTMLElement.prototype, 'scrollIntoView', {+ configurable: true,+ value: scrollIntoView,+ });+ return scrollIntoView;+}++afterEach(() => {+ if (scrollIntoViewDescriptor) {+ Object.defineProperty(+ HTMLElement.prototype,+ 'scrollIntoView',+ scrollIntoViewDescriptor,+ );+ } else {+ delete (HTMLElement.prototype as unknown as {scrollIntoView?: unknown})+ .scrollIntoView;+ }+});+describe('XDSCommandPaletteItem', () => {it('renders children', () => {render(@@ -77,6 +105,58 @@ describe('XDSCommandPaletteItem', () => {);});+ it('scrolls highlighted items into view by default', async () => {+ const scrollIntoView = mockScrollIntoView();++ render(+ <XDSCommandPaletteItem value="test" isHighlighted>+ Item+ </XDSCommandPaletteItem>,+ );++ await waitFor(() => {+ expect(scrollIntoView).toHaveBeenCalledWith({block: 'nearest'});+ });+ });++ it('does not scroll initially highlighted items in inline dialogs', () => {+ const scrollIntoView = mockScrollIntoView();++ render(+ <XDSDialog isOpen isInline onOpenChange={() => {}}>+ <XDSCommandPaletteItem value="test" isHighlighted>+ Item+ </XDSCommandPaletteItem>+ </XDSDialog>,+ );++ expect(scrollIntoView).not.toHaveBeenCalled();+ });++ it('scrolls inline dialog items after highlight changes', async () => {+ const scrollIntoView = mockScrollIntoView();++ const {rerender} = render(+ <XDSDialog isOpen isInline onOpenChange={() => {}}>+ <XDSCommandPaletteItem value="test" isHighlighted={false}>+ Item+ </XDSCommandPaletteItem>+ </XDSDialog>,+ );++ rerender(+ <XDSDialog isOpen isInline onOpenChange={() => {}}>+ <XDSCommandPaletteItem value="test" isHighlighted>+ Item+ </XDSCommandPaletteItem>+ </XDSDialog>,+ );++ await waitFor(() => {+ expect(scrollIntoView).toHaveBeenCalledWith({block: 'nearest'});+ });+ });+it('sets data-value attribute', () => {render(<XDSCommandPaletteItem value="my-value">Item</XDSCommandPaletteItem>,diff --git a/packages/core/src/CommandPalette/XDSCommandPaletteItem.tsx b/packages/core/src/CommandPalette/XDSCommandPaletteItem.tsxindex a4950ebbad..68b07b7f87 100644--- a/packages/core/src/CommandPalette/XDSCommandPaletteItem.tsx+++ b/packages/core/src/CommandPalette/XDSCommandPaletteItem.tsx@@ -3,7 +3,7 @@'use client';/*** @file XDSCommandPaletteItem.tsx- * @input Uses React, StyleX, CommandPaletteContext+ * @input Uses React, StyleX, CommandPaletteContext, DialogContext* @output Exports XDSCommandPaletteItem component* @position Sub-component; individual selectable item*@@ -23,6 +23,7 @@ import {typeScaleVars,} from '../theme/tokens.stylex';import {useCommandPaletteContext} from './CommandPaletteContext';+import {useDialogContext} from '../Dialog/DialogContext';import {xdsThemeProps} from '../utils/xdsThemeProps';const HOVER_HOVER = '@media (hover: hover)';@@ -129,7 +130,10 @@ export function XDSCommandPaletteItem({...props}: XDSCommandPaletteItemProps) {const ctx = useCommandPaletteContext();+ const dialogContext = useDialogContext();+ const isInlineDialog = dialogContext?.isInline === true;const itemRef = useRef<HTMLDivElement>(null);+ const didMountRef = useRef(false);// Find this item's index in the flat selectable items list (DOM order).// This aligns with useCombobox's index-based navigation.@@ -145,10 +149,21 @@ export function XDSCommandPaletteItem({const isSelected = controlledSelected ?? (ctx ? ctx.value === value : false);useEffect(() => {+ // Inline dialogs are documentation/showcase previews. Avoid scrolling the+ // surrounding page when picker mode auto-highlights its selected item on+ // mount, while preserving scroll-into-view after user navigation.+ const shouldSkipInitialInlineScroll =+ isInlineDialog && !didMountRef.current;+ didMountRef.current = true;++ if (shouldSkipInitialInlineScroll) {+ return;+ }+if (isHighlighted && itemRef.current) {itemRef.current.scrollIntoView?.({block: 'nearest'});}- }, [isHighlighted]);+ }, [isHighlighted, isInlineDialog]);const handleClick = useCallback(() => {if (isDisabled) {