Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

feat: add @xds/lab package for experimental components (#633)

Cindy Zhange62ac82b1131
diff --git a/apps/storybook/stories/CommandPalette.stories.tsx b/apps/storybook/stories/CommandPalette.stories.tsx
new file mode 100644
index 0000000000..35d9a67514
--- /dev/null
+++ b/apps/storybook/stories/CommandPalette.stories.tsx
@@ -0,0 +1,195 @@
+import {useState} from 'react';
+import type {Meta, StoryObj} from '@storybook/react';
+import {
+ XDSCommandPalette,
+ XDSCommandPaletteInput,
+ XDSCommandPaletteList,
+ XDSCommandPaletteItem,
+ XDSCommandPaletteGroup,
+ XDSCommandPaletteFooter,
+} from '@xds/lab';
+import {XDSButton} from '@xds/core/Button';
+import {XDSIcon} from '@xds/core/Icon';
+import {XDSDivider} from '@xds/core/Divider';
+
+const meta: Meta<typeof XDSCommandPalette> = {
+ title: 'Lab/XDSCommandPalette',
+ component: XDSCommandPalette,
+ tags: ['autodocs'],
+ argTypes: {
+ isOpen: {
+ control: 'boolean',
+ description: 'Whether the command palette is open',
+ },
+ width: {
+ control: 'number',
+ description: 'Width of the dialog',
+ },
+ maxHeight: {
+ control: 'number',
+ description: 'Maximum height of the dialog',
+ },
+ label: {
+ control: 'text',
+ description: 'Accessible label',
+ },
+ },
+};
+
+export default meta;
+type Story = StoryObj<typeof XDSCommandPalette>;
+
+/**
+ * Full command palette with context-driven filtering and selection.
+ * Type to filter items. Arrow keys to navigate. Enter to select.
+ */
+export const Default: Story = {
+ render: function Render() {
+ const [isOpen, setIsOpen] = useState(false);
+
+ return (
+ <>
+ <XDSButton
+ label="Open Command Palette (or press ⌘K)"
+ onClick={() => setIsOpen(true)}
+ />
+ <XDSCommandPalette
+ isOpen={isOpen}
+ onOpenChange={setIsOpen}
+ onValueChange={value => {
+ console.log('Selected:', value);
+ }}>
+ <XDSCommandPaletteInput placeholder="Type a command..." />
+ <XDSDivider />
+ <XDSCommandPaletteList>
+ <XDSCommandPaletteGroup heading="Navigation">
+ <XDSCommandPaletteItem value="Go to Dashboard">
+ <XDSIcon icon="home" size="sm" />
+ Go to Dashboard
+ </XDSCommandPaletteItem>
+ <XDSCommandPaletteItem value="Open Settings">
+ <XDSIcon icon="settings" size="sm" />
+ Open Settings
+ </XDSCommandPaletteItem>
+ <XDSCommandPaletteItem value="View Profile">
+ <XDSIcon icon="user" size="sm" />
+ View Profile
+ </XDSCommandPaletteItem>
+ </XDSCommandPaletteGroup>
+ <XDSCommandPaletteGroup heading="Actions">
+ <XDSCommandPaletteItem
+ value="Toggle Dark Mode"
+ keywords={['theme', 'appearance']}>
+ Toggle Dark Mode
+ </XDSCommandPaletteItem>
+ <XDSCommandPaletteItem value="Create New File">
+ Create New File
+ </XDSCommandPaletteItem>
+ <XDSCommandPaletteItem value="Search Files">
+ <XDSIcon icon="search" size="sm" />
+ Search Files
+ </XDSCommandPaletteItem>
+ </XDSCommandPaletteGroup>
+ </XDSCommandPaletteList>
+ <XDSCommandPaletteFooter />
+ </XDSCommandPalette>
+ </>
+ );
+ },
+};
+
+/**
+ * Flat list without groups — items filter automatically.
+ */
+export const FlatList: Story = {
+ render: function Render() {
+ const [isOpen, setIsOpen] = useState(false);
+
+ return (
+ <>
+ <XDSButton label="Open Flat Palette" onClick={() => setIsOpen(true)} />
+ <XDSCommandPalette isOpen={isOpen} onOpenChange={setIsOpen}>
+ <XDSCommandPaletteInput placeholder="Search..." />
+ <XDSDivider />
+ <XDSCommandPaletteList>
+ <XDSCommandPaletteItem value="Home">Go Home</XDSCommandPaletteItem>
+ <XDSCommandPaletteItem value="Settings">
+ Settings
+ </XDSCommandPaletteItem>
+ <XDSCommandPaletteItem value="Disabled Item" isDisabled>
+ Disabled Item
+ </XDSCommandPaletteItem>
+ <XDSCommandPaletteItem value="Profile">
+ Profile
+ </XDSCommandPaletteItem>
+ </XDSCommandPaletteList>
+ <XDSCommandPaletteFooter />
+ </XDSCommandPalette>
+ </>
+ );
+ },
+};
+
+/**
+ * With custom footer content.
+ */
+export const CustomFooter: Story = {
+ render: function Render() {
+ const [isOpen, setIsOpen] = useState(false);
+
+ return (
+ <>
+ <XDSButton label="Open Custom Footer" onClick={() => setIsOpen(true)} />
+ <XDSCommandPalette isOpen={isOpen} onOpenChange={setIsOpen}>
+ <XDSCommandPaletteInput placeholder="Search..." />
+ <XDSDivider />
+ <XDSCommandPaletteList>
+ <XDSCommandPaletteItem value="Option A">
+ Option A
+ </XDSCommandPaletteItem>
+ <XDSCommandPaletteItem value="Option B">
+ Option B
+ </XDSCommandPaletteItem>
+ </XDSCommandPaletteList>
+ <XDSCommandPaletteFooter>
+ <span>Tip: Use ⌘K to open this palette</span>
+ </XDSCommandPaletteFooter>
+ </XDSCommandPalette>
+ </>
+ );
+ },
+};
+
+/**
+ * With external filtering disabled — all items always shown.
+ */
+export const UnfilteredList: Story = {
+ render: function Render() {
+ const [isOpen, setIsOpen] = useState(false);
+
+ return (
+ <>
+ <XDSButton label="Open Unfiltered" onClick={() => setIsOpen(true)} />
+ <XDSCommandPalette
+ isOpen={isOpen}
+ onOpenChange={setIsOpen}
+ isFiltered={false}>
+ <XDSCommandPaletteInput placeholder="Search (no filtering)..." />
+ <XDSDivider />
+ <XDSCommandPaletteList>
+ <XDSCommandPaletteItem value="Always Visible A">
+ Always Visible A
+ </XDSCommandPaletteItem>
+ <XDSCommandPaletteItem value="Always Visible B">
+ Always Visible B
+ </XDSCommandPaletteItem>
+ <XDSCommandPaletteItem value="Always Visible C">
+ Always Visible C
+ </XDSCommandPaletteItem>
+ </XDSCommandPaletteList>
+ <XDSCommandPaletteFooter />
+ </XDSCommandPalette>
+ </>
+ );
+ },
+};
diff --git a/packages/lab/README.md b/packages/lab/README.md
new file mode 100644
index 0000000000..388da3a666
--- /dev/null
+++ b/packages/lab/README.md
@@ -0,0 +1,37 @@
+# @xds/lab
+
+Experimental XDS components. This package is **never published** — it exists as a staging area for components that are functional but not yet hardened for production.
+
+## Purpose
+
+Designers and engineers can vibe components here without the quality bar required for `@xds/core`. Components in lab:
+
+- Are importable in storybook and sandbox for testing
+- Can be iterated on freely without worrying about breaking consumers
+- Compose with `@xds/core` components (use the theme, follow naming conventions)
+- Graduate to `@xds/core` after thorough engineering review
+
+## What's here vs what's in core
+
+**Lab:** Works, has basic props, maybe has stories. API might change. Not accessibility-hardened, not vibe-tested, not fully themed.
+
+**Core:** Full keyboard/a11y, hover guards, theming story, status states, spec compliance, vibe tested. Shipped to consumers.
+
+## Components
+
+| Component | Status | Notes |
+| -------------- | ---------- | ----------------------------------------------------------------------------- |
+| CommandPalette | Functional | Dialog shell, input, list, items, groups, footer, context provider, filtering |
+
+## Usage
+
+```tsx
+import {
+ XDSCommandPalette,
+ XDSCommandPaletteInput,
+ XDSCommandPaletteList,
+ XDSCommandPaletteItem,
+} from '@xds/lab';
+```
+
+Since this is a workspace package (not published), imports resolve via yarn workspaces in storybook and sandbox.
diff --git a/packages/lab/package.json b/packages/lab/package.json
new file mode 100644
index 0000000000..9ae6d61384
--- /dev/null
+++ b/packages/lab/package.json
@@ -0,0 +1,15 @@
+{
+ "name": "@xds/lab",
+ "version": "0.0.1",
+ "private": true,
+ "description": "Experimental XDS components — not published, available in storybook and sandbox for testing",
+ "main": "./src/index.ts",
+ "types": "./src/index.ts",
+ "sideEffects": false,
+ "peerDependencies": {
+ "@stylexjs/stylex": ">=0.10.0",
+ "@xds/core": "*",
+ "react": ">=19.0.0",
+ "react-dom": ">=19.0.0"
+ }
+}
diff --git a/packages/lab/src/CommandPalette/CommandPalette.doc.mjs b/packages/lab/src/CommandPalette/CommandPalette.doc.mjs
new file mode 100644
index 0000000000..37422d9f83
--- /dev/null
+++ b/packages/lab/src/CommandPalette/CommandPalette.doc.mjs
@@ -0,0 +1,68 @@
+/** @type {import('../docs-types').ComponentDoc} */
+
+export const docs = {
+ name: 'CommandPalette',
+ description:
+ 'A modal dialog shell for command palette interfaces. Provides the structural container with composable slots for input, list, and footer areas.',
+ features: [
+ 'Dialog shell: Wraps XDSDialog with command palette defaults (640×480, centered, info purpose)',
+ 'Composable slots: Children render as a flex column — input at top, scrollable list in middle, footer at bottom',
+ 'Accessible: Uses native <dialog> with aria-label for screen readers',
+ 'Keyboard dismissal: Escape key closes the palette (inherited from XDSDialog purpose="info")',
+ 'Configurable size: width and maxHeight props for custom dimensions',
+ ],
+ examples: [
+ {
+ label: 'Basic command palette',
+ code: `import {XDSCommandPalette} from '@xds/core/CommandPalette';
+import {useState} from 'react';
+
+function Example() {
+ const [isOpen, setIsOpen] = useState(false);
+
+ return (
+ <XDSCommandPalette isOpen={isOpen} onOpenChange={setIsOpen}>
+ <input placeholder="Type a command..." />
+ <div>List of commands</div>
+ </XDSCommandPalette>
+ );
+}`,
+ },
+ ],
+ props: {
+ isOpen: {
+ type: 'boolean',
+ required: true,
+ description: 'Whether the command palette is open.',
+ },
+ onOpenChange: {
+ type: '(isOpen: boolean) => void',
+ required: true,
+ description:
+ 'Called when the palette visibility changes. Called with false on Escape or backdrop click.',
+ },
+ label: {
+ type: 'string',
+ default: "'Command palette'",
+ description: 'Accessible label for the dialog.',
+ },
+ width: {
+ type: 'number | string',
+ default: '640',
+ description:
+ 'Width of the dialog. Numbers are pixels, strings are CSS values.',
+ },
+ maxHeight: {
+ type: 'number | string',
+ default: '480',
+ description:
+ 'Maximum height of the dialog. Numbers are pixels, strings are CSS values.',
+ },
+ children: {
+ type: 'ReactNode',
+ required: true,
+ description:
+ 'Composable sub-components: input, list, footer, etc.',
+ },
+ },
+};
diff --git a/packages/lab/src/CommandPalette/CommandPaletteContext.ts b/packages/lab/src/CommandPalette/CommandPaletteContext.ts
new file mode 100644
index 0000000000..68ca67113a
--- /dev/null
+++ b/packages/lab/src/CommandPalette/CommandPaletteContext.ts
@@ -0,0 +1,50 @@
+/**
+ * @file CommandPaletteContext.ts
+ * @input Uses React createContext
+ * @output Exports CommandPaletteContext and useCommandPaletteContext hook
+ * @position Internal context; consumed by composable sub-components
+ */
+
+import {createContext, useContext} from 'react';
+import type {CommandPaletteFilterFn} from './types';
+
+export interface CommandPaletteContextValue {
+ /** Current search query. */
+ search: string;
+ /** Update the search query. */
+ setSearch: (search: string) => void;
+ /** Currently selected value. */
+ value: string;
+ /** Update the selected value. */
+ setValue: (value: string) => void;
+ /** Filter function. */
+ filter: CommandPaletteFilterFn;
+ /** Whether built-in filtering is enabled. */
+ isFiltered: boolean;
+ /** Unique ID prefix for ARIA. */
+ listId: string;
+ /** Index of the currently highlighted item. */
+ highlightedIndex: number;
+ /** Update highlighted index. */
+ setHighlightedIndex: (index: number) => void;
+ /** All registered item values (for keyboard navigation). */
+ items: Array<{value: string; isDisabled?: boolean}>;
+ /** Register an item. Returns unregister function. */
+ registerItem: (value: string, isDisabled?: boolean) => () => void;
+ /** Select an item by value. */
+ selectItem: (value: string) => void;
+ /** Close the palette. */
+ onClose: () => void;
+}
+
+export const CommandPaletteContext =
+ createContext<CommandPaletteContextValue | null>(null);
+
+/**
+ * Access the command palette context.
+ * Throws if used outside of a CommandPalette with context enabled.
+ * Returns null when context is not available (for standalone usage).
+ */
+export function useCommandPaletteContext(): CommandPaletteContextValue | null {
+ return useContext(CommandPaletteContext);
+}
diff --git a/packages/lab/src/CommandPalette/README.md b/packages/lab/src/CommandPalette/README.md
new file mode 100644
index 0000000000..117e223cb8
--- /dev/null
+++ b/packages/lab/src/CommandPalette/README.md
@@ -0,0 +1,34 @@
+# CommandPalette
+
+Command palette dialog for quick access to commands, navigation, and search.
+
+## Architecture
+
+The command palette is built incrementally as composable pieces:
+
+1. **XDSCommandPalette** — Dialog shell with flex column layout (this PR)
+2. **XDSCommandPaletteInput** — Search input with icon (planned)
+3. **XDSCommandPaletteList / Item / Group** — Scrollable item list (planned)
+4. **XDSCommandPaletteFooter** — Keyboard shortcut hints (planned)
+5. **CommandPaletteContext** — State management provider (planned)
+
+## Files
+
+| File | Purpose |
+| ---------------------------- | --------------------------- |
+| `XDSCommandPalette.tsx` | Root dialog shell component |
+| `index.ts` | Public exports |
+| `README.md` | This file |
+| `XDSCommandPalette.test.tsx` | Unit tests |
+
+## Usage
+
+```tsx
+import {XDSCommandPalette} from '@xds/core/CommandPalette';
+
+const [isOpen, setIsOpen] = useState(false);
+
+<XDSCommandPalette isOpen={isOpen} onOpenChange={setIsOpen}>
+ {/* Sub-components go here */}
+</XDSCommandPalette>;
+```
diff --git a/packages/lab/src/CommandPalette/XDSCommandPalette.test.tsx b/packages/lab/src/CommandPalette/XDSCommandPalette.test.tsx
new file mode 100644
index 0000000000..1f3cf559d4
--- /dev/null
+++ b/packages/lab/src/CommandPalette/XDSCommandPalette.test.tsx
@@ -0,0 +1,106 @@
+/**
+ * @file XDSCommandPalette.test.tsx
+ * @input Uses vitest, @testing-library/react, XDSCommandPalette
+ * @output Unit tests for XDSCommandPalette dialog shell
+ * @position Testing; validates XDSCommandPalette.tsx implementation
+ *
+ * SYNC: When XDSCommandPalette.tsx changes, update tests to match
+ */
+
+import {describe, it, expect, vi, beforeEach} from 'vitest';
+import {render, screen} from '@testing-library/react';
+import {XDSCommandPalette} from './XDSCommandPalette';
+
+// Mock showModal and close since jsdom doesn't implement them
+beforeEach(() => {
+ HTMLDialogElement.prototype.showModal = vi.fn(function (
+ this: HTMLDialogElement,
+ ) {
+ this.setAttribute('open', '');
+ });
+ HTMLDialogElement.prototype.close = vi.fn(function (this: HTMLDialogElement) {
+ this.removeAttribute('open');
+ });
+});
+
+describe('XDSCommandPalette', () => {
+ it('renders when isOpen is true', () => {
+ render(
+ <XDSCommandPalette isOpen={true} onOpenChange={() => {}}>
+ <div>Content</div>
+ </XDSCommandPalette>,
+ );
+ expect(screen.getByRole('dialog')).toBeInTheDocument();
+ expect(screen.getByText('Content')).toBeInTheDocument();
+ });
+
+ it('does not show content when isOpen is false', () => {
+ render(
+ <XDSCommandPalette isOpen={false} onOpenChange={() => {}}>
+ <div>Hidden</div>
+ </XDSCommandPalette>,
+ );
+ const dialog = screen.getByRole('dialog', {hidden: true});
+ expect(dialog).not.toHaveAttribute('open');
+ });
+
+ it('has correct aria-label', () => {
+ render(
+ <XDSCommandPalette isOpen={true} onOpenChange={() => {}}>
+ <div>Content</div>
+ </XDSCommandPalette>,
+ );
+ expect(screen.getByRole('dialog')).toHaveAttribute(
+ 'aria-label',
+ 'Command palette',
+ );
+ });
+
+ it('supports custom label', () => {
+ render(
+ <XDSCommandPalette
+ isOpen={true}
+ onOpenChange={() => {}}
+ label="Quick search">
+ <div>Content</div>
+ </XDSCommandPalette>,
+ );
+ expect(screen.getByRole('dialog')).toHaveAttribute(
+ 'aria-label',
+ 'Quick search',
+ );
+ });
+
+ it('renders children as composable slots', () => {
+ render(
+ <XDSCommandPalette isOpen={true} onOpenChange={() => {}}>
+ <div data-testid="input-slot">Input</div>
+ <div data-testid="list-slot">List</div>
+ <div data-testid="footer-slot">Footer</div>
+ </XDSCommandPalette>,
+ );
+ expect(screen.getByTestId('input-slot')).toBeInTheDocument();
+ expect(screen.getByTestId('list-slot')).toBeInTheDocument();
+ expect(screen.getByTestId('footer-slot')).toBeInTheDocument();
+ });
+
+ it('calls onOpenChange(false) when Escape is pressed', () => {
+ const handleOpenChange = vi.fn();
+
+ render(
+ <XDSCommandPalette isOpen={true} onOpenChange={handleOpenChange}>
+ <div>Content</div>
+ </XDSCommandPalette>,
+ );
+
+ const dialog = screen.getByRole('dialog');
+ const escapeEvent = new KeyboardEvent('keydown', {
+ key: 'Escape',
+ bubbles: true,
+ cancelable: true,
+ });
+ dialog.dispatchEvent(escapeEvent);
+
+ expect(handleOpenChange).toHaveBeenCalledWith(false);
+ });
+});
diff --git a/packages/lab/src/CommandPalette/XDSCommandPalette.tsx b/packages/lab/src/CommandPalette/XDSCommandPalette.tsx
new file mode 100644
index 0000000000..e455c19f3c
--- /dev/null
+++ b/packages/lab/src/CommandPalette/XDSCommandPalette.tsx
@@ -0,0 +1,257 @@
+/**
+ * @file XDSCommandPalette.tsx
+ * @input Uses React, StyleX, XDSDialog, CommandPaletteContext
+ * @output Exports XDSCommandPalette root component and props
+ * @position Core root component; dialog shell with optional state management
+ *
+ * SYNC: When modified, update these files to stay in sync:
+ * - /packages/core/src/CommandPalette/README.md
+ * - /packages/core/src/CommandPalette/index.ts
+ * - /apps/storybook/stories/CommandPalette.stories.tsx
+ */
+
+'use client';
+
+import {
+ useCallback,
+ useId,
+ useMemo,
+ useRef,
+ useState,
+ type ReactNode,
+} from 'react';
+import * as stylex from '@stylexjs/stylex';
+import {XDSDialog} from '@xds/core/Dialog';
+import {CommandPaletteContext} from './CommandPaletteContext';
+import {defaultFilter} from './filter';
+import type {CommandPaletteFilterFn} from './types';
+
+const styles = stylex.create({
+ wrapper: {
+ display: 'flex',
+ flexDirection: 'column',
+ height: '100%',
+ overflow: 'hidden',
+ },
+});
+
+// =============================================================================
+// Module Augmentation - Register CommandPalette's style surfaces
+// =============================================================================
+
+declare module '../theme/types' {
+ interface ComponentStyles {
+ commandPalette?: {
+ root?: import('../theme/types').StyleXStyles;
+ };
+ }
+}
+
+export interface XDSCommandPaletteProps {
+ /**
+ * Whether the command palette is open.
+ */
+ isOpen: boolean;
+
+ /**
+ * Called when the command palette visibility changes.
+ * Called with `false` when the palette requests to close
+ * (via Escape key or backdrop click).
+ */
+ onOpenChange: (isOpen: boolean) => void;
+
+ /**
+ * Controlled selected value.
+ */
+ value?: string;
+
+ /**
+ * Called when the selected value changes.
+ */
+ onValueChange?: (value: string) => void;
+
+ /**
+ * Custom filter function. Return a score between 0 and 1.
+ * When provided, replaces the built-in substring filter.
+ */
+ filter?: CommandPaletteFilterFn;
+
+ /**
+ * Whether built-in filtering is enabled.
+ * Set to false when filtering is handled externally (e.g., server-side).
+ * @default true
+ */
+ isFiltered?: boolean;
+
+ /**
+ * Accessible label for the command palette dialog.
+ * @default 'Command palette'
+ */
+ label?: string;
+
+ /**
+ * Width of the command palette dialog.
+ * Numbers are treated as pixels, strings are used as-is.
+ * @default 640
+ */
+ width?: number | string;
+
+ /**
+ * Maximum height of the command palette dialog.
+ * Numbers are treated as pixels, strings are used as-is.
+ * @default 480
+ */
+ maxHeight?: number | string;
+
+ /**
+ * Composable content slots.
+ * Typically includes XDSCommandPaletteInput, XDSCommandPaletteList, and XDSCommandPaletteFooter.
+ *
+ * @example
+ * ```
+ * <XDSCommandPalette isOpen={isOpen} onOpenChange={setIsOpen}>
+ * <XDSCommandPaletteInput placeholder="Search commands..." />
+ * <XDSCommandPaletteList>
+ * <XDSCommandPaletteItem value="home">Go Home</XDSCommandPaletteItem>
+ * </XDSCommandPaletteList>
+ * <XDSCommandPaletteFooter />
+ * </XDSCommandPalette>
+ * ```
+ */
+ children: ReactNode;
+}
+
+/**
+ * Command palette root component.
+ *
+ * Wraps XDSDialog with command palette defaults and provides context
+ * for state management (search, filtering, keyboard navigation, selection).
+ *
+ * Sub-components (Input, List, Item, Group, Footer) can be used as
+ * controlled components via props, or they can consume the context
+ * for automatic state wiring.
+ *
+ * @compositionHint Compose with XDSCommandPaletteInput (search),
+ * XDSCommandPaletteList (scrollable items), and XDSCommandPaletteFooter
+ * (keyboard hints) as children.
+ *
+ * @example
+ * ```
+ * const [isOpen, setIsOpen] = useState(false);
+ *
+ * <XDSCommandPalette isOpen={isOpen} onOpenChange={setIsOpen}>
+ * <XDSCommandPaletteInput placeholder="Type a command..." />
+ * <XDSCommandPaletteList>
+ * <XDSCommandPaletteItem value="home" onSelect={() => navigate('/')}>
+ * Go Home
+ * </XDSCommandPaletteItem>
+ * </XDSCommandPaletteList>
+ * <XDSCommandPaletteFooter />
+ * </XDSCommandPalette>
+ * ```
+ */
+export function XDSCommandPalette({
+ isOpen,
+ onOpenChange,
+ value: controlledValue,
+ onValueChange,
+ filter = defaultFilter,
+ isFiltered = true,
+ label = 'Command palette',
+ width = 640,
+ maxHeight = 480,
+ children,
+}: XDSCommandPaletteProps) {
+ const listId = useId();
+ const [search, setSearch] = useState('');
+ const [internalValue, setInternalValue] = useState('');
+ const [highlightedIndex, setHighlightedIndex] = useState(0);
+ const itemsRef = useRef<Array<{value: string; isDisabled?: boolean}>>([]);
+
+ const value = controlledValue ?? internalValue;
+
+ const setValue = useCallback(
+ (newValue: string) => {
+ if (controlledValue === undefined) {
+ setInternalValue(newValue);
+ }
+ onValueChange?.(newValue);
+ },
+ [controlledValue, onValueChange],
+ );
+
+ const registerItem = useCallback(
+ (itemValue: string, isDisabled?: boolean) => {
+ itemsRef.current = [...itemsRef.current, {value: itemValue, isDisabled}];
+ return () => {
+ itemsRef.current = itemsRef.current.filter(
+ item => item.value !== itemValue,
+ );
+ };
+ },
+ [],
+ );
+
+ const selectItem = useCallback(
+ (itemValue: string) => {
+ setValue(itemValue);
+ },
+ [setValue],
+ );
+
+ // Reset search and highlight when closing
+ const handleClose = useCallback(() => {
+ setSearch('');
+ setHighlightedIndex(0);
+ onOpenChange(false);
+ }, [onOpenChange]);
+
+ const contextValue = useMemo(
+ () => ({
+ search,
+ setSearch,
+ value,
+ setValue,
+ filter,
+ isFiltered,
+ listId,
+ highlightedIndex,
+ setHighlightedIndex,
+ items: itemsRef.current,
+ registerItem,
+ selectItem,
+ onClose: handleClose,
+ }),
+ [
+ search,
+ value,
+ setValue,
+ filter,
+ isFiltered,
+ listId,
+ highlightedIndex,
+ registerItem,
+ selectItem,
+ handleClose,
+ ],
+ );
+
+ return (
+ <XDSDialog
+ isOpen={isOpen}
+ onOpenChange={open => {
+ if (!open) handleClose();
+ else onOpenChange(true);
+ }}
+ width={width}
+ maxHeight={maxHeight}
+ purpose="info"
+ aria-label={label}>
+ <CommandPaletteContext.Provider value={contextValue}>
+ <div {...stylex.props(styles.wrapper)}>{children}</div>
+ </CommandPaletteContext.Provider>
+ </XDSDialog>
+ );
+}
+
+XDSCommandPalette.displayName = 'XDSCommandPalette';
diff --git a/packages/lab/src/CommandPalette/XDSCommandPaletteFooter.test.tsx b/packages/lab/src/CommandPalette/XDSCommandPaletteFooter.test.tsx
new file mode 100644
index 0000000000..972cff6bb9
--- /dev/null
+++ b/packages/lab/src/CommandPalette/XDSCommandPaletteFooter.test.tsx
@@ -0,0 +1,33 @@
+/**
+ * @file XDSCommandPaletteFooter.test.tsx
+ * @input Uses vitest, @testing-library/react
+ * @output Unit tests for XDSCommandPaletteFooter
+ */
+
+import {describe, it, expect} from 'vitest';
+import {render, screen} from '@testing-library/react';
+import {XDSCommandPaletteFooter} from './XDSCommandPaletteFooter';
+
+describe('XDSCommandPaletteFooter', () => {
+ it('renders default keyboard hints', () => {
+ render(<XDSCommandPaletteFooter />);
+ expect(screen.getByText(/Navigate/)).toBeInTheDocument();
+ expect(screen.getByText(/Select/)).toBeInTheDocument();
+ expect(screen.getByText(/Close/)).toBeInTheDocument();
+ });
+
+ it('renders custom children instead of defaults', () => {
+ render(
+ <XDSCommandPaletteFooter>
+ <span>Custom footer content</span>
+ </XDSCommandPaletteFooter>,
+ );
+ expect(screen.getByText('Custom footer content')).toBeInTheDocument();
+ expect(screen.queryByText(/Navigate/)).not.toBeInTheDocument();
+ });
+
+ it('renders a divider', () => {
+ render(<XDSCommandPaletteFooter />);
+ expect(screen.getByRole('separator')).toBeInTheDocument();
+ });
+});
diff --git a/packages/lab/src/CommandPalette/XDSCommandPaletteFooter.tsx b/packages/lab/src/CommandPalette/XDSCommandPaletteFooter.tsx
new file mode 100644
index 0000000000..aa32eff30d
--- /dev/null
+++ b/packages/lab/src/CommandPalette/XDSCommandPaletteFooter.tsx
@@ -0,0 +1,87 @@
+/**
+ * @file XDSCommandPaletteFooter.tsx
+ * @input Uses React, StyleX, XDSKbd
+ * @output Exports XDSCommandPaletteFooter component
+ * @position Sub-component; footer with keyboard hints
+ *
+ * SYNC: When modified, update:
+ * - /packages/core/src/CommandPalette/README.md
+ * - /packages/core/src/CommandPalette/index.ts
+ */
+
+'use client';
+
+import type {ReactNode} from 'react';
+import * as stylex from '@stylexjs/stylex';
+import {
+ colorVars,
+ spacingVars,
+ textSizeVars,
+ typographyVars,
+} from '@xds/core/theme/tokens.stylex';
+import {XDSDivider} from '@xds/core/Divider';
+
+const styles = stylex.create({
+ footer: {
+ display: 'flex',
+ alignItems: 'center',
+ gap: spacingVars['--spacing-4'],
+ paddingInline: spacingVars['--spacing-4'],
+ paddingBlock: spacingVars['--spacing-2'],
+ flexShrink: 0,
+ },
+ hint: {
+ display: 'flex',
+ alignItems: 'center',
+ gap: spacingVars['--spacing-1'],
+ fontFamily: typographyVars['--font-body'],
+ fontSize: textSizeVars['--text-xsm'],
+ color: colorVars['--color-text-secondary'],
+ },
+});
+
+export interface XDSCommandPaletteFooterProps {
+ /**
+ * Footer content. When provided, renders custom content instead of default hints.
+ * When omitted, renders default keyboard navigation hints.
+ */
+ children?: ReactNode;
+}
+
+/**
+ * Footer for the command palette showing keyboard navigation hints.
+ *
+ * When no children are provided, renders default hints for
+ * arrow keys, Enter to select, and Escape to close.
+ *
+ * @compositionHint Place as the last child of XDSCommandPalette.
+ *
+ * @example
+ * ```
+ * <XDSCommandPalette isOpen={isOpen} onOpenChange={setIsOpen}>
+ * <XDSCommandPaletteInput />
+ * <XDSCommandPaletteList>...</XDSCommandPaletteList>
+ * <XDSCommandPaletteFooter />
+ * </XDSCommandPalette>
+ * ```
+ */
+export function XDSCommandPaletteFooter({
+ children,
+}: XDSCommandPaletteFooterProps) {
+ return (
+ <>
+ <XDSDivider />
+ <div {...stylex.props(styles.footer)}>
+ {children ?? (
+ <>
+ <span {...stylex.props(styles.hint)}>↑↓ Navigate</span>
+ <span {...stylex.props(styles.hint)}>↵ Select</span>
+ <span {...stylex.props(styles.hint)}>Esc Close</span>
+ </>
+ )}
+ </div>
+ </>
+ );
+}
+
+XDSCommandPaletteFooter.displayName = 'XDSCommandPaletteFooter';
diff --git a/packages/lab/src/CommandPalette/XDSCommandPaletteGroup.test.tsx b/packages/lab/src/CommandPalette/XDSCommandPaletteGroup.test.tsx
new file mode 100644
index 0000000000..f59dd19078
--- /dev/null
+++ b/packages/lab/src/CommandPalette/XDSCommandPaletteGroup.test.tsx
@@ -0,0 +1,52 @@
+/**
+ * @file XDSCommandPaletteGroup.test.tsx
+ * @input Uses vitest, @testing-library/react
+ * @output Unit tests for XDSCommandPaletteGroup
+ */
+
+import {describe, it, expect} from 'vitest';
+import {render, screen} from '@testing-library/react';
+import {XDSCommandPaletteGroup} from './XDSCommandPaletteGroup';
+
+describe('XDSCommandPaletteGroup', () => {
+ it('renders heading', () => {
+ render(
+ <XDSCommandPaletteGroup heading="Navigation">
+ <div>Item</div>
+ </XDSCommandPaletteGroup>,
+ );
+ expect(screen.getByText('Navigation')).toBeInTheDocument();
+ });
+
+ it('renders children', () => {
+ render(
+ <XDSCommandPaletteGroup heading="Group">
+ <div>Child 1</div>
+ <div>Child 2</div>
+ </XDSCommandPaletteGroup>,
+ );
+ expect(screen.getByText('Child 1')).toBeInTheDocument();
+ expect(screen.getByText('Child 2')).toBeInTheDocument();
+ });
+
+ it('has group role with aria-label', () => {
+ render(
+ <XDSCommandPaletteGroup heading="Actions">
+ <div>Item</div>
+ </XDSCommandPaletteGroup>,
+ );
+ expect(screen.getByRole('group')).toHaveAttribute('aria-label', 'Actions');
+ });
+
+ it('heading is aria-hidden', () => {
+ render(
+ <XDSCommandPaletteGroup heading="Hidden Heading">
+ <div>Item</div>
+ </XDSCommandPaletteGroup>,
+ );
+ expect(screen.getByText('Hidden Heading')).toHaveAttribute(
+ 'aria-hidden',
+ 'true',
+ );
+ });
+});
diff --git a/packages/lab/src/CommandPalette/XDSCommandPaletteGroup.tsx b/packages/lab/src/CommandPalette/XDSCommandPaletteGroup.tsx
new file mode 100644
index 0000000000..327b8b62af
--- /dev/null
+++ b/packages/lab/src/CommandPalette/XDSCommandPaletteGroup.tsx
@@ -0,0 +1,92 @@
+/**
+ * @file XDSCommandPaletteGroup.tsx
+ * @input Uses React, StyleX
+ * @output Exports XDSCommandPaletteGroup component
+ * @position Sub-component; visual grouping with heading
+ *
+ * SYNC: When modified, update:
+ * - /packages/core/src/CommandPalette/README.md
+ * - /packages/core/src/CommandPalette/index.ts
+ */
+
+'use client';
+
+import type {ReactNode} from 'react';
+import * as stylex from '@stylexjs/stylex';
+import type {StyleXStyles} from '@stylexjs/stylex';
+import {
+ colorVars,
+ spacingVars,
+ textSizeVars,
+ typographyVars,
+ fontWeightVars,
+} from '@xds/core/theme/tokens.stylex';
+
+const styles = stylex.create({
+ group: {
+ paddingBlock: spacingVars['--spacing-1'],
+ },
+ heading: {
+ paddingInline: spacingVars['--spacing-3'],
+ paddingBlock: spacingVars['--spacing-1'],
+ fontFamily: typographyVars['--font-body'],
+ fontSize: textSizeVars['--text-xsm'],
+ fontWeight: fontWeightVars['--font-weight-semibold'],
+ color: colorVars['--color-text-secondary'],
+ textTransform: 'uppercase' as const,
+ letterSpacing: '0.05em',
+ userSelect: 'none',
+ },
+});
+
+export interface XDSCommandPaletteGroupProps {
+ /**
+ * Group heading text.
+ */
+ heading: string;
+
+ /**
+ * Items within this group.
+ */
+ children: ReactNode;
+
+ /**
+ * StyleX overrides for the group container.
+ */
+ xstyle?: StyleXStyles;
+}
+
+/**
+ * Visual grouping for command palette items with a heading label.
+ *
+ * @compositionHint Place inside XDSCommandPaletteList.
+ * Contains XDSCommandPaletteItem children.
+ *
+ * @example
+ * ```
+ * <XDSCommandPaletteGroup heading="Navigation">
+ * <XDSCommandPaletteItem value="home" onSelect={goHome}>
+ * Home
+ * </XDSCommandPaletteItem>
+ * </XDSCommandPaletteGroup>
+ * ```
+ */
+export function XDSCommandPaletteGroup({
+ heading,
+ children,
+ xstyle,
+}: XDSCommandPaletteGroupProps) {
+ return (
+ <div
+ role="group"
+ aria-label={heading}
+ {...stylex.props(styles.group, xstyle)}>
+ <div aria-hidden="true" {...stylex.props(styles.heading)}>
+ {heading}
+ </div>
+ {children}
+ </div>
+ );
+}
+
+XDSCommandPaletteGroup.displayName = 'XDSCommandPaletteGroup';
diff --git a/packages/lab/src/CommandPalette/XDSCommandPaletteInput.test.tsx b/packages/lab/src/CommandPalette/XDSCommandPaletteInput.test.tsx
new file mode 100644
index 0000000000..bd79b1525e
--- /dev/null
+++ b/packages/lab/src/CommandPalette/XDSCommandPaletteInput.test.tsx
@@ -0,0 +1,69 @@
+/**
+ * @file XDSCommandPaletteInput.test.tsx
+ * @input Uses vitest, @testing-library/react, XDSCommandPaletteInput
+ * @output Unit tests for XDSCommandPaletteInput component
+ * @position Testing; validates XDSCommandPaletteInput.tsx implementation
+ */
+
+import {describe, it, expect, vi} from 'vitest';
+import {render, screen, fireEvent} from '@testing-library/react';
+import {XDSCommandPaletteInput} from './XDSCommandPaletteInput';
+
+describe('XDSCommandPaletteInput', () => {
+ it('renders with default placeholder', () => {
+ render(<XDSCommandPaletteInput />);
+ expect(screen.getByPlaceholderText('Search...')).toBeInTheDocument();
+ });
+
+ it('renders with custom placeholder', () => {
+ render(<XDSCommandPaletteInput placeholder="Type a command..." />);
+ expect(
+ screen.getByPlaceholderText('Type a command...'),
+ ).toBeInTheDocument();
+ });
+
+ it('has combobox role', () => {
+ render(<XDSCommandPaletteInput />);
+ expect(screen.getByRole('combobox')).toBeInTheDocument();
+ });
+
+ it('calls onValueChange when typing', () => {
+ const handleChange = vi.fn();
+ render(<XDSCommandPaletteInput onValueChange={handleChange} />);
+
+ const input = screen.getByRole('combobox');
+ fireEvent.change(input, {target: {value: 'test'}});
+
+ expect(handleChange).toHaveBeenCalledWith('test');
+ });
+
+ it('displays controlled value', () => {
+ render(<XDSCommandPaletteInput value="hello" onValueChange={() => {}} />);
+ expect(screen.getByRole('combobox')).toHaveValue('hello');
+ });
+
+ it('forwards native onChange alongside onValueChange', () => {
+ const handleChange = vi.fn();
+ const handleNativeChange = vi.fn();
+
+ render(
+ <XDSCommandPaletteInput
+ onValueChange={handleChange}
+ onChange={handleNativeChange}
+ />,
+ );
+
+ const input = screen.getByRole('combobox');
+ fireEvent.change(input, {target: {value: 'x'}});
+
+ expect(handleChange).toHaveBeenCalledWith('x');
+ expect(handleNativeChange).toHaveBeenCalled();
+ });
+
+ it('has aria-expanded and aria-autocomplete', () => {
+ render(<XDSCommandPaletteInput />);
+ const input = screen.getByRole('combobox');
+ expect(input).toHaveAttribute('aria-expanded', 'true');
+ expect(input).toHaveAttribute('aria-autocomplete', 'list');
+ });
+});
diff --git a/packages/lab/src/CommandPalette/XDSCommandPaletteInput.tsx b/packages/lab/src/CommandPalette/XDSCommandPaletteInput.tsx
new file mode 100644
index 0000000000..e7a5d36c77
--- /dev/null
+++ b/packages/lab/src/CommandPalette/XDSCommandPaletteInput.tsx
@@ -0,0 +1,233 @@
+/**
+ * @file XDSCommandPaletteInput.tsx
+ * @input Uses React, StyleX, XDSIcon, CommandPaletteContext
+ * @output Exports XDSCommandPaletteInput component and props
+ * @position Search input for the command palette
+ *
+ * SYNC: When modified, update these files to stay in sync:
+ * - /packages/core/src/CommandPalette/README.md
+ * - /packages/core/src/CommandPalette/index.ts
+ * - /apps/storybook/stories/CommandPalette.stories.tsx
+ */
+
+'use client';
+
+import {
+ forwardRef,
+ useCallback,
+ useEffect,
+ useRef,
+ type InputHTMLAttributes,
+} from 'react';
+import * as stylex from '@stylexjs/stylex';
+import {XDSIcon} from '@xds/core/Icon';
+import {
+ colorVars,
+ lineHeightVars,
+ spacingVars,
+ typographyVars,
+ textSizeVars,
+} from '@xds/core/theme/tokens.stylex';
+import {useCommandPaletteContext} from './CommandPaletteContext';
+
+const styles = stylex.create({
+ wrapper: {
+ display: 'flex',
+ alignItems: 'center',
+ gap: spacingVars['--spacing-2'],
+ paddingInline: spacingVars['--spacing-4'],
+ paddingBlock: spacingVars['--spacing-3'],
+ flexShrink: 0,
+ },
+ icon: {
+ flexShrink: 0,
+ color: colorVars['--color-text-secondary'],
+ },
+ input: {
+ flex: 1,
+ minWidth: 0,
+ border: 'none',
+ outline: 'none',
+ backgroundColor: 'transparent',
+ color: colorVars['--color-text-primary'],
+ fontFamily: typographyVars['--font-body'],
+ fontSize: textSizeVars['--text-base'],
+ lineHeight: lineHeightVars['--leading-normal'],
+ padding: 0,
+ '::placeholder': {
+ color: colorVars['--color-text-secondary'],
+ },
+ },
+});
+
+export interface XDSCommandPaletteInputProps extends Omit<
+ InputHTMLAttributes<HTMLInputElement>,
+ 'type' | 'role' | 'children' | 'autoFocus'
+> {
+ /**
+ * The current search value.
+ * When omitted inside XDSCommandPalette, reads from context.
+ */
+ value?: string;
+
+ /**
+ * Called when the search value changes.
+ * When omitted inside XDSCommandPalette, writes to context.
+ */
+ onValueChange?: (value: string) => void;
+
+ /**
+ * Placeholder text for the input.
+ * @default 'Search...'
+ */
+ placeholder?: string;
+
+ /**
+ * Whether to auto-focus the input when mounted.
+ * @default true
+ */
+ hasAutoFocus?: boolean;
+}
+
+/**
+ * Search input for the command palette.
+ *
+ * Renders a search icon and a text input. Auto-focuses when mounted
+ * so users can start typing immediately.
+ *
+ * When used inside XDSCommandPalette, automatically wires to the
+ * context for search state. Can also be used standalone with explicit
+ * value/onValueChange props.
+ *
+ * @compositionHint Place as the first child of XDSCommandPalette.
+ *
+ * @example
+ * ```
+ * <XDSCommandPalette isOpen={isOpen} onOpenChange={setIsOpen}>
+ * <XDSCommandPaletteInput
+ * placeholder="Search commands..."
+ * />
+ * </XDSCommandPalette>
+ * ```
+ */
+export const XDSCommandPaletteInput = forwardRef<
+ HTMLInputElement,
+ XDSCommandPaletteInputProps
+>(function XDSCommandPaletteInput(
+ {
+ value: controlledValue,
+ onValueChange,
+ placeholder = 'Search...',
+ hasAutoFocus = true,
+ onChange,
+ onKeyDown,
+ ...props
+ },
+ ref,
+) {
+ const ctx = useCommandPaletteContext();
+ const inputRef = useRef<HTMLInputElement>(null);
+
+ // Use context values as fallback
+ const value = controlledValue ?? ctx?.search;
+ const handleValueChange = onValueChange ?? ctx?.setSearch;
+
+ // Merge refs
+ const setRefs = (element: HTMLInputElement | null) => {
+ (inputRef as React.MutableRefObject<HTMLInputElement | null>).current =
+ element;
+ if (typeof ref === 'function') {
+ ref(element);
+ } else if (ref) {
+ ref.current = element;
+ }
+ };
+
+ // Auto-focus on mount
+ useEffect(() => {
+ if (hasAutoFocus && inputRef.current) {
+ requestAnimationFrame(() => {
+ inputRef.current?.focus();
+ });
+ }
+ }, [hasAutoFocus]);
+
+ // Keyboard navigation when context is available
+ const handleKeyDown = useCallback(
+ (e: React.KeyboardEvent<HTMLInputElement>) => {
+ onKeyDown?.(e);
+ if (!ctx || e.defaultPrevented) return;
+
+ const items = ctx.items.filter(item => !item.isDisabled);
+ if (items.length === 0) return;
+
+ switch (e.key) {
+ case 'ArrowDown': {
+ e.preventDefault();
+ ctx.setHighlightedIndex(
+ Math.min(ctx.highlightedIndex + 1, items.length - 1),
+ );
+ break;
+ }
+ case 'ArrowUp': {
+ e.preventDefault();
+ ctx.setHighlightedIndex(Math.max(ctx.highlightedIndex - 1, 0));
+ break;
+ }
+ case 'Home': {
+ e.preventDefault();
+ ctx.setHighlightedIndex(0);
+ break;
+ }
+ case 'End': {
+ e.preventDefault();
+ ctx.setHighlightedIndex(items.length - 1);
+ break;
+ }
+ case 'Enter': {
+ e.preventDefault();
+ const highlighted = items[ctx.highlightedIndex];
+ if (highlighted) {
+ ctx.selectItem(highlighted.value);
+ }
+ break;
+ }
+ }
+ },
+ [ctx, onKeyDown],
+ );
+
+ return (
+ <div {...stylex.props(styles.wrapper)}>
+ <span {...stylex.props(styles.icon)}>
+ <XDSIcon icon="search" size="sm" color="inherit" />
+ </span>
+ <input
+ ref={setRefs}
+ type="text"
+ role="combobox"
+ aria-expanded={true}
+ aria-autocomplete="list"
+ aria-controls={ctx?.listId}
+ aria-activedescendant={
+ ctx && ctx.highlightedIndex >= 0
+ ? `${ctx.listId}-item-${ctx.highlightedIndex}`
+ : undefined
+ }
+ placeholder={placeholder}
+ value={value}
+ onChange={e => {
+ handleValueChange?.(e.target.value);
+ onChange?.(e);
+ // Reset highlight when search changes
+ ctx?.setHighlightedIndex(0);
+ }}
+ onKeyDown={handleKeyDown}
+ {...stylex.props(styles.input)}
+ {...props}
+ />
+ </div>
+ );
+});
+
+XDSCommandPaletteInput.displayName = 'XDSCommandPaletteInput';
diff --git a/packages/lab/src/CommandPalette/XDSCommandPaletteItem.test.tsx b/packages/lab/src/CommandPalette/XDSCommandPaletteItem.test.tsx
new file mode 100644
index 0000000000..18b74145da
--- /dev/null
+++ b/packages/lab/src/CommandPalette/XDSCommandPaletteItem.test.tsx
@@ -0,0 +1,73 @@
+/**
+ * @file XDSCommandPaletteItem.test.tsx
+ * @input Uses vitest, @testing-library/react
+ * @output Unit tests for XDSCommandPaletteItem
+ */
+
+import {describe, it, expect, vi} from 'vitest';
+import {render, screen, fireEvent} from '@testing-library/react';
+import {XDSCommandPaletteItem} from './XDSCommandPaletteItem';
+
+describe('XDSCommandPaletteItem', () => {
+ it('renders children', () => {
+ render(
+ <XDSCommandPaletteItem value="test">Test Item</XDSCommandPaletteItem>,
+ );
+ expect(screen.getByText('Test Item')).toBeInTheDocument();
+ });
+
+ it('has option role', () => {
+ render(<XDSCommandPaletteItem value="test">Item</XDSCommandPaletteItem>);
+ expect(screen.getByRole('option')).toBeInTheDocument();
+ });
+
+ it('calls onSelect when clicked', () => {
+ const handleSelect = vi.fn();
+ render(
+ <XDSCommandPaletteItem value="test" onSelect={handleSelect}>
+ Item
+ </XDSCommandPaletteItem>,
+ );
+ fireEvent.click(screen.getByRole('option'));
+ expect(handleSelect).toHaveBeenCalledWith('test');
+ });
+
+ it('does not call onSelect when disabled', () => {
+ const handleSelect = vi.fn();
+ render(
+ <XDSCommandPaletteItem value="test" onSelect={handleSelect} isDisabled>
+ Item
+ </XDSCommandPaletteItem>,
+ );
+ fireEvent.click(screen.getByRole('option'));
+ expect(handleSelect).not.toHaveBeenCalled();
+ });
+
+ it('sets aria-disabled when disabled', () => {
+ render(
+ <XDSCommandPaletteItem value="test" isDisabled>
+ Item
+ </XDSCommandPaletteItem>,
+ );
+ expect(screen.getByRole('option')).toHaveAttribute('aria-disabled', 'true');
+ });
+
+ it('sets aria-selected when highlighted', () => {
+ render(
+ <XDSCommandPaletteItem value="test" isHighlighted>
+ Item
+ </XDSCommandPaletteItem>,
+ );
+ expect(screen.getByRole('option')).toHaveAttribute('aria-selected', 'true');
+ });
+
+ it('sets data-value attribute', () => {
+ render(
+ <XDSCommandPaletteItem value="my-value">Item</XDSCommandPaletteItem>,
+ );
+ expect(screen.getByRole('option')).toHaveAttribute(
+ 'data-value',
+ 'my-value',
+ );
+ });
+});
diff --git a/packages/lab/src/CommandPalette/XDSCommandPaletteItem.tsx b/packages/lab/src/CommandPalette/XDSCommandPaletteItem.tsx
new file mode 100644
index 0000000000..51899c35ac
--- /dev/null
+++ b/packages/lab/src/CommandPalette/XDSCommandPaletteItem.tsx
@@ -0,0 +1,230 @@
+/**
+ * @file XDSCommandPaletteItem.tsx
+ * @input Uses React, StyleX, CommandPaletteContext
+ * @output Exports XDSCommandPaletteItem component
+ * @position Sub-component; individual selectable item
+ *
+ * SYNC: When modified, update:
+ * - /packages/core/src/CommandPalette/README.md
+ * - /packages/core/src/CommandPalette/index.ts
+ */
+
+'use client';
+
+import {
+ forwardRef,
+ useCallback,
+ useEffect,
+ useRef,
+ type ReactNode,
+} from 'react';
+import * as stylex from '@stylexjs/stylex';
+import type {StyleXStyles} from '@stylexjs/stylex';
+import {
+ colorVars,
+ spacingVars,
+ radiusVars,
+ typographyVars,
+ textSizeVars,
+} from '@xds/core/theme/tokens.stylex';
+import {useCommandPaletteContext} from './CommandPaletteContext';
+
+const HOVER_HOVER = '@media (hover: hover)';
+
+const styles = stylex.create({
+ item: {
+ display: 'flex',
+ alignItems: 'center',
+ gap: spacingVars['--spacing-2'],
+ width: '100%',
+ paddingInline: spacingVars['--spacing-3'],
+ paddingBlock: spacingVars['--spacing-2'],
+ borderRadius: radiusVars['--radius-content'],
+ fontFamily: typographyVars['--font-body'],
+ fontSize: textSizeVars['--text-base'],
+ color: colorVars['--color-text-primary'],
+ backgroundColor: 'transparent',
+ border: 'none',
+ cursor: 'pointer',
+ textAlign: 'left',
+ outline: 'none',
+ userSelect: 'none',
+ },
+ itemHover: {
+ ':hover': {
+ [HOVER_HOVER]: {
+ backgroundColor: colorVars['--color-hover-overlay'],
+ },
+ },
+ },
+ itemHighlighted: {
+ backgroundColor: colorVars['--color-hover-overlay'],
+ },
+ itemDisabled: {
+ opacity: 0.5,
+ cursor: 'not-allowed',
+ },
+ itemSelected: {
+ backgroundColor: colorVars['--color-accent-deemphasized'],
+ },
+});
+
+export interface XDSCommandPaletteItemProps {
+ /**
+ * Unique value for identification and selection.
+ */
+ value: string;
+
+ /**
+ * Called when this item is selected (via click or Enter).
+ */
+ onSelect?: (value: string) => void;
+
+ /**
+ * Additional search terms for filtering (used by context filter).
+ */
+ keywords?: string[];
+
+ /**
+ * Whether this item is visually highlighted (e.g., via keyboard navigation).
+ * When omitted inside XDSCommandPalette, derived from context.
+ * @default false
+ */
+ isHighlighted?: boolean;
+
+ /**
+ * Whether this item is currently selected.
+ * When omitted inside XDSCommandPalette, derived from context.
+ * @default false
+ */
+ isSelected?: boolean;
+
+ /**
+ * Whether the item is disabled.
+ * @default false
+ */
+ isDisabled?: boolean;
+
+ /**
+ * Item content. Fully custom — render icons, descriptions, shortcuts, etc.
+ */
+ children: ReactNode;
+
+ /**
+ * StyleX overrides for the item.
+ */
+ xstyle?: StyleXStyles;
+}
+
+/**
+ * A selectable item in the command palette.
+ * Accepts arbitrary children for full rendering control.
+ *
+ * When used inside XDSCommandPalette, registers with context for
+ * filtering, keyboard navigation, and selection. Can also be used
+ * standalone with explicit isHighlighted/isSelected props.
+ *
+ * @compositionHint Place inside XDSCommandPaletteList or XDSCommandPaletteGroup.
+ *
+ * @example
+ * ```
+ * <XDSCommandPaletteItem value="settings" onSelect={() => navigate('/settings')}>
+ * Settings
+ * </XDSCommandPaletteItem>
+ * ```
+ */
+export const XDSCommandPaletteItem = forwardRef<
+ HTMLDivElement,
+ XDSCommandPaletteItemProps
+>(function XDSCommandPaletteItem(
+ {
+ value,
+ onSelect,
+ keywords,
+ isHighlighted: controlledHighlighted,
+ isSelected: controlledSelected,
+ isDisabled = false,
+ children,
+ xstyle,
+ },
+ ref,
+) {
+ const ctx = useCommandPaletteContext();
+ const itemRef = useRef<HTMLDivElement>(null);
+
+ // Merge refs
+ const setRefs = (element: HTMLDivElement | null) => {
+ (itemRef as React.MutableRefObject<HTMLDivElement | null>).current =
+ element;
+ if (typeof ref === 'function') {
+ ref(element);
+ } else if (ref) {
+ ref.current = element;
+ }
+ };
+
+ // Register with context on mount
+ useEffect(() => {
+ if (!ctx) return;
+ const unregister = ctx.registerItem(value, isDisabled);
+ return unregister;
+ }, [value, isDisabled, ctx]);
+
+ // Derive state from context or props
+ const itemIndex = ctx?.items.findIndex(item => item.value === value) ?? -1;
+ const isHighlighted =
+ controlledHighlighted ?? (ctx ? itemIndex === ctx.highlightedIndex : false);
+ const isSelected = controlledSelected ?? (ctx ? ctx.value === value : false);
+
+ // Filter: check if this item matches the search
+ const score =
+ ctx?.isFiltered && ctx.search ? ctx.filter(value, ctx.search, keywords) : 1;
+
+ // Scroll highlighted item into view
+ useEffect(() => {
+ if (isHighlighted && itemRef.current) {
+ itemRef.current.scrollIntoView?.({block: 'nearest'});
+ }
+ }, [isHighlighted]);
+
+ const handleClick = useCallback(() => {
+ if (isDisabled) return;
+ onSelect?.(value);
+ if (ctx) {
+ ctx.selectItem(value);
+ ctx.onClose();
+ }
+ }, [isDisabled, value, onSelect, ctx]);
+
+ const handleMouseEnter = useCallback(() => {
+ if (isDisabled || !ctx) return;
+ ctx.setHighlightedIndex(itemIndex);
+ }, [isDisabled, itemIndex, ctx]);
+
+ // Don't render if filtered out
+ if (score === 0) return null;
+
+ return (
+ <div
+ ref={setRefs}
+ id={ctx ? `${ctx.listId}-item-${itemIndex}` : undefined}
+ role="option"
+ aria-selected={isHighlighted}
+ aria-disabled={isDisabled || undefined}
+ data-value={value}
+ onClick={handleClick}
+ onMouseEnter={handleMouseEnter}
+ {...stylex.props(
+ styles.item,
+ !isDisabled && styles.itemHover,
+ isHighlighted && styles.itemHighlighted,
+ isSelected && styles.itemSelected,
+ isDisabled && styles.itemDisabled,
+ xstyle,
+ )}>
+ {children}
+ </div>
+ );
+});
+
+XDSCommandPaletteItem.displayName = 'XDSCommandPaletteItem';
diff --git a/packages/lab/src/CommandPalette/XDSCommandPaletteList.test.tsx b/packages/lab/src/CommandPalette/XDSCommandPaletteList.test.tsx
new file mode 100644
index 0000000000..313dd5593a
--- /dev/null
+++ b/packages/lab/src/CommandPalette/XDSCommandPaletteList.test.tsx
@@ -0,0 +1,55 @@
+/**
+ * @file XDSCommandPaletteList.test.tsx
+ * @input Uses vitest, @testing-library/react
+ * @output Unit tests for XDSCommandPaletteList
+ */
+
+import {describe, it, expect} from 'vitest';
+import {render, screen} from '@testing-library/react';
+import {XDSCommandPaletteList} from './XDSCommandPaletteList';
+
+describe('XDSCommandPaletteList', () => {
+ it('renders children', () => {
+ render(
+ <XDSCommandPaletteList>
+ <div>Item 1</div>
+ <div>Item 2</div>
+ </XDSCommandPaletteList>,
+ );
+ expect(screen.getByText('Item 1')).toBeInTheDocument();
+ expect(screen.getByText('Item 2')).toBeInTheDocument();
+ });
+
+ it('has listbox role', () => {
+ render(
+ <XDSCommandPaletteList>
+ <div>Item</div>
+ </XDSCommandPaletteList>,
+ );
+ expect(screen.getByRole('listbox')).toBeInTheDocument();
+ });
+
+ it('has default aria-label', () => {
+ render(
+ <XDSCommandPaletteList>
+ <div>Item</div>
+ </XDSCommandPaletteList>,
+ );
+ expect(screen.getByRole('listbox')).toHaveAttribute(
+ 'aria-label',
+ 'Commands',
+ );
+ });
+
+ it('supports custom label', () => {
+ render(
+ <XDSCommandPaletteList label="Search results">
+ <div>Item</div>
+ </XDSCommandPaletteList>,
+ );
+ expect(screen.getByRole('listbox')).toHaveAttribute(
+ 'aria-label',
+ 'Search results',
+ );
+ });
+});
diff --git a/packages/lab/src/CommandPalette/XDSCommandPaletteList.tsx b/packages/lab/src/CommandPalette/XDSCommandPaletteList.tsx
new file mode 100644
index 0000000000..5e225a0e05
--- /dev/null
+++ b/packages/lab/src/CommandPalette/XDSCommandPaletteList.tsx
@@ -0,0 +1,84 @@
+/**
+ * @file XDSCommandPaletteList.tsx
+ * @input Uses React, StyleX, CommandPaletteContext
+ * @output Exports XDSCommandPaletteList component
+ * @position Sub-component; scrollable results container
+ *
+ * SYNC: When modified, update:
+ * - /packages/core/src/CommandPalette/README.md
+ * - /packages/core/src/CommandPalette/index.ts
+ */
+
+'use client';
+
+import type {ReactNode} from 'react';
+import * as stylex from '@stylexjs/stylex';
+import type {StyleXStyles} from '@stylexjs/stylex';
+import {spacingVars} from '@xds/core/theme/tokens.stylex';
+import {useCommandPaletteContext} from './CommandPaletteContext';
+
+const styles = stylex.create({
+ list: {
+ overflowY: 'auto',
+ maxHeight: '100%',
+ padding: spacingVars['--spacing-1'],
+ flex: 1,
+ },
+});
+
+export interface XDSCommandPaletteListProps {
+ /**
+ * Command palette items, groups, empty states, etc.
+ */
+ children: ReactNode;
+
+ /**
+ * Accessible label for the listbox.
+ * @default 'Commands'
+ */
+ label?: string;
+
+ /**
+ * StyleX overrides for the list container.
+ */
+ xstyle?: StyleXStyles;
+}
+
+/**
+ * Scrollable results container for the command palette.
+ * Renders as a listbox for ARIA compliance.
+ *
+ * When used inside XDSCommandPalette, automatically gets the correct
+ * ID for aria-controls linking with the input.
+ *
+ * @compositionHint Place inside XDSCommandPalette, after XDSCommandPaletteInput.
+ * Contains XDSCommandPaletteItem and XDSCommandPaletteGroup children.
+ *
+ * @example
+ * ```
+ * <XDSCommandPaletteList>
+ * <XDSCommandPaletteItem value="home" onSelect={goHome}>
+ * Go Home
+ * </XDSCommandPaletteItem>
+ * </XDSCommandPaletteList>
+ * ```
+ */
+export function XDSCommandPaletteList({
+ children,
+ label = 'Commands',
+ xstyle,
+}: XDSCommandPaletteListProps) {
+ const ctx = useCommandPaletteContext();
+
+ return (
+ <div
+ id={ctx?.listId}
+ role="listbox"
+ aria-label={label}
+ {...stylex.props(styles.list, xstyle)}>
+ {children}
+ </div>
+ );
+}
+
+XDSCommandPaletteList.displayName = 'XDSCommandPaletteList';
diff --git a/packages/lab/src/CommandPalette/filter.test.ts b/packages/lab/src/CommandPalette/filter.test.ts
new file mode 100644
index 0000000000..bc5bf0c0f7
--- /dev/null
+++ b/packages/lab/src/CommandPalette/filter.test.ts
@@ -0,0 +1,47 @@
+/**
+ * @file filter.test.ts
+ * @input Uses vitest
+ * @output Unit tests for default filter function
+ */
+
+import {describe, it, expect} from 'vitest';
+import {defaultFilter} from './filter';
+
+describe('defaultFilter', () => {
+ it('returns 1 for empty search', () => {
+ expect(defaultFilter('anything', '')).toBe(1);
+ });
+
+ it('returns 1 for exact match', () => {
+ expect(defaultFilter('settings', 'settings')).toBe(1);
+ });
+
+ it('returns 0.9 for starts-with match', () => {
+ expect(defaultFilter('settings', 'set')).toBe(0.9);
+ });
+
+ it('returns 0.7 for contains match', () => {
+ expect(defaultFilter('settings', 'ting')).toBe(0.7);
+ });
+
+ it('returns 0 for no match', () => {
+ expect(defaultFilter('settings', 'xyz')).toBe(0);
+ });
+
+ it('is case-insensitive', () => {
+ expect(defaultFilter('Settings', 'settings')).toBe(1);
+ expect(defaultFilter('settings', 'SET')).toBe(0.9);
+ });
+
+ it('matches keywords', () => {
+ expect(defaultFilter('theme', 'dark', ['dark mode', 'appearance'])).toBe(
+ 0.6,
+ );
+ });
+
+ it('returns 0.5 for keyword contains match', () => {
+ expect(defaultFilter('theme', 'ear', ['dark mode', 'appearance'])).toBe(
+ 0.5,
+ );
+ });
+});
diff --git a/packages/lab/src/CommandPalette/filter.ts b/packages/lab/src/CommandPalette/filter.ts
new file mode 100644
index 0000000000..a83abf1d10
--- /dev/null
+++ b/packages/lab/src/CommandPalette/filter.ts
@@ -0,0 +1,45 @@
+/**
+ * @file filter.ts
+ * @input Search string and item value/keywords
+ * @output Score between 0 and 1 indicating match quality
+ * @position Utility; used by CommandPaletteContext for default filtering
+ */
+
+import type {CommandPaletteFilterFn} from './types';
+
+/**
+ * Default filter function for command palette.
+ * Uses substring matching with keyword support.
+ * Returns a score between 0 (no match) and 1 (exact match).
+ */
+export const defaultFilter: CommandPaletteFilterFn = (
+ value: string,
+ search: string,
+ keywords?: string[],
+): number => {
+ if (search.length === 0) return 1;
+
+ const searchLower = search.toLowerCase();
+ const valueLower = value.toLowerCase();
+
+ // Exact match
+ if (valueLower === searchLower) return 1;
+
+ // Starts with
+ if (valueLower.startsWith(searchLower)) return 0.9;
+
+ // Contains
+ if (valueLower.includes(searchLower)) return 0.7;
+
+ // Check keywords
+ if (keywords) {
+ for (const keyword of keywords) {
+ const keywordLower = keyword.toLowerCase();
+ if (keywordLower.startsWith(searchLower)) return 0.6;
+ if (keywordLower.includes(searchLower)) return 0.5;
+ }
+ }
+
+ // No match
+ return 0;
+};
diff --git a/packages/lab/src/CommandPalette/index.ts b/packages/lab/src/CommandPalette/index.ts
new file mode 100644
index 0000000000..7645732dd4
--- /dev/null
+++ b/packages/lab/src/CommandPalette/index.ts
@@ -0,0 +1,32 @@
+/**
+ * @file index.ts
+ * @input Imports CommandPalette components and types
+ * @output Exports all CommandPalette components and types
+ * @position Component entry point; re-exported by /packages/core/src/index.ts
+ *
+ * SYNC: When modified, update this header
+ */
+
+export {XDSCommandPalette} from './XDSCommandPalette';
+export type {XDSCommandPaletteProps} from './XDSCommandPalette';
+
+export {XDSCommandPaletteInput} from './XDSCommandPaletteInput';
+export type {XDSCommandPaletteInputProps} from './XDSCommandPaletteInput';
+
+export {XDSCommandPaletteList} from './XDSCommandPaletteList';
+export type {XDSCommandPaletteListProps} from './XDSCommandPaletteList';
+
+export {XDSCommandPaletteItem} from './XDSCommandPaletteItem';
+export type {XDSCommandPaletteItemProps} from './XDSCommandPaletteItem';
+
+export {XDSCommandPaletteGroup} from './XDSCommandPaletteGroup';
+export type {XDSCommandPaletteGroupProps} from './XDSCommandPaletteGroup';
+
+export {XDSCommandPaletteFooter} from './XDSCommandPaletteFooter';
+export type {XDSCommandPaletteFooterProps} from './XDSCommandPaletteFooter';
+
+export {useCommandPaletteContext} from './CommandPaletteContext';
+export type {CommandPaletteContextValue} from './CommandPaletteContext';
+
+export {defaultFilter} from './filter';
+export type {CommandPaletteFilterFn} from './types';
diff --git a/packages/lab/src/CommandPalette/types.ts b/packages/lab/src/CommandPalette/types.ts
new file mode 100644
index 0000000000..77acba9266
--- /dev/null
+++ b/packages/lab/src/CommandPalette/types.ts
@@ -0,0 +1,16 @@
+/**
+ * @file types.ts
+ * @input None
+ * @output Exports shared types for CommandPalette components
+ * @position Type definitions; consumed by CommandPalette components
+ */
+
+/**
+ * Custom filter function. Return a score between 0 and 1.
+ * 0 means no match (hidden), 1 means perfect match.
+ */
+export type CommandPaletteFilterFn = (
+ value: string,
+ search: string,
+ keywords?: string[],
+) => number;
diff --git a/packages/lab/src/index.ts b/packages/lab/src/index.ts
new file mode 100644
index 0000000000..b79b44deee
--- /dev/null
+++ b/packages/lab/src/index.ts
@@ -0,0 +1,28 @@
+/**
+ * @xds/lab — Experimental XDS components
+ *
+ * Components here are functional but not yet hardened for production.
+ * They're available in storybook and sandbox for testing and iteration.
+ * Once vetted, components graduate to @xds/core.
+ *
+ * This package is never published to npm.
+ */
+
+export {
+ XDSCommandPalette,
+ type XDSCommandPaletteProps,
+ XDSCommandPaletteInput,
+ type XDSCommandPaletteInputProps,
+ XDSCommandPaletteList,
+ type XDSCommandPaletteListProps,
+ XDSCommandPaletteItem,
+ type XDSCommandPaletteItemProps,
+ XDSCommandPaletteGroup,
+ type XDSCommandPaletteGroupProps,
+ XDSCommandPaletteFooter,
+ type XDSCommandPaletteFooterProps,
+ useCommandPaletteContext,
+ type CommandPaletteContextValue,
+ defaultFilter,
+ type CommandPaletteFilterFn,
+} from './CommandPalette';
diff --git a/vitest.config.ts b/vitest.config.ts
index a47a8d7784..310a119459 100644
--- a/vitest.config.ts
+++ b/vitest.config.ts
@@ -7,9 +7,13 @@
* SYNC: When modified, update this header and root README.md
*/
+import path from 'path';
import {defineConfig} from 'vitest/config';
import react from '@vitejs/plugin-react';
+const rootDir = path.resolve(__dirname, '.');
+const coreSrc = path.resolve(__dirname, 'packages/core/src');
+
export default defineConfig({
plugins: [
react({
@@ -22,9 +26,13 @@ export default defineConfig({
runtimeInjection: true,
genConditionalClasses: true,
treeshakeCompensation: true,
+ aliases: {
+ '@xds/core/*': [path.join(rootDir, 'packages/core/src/*')],
+ '@xds/core': [path.join(rootDir, 'packages/core/src')],
+ },
unstable_moduleResolution: {
type: 'commonJS',
- rootDir: '.',
+ rootDir: rootDir,
},
},
],
@@ -32,6 +40,14 @@ export default defineConfig({
},
}),
],
+ resolve: {
+ alias: [
+ // Map @xds/core subpath imports to source for lab package tests.
+ // Must use regex to match subpaths like @xds/core/Dialog, @xds/core/theme/tokens.stylex
+ // while not breaking core's own relative imports.
+ { find: /^@xds\/core\/(.*)$/, replacement: path.join(coreSrc, '$1') },
+ ],
+ },
test: {
globals: true,
environment: 'jsdom',