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.tsxnew file mode 100644index 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.mdnew file mode 100644index 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.jsonnew file mode 100644index 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.mjsnew file mode 100644index 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.tsnew file mode 100644index 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.mdnew file mode 100644index 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.tsxnew file mode 100644index 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.tsxnew file mode 100644index 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.tsxnew file mode 100644index 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.tsxnew file mode 100644index 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.tsxnew file mode 100644index 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.tsxnew file mode 100644index 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.tsxnew file mode 100644index 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.tsxnew file mode 100644index 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.tsxnew file mode 100644index 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.tsxnew file mode 100644index 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.tsxnew file mode 100644index 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.tsxnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsindex 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',