An open source design system that's fully customizable and agent ready
TypeScript
docs: add CodeBlock and CommandPalette docs, fix Storybook @example fences (#1136)
Joey4eb6c26c6b38
diff --git a/packages/cli/src/commands/component.test.mjs b/packages/cli/src/commands/component.test.mjsindex 76a76efc12..10d5a451de 100644--- a/packages/cli/src/commands/component.test.mjs+++ b/packages/cli/src/commands/component.test.mjs@@ -521,8 +521,9 @@ describe('searchComponents', () => {const {searchComponents, discoverComponents} = await import('./component/index.mjs');const components = discoverComponents('packages/core');const results = await searchComponents('modal', 'packages/core', components);- expect(results[0].name).toBe('Dialog');- expect(results[0].score).toBe(90);+ const dialog = results.find(r => r.name === 'Dialog');+ expect(dialog).toBeDefined();+ expect(dialog.score).toBe(90);});it('returns multiple matches for ambiguous terms like "select"', async () => {diff --git a/packages/core/src/CodeBlock/XDSCodeBlock.doc.mjs b/packages/core/src/CodeBlock/XDSCodeBlock.doc.mjsnew file mode 100644index 0000000000..61de8f865c--- /dev/null+++ b/packages/core/src/CodeBlock/XDSCodeBlock.doc.mjs@@ -0,0 +1,214 @@+/** @type {import('../docs-types').ComponentDoc} */+export const docs = {+ name: 'CodeBlock',+ description:+ 'Syntax-highlighted code block using the CSS Custom Highlight API for zero-DOM-overhead coloring, with span-based fallback. XDSCode renders inline code within prose.',+ keywords: [+ 'code', 'syntax', 'highlight', 'snippet', 'prism', 'shiki',+ 'pre', 'monospace', 'codeblock', 'inline',+ ],+ features: [+ "CSS Custom Highlight API: zero-DOM-overhead syntax coloring; spans fallback for unsupported browsers",+ "Line numbers: optional gutter via hasLineNumbers",+ "Line highlighting: 1-indexed lines via highlightLines",+ "Copy button: built-in with onCopy callback",+ "Header: optional title + language label",+ "Sizes: sm and md",+ "Wrapping: isWrapped toggles long-line wrapping vs horizontal scroll",+ "Languages: TypeScript, JavaScript, CSS, HTML, JSON, plaintext (default)",+ "XDSCode: inline code element with monospace styling for use inside prose",+ ],+ components: [+ {+ name: 'XDSCodeBlock',+ description: 'Fenced code block with syntax highlighting. Use for multi-line code snippets.',+ props: [+ {name: 'code', type: 'string', description: 'The code string to display.', required: true},+ {name: 'language', type: 'string', description: 'Language for syntax highlighting. Use "plaintext" to disable.', default: "'plaintext'"},+ {name: 'title', type: 'string', description: 'Filename or label shown in the header bar.'},+ {name: 'hasLanguageLabel', type: 'boolean', description: 'Show the language name in the header bar. Hidden when language is "plaintext".', default: 'true'},+ {name: 'hasLineNumbers', type: 'boolean', description: 'Show a line number gutter.', default: 'false'},+ {name: 'highlightLines', type: 'number[]', description: '1-indexed line numbers to highlight.'},+ {name: 'hasCopyButton', type: 'boolean', description: 'Show a copy-to-clipboard button.', default: 'true'},+ {name: 'onCopy', type: '() => void', description: 'Callback after the code is copied.'},+ {name: 'isWrapped', type: 'boolean', description: 'Wrap long lines instead of enabling horizontal scroll.', default: 'false'},+ {name: 'maxHeight', type: 'number | string', description: 'Max height before the block scrolls vertically.'},+ {name: 'size', type: "'sm' | 'md'", description: 'Text size variant.', default: "'md'"},+ {name: 'tokenizer', type: '(code: string, language: string) => Array<{type: string; start: number; end: number}>', description: 'Custom tokenizer override for unsupported languages.'},+ {name: 'xstyle', type: 'StyleXStyles', description: 'StyleX styles for layout customization. Must be a stylex.create() value.'},+ {name: 'className', type: 'string', description: 'CSS class name for the root element. Prefer xstyle for styling.'},+ {name: 'style', type: 'CSSProperties', description: 'Inline styles. Prefer xstyle for StyleX-optimized styling.'},+ {name: 'data-testid', type: 'string', description: 'Test selector for automated testing frameworks.'},+ ],+ examples: [+ {label: 'Basic usage', code: '<XDSCodeBlock\n code={`const x = 42;`}\n language="typescript"\n hasLineNumbers\n/>'},+ {label: 'With title and line highlighting', code: '<XDSCodeBlock\n code={snippetCode}\n language="typescript"\n title="utils.ts"\n highlightLines={[3, 4, 5]}\n/>'},+ ],+ },+ {+ name: 'XDSCode',+ description: 'Inline code element. Renders a styled <code> with monospace font and muted background. For fenced blocks, use XDSCodeBlock.',+ props: [+ {name: 'children', type: 'ReactNode', description: 'Code content.', required: true},+ {name: 'xstyle', type: 'StyleXStyles', description: 'StyleX styles for layout customization. Must be a stylex.create() value.'},+ {name: 'className', type: 'string', description: 'CSS class name for the root element. Prefer xstyle for styling.'},+ {name: 'style', type: 'CSSProperties', description: 'Inline styles. Prefer xstyle for StyleX-optimized styling.'},+ {name: 'data-testid', type: 'string', description: 'Test selector for automated testing frameworks.'},+ ],+ examples: [+ {label: 'Inline in prose', code: '<XDSText type="body">\n Pass <XDSCode>xstyle</XDSCode> a <XDSCode>stylex.create()</XDSCode> value.\n</XDSText>'},+ ],+ },+ ],+ examples: [+ {label: 'TypeScript with line numbers', code: '<XDSCodeBlock\n code={`function greet(name: string) { return name; }`}\n language="typescript"\n hasLineNumbers\n title="greet.ts"\n/>'},+ {label: 'Inline code in text', code: '<XDSText type="body">\n Use <XDSCode>const</XDSCode> for block-scoped declarations.\n</XDSText>'},+ ],+ theming: {+ targets: [+ {className: 'xds-code'},+ {className: 'xds-codeblock', visualProps: ['size', 'language']},+ ],+ },+ accessibility: [+ 'XDSCodeBlock renders as <pre> with nested <code> for correct semantic markup.',+ 'Copy button has an accessible label and uses aria-live to announce copy success.',+ 'Line numbers are aria-hidden to avoid screen reader noise.',+ 'Title and language label are visible text in the header, not tooltips.',+ ],+ notes: [+ 'Uses CSS Custom Highlight API (CSS.highlights) when available; falls back to span-based rendering automatically.',+ 'Tokenization is async -- initial render shows unstyled code, highlights applied on next paint.',+ 'SYNC_TOKENIZE_THRESHOLD: short code strings tokenized synchronously to avoid async flash.',+ 'Custom tokenizers support unsupported languages -- pass {type, start, end}[] token array.',+ 'Token types map to xds-token-{type} CSS classes for custom syntax theme overrides.',+ ],+};++/** @type {import('../docs-types').TranslationDoc} */+export const docsZh = {+ description: '使用 CSS Custom Highlight API 实现零 DOM 开销语法高亮的代码块,不支持时回退到基于 span 的渲染。XDSCode 用于在正文中渲染内联代码。',+ features: [+ 'CSS Custom Highlight API:零 DOM 开销语法高亮;不支持浏览器时回退到 span',+ '行号:通过 hasLineNumbers 显示可选的行号栏',+ '行高亮:通过 highlightLines 指定 1-indexed 的高亮行',+ '复制按钮:内置,支持 onCopy 回调',+ '标题栏:可选的标题和语言标签',+ '尺寸:sm 和 md 两种',+ '换行:isWrapped 切换长行换行与水平滚动',+ '语言:TypeScript、JavaScript、CSS、HTML、JSON、plaintext(默认)',+ 'XDSCode:用于正文中内联代码的等宽字体样式元素',+ ],+ accessibility: [+ 'XDSCodeBlock 渲染为带嵌套 <code> 的 <pre>,具有正确的语义标记。',+ '复制按钮有无障碍标签,并使用 aria-live 播报复制成功。',+ '行号设置 aria-hidden 以避免屏幕阅读器噪音。',+ '标题和语言标签是标题栏中的可见文本,而非工具提示。',+ ],+ notes: [+ '可用时使用 CSS Custom Highlight API(CSS.highlights),自动回退到基于 span 的渲染。',+ '分词是异步的——初始渲染显示未高亮代码,下一帧应用高亮。',+ 'SYNC_TOKENIZE_THRESHOLD:短代码字符串同步分词以避免异步闪烁。',+ '自定义分词器支持内置不支持的语言——传入 {type, start, end}[] token 数组。',+ 'Token 类型映射到 xds-token-{type} CSS 类,支持自定义语法主题覆盖。',+ ],+ components: [+ {+ name: 'XDSCodeBlock',+ description: '带语法高亮的围栏代码块。用于多行代码片段。',+ propDescriptions: {+ code: '要显示的代码字符串。',+ language: '语法高亮语言。使用 "plaintext" 禁用高亮。',+ title: '在标题栏中显示的文件名或标签。',+ hasLanguageLabel: '在标题栏中显示语言名称。language 为 "plaintext" 时隐藏。',+ hasLineNumbers: '显示行号栏。',+ highlightLines: '需要高亮的 1-indexed 行号。',+ hasCopyButton: '显示复制到剪贴板按钮。',+ onCopy: '代码复制后的回调函数。',+ isWrapped: '换行显示长行,而非启用水平滚动。',+ maxHeight: '代码块垂直滚动前的最大高度。',+ size: '文字大小变体。',+ tokenizer: '用于不支持语言的自定义分词器。',+ xstyle: 'StyleX 布局自定义样式。必须是 stylex.create() 的值。',+ className: '根元素的 CSS 类名。优先使用 xstyle。',+ style: '内联样式。优先使用 xstyle。',+ 'data-testid': '自动化测试框架的测试选择器。',+ },+ },+ {+ name: 'XDSCode',+ description: '内联代码元素。渲染带等宽字体和低调背景的 <code>。如需围栏代码块,请使用 XDSCodeBlock。',+ propDescriptions: {+ children: '代码内容。',+ xstyle: 'StyleX 布局自定义样式。必须是 stylex.create() 的值。',+ className: '根元素的 CSS 类名。优先使用 xstyle。',+ style: '内联样式。优先使用 xstyle。',+ 'data-testid': '自动化测试框架的测试选择器。',+ },+ },+ ],+};++/** @type {import('../docs-types').TranslationDoc} */+export const docsDense = {+ description: 'syntax-highlighted code block via CSS Custom Highlight API (0-DOM overhead); span-based fallback; XDSCode for inline code in prose',+ features: [+ 'CSS Custom Highlight API: 0-DOM-overhead syntax coloring; span fallback',+ 'line numbers: optional gutter via hasLineNumbers',+ 'line highlighting: 1-indexed via highlightLines',+ 'copy button: built-in w/ onCopy callback',+ 'header: optional title + language label',+ 'sizes: sm/md',+ 'wrapping: isWrapped toggles wrap vs h-scroll',+ 'languages: TS/JS/CSS/HTML/JSON/plaintext',+ 'XDSCode: inline code element w/ monospace styling for prose',+ ],+ accessibility: [+ '<pre>+<code> for correct semantic markup',+ 'copy button: a11y label + aria-live announces copy success',+ 'line numbers: aria-hidden',+ 'title/language: visible text in header',+ ],+ notes: [+ 'CSS.highlights API when available; auto-fallback to span rendering',+ 'tokenization async -- highlights applied on next paint',+ 'SYNC_TOKENIZE_THRESHOLD: short code tokenized sync to avoid flash',+ 'custom tokenizer: pass {type,start,end}[] for unsupported languages',+ 'xds-token-{type} CSS classes for custom syntax theme overrides',+ ],+ components: [+ {+ name: 'XDSCodeBlock',+ description: 'fenced code block w/ syntax highlighting; for multi-line snippets',+ propDescriptions: {+ code: 'code string to display',+ language: 'highlight language; "plaintext" disables',+ title: 'filename/label in header bar',+ hasLanguageLabel: 'show language name in header; hidden for "plaintext"',+ hasLineNumbers: 'show line number gutter',+ highlightLines: '1-indexed lines to highlight',+ hasCopyButton: 'show copy button',+ onCopy: 'callback after copy',+ isWrapped: 'wrap long lines vs h-scroll',+ maxHeight: 'max height before vertical scroll',+ size: 'text size variant',+ tokenizer: 'custom tokenizer for unsupported languages',+ xstyle: 'StyleX layout styles; must be stylex.create() value',+ className: 'CSS class for root; prefer xstyle',+ style: 'inline styles; prefer xstyle',+ 'data-testid': 'test selector',+ },+ },+ {+ name: 'XDSCode',+ description: 'inline code element; styled <code> w/ monospace+muted bg; for prose',+ propDescriptions: {+ children: 'code content',+ xstyle: 'StyleX layout styles; must be stylex.create() value',+ className: 'CSS class for root; prefer xstyle',+ style: 'inline styles; prefer xstyle',+ 'data-testid': 'test selector',+ },+ },+ ],+};diff --git a/packages/core/src/CodeBlock/XDSCodeBlock.tsx b/packages/core/src/CodeBlock/XDSCodeBlock.tsxindex 99ef2b1a54..d4dd08c7b5 100644--- a/packages/core/src/CodeBlock/XDSCodeBlock.tsx+++ b/packages/core/src/CodeBlock/XDSCodeBlock.tsx@@ -273,7 +273,7 @@ function buildSpanLine(* `highlightMode="spans"` is explicitly set.** @example- * ```tsx+ * ```* <XDSCodeBlock* code={`const x = 42;`}* language="typescript"diff --git a/packages/core/src/CommandPalette/XDSCommandPalette.doc.mjs b/packages/core/src/CommandPalette/XDSCommandPalette.doc.mjsnew file mode 100644index 0000000000..e6b2ba06e6--- /dev/null+++ b/packages/core/src/CommandPalette/XDSCommandPalette.doc.mjs@@ -0,0 +1,649 @@+/** @type {import('../docs-types').ComponentDoc} */+export const docs = {+ name: 'CommandPalette',+ description:+ 'A searchSource-driven command palette dialog. Provide a search source and get filtering, keyboard navigation, grouping, and selection. Uses the same XDSSearchSource interface as XDSTypeahead.',+ keywords: [+ 'command',+ 'spotlight',+ 'launcher',+ 'omnibox',+ 'quicksearch',+ 'palette',+ 'finder',+ 'search',+ 'modal',+ 'dialog',+ 'navigation',+ ],+ features: [+ 'searchSource: same XDSSearchSource interface as XDSTypeahead — static, async, or hybrid',+ 'Auto-grouping: items with auxiliaryData.group are auto-grouped in default rendering',+ 'createStaticSource: utility for static lists with optional keyword matching',+ 'Async support: spinner shows in input while search resolves',+ 'Keyboard navigation: arrow keys, Enter to select, Escape to close',+ 'Picker mode: value/onValueChange for persistent selection',+ 'Composable: XDSCommandPaletteInput, XDSCommandPaletteList, XDSCommandPaletteGroup, XDSCommandPaletteItem, XDSCommandPaletteFooter, XDSCommandPaletteEmpty',+ 'renderItem: custom per-item render while preserving auto-grouping',+ ],+ components: [+ {+ name: 'XDSCommandPalette',+ description:+ 'Root component. Manages open state, search, keyboard navigation, and composition slots.',+ props: [+ {+ name: 'isOpen',+ type: 'boolean',+ description: 'Whether the command palette dialog is visible.',+ required: true,+ },+ {+ name: 'onOpenChange',+ type: '(isOpen: boolean) => void',+ description: 'Called when the palette visibility changes.',+ required: true,+ },+ {+ name: 'searchSource',+ type: 'XDSSearchSource<T>',+ description:+ 'Search source providing items via search(query) and bootstrap(). Use createStaticSource for static lists.',+ required: true,+ },+ {+ name: 'input',+ type: 'ReactNode',+ description:+ 'Input slot. Defaults to XDSCommandPaletteInput with standard behavior.',+ default: '<XDSCommandPaletteInput />',+ },+ {+ name: 'footer',+ type: 'ReactNode',+ description:+ 'Footer slot. Defaults to XDSCommandPaletteFooter showing keyboard hints.',+ default: '<XDSCommandPaletteFooter />',+ },+ {+ name: 'renderItem',+ type: '(item: T, isSelected: boolean) => ReactNode',+ description:+ 'Per-item render function. Auto-grouping by auxiliaryData.group is preserved. When omitted, renders label text.',+ },+ {+ name: 'emptySearchText',+ type: 'ReactNode',+ description: 'Content shown when a search query returns no results.',+ default: "'No results'",+ },+ {+ name: 'emptyBootstrapText',+ type: 'ReactNode',+ description:+ 'Content shown when there is no search query and bootstrap() returns nothing.',+ default: "'Type to search'",+ },+ {+ name: 'value',+ type: 'string',+ description: 'Controlled selected value for picker mode.',+ },+ {+ name: 'onValueChange',+ type: '(value: string) => void',+ description: 'Called when the selected value changes in picker mode.',+ },+ {+ name: 'label',+ type: 'string',+ description: 'Accessible label for the command palette dialog.',+ default: "'Command palette'",+ },+ {+ name: 'width',+ type: 'number | string',+ description: 'Width of the dialog.',+ default: '640',+ },+ {+ name: 'maxHeight',+ type: 'number | string',+ description: 'Maximum height of the dialog.',+ default: '480',+ },+ ],+ examples: [+ {+ label: 'Static source',+ code: `const source = createStaticSource([+ {id: 'home', label: 'Home'},+ {id: 'settings', label: 'Settings'},+]);++<XDSCommandPalette+ isOpen={isOpen}+ onOpenChange={setIsOpen}+ searchSource={source}+/>`,+ },+ ],+ },+ {+ name: 'XDSCommandPaletteInput',+ description:+ 'Search input slot. Auto-focuses on mount. Wires to command palette context when used inside XDSCommandPalette.',+ props: [+ {+ name: 'placeholder',+ type: 'string',+ description: 'Placeholder text for the input.',+ default: "'Search...'",+ },+ {+ name: 'hasAutoFocus',+ type: 'boolean',+ description: 'Auto-focus the input when mounted.',+ default: 'true',+ },+ {+ name: 'endContent',+ type: 'ReactNode',+ description:+ 'Content rendered at the trailing end of the input, after the spinner. Use for clear buttons or keyboard shortcut hints.',+ },+ {+ name: 'value',+ type: 'string',+ description:+ 'Search value. When omitted inside XDSCommandPalette, reads from context.',+ },+ {+ name: 'onValueChange',+ type: '(value: string) => void',+ description:+ 'Called when search value changes. When omitted inside XDSCommandPalette, writes to context.',+ },+ {+ name: 'xstyle',+ type: 'StyleXStyles',+ description:+ 'StyleX styles for layout customization. Must be a stylex.create() value.',+ },+ ],+ examples: [+ {+ label: 'Custom placeholder',+ code: `<XDSCommandPalette isOpen={isOpen} onOpenChange={setIsOpen} searchSource={source}+ input={<XDSCommandPaletteInput placeholder="Search commands..." />}+/>`,+ },+ ],+ },+ {+ name: 'XDSCommandPaletteList',+ description:+ 'Scrollable results container. Renders as a listbox for ARIA. Contains XDSCommandPaletteItem and XDSCommandPaletteGroup children.',+ props: [+ {+ name: 'children',+ type: 'ReactNode',+ description: 'Items, groups, and empty states.',+ required: true,+ },+ {+ name: 'label',+ type: 'string',+ description: 'Accessible label for the listbox.',+ default: "'Commands'",+ },+ {+ name: 'xstyle',+ type: 'StyleXStyles',+ description:+ 'StyleX styles for layout customization. Must be a stylex.create() value.',+ },+ ],+ examples: [+ {+ label: 'Basic',+ code: `<XDSCommandPaletteList>+ <XDSCommandPaletteItem value="home" onSelect={goHome}>+ Go Home+ </XDSCommandPaletteItem>+</XDSCommandPaletteList>`,+ },+ ],+ },+ {+ name: 'XDSCommandPaletteItem',+ description:+ 'A selectable item. Accepts arbitrary children for full rendering control. Registers with context for keyboard navigation when inside XDSCommandPalette.',+ props: [+ {+ name: 'value',+ type: 'string',+ description: 'Unique value for identification and selection.',+ required: true,+ },+ {+ name: 'children',+ type: 'ReactNode',+ description:+ 'Item content — render icons, descriptions, keyboard shortcuts, etc.',+ required: true,+ },+ {+ name: 'onSelect',+ type: '(value: string) => void',+ description: 'Called when this item is selected via click or Enter.',+ },+ {+ name: 'isHighlighted',+ type: 'boolean',+ description:+ 'Whether this item has keyboard focus. Derived from context when inside XDSCommandPalette.',+ default: 'false',+ },+ {+ name: 'isSelected',+ type: 'boolean',+ description: 'Whether this item is selected in picker mode.',+ default: 'false',+ },+ {+ name: 'isDisabled',+ type: 'boolean',+ description: 'Whether the item is non-interactive.',+ default: 'false',+ },+ {+ name: 'xstyle',+ type: 'StyleXStyles',+ description:+ 'StyleX styles for layout customization. Must be a stylex.create() value.',+ },+ ],+ examples: [+ {+ label: 'With icon and shortcut',+ code: `<XDSCommandPaletteItem value="settings" onSelect={() => navigate('/settings')}>+ <XDSIcon name="settings" size="sm" />+ Settings+ <XDSKbd keys={['⌘', ',']} />+</XDSCommandPaletteItem>`,+ },+ ],+ },+ {+ name: 'XDSCommandPaletteGroup',+ description: 'Visual grouping with a heading label. Place inside XDSCommandPaletteList.',+ props: [+ {+ name: 'heading',+ type: 'string',+ description: 'Group heading text.',+ required: true,+ },+ {+ name: 'children',+ type: 'ReactNode',+ description: 'XDSCommandPaletteItem children.',+ required: true,+ },+ {+ name: 'xstyle',+ type: 'StyleXStyles',+ description:+ 'StyleX styles for layout customization. Must be a stylex.create() value.',+ },+ ],+ examples: [+ {+ label: 'Basic',+ code: `<XDSCommandPaletteGroup heading="Navigation">+ <XDSCommandPaletteItem value="home" onSelect={goHome}>Home</XDSCommandPaletteItem>+ <XDSCommandPaletteItem value="settings" onSelect={goSettings}>Settings</XDSCommandPaletteItem>+</XDSCommandPaletteGroup>`,+ },+ ],+ },+ {+ name: 'XDSCommandPaletteFooter',+ description:+ 'Footer showing keyboard navigation hints. Renders default arrow/Enter/Escape hints when no children are provided.',+ props: [+ {+ name: 'children',+ type: 'ReactNode',+ description:+ 'Custom footer content. When omitted, renders default keyboard hints via XDSKbd.',+ },+ {+ name: 'xstyle',+ type: 'StyleXStyles',+ description:+ 'StyleX styles for layout customization. Must be a stylex.create() value.',+ },+ ],+ examples: [+ {+ label: 'Default hints',+ code: `<XDSCommandPalette isOpen={isOpen} onOpenChange={setIsOpen} searchSource={source}+ footer={<XDSCommandPaletteFooter />}+/>`,+ },+ ],+ },+ {+ name: 'XDSCommandPaletteEmpty',+ description:+ 'Empty state display for the results area. Rendered automatically by XDSCommandPalette for no-results and no-query states.',+ props: [+ {+ name: 'children',+ type: 'ReactNode',+ description: 'Message or content to display.',+ required: true,+ },+ ],+ examples: [+ {+ label: 'Custom empty state',+ code: `<XDSCommandPalette+ isOpen={isOpen}+ onOpenChange={setIsOpen}+ searchSource={source}+ emptySearchText={+ <XDSCommandPaletteEmpty>No commands found</XDSCommandPaletteEmpty>+ }+/>`,+ },+ ],+ },+ ],+ examples: [+ {+ label: 'Static source with createStaticSource',+ code: `const source = createStaticSource([+ {id: 'home', label: 'Home'},+ {id: 'settings', label: 'Settings'},+ {id: 'logout', label: 'Sign out'},+]);++function MyCommandPalette() {+ const [isOpen, setIsOpen] = useState(false);+ return (+ <XDSCommandPalette+ isOpen={isOpen}+ onOpenChange={setIsOpen}+ searchSource={source}+ />+ );+}`,+ },+ {+ label: 'Grouped items with renderItem',+ code: `<XDSCommandPalette+ isOpen={isOpen}+ onOpenChange={setIsOpen}+ searchSource={source}+ renderItem={(item) => (+ <>+ <XDSIcon name={item.auxiliaryData.icon} size="sm" />+ {item.label}+ </>+ )}+/>`,+ },+ ],+ theming: {+ targets: [+ {className: 'xds-command-palette-footer'},+ {className: 'xds-command-palette-group'},+ {className: 'xds-command-palette-input'},+ {className: 'xds-command-palette-item'},+ {className: 'xds-command-palette-list'},+ ],+ },+ accessibility: [+ 'Dialog uses XDSDialog — native <dialog> with showModal() for correct modal ARIA semantics.',+ 'Input renders as a search input with combobox role, aria-expanded, and aria-controls pointing to the list.',+ 'List renders as role="listbox" with aria-label.',+ 'Items render as role="option" with aria-selected.',+ 'Keyboard navigation uses useCombobox from XDSSelector for consistent arrow key, Home/End, Enter, and Escape behavior.',+ 'Spinner in input uses role="status" to announce loading to screen readers.',+ ],+ keyboard:+ 'Arrow Up/Down: navigate items; Enter: select highlighted item; Escape: close palette; Tab: moves focus to footer actions',+ notes: [+ 'Uses XDSSearchSource interface — the same as XDSTypeahead. Any source compatible with XDSTypeahead works here.',+ 'createStaticSource supports keyword-based matching in addition to substring matching.',+ 'Auto-grouping reads auxiliaryData.group from each item — no extra config needed.',+ 'Picker mode (value/onValueChange) keeps the palette open and tracks a persistent selection.',+ 'The isBusy signal from searchSource drives the spinner in XDSCommandPaletteInput automatically.',+ ],+};++/** @type {import('../docs-types').TranslationDoc} */+export const docsZh = {+ description:+ '由 searchSource 驱动的命令面板对话框。提供搜索源,即可获得过滤、键盘导航、分组和选择功能。与 XDSTypeahead 使用相同的 XDSSearchSource 接口。',+ features: [+ 'searchSource:与 XDSTypeahead 相同的 XDSSearchSource 接口——静态、异步或混合',+ '自动分组:auxiliaryData.group 中的项目在默认渲染中自动分组',+ 'createStaticSource:用于静态列表的工具函数,支持关键词匹配',+ '异步支持:搜索解析时在输入框中显示加载指示器',+ '键盘导航:方向键、Enter 选择、Escape 关闭',+ '选择器模式:通过 value/onValueChange 实现持久选择',+ '可组合:XDSCommandPaletteInput、XDSCommandPaletteList、XDSCommandPaletteGroup 等子组件',+ 'renderItem:自定义每个条目的渲染,同时保留自动分组',+ ],+ accessibility: [+ '对话框使用 XDSDialog——原生 <dialog> 配合 showModal() 实现正确的模态 ARIA 语义。',+ '输入框渲染为搜索输入,具有 combobox 角色、aria-expanded 和指向列表的 aria-controls。',+ '列表渲染为 role="listbox",带有 aria-label。',+ '条目渲染为 role="option",带有 aria-selected。',+ '键盘导航使用 XDSSelector 的 useCombobox,确保方向键、Home/End、Enter 和 Escape 行为一致。',+ '输入框中的加载指示器使用 role="status" 向屏幕阅读器播报加载状态。',+ ],+ keyboard:+ '上下方向键:导航条目;Enter:选择高亮条目;Escape:关闭面板;Tab:移动焦点到页脚操作',+ notes: [+ '使用 XDSSearchSource 接口——与 XDSTypeahead 相同。任何与 XDSTypeahead 兼容的源都可以在此使用。',+ 'createStaticSource 除子字符串匹配外还支持关键词匹配。',+ '自动分组读取每个条目的 auxiliaryData.group——无需额外配置。',+ '选择器模式(value/onValueChange)保持面板打开并跟踪持久选择。',+ '来自 searchSource 的 isBusy 信号自动驱动 XDSCommandPaletteInput 中的加载指示器。',+ ],+ components: [+ {+ name: 'XDSCommandPalette',+ description: '根组件。管理打开状态、搜索、键盘导航和组合插槽。',+ propDescriptions: {+ isOpen: '命令面板对话框是否可见。',+ onOpenChange: '面板可见性变化时调用。',+ searchSource: '通过 search(query) 和 bootstrap() 提供条目的搜索源。',+ input: '输入插槽。默认为 XDSCommandPaletteInput。',+ footer: '页脚插槽。默认为 XDSCommandPaletteFooter 显示键盘提示。',+ renderItem: '每个条目的渲染函数。保留 auxiliaryData.group 自动分组。',+ emptySearchText: '搜索查询无结果时显示的内容。',+ emptyBootstrapText: '无搜索词且 bootstrap() 返回空时显示的内容。',+ value: '选择器模式下的受控选中值。',+ onValueChange: '选择器模式下选中值变化时调用。',+ label: '命令面板对话框的无障碍标签。',+ width: '对话框宽度。',+ maxHeight: '对话框最大高度。',+ },+ },+ {+ name: 'XDSCommandPaletteInput',+ description: '搜索输入插槽。挂载时自动聚焦。在 XDSCommandPalette 内使用时连接到上下文。',+ propDescriptions: {+ placeholder: '输入框的占位文本。',+ hasAutoFocus: '挂载时自动聚焦输入框。',+ endContent: '渲染在输入框末尾的内容,位于加载指示器之后。',+ value: '搜索值。在 XDSCommandPalette 内省略时从上下文读取。',+ onValueChange: '搜索值变化时调用。在 XDSCommandPalette 内省略时写入上下文。',+ xstyle: 'StyleX 布局自定义样式。必须是 stylex.create() 的值。',+ },+ },+ {+ name: 'XDSCommandPaletteList',+ description: '可滚动的结果容器。作为 listbox 渲染以符合 ARIA 规范。',+ propDescriptions: {+ children: '条目、分组和空状态。',+ label: 'listbox 的无障碍标签。',+ xstyle: 'StyleX 布局自定义样式。必须是 stylex.create() 的值。',+ },+ },+ {+ name: 'XDSCommandPaletteItem',+ description: '可选择的条目。接受任意子元素以实现完整的渲染控制。',+ propDescriptions: {+ value: '用于标识和选择的唯一值。',+ children: '条目内容——渲染图标、描述、键盘快捷键等。',+ onSelect: '通过点击或 Enter 选择此条目时调用。',+ isHighlighted: '此条目是否具有键盘焦点。在 XDSCommandPalette 内从上下文派生。',+ isSelected: '此条目在选择器模式下是否被选中。',+ isDisabled: '条目是否为非交互状态。',+ xstyle: 'StyleX 布局自定义样式。必须是 stylex.create() 的值。',+ },+ },+ {+ name: 'XDSCommandPaletteGroup',+ description: '带标题标签的视觉分组。放置在 XDSCommandPaletteList 内。',+ propDescriptions: {+ heading: '分组标题文本。',+ children: 'XDSCommandPaletteItem 子元素。',+ xstyle: 'StyleX 布局自定义样式。必须是 stylex.create() 的值。',+ },+ },+ {+ name: 'XDSCommandPaletteFooter',+ description: '显示键盘导航提示的页脚。未提供子元素时渲染默认方向键/Enter/Escape 提示。',+ propDescriptions: {+ children: '自定义页脚内容。省略时通过 XDSKbd 渲染默认键盘提示。',+ xstyle: 'StyleX 布局自定义样式。必须是 stylex.create() 的值。',+ },+ },+ {+ name: 'XDSCommandPaletteEmpty',+ description: '结果区域的空状态展示。由 XDSCommandPalette 在无结果和无查询状态下自动渲染。',+ propDescriptions: {+ children: '要显示的消息或内容。',+ },+ },+ ],+};++/** @type {import('../docs-types').TranslationDoc} */+export const docsDense = {+ description:+ 'searchSource-driven command palette dialog; filtering, keyboard nav, grouping, selection; same XDSSearchSource interface as XDSTypeahead',+ features: [+ 'searchSource: same interface as XDSTypeahead — static/async/hybrid',+ 'auto-grouping: auxiliaryData.group auto-groups items',+ 'createStaticSource: util for static lists w/ keyword matching',+ 'async: spinner in input while search resolves',+ 'keyboard: arrow keys, Enter=select, Escape=close',+ 'picker mode: value/onValueChange for persistent selection',+ 'composable: Input, List, Group, Item, Footer, Empty sub-components',+ 'renderItem: custom per-item render w/ auto-grouping preserved',+ ],+ accessibility: [+ 'dialog uses XDSDialog native <dialog> w/ showModal() for modal ARIA semantics',+ 'input: combobox role, aria-expanded, aria-controls to list',+ 'list: role="listbox" w/ aria-label',+ 'items: role="option" w/ aria-selected',+ 'keyboard nav via useCombobox from XDSSelector',+ 'spinner: role="status" announces loading',+ ],+ keyboard: 'Arrow Up/Down=navigate; Enter=select; Escape=close; Tab=footer actions',+ notes: [+ 'XDSSearchSource interface — same as XDSTypeahead; any compatible source works',+ 'createStaticSource: keyword matching + substring matching',+ 'auto-grouping reads auxiliaryData.group — no extra config',+ 'picker mode keeps palette open, tracks persistent selection',+ 'isBusy from searchSource drives spinner automatically',+ ],+ components: [+ {+ name: 'XDSCommandPalette',+ description: 'root; manages open state, search, keyboard nav, composition slots',+ propDescriptions: {+ isOpen: 'dialog visible',+ onOpenChange: 'called on visibility change',+ searchSource: 'provides items via search(query)+bootstrap()',+ input: 'input slot; default=XDSCommandPaletteInput',+ footer: 'footer slot; default=XDSCommandPaletteFooter w/ kbd hints',+ renderItem: 'per-item render fn; auto-grouping preserved',+ emptySearchText: 'shown when query returns no results',+ emptyBootstrapText: 'shown when no query+bootstrap() empty',+ value: 'controlled selected value for picker mode',+ onValueChange: 'called on selected value change',+ label: 'a11y label for dialog',+ width: 'dialog width',+ maxHeight: 'dialog max height',+ },+ },+ {+ name: 'XDSCommandPaletteInput',+ description: 'search input; auto-focus on mount; wires to context inside XDSCommandPalette',+ propDescriptions: {+ placeholder: 'input placeholder text',+ hasAutoFocus: 'auto-focus on mount',+ endContent: 'trailing content after spinner',+ value: 'search value; reads context when omitted inside palette',+ onValueChange: 'called on change; writes context when omitted inside palette',+ xstyle: 'StyleX layout styles; must be stylex.create() value',+ },+ },+ {+ name: 'XDSCommandPaletteList',+ description: 'scrollable results container; role=listbox',+ propDescriptions: {+ children: 'items, groups, empty states',+ label: 'a11y label for listbox',+ xstyle: 'StyleX layout styles; must be stylex.create() value',+ },+ },+ {+ name: 'XDSCommandPaletteItem',+ description: 'selectable item; arbitrary children; registers w/ context for kbd nav',+ propDescriptions: {+ value: 'unique id for selection',+ children: 'item content — icons, descriptions, shortcuts',+ onSelect: 'called on click or Enter',+ isHighlighted: 'keyboard focus; derived from context inside palette',+ isSelected: 'selected in picker mode',+ isDisabled: 'non-interactive',+ xstyle: 'StyleX layout styles; must be stylex.create() value',+ },+ },+ {+ name: 'XDSCommandPaletteGroup',+ description: 'group w/ heading label; inside XDSCommandPaletteList',+ propDescriptions: {+ heading: 'group heading text',+ children: 'XDSCommandPaletteItem children',+ xstyle: 'StyleX layout styles; must be stylex.create() value',+ },+ },+ {+ name: 'XDSCommandPaletteFooter',+ description: 'footer w/ kbd hints; default=arrow/Enter/Escape hints via XDSKbd',+ propDescriptions: {+ children: 'custom content; default renders kbd hints',+ xstyle: 'StyleX layout styles; must be stylex.create() value',+ },+ },+ {+ name: 'XDSCommandPaletteEmpty',+ description: 'empty state; auto-rendered by palette for no-results+no-query states',+ propDescriptions: {+ children: 'message or content to display',+ },+ },+ ],+};diff --git a/packages/core/src/CommandPalette/XDSCommandPalette.tsx b/packages/core/src/CommandPalette/XDSCommandPalette.tsxindex aecf96a244..778b9e7cb3 100644--- a/packages/core/src/CommandPalette/XDSCommandPalette.tsx+++ b/packages/core/src/CommandPalette/XDSCommandPalette.tsx@@ -238,26 +238,12 @@ function ItemRenderer<T extends XDSSearchableItem>({* - `renderItem(item, isSelected)`: custom per-item content (grouping preserved)** @example- * ```tsx- * // Simplest — zero config beyond open state and source+ * ```* <XDSCommandPalette* isOpen={isOpen}* onOpenChange={setIsOpen}* searchSource={createStaticSource(commands)}* />- *- * // Custom item rendering (grouping still automatic)- * <XDSCommandPalette- * isOpen={isOpen}- * onOpenChange={setIsOpen}- * searchSource={source}- * renderItem={(item, isSelected) => (- * <>- * <XDSIcon icon={item.auxiliaryData.icon} size="sm" />- * {item.label}- * </>- * )}- * />* ```*/export function XDSCommandPalette<