Skip to content

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

TypeScript

fix(cli): read component groups from doc files instead of hardcoded map (#1650)

Cindy Zhang43455a2eb65b
diff --git a/packages/cli/src/commands/component.test.mjs b/packages/cli/src/commands/component.test.mjs
index c1ec098ff8..a5b2f5a9f9 100644
--- a/packages/cli/src/commands/component.test.mjs
+++ b/packages/cli/src/commands/component.test.mjs
@@ -23,37 +23,59 @@ afterEach(() => {
});
describe('discoverComponents', () => {
- it('groups XDS*.tsx files by category', () => {
+ it('reads group from .doc.mjs and groups components', () => {
const srcDir = path.join(tmpDir, 'src');
- // Create Button dir with XDSButton.tsx
+
+ // Button with group: 'Buttons'
const buttonDir = path.join(srcDir, 'Button');
fs.mkdirSync(buttonDir, {recursive: true});
fs.writeFileSync(path.join(buttonDir, 'XDSButton.tsx'), '');
+ fs.writeFileSync(path.join(buttonDir, 'Button.doc.mjs'), "export const docs = {\n name: 'Button',\n group: 'Buttons',\n};");
+
+ // IconButton with group: 'Buttons'
+ const iconBtnDir = path.join(srcDir, 'IconButton');
+ fs.mkdirSync(iconBtnDir, {recursive: true});
+ fs.writeFileSync(path.join(iconBtnDir, 'XDSIconButton.tsx'), '');
+ fs.writeFileSync(path.join(iconBtnDir, 'IconButton.doc.mjs'), "export const docs = {\n name: 'IconButton',\n group: 'Buttons',\n};");
- // Create Avatar dir with XDSAvatar.tsx
+ // Avatar with no group
const avatarDir = path.join(srcDir, 'Avatar');
fs.mkdirSync(avatarDir, {recursive: true});
fs.writeFileSync(path.join(avatarDir, 'XDSAvatar.tsx'), '');
- // Create Grid dir with XDSGrid.tsx
- const gridDir = path.join(srcDir, 'Grid');
- fs.mkdirSync(gridDir, {recursive: true});
- fs.writeFileSync(path.join(gridDir, 'XDSGrid.tsx'), '');
-
- // Skip dirs
- const themeDir = path.join(srcDir, 'theme');
- fs.mkdirSync(themeDir, {recursive: true});
- fs.writeFileSync(path.join(themeDir, 'XDSTheme.tsx'), '');
-
const result = discoverComponents(tmpDir);
expect(result).toEqual({
- Layout: ['Grid'],
- Display: ['Avatar'],
- Action: ['Button'],
+ Avatar: ['Avatar'],
+ Buttons: ['Button', 'IconButton'],
});
});
+ it('sorts groups and ungrouped components alphabetically', () => {
+ const srcDir = path.join(tmpDir, 'src');
+
+ // Zebra (ungrouped)
+ const zebraDir = path.join(srcDir, 'Zebra');
+ fs.mkdirSync(zebraDir, {recursive: true});
+ fs.writeFileSync(path.join(zebraDir, 'XDSZebra.tsx'), '');
+
+ // Alpha (ungrouped)
+ const alphaDir = path.join(srcDir, 'Alpha');
+ fs.mkdirSync(alphaDir, {recursive: true});
+ fs.writeFileSync(path.join(alphaDir, 'XDSAlpha.tsx'), '');
+
+ // Middle in group 'Inputs'
+ const middleDir = path.join(srcDir, 'Middle');
+ fs.mkdirSync(middleDir, {recursive: true});
+ fs.writeFileSync(path.join(middleDir, 'XDSMiddle.tsx'), '');
+ fs.writeFileSync(path.join(middleDir, 'Middle.doc.mjs'), "export const docs = {\n name: 'Middle',\n group: 'Inputs',\n};");
+
+ const result = discoverComponents(tmpDir);
+ const keys = Object.keys(result);
+
+ expect(keys).toEqual(['Alpha', 'Inputs', 'Zebra']);
+ });
+
it('skips test files', () => {
const srcDir = path.join(tmpDir, 'src');
const buttonDir = path.join(srcDir, 'Button');
@@ -62,17 +84,31 @@ describe('discoverComponents', () => {
fs.writeFileSync(path.join(buttonDir, 'XDSButton.test.tsx'), '');
const result = discoverComponents(tmpDir);
- expect(result).toEqual({Action: ['Button']});
+ expect(result).toEqual({Button: ['Button']});
});
- it('puts unknown directories under Other', () => {
+ it('ungrouped components without .doc.mjs appear as standalone entries', () => {
const srcDir = path.join(tmpDir, 'src');
const customDir = path.join(srcDir, 'CustomWidget');
fs.mkdirSync(customDir, {recursive: true});
fs.writeFileSync(path.join(customDir, 'XDSCustomWidget.tsx'), '');
const result = discoverComponents(tmpDir);
- expect(result).toEqual({Other: ['CustomWidget']});
+ expect(result).toEqual({CustomWidget: ['CustomWidget']});
+ });
+
+ it('skips hooks/utils directories', () => {
+ const srcDir = path.join(tmpDir, 'src');
+ const hooksDir = path.join(srcDir, 'hooks');
+ fs.mkdirSync(hooksDir, {recursive: true});
+ fs.writeFileSync(path.join(hooksDir, 'XDSHook.tsx'), '');
+
+ const utilsDir = path.join(srcDir, 'utils');
+ fs.mkdirSync(utilsDir, {recursive: true});
+ fs.writeFileSync(path.join(utilsDir, 'XDSUtil.tsx'), '');
+
+ const result = discoverComponents(tmpDir);
+ expect(result).toEqual({});
});
});
diff --git a/packages/cli/src/commands/component/index.mjs b/packages/cli/src/commands/component/index.mjs
index c57944eebb..627358c31d 100644
--- a/packages/cli/src/commands/component/index.mjs
+++ b/packages/cli/src/commands/component/index.mjs
@@ -89,11 +89,16 @@ export function registerComponent(program) {
console.log('');
} else {
console.log('');
- for (const [cat, comps] of Object.entries(result.data)) {
- console.log(`${cat}:`);
- for (const comp of comps) console.log(` ${comp}`);
- console.log('');
+ for (const [key, comps] of Object.entries(result.data)) {
+ const isUngrouped = comps.length === 1 && comps[0] === key;
+ if (isUngrouped) {
+ console.log(key);
+ } else {
+ console.log(key);
+ for (const comp of comps) console.log(` ${comp}`);
+ }
}
+ console.log('');
console.log(`Usage: ${run} xds component <name>`);
console.log('');
}
diff --git a/packages/cli/src/lib/component-discovery.mjs b/packages/cli/src/lib/component-discovery.mjs
index 6c5504b94d..ec56da0d60 100644
--- a/packages/cli/src/lib/component-discovery.mjs
+++ b/packages/cli/src/lib/component-discovery.mjs
@@ -5,58 +5,52 @@
import * as fs from 'node:fs';
import * as path from 'node:path';
-const DIR_TO_CATEGORY = {
- // Layout
- AspectRatio: 'Layout',
- Center: 'Layout',
- CollapsibleGroup: 'Layout',
- Grid: 'Layout',
- Layout: 'Layout',
- Stack: 'Layout',
- // Display
- Avatar: 'Display',
- Badge: 'Display',
- Divider: 'Display',
- Icon: 'Display',
- Skeleton: 'Display',
- Table: 'Display',
- Text: 'Display',
- // Form
- CheckboxInput: 'Form',
- DateInput: 'Form',
- Field: 'Form',
- NumberInput: 'Form',
- RadioList: 'Form',
- Selector: 'Form',
- Slider: 'Form',
- Switch: 'Form',
- TextArea: 'Form',
- TextInput: 'Form',
- TimeInput: 'Form',
- // Action
- Button: 'Action',
- CloseButton: 'Action',
- DropdownMenu: 'Action',
- Link: 'Action',
- // Navigation
- TabList: 'Navigation',
- TopNav: 'Navigation',
- // Overlay
- Calendar: 'Overlay',
- Dialog: 'Overlay',
- Layer: 'Overlay',
-};
-
-const CATEGORY_ORDER = ['Layout', 'Display', 'Form', 'Action', 'Navigation', 'Overlay'];
-const SKIP_DIRS = new Set(['theme', 'hooks', 'utils', '__tests__', 'node_modules']);
+const SKIP_DIRS = new Set(['hooks', 'utils', '__tests__', 'node_modules']);
+
+// Matches the top-level `group: 'GroupName'` field in a .doc.mjs file.
+// Only matches at shallow indentation (≤ 4 spaces from line start) to avoid
+// picking up nested `group:` fields inside prop descriptions.
+const GROUP_RE = /(?:^|\n) {0,4}group:\s*['"]([^'"]+)['"]/;
+const INTERNAL_COMPONENTS_RE = /(?:^|\n) {0,4}internalComponents:\s*\[([^\]]*)\]/;
+
+/**
+ * Read the `group` and `internalComponents` fields from a
+ * component's .doc.mjs file (synchronous).
+ */
+function readDocMeta(docPath) {
+ try {
+ const content = fs.readFileSync(docPath, 'utf-8');
+ const groupMatch = GROUP_RE.exec(content);
+ const internalCompsMatch = INTERNAL_COMPONENTS_RE.exec(content);
+ const hiddenSet = new Set();
+ if (internalCompsMatch) {
+ for (const m of internalCompsMatch[1].matchAll(/['"]([^'"]+)['"]/g)) {
+ hiddenSet.add(m[1]);
+ }
+ }
+ return {
+ group: groupMatch ? groupMatch[1] : null,
+ internalComponents: hiddenSet,
+ };
+ } catch {
+ return {group: null, internalComponents: new Set()};
+ }
+}
/**
* Auto-discover components by scanning for XDS*.tsx files in core/src/.
- * Groups them by category using the DIR_TO_CATEGORY mapping.
+ *
+ * Returns an ordered Record where:
+ * - Grouped components use the group name as key: `'Buttons': ['Button', 'IconButton']`
+ * - Ungrouped components use their own name as key: `'Avatar': ['Avatar']`
+ *
+ * Keys are sorted alphabetically (groups and ungrouped components interleaved).
+ * Components within each group are also sorted alphabetically.
*/
export function discoverComponents(coreDir) {
const srcDir = path.join(coreDir, 'src');
- const categories = {};
+ /** @type {Map<string, string|null>} componentName → group */
+ const componentGroups = new Map();
function collectXDSFiles(dirPath) {
const results = [];
@@ -80,31 +74,75 @@ export function discoverComponents(coreDir) {
for (const entry of topEntries) {
if (!entry.isDirectory() || SKIP_DIRS.has(entry.name)) continue;
- const category = DIR_TO_CATEGORY[entry.name] || 'Other';
- const xdsFiles = collectXDSFiles(path.join(srcDir, entry.name));
+ const dirPath = path.join(srcDir, entry.name);
+ const xdsFiles = collectXDSFiles(dirPath);
+
+ // Read the group from the directory's .doc.mjs file (if it exists)
+ // Check both {Name}.doc.mjs and XDS{Name}.doc.mjs naming conventions
+ let docFile = path.join(dirPath, `${entry.name}.doc.mjs`);
+ if (!fs.existsSync(docFile)) {
+ docFile = path.join(dirPath, `XDS${entry.name}.doc.mjs`);
+ }
+ const {group, internalComponents} = fs.existsSync(docFile)
+ ? readDocMeta(docFile)
+ : {group: null, internalComponents: new Set()};
for (const fileName of xdsFiles) {
const componentName = fileName.replace(/^XDS/, '').replace(/\.tsx$/, '');
- if (!categories[category]) categories[category] = [];
- if (!categories[category].includes(componentName)) {
- categories[category].push(componentName);
+ if (internalComponents.has(componentName)) continue;
+
+ // Check for a per-component doc file that overrides the directory group
+ let compGroup = group;
+ let compDoc = path.join(dirPath, `${componentName}.doc.mjs`);
+ if (!fs.existsSync(compDoc)) {
+ compDoc = path.join(dirPath, `XDS${componentName}.doc.mjs`);
+ }
+ if (fs.existsSync(compDoc)) {
+ const compMeta = readDocMeta(compDoc);
+ if (compMeta.group) compGroup = compMeta.group;
+ }
+
+ if (!componentGroups.has(componentName)) {
+ componentGroups.set(componentName, compGroup);
}
}
}
- // Sort components within each category
- for (const cat of Object.keys(categories)) {
- categories[cat].sort();
+ // Build the result: group name → sorted members, or component name → [self]
+ /** @type {Map<string, string[]>} */
+ const groups = new Map();
+ /** @type {string[]} ungrouped component names */
+ const ungrouped = [];
+
+ for (const [name, group] of componentGroups) {
+ if (group) {
+ if (!groups.has(group)) groups.set(group, []);
+ groups.get(group).push(name);
+ } else {
+ ungrouped.push(name);
+ }
}
- // Return in defined order
- const ordered = {};
- for (const cat of CATEGORY_ORDER) {
- if (categories[cat]) ordered[cat] = categories[cat];
+ // Sort members within each group
+ for (const members of groups.values()) {
+ members.sort();
+ }
+
+ // Merge groups and ungrouped into a single alphabetically-ordered record
+ /** @type {Array<{key: string, values: string[]}>} */
+ const entries = [];
+ for (const [groupName, members] of groups) {
+ entries.push({key: groupName, values: members});
+ }
+ for (const name of ungrouped) {
+ entries.push({key: name, values: [name]});
}
- // Append any categories not in CATEGORY_ORDER (e.g. "Other")
- for (const cat of Object.keys(categories)) {
- if (!ordered[cat]) ordered[cat] = categories[cat];
+ entries.sort((a, b) => a.key.localeCompare(b.key));
+
+ /** @type {Record<string, string[]>} */
+ const ordered = {};
+ for (const {key, values} of entries) {
+ ordered[key] = values;
}
return ordered;
@@ -118,17 +156,31 @@ export function discoverComponents(coreDir) {
export function findComponentReadme(coreDir, name) {
const srcDir = path.join(coreDir, 'src');
const exactDoc = `${name}.doc.mjs`;
+ const xdsDoc = `XDS${name}.doc.mjs`;
- // Direct match: src/{name}/{Name}.doc.mjs
+ // Direct match: src/{name}/{Name}.doc.mjs or src/{name}/XDS{Name}.doc.mjs
const direct = path.join(srcDir, name, exactDoc);
if (fs.existsSync(direct)) return direct;
+ const directXds = path.join(srcDir, name, xdsDoc);
+ if (fs.existsSync(directXds)) return directXds;
- // Nested match: src/*/{name}/{Name}.doc.mjs
+ // Nested match: src/*/{name}/{Name}.doc.mjs or src/*/{name}/XDS{Name}.doc.mjs
const entries = fs.readdirSync(srcDir, {withFileTypes: true});
for (const entry of entries) {
if (!entry.isDirectory()) continue;
const nested = path.join(srcDir, entry.name, name, exactDoc);
if (fs.existsSync(nested)) return nested;
+ const nestedXds = path.join(srcDir, entry.name, name, xdsDoc);
+ if (fs.existsSync(nestedXds)) return nestedXds;
+ }
+
+ // Per-component doc in a parent directory: src/*/{Name}.doc.mjs or src/*/XDS{Name}.doc.mjs
+ for (const entry of entries) {
+ if (!entry.isDirectory()) continue;
+ const perComp = path.join(srcDir, entry.name, exactDoc);
+ if (fs.existsSync(perComp)) return perComp;
+ const perCompXds = path.join(srcDir, entry.name, xdsDoc);
+ if (fs.existsSync(perCompXds)) return perCompXds;
}
// Sub-component fallback: find the source file, then walk up
diff --git a/packages/cli/src/lib/component-format.mjs b/packages/cli/src/lib/component-format.mjs
index 4c50adebe3..a0e9c08b7b 100644
--- a/packages/cli/src/lib/component-format.mjs
+++ b/packages/cli/src/lib/component-format.mjs
@@ -475,8 +475,11 @@ export async function formatBriefAll(coreDir, {zh = false, lang, themeData = nul
const components = discoverComponents(coreDir);
const output = [];
- for (const [category, comps] of Object.entries(components)) {
- output.push(`## ${category}\n`);
+ for (const [key, comps] of Object.entries(components)) {
+ const isUngrouped = comps.length === 1 && comps[0] === key;
+ if (!isUngrouped) {
+ output.push(`## ${key}\n`);
+ }
for (const comp of comps) {
const readmePath = findComponentReadme(coreDir, comp);
if (readmePath && readmePath.endsWith('.doc.mjs')) {
diff --git a/packages/core/src/AlertDialog/AlertDialog.doc.mjs b/packages/core/src/AlertDialog/AlertDialog.doc.mjs
index d54c529257..69b3e0c994 100644
--- a/packages/core/src/AlertDialog/AlertDialog.doc.mjs
+++ b/packages/core/src/AlertDialog/AlertDialog.doc.mjs
@@ -2,7 +2,7 @@
export const docs = {
name: 'AlertDialog',
- group: 'Dialogs',
+ group: 'Dialog',
keywords: [
'alert',
'alertdialog',
diff --git a/packages/core/src/AppShell/XDSAppShell.tsx b/packages/core/src/AppShell/XDSAppShell.tsx
index e1a491a321..4271d6b65f 100644
--- a/packages/core/src/AppShell/XDSAppShell.tsx
+++ b/packages/core/src/AppShell/XDSAppShell.tsx
@@ -45,7 +45,7 @@ import {XDSSideNavRenderContext} from '../SideNav/XDSSideNavRenderContext';
import {XDSTopNavRenderContext} from '../TopNav/XDSTopNavRenderContext';
import {XDSTopNavMobileContentContext} from '../TopNav/XDSTopNavMobileContentContext';
import {XDSAppShellMobileContext} from './XDSAppShellMobileContext';
-import {useXDSSlotPresence} from './XDSAppShellSlotPresence';
+import {useXDSSlotPresence} from './useXDSSlotPresence';
import type {XDSAppShellMobileContextValue} from './XDSAppShellMobileContext';
import type {SpacingStep} from '../utils/types';
import {xdsClassName, mergeProps} from '../utils';
diff --git a/packages/core/src/AppShell/XDSAppShellSlotPresence.tsx b/packages/core/src/AppShell/useXDSSlotPresence.tsx
similarity index 98%
rename from packages/core/src/AppShell/XDSAppShellSlotPresence.tsx
rename to packages/core/src/AppShell/useXDSSlotPresence.tsx
index 7dea30fe96..417eb31778 100644
--- a/packages/core/src/AppShell/XDSAppShellSlotPresence.tsx
+++ b/packages/core/src/AppShell/useXDSSlotPresence.tsx
@@ -1,7 +1,7 @@
'use client';
/**
- * @file XDSAppShellSlotPresence.tsx
+ * @file useXDSSlotPresence.tsx
* @input Uses React useCallback, useLayoutEffect, useRef, useState
* @output Exports useXDSSlotPresence hook
* @position Internal hook for detecting whether slot containers have rendered content.
diff --git a/packages/core/src/Avatar/Avatar.doc.mjs b/packages/core/src/Avatar/Avatar.doc.mjs
index 5b177aa30f..555155e11b 100644
--- a/packages/core/src/Avatar/Avatar.doc.mjs
+++ b/packages/core/src/Avatar/Avatar.doc.mjs
@@ -2,6 +2,7 @@
export const docs = {
name: 'Avatar',
+ group: 'Avatar',
keywords: ["avatar","profile","user","photo","thumbnail","initials","gravatar","pfp","userpic"],
usage: {
description:
@@ -86,6 +87,7 @@ export const docs = {
/** @type {import('../docs-types').ComponentDoc} */
export const docsZh = {
name: 'Avatar',
+ group: 'Avatar',
usage: {
description:
'Avatar displays a user or entity\'s profile picture with automatic fallback to initials or a default icon. Use it alongside user information to visually represent people, teams, or entities throughout the interface.',
diff --git a/packages/core/src/Breadcrumbs/Breadcrumbs.doc.mjs b/packages/core/src/Breadcrumbs/Breadcrumbs.doc.mjs
index 037c0d9a54..54218f32b2 100644
--- a/packages/core/src/Breadcrumbs/Breadcrumbs.doc.mjs
+++ b/packages/core/src/Breadcrumbs/Breadcrumbs.doc.mjs
@@ -2,6 +2,7 @@
export const docs = {
name: 'Breadcrumbs',
+ group: 'Breadcrumbs',
keywords: ["breadcrumbs","breadcrumb","navigation","nav","crumbs","trail","path","hierarchy","wayfinding","steps"],
usage: {
description:
@@ -115,6 +116,7 @@ export const docs = {
/** @type {import('../docs-types').ComponentDoc} */
export const docsZh = {
name: 'Breadcrumbs',
+ group: 'Breadcrumbs',
usage: {
description:
'Breadcrumbs show a trail of links from the root to the current page. Use them at the top of detail pages, settings panels, or anywhere the user needs to see where they are and navigate back up.',
diff --git a/packages/core/src/Button/Button.doc.mjs b/packages/core/src/Button/Button.doc.mjs
index 7533383b09..d2c8f3a61b 100644
--- a/packages/core/src/Button/Button.doc.mjs
+++ b/packages/core/src/Button/Button.doc.mjs
@@ -2,7 +2,7 @@
export const docs = {
name: 'Button',
- group: 'Buttons',
+ group: 'Button',
keywords: ["button","btn","cta","submit","action","loading","primary","secondary","ghost","destructive","danger"],
diff --git a/packages/core/src/Chat/Chat.doc.mjs b/packages/core/src/Chat/Chat.doc.mjs
index 74cbd9b7cc..30420b9486 100644
--- a/packages/core/src/Chat/Chat.doc.mjs
+++ b/packages/core/src/Chat/Chat.doc.mjs
@@ -2,6 +2,7 @@
export const docs = {
name: 'Chat',
+ group: 'Chat',
keywords: ['chat', 'message', 'bubble', 'conversation', 'ai', 'assistant', 'thread', 'system-message', 'composer', 'mention', 'trigger', 'typeahead', 'token', 'imperative', 'tokenized-text'],
theming: {
targets: [
diff --git a/packages/core/src/CheckboxInput/CheckboxInput.doc.mjs b/packages/core/src/CheckboxInput/CheckboxInput.doc.mjs
index d66fa70f80..35c42d1fcd 100644
--- a/packages/core/src/CheckboxInput/CheckboxInput.doc.mjs
+++ b/packages/core/src/CheckboxInput/CheckboxInput.doc.mjs
@@ -2,7 +2,6 @@
export const docs = {
name: 'CheckboxInput',
- group: 'Inputs',
keywords: ["checkbox","check","toggle","tick","indeterminate","boolean","tristate"],
props: [
{
diff --git a/packages/core/src/CheckboxList/CheckboxList.doc.mjs b/packages/core/src/CheckboxList/CheckboxList.doc.mjs
index 81fce0bd9d..94c73bbb54 100644
--- a/packages/core/src/CheckboxList/CheckboxList.doc.mjs
+++ b/packages/core/src/CheckboxList/CheckboxList.doc.mjs
@@ -2,7 +2,7 @@
export const docs = {
name: 'CheckboxList',
- group: 'Inputs',
+ group: 'CheckboxList',
keywords: ["checkboxlist","checkbox","checkboxgroup","multichoice","multiselect","checklist"],
components: [
{
diff --git a/packages/core/src/Collapsible/Collapsible.doc.mjs b/packages/core/src/Collapsible/Collapsible.doc.mjs
index 75ec4c409f..c58194434f 100644
--- a/packages/core/src/Collapsible/Collapsible.doc.mjs
+++ b/packages/core/src/Collapsible/Collapsible.doc.mjs
@@ -2,6 +2,7 @@
export const docs = {
name: 'Collapsible',
+ group: 'Collapsible',
keywords: ["accordion","collapse","expandable","disclosure","toggle","panel","foldable","expander","expand"],
theming: {
targets: [
@@ -106,6 +107,7 @@ export const docs = {
/** @type {import('../docs-types').ComponentDoc} */
export const docsZh = {
name: 'Collapsible',
+ group: 'Collapsible',
usage: {
description: 'Collapsible hides and reveals content behind a trigger button. Use it in settings panels, FAQ pages, or detail views to keep the page scannable while letting users drill into sections they care about. Wrap multiple collapsibles in XDSCollapsibleGroup for accordion behavior.',
bestPractices: [
diff --git a/packages/core/src/CommandPalette/XDSCommandPalette.doc.mjs b/packages/core/src/CommandPalette/XDSCommandPalette.doc.mjs
index c9961153ce..9c79978d43 100644
--- a/packages/core/src/CommandPalette/XDSCommandPalette.doc.mjs
+++ b/packages/core/src/CommandPalette/XDSCommandPalette.doc.mjs
@@ -1,6 +1,7 @@
/** @type {import('../docs-types').ComponentDoc} */
export const docs = {
name: 'CommandPalette',
+ group: 'CommandPalette',
keywords: [
'command',
'spotlight',
diff --git a/packages/core/src/DateInput/DateInput.doc.mjs b/packages/core/src/DateInput/DateInput.doc.mjs
index e72d1e7b17..aabb3d93ce 100644
--- a/packages/core/src/DateInput/DateInput.doc.mjs
+++ b/packages/core/src/DateInput/DateInput.doc.mjs
@@ -2,7 +2,6 @@
export const docs = {
name: 'DateInput',
- group: 'Inputs',
keywords: ["dateinput","datepicker","datefield","calendar","dateselect","dateentry","datechooser"],
props: [
{
diff --git a/packages/core/src/Dialog/Dialog.doc.mjs b/packages/core/src/Dialog/Dialog.doc.mjs
index c72547edc6..b442237549 100644
--- a/packages/core/src/Dialog/Dialog.doc.mjs
+++ b/packages/core/src/Dialog/Dialog.doc.mjs
@@ -2,7 +2,7 @@
export const docs = {
name: 'Dialog',
- group: 'Dialogs',
+ group: 'Dialog',
keywords: ["dialog","modal","popup","overlay","lightbox","alert","confirm","prompt","backdrop","focus trap"],
theming: {
container: true,
diff --git a/packages/core/src/DropdownMenu/DropdownMenu.doc.mjs b/packages/core/src/DropdownMenu/DropdownMenu.doc.mjs
index d3d6b409bb..1100ccfc74 100644
--- a/packages/core/src/DropdownMenu/DropdownMenu.doc.mjs
+++ b/packages/core/src/DropdownMenu/DropdownMenu.doc.mjs
@@ -2,6 +2,7 @@
export const docs = {
name: 'DropdownMenu',
+ group: 'DropdownMenu',
keywords: ["dropdown","menu","popover","select","actions","contextmenu","overflow","kebab","menubutton"],
theming: {
targets: [
diff --git a/packages/core/src/Field/Field.doc.mjs b/packages/core/src/Field/Field.doc.mjs
index 31a7e12868..fabd1a5983 100644
--- a/packages/core/src/Field/Field.doc.mjs
+++ b/packages/core/src/Field/Field.doc.mjs
@@ -2,7 +2,7 @@
export const docs = {
name: 'Field',
- group: 'Inputs',
+ group: 'Field',
keywords: ["field","formfield","formgroup","formcontrol","label","input","required","optional","helpertext","hint"],
theming: {
targets: [
diff --git a/packages/core/src/FormLayout/FormLayout.doc.mjs b/packages/core/src/FormLayout/FormLayout.doc.mjs
index e7bd9ce282..a5c9cb0d2e 100644
--- a/packages/core/src/FormLayout/FormLayout.doc.mjs
+++ b/packages/core/src/FormLayout/FormLayout.doc.mjs
@@ -2,7 +2,6 @@
export const docs = {
name: 'FormLayout',
- group: 'Inputs',
keywords: ["formlayout","form","fieldset","formgroup","formcontainer","fields","vertical","horizontal"],
props: [
{
diff --git a/packages/core/src/Grid/Grid.doc.mjs b/packages/core/src/Grid/Grid.doc.mjs
index 43f62cd95d..9782a7ea14 100644
--- a/packages/core/src/Grid/Grid.doc.mjs
+++ b/packages/core/src/Grid/Grid.doc.mjs
@@ -2,6 +2,7 @@
export const docs = {
name: 'Grid',
+ group: 'Grid',
keywords: ["grid","columns","responsive","auto-fill","auto-fit","masonry","tiles","row","col","simplegrid","responsive grid","card grid"],
usage: {
description:
@@ -112,6 +113,7 @@ export const docs = {
/** @type {import('../docs-types').ComponentDoc} */
export const docsZh = {
name: 'Grid',
+ group: 'Grid',
theming: {
targets: [
{className: 'xds-grid', visualProps: ['align', 'columns', 'gap', 'justify']},
diff --git a/packages/core/src/IconButton/IconButton.doc.mjs b/packages/core/src/IconButton/IconButton.doc.mjs
index d5e1844232..f83d48d260 100644
--- a/packages/core/src/IconButton/IconButton.doc.mjs
+++ b/packages/core/src/IconButton/IconButton.doc.mjs
@@ -2,7 +2,7 @@
export const docs = {
name: 'IconButton',
- group: 'Buttons',
+ group: 'Button',
keywords: ['icon-button', 'icon', 'button', 'toolbar', 'action', 'compact'],
props: [
diff --git a/packages/core/src/Layer/Layer.doc.mjs b/packages/core/src/Layer/Layer.doc.mjs
index 49962a59a7..215e73f130 100644
--- a/packages/core/src/Layer/Layer.doc.mjs
+++ b/packages/core/src/Layer/Layer.doc.mjs
@@ -2,6 +2,7 @@
export const docs = {
name: 'Layer',
+ group: 'Utility',
keywords: ["layer","overlay","popover","positioning","anchor","floating","dropdown","popper","popup","portal"],
components: [
{
diff --git a/packages/core/src/Layout/Layout.doc.mjs b/packages/core/src/Layout/Layout.doc.mjs
index 2415d6ec96..7cbab6878d 100644
--- a/packages/core/src/Layout/Layout.doc.mjs
+++ b/packages/core/src/Layout/Layout.doc.mjs
@@ -2,6 +2,7 @@
export const docs = {
name: 'Layout',
+ group: 'Layout',
keywords: ["layout","container","content","flex","box","wrapper","scaffold","page","shell"],
theming: {
targets: [
diff --git a/packages/core/src/Link/LinkProvider.doc.mjs b/packages/core/src/Link/LinkProvider.doc.mjs
new file mode 100644
index 0000000000..6569074d6d
--- /dev/null
+++ b/packages/core/src/Link/LinkProvider.doc.mjs
@@ -0,0 +1,14 @@
+/** @type {import('../docs-types').ComponentDoc} */
+
+export const docs = {
+ name: 'LinkProvider',
+ group: 'Utility',
+ keywords: ['link', 'provider', 'router', 'nextjs', 'client-side-routing'],
+ usage: {
+ description: 'Wraps your app to replace the default <a> tag with a framework-specific link component (e.g. Next.js Link) for client-side routing across all XDS components.',
+ },
+ props: [
+ {name: 'component', type: 'XDSLinkComponentType', required: true, description: 'Link component to use for all link elements in the subtree (e.g. Next.js Link).'},
+ {name: 'children', type: 'ReactNode', required: true, description: 'Content to render with the link provider.'},
+ ],
+};
diff --git a/packages/core/src/List/List.doc.mjs b/packages/core/src/List/List.doc.mjs
index 3b407caf55..43f072f91f 100644
--- a/packages/core/src/List/List.doc.mjs
+++ b/packages/core/src/List/List.doc.mjs
@@ -2,6 +2,7 @@
export const docs = {
name: 'List',
+ group: 'List',
keywords: ["list","listitem","listbox","menu","collection","items","ul","navlist"],
theming: {
targets: [
@@ -131,6 +132,7 @@ export const docs = {
/** @type {import('../docs-types').ComponentDoc} */
export const docsZh = {
name: 'List',
+ group: 'List',
theming: {
targets: [
{className: 'xds-list', visualProps: ['density', 'listStyle']},
diff --git a/packages/core/src/MetadataList/MetadataList.doc.mjs b/packages/core/src/MetadataList/MetadataList.doc.mjs
index d66ab0ea58..4e732619f2 100644
--- a/packages/core/src/MetadataList/MetadataList.doc.mjs
+++ b/packages/core/src/MetadataList/MetadataList.doc.mjs
@@ -2,6 +2,7 @@
export const docs = {
name: 'MetadataList',
+ group: 'MetadataList',
keywords: ["metadata","description","definition","keyvalue","properties","details","attributes","summary"],
theming: {
targets: [
diff --git a/packages/core/src/MultiSelector/MultiSelector.doc.mjs b/packages/core/src/MultiSelector/MultiSelector.doc.mjs
index 5899e81f1d..3c017d415b 100644
--- a/packages/core/src/MultiSelector/MultiSelector.doc.mjs
+++ b/packages/core/src/MultiSelector/MultiSelector.doc.mjs
@@ -2,7 +2,6 @@
export const docs = {
name: 'MultiSelector',
- group: 'Inputs',
keywords: ['multiselect', 'checkbox', 'dropdown', 'multi', 'picker', 'checklist', 'facet', 'filter', 'select'],
theming: {
targets: [
diff --git a/packages/core/src/NavMenu/NavMenu.doc.mjs b/packages/core/src/NavMenu/NavMenu.doc.mjs
new file mode 100644
index 0000000000..0d1d36da14
--- /dev/null
+++ b/packages/core/src/NavMenu/NavMenu.doc.mjs
@@ -0,0 +1,18 @@
+/** @type {import('../docs-types').ComponentDoc} */
+
+export const docs = {
+ name: 'NavMenu',
+ group: 'Navigation',
+ keywords: ['nav', 'menu', 'navigation', 'menu-item'],
+ usage: {
+ description: 'Menu item used within navigation components like SideNav and TopNav.',
+ },
+ props: [
+ {name: 'icon', type: 'XDSIconType', description: 'Icon displayed before the label.'},
+ {name: 'label', type: 'ReactNode', required: true, description: 'Primary label text.'},
+ {name: 'description', type: 'ReactNode', description: 'Secondary description below the label.'},
+ {name: 'href', type: 'string', description: 'URL to navigate to. Renders as an anchor.'},
+ {name: 'onClick', type: '() => void', description: 'Callback when the item is selected.'},
+ {name: 'isDisabled', type: 'boolean', default: 'false', description: 'Whether the item is disabled.'},
+ ],
+};
diff --git a/packages/core/src/NumberInput/NumberInput.doc.mjs b/packages/core/src/NumberInput/NumberInput.doc.mjs
index bf08f38597..32a1e84807 100644
--- a/packages/core/src/NumberInput/NumberInput.doc.mjs
+++ b/packages/core/src/NumberInput/NumberInput.doc.mjs
@@ -2,7 +2,6 @@
export const docs = {
name: 'NumberInput',
- group: 'Inputs',
keywords: ["numberinput","numberfield","stepper","spinner","counter","increment","decrement","quantity","numberpicker"],
props: [
{
diff --git a/packages/core/src/PowerSearch/PowerSearch.doc.mjs b/packages/core/src/PowerSearch/PowerSearch.doc.mjs
index cb231774a9..5edb1864b1 100644
--- a/packages/core/src/PowerSearch/PowerSearch.doc.mjs
+++ b/packages/core/src/PowerSearch/PowerSearch.doc.mjs
@@ -2,7 +2,6 @@
export const docs = {
name: 'PowerSearch',
- group: 'Inputs',
keywords: ["powersearch","search","searchbar","filter","filterbar","faceted","querybuilder","structured","omnibar"],
props: [
{
diff --git a/packages/core/src/RadioList/RadioList.doc.mjs b/packages/core/src/RadioList/RadioList.doc.mjs
index e79da4107a..b566451d23 100644
--- a/packages/core/src/RadioList/RadioList.doc.mjs
+++ b/packages/core/src/RadioList/RadioList.doc.mjs
@@ -2,7 +2,7 @@
export const docs = {
name: 'RadioList',
- group: 'Inputs',
+ group: 'RadioList',
keywords: ["radiolist","radio","radiogroup","radiobutton","optionlist","singlechoice","choicelist"],
theming: {
targets: [
diff --git a/packages/core/src/SegmentedControl/SegmentedControl.doc.mjs b/packages/core/src/SegmentedControl/SegmentedControl.doc.mjs
index f9dee65ddc..51246cc450 100644
--- a/packages/core/src/SegmentedControl/SegmentedControl.doc.mjs
+++ b/packages/core/src/SegmentedControl/SegmentedControl.doc.mjs
@@ -2,7 +2,7 @@
export const docs = {
name: 'SegmentedControl',
- group: 'Inputs',
+ group: 'SegmentedControl',
keywords: ['radio', 'tabs', 'toggle', 'toggle-group', 'pill', 'button-group', 'switch', 'segment', 'control'],
theming: {
targets: [
diff --git a/packages/core/src/Selector/Selector.doc.mjs b/packages/core/src/Selector/Selector.doc.mjs
index d2c46b21c7..52abc84876 100644
--- a/packages/core/src/Selector/Selector.doc.mjs
+++ b/packages/core/src/Selector/Selector.doc.mjs
@@ -2,7 +2,7 @@
export const docs = {
name: 'Selector',
- group: 'Inputs',
+ group: 'Selector',
keywords: ["selector","select","dropdown","combobox","picker","listbox","chooser","autocomplete","option","selectmenu"],
theming: {
targets: [
diff --git a/packages/core/src/Stack/Stack.doc.mjs b/packages/core/src/Stack/Stack.doc.mjs
index 3345ddf312..7bdb4180ad 100644
--- a/packages/core/src/Stack/Stack.doc.mjs
+++ b/packages/core/src/Stack/Stack.doc.mjs
@@ -2,6 +2,7 @@
export const docs = {
name: 'Stack',
+ group: 'Stack',
keywords: ["stack","hstack","vstack","flexbox","flex","spacing","gap","horizontal","vertical","row","column"],
theming: {
targets: [
@@ -184,6 +185,7 @@ export const docs = {
/** @type {import('../docs-types').ComponentDoc} */
export const docsZh = {
name: 'Stack',
+ group: 'Stack',
theming: {
targets: [
{className: 'xds-stack', visualProps: ['direction', 'gap', 'wrap']},
diff --git a/packages/core/src/TabList/TabList.doc.mjs b/packages/core/src/TabList/TabList.doc.mjs
index 9dc1afe6ce..6dc0ef69d1 100644
--- a/packages/core/src/TabList/TabList.doc.mjs
+++ b/packages/core/src/TabList/TabList.doc.mjs
@@ -2,6 +2,7 @@
export const docs = {
name: 'TabList',
+ group: 'TabList',
keywords: ["tabs","tabbar","tabstrip","navigation","tabpanel","tabgroup","segmented","navtabs","tab"],
theming: {
targets: [
@@ -147,6 +148,7 @@ export const docs = {
/** @type {import('../docs-types').ComponentDoc} */
export const docsZh = {
name: 'TabList',
+ group: 'TabList',
theming: {
targets: [
{className: 'xds-tab-list', visualProps: ['size']},
diff --git a/packages/core/src/Table/Table.doc.mjs b/packages/core/src/Table/Table.doc.mjs
index fe546747c7..7f8e874853 100644
--- a/packages/core/src/Table/Table.doc.mjs
+++ b/packages/core/src/Table/Table.doc.mjs
@@ -2,6 +2,7 @@
export const docs = {
name: 'Table',
+ group: 'Table',
keywords: ["table","datatable","datagrid","spreadsheet","sorting","virtualized","columns","rows","selection","pinning"],
theming: {
targets: [
@@ -430,6 +431,7 @@ export const docs = {
/** @type {import('../docs-types').ComponentDoc} */
export const docsZh = {
name: 'Table',
+ group: 'Table',
theming: {
targets: [
{className: 'xds-base-table'},
diff --git a/packages/core/src/TextArea/TextArea.doc.mjs b/packages/core/src/TextArea/TextArea.doc.mjs
index 1e73adeb92..f02a4f0c19 100644
--- a/packages/core/src/TextArea/TextArea.doc.mjs
+++ b/packages/core/src/TextArea/TextArea.doc.mjs
@@ -2,7 +2,6 @@
export const docs = {
name: 'TextArea',
- group: 'Inputs',
keywords: ["textarea","textfield","multiline","comment","message","autoresize","autosize","charlimit"],
props: [
{
diff --git a/packages/core/src/TextInput/TextInput.doc.mjs b/packages/core/src/TextInput/TextInput.doc.mjs
index e901d5ed9b..4768ab72fc 100644
--- a/packages/core/src/TextInput/TextInput.doc.mjs
+++ b/packages/core/src/TextInput/TextInput.doc.mjs
@@ -2,7 +2,6 @@
export const docs = {
name: 'TextInput',
- group: 'Inputs',
keywords: ["textinput","textfield","input","search","clearable","prefix","suffix","adornment","validation"],
props: [
{
diff --git a/packages/core/src/TimeInput/TimeInput.doc.mjs b/packages/core/src/TimeInput/TimeInput.doc.mjs
index 8051cd5fd8..9b377feb03 100644
--- a/packages/core/src/TimeInput/TimeInput.doc.mjs
+++ b/packages/core/src/TimeInput/TimeInput.doc.mjs
@@ -2,7 +2,6 @@
export const docs = {
name: 'TimeInput',
- group: 'Inputs',
keywords: ["timeinput","timepicker","time","clock","hour","minute","ampm","timeselect","timefield","schedule"],
usage: {
diff --git a/packages/core/src/Toast/Toast.doc.mjs b/packages/core/src/Toast/Toast.doc.mjs
index f5896018a2..cd69a36404 100644
--- a/packages/core/src/Toast/Toast.doc.mjs
+++ b/packages/core/src/Toast/Toast.doc.mjs
@@ -2,6 +2,8 @@
export const docs = {
name: 'Toast',
+ group: 'Toast',
+ internalComponents: ['ToastViewport'],
keywords: ["toast","notification","snackbar","alert","message","feedback","status"],
props: [
diff --git a/packages/core/src/ToggleButton/ToggleButton.doc.mjs b/packages/core/src/ToggleButton/ToggleButton.doc.mjs
index a77cf7300c..5584b29d46 100644
--- a/packages/core/src/ToggleButton/ToggleButton.doc.mjs
+++ b/packages/core/src/ToggleButton/ToggleButton.doc.mjs
@@ -2,7 +2,7 @@
export const docs = {
name: 'ToggleButton',
- group: 'Buttons',
+ group: 'Button',
keywords: ["toggle","togglebutton","pressed","toolbar","formatting","segmented","button-group","exclusive","multi-select"],
theming: {
targets: [
diff --git a/packages/core/src/Tokenizer/Tokenizer.doc.mjs b/packages/core/src/Tokenizer/Tokenizer.doc.mjs
index bb809a4d21..fd040489d2 100644
--- a/packages/core/src/Tokenizer/Tokenizer.doc.mjs
+++ b/packages/core/src/Tokenizer/Tokenizer.doc.mjs
@@ -2,7 +2,6 @@
export const docs = {
name: 'Tokenizer',
- group: 'Inputs',
keywords: ["tokenizer","multiselect","multi-select","chips","tags","combobox","autocomplete","taginput","chipinput"],
props: [
{
diff --git a/packages/core/src/TreeList/TreeList.doc.mjs b/packages/core/src/TreeList/TreeList.doc.mjs
index c7027eca6f..23fb8152fa 100644
--- a/packages/core/src/TreeList/TreeList.doc.mjs
+++ b/packages/core/src/TreeList/TreeList.doc.mjs
@@ -2,6 +2,7 @@
export const docs = {
name: 'TreeList',
+ group: 'TreeList',
keywords: ['tree', 'hierarchy', 'nested', 'accordion', 'folder', 'expand', 'collapse', 'treeview', 'outline'],
theming: {
targets: [
@@ -62,6 +63,7 @@ export const docs = {
/** @type {import('../docs-types').ComponentDoc} */
export const docsZh = {
name: 'TreeList',
+ group: 'TreeList',
theming: {
targets: [
{className: 'xds-tree-list', visualProps: ['density']},
diff --git a/packages/core/src/Typeahead/Typeahead.doc.mjs b/packages/core/src/Typeahead/Typeahead.doc.mjs
index 48b39253ee..d776262428 100644
--- a/packages/core/src/Typeahead/Typeahead.doc.mjs
+++ b/packages/core/src/Typeahead/Typeahead.doc.mjs
@@ -2,7 +2,7 @@
export const docs = {
name: 'Typeahead',
- group: 'Inputs',
+ group: 'Typeahead',
keywords: ["typeahead","autocomplete","combobox","searchbox","autosuggest","select","dropdown","lookup","searchable","suggestion","picker"],
components: [
{
diff --git a/packages/core/src/docs-types.ts b/packages/core/src/docs-types.ts
index 3b1d830323..a3bfb87c50 100644
--- a/packages/core/src/docs-types.ts
+++ b/packages/core/src/docs-types.ts
@@ -268,16 +268,39 @@ interface BaseDoc {
* Lowercase only. Used by `xds component <term>` for fuzzy matching.
* e.g. `['accordion', 'expand', 'toggle', 'disclosure']` for Collapsible */
keywords?: string[];
+ /** Sub-component names to hide from discovery. Use when the directory's
+ * doc covers a group but some XDS*.tsx files are internal. */
+ internalComponents?: string[];
/** Optional group for sidebar/docs organization.
* Components without a group appear flat in alphabetical order.
* Groups cluster related components that are always used together
* or are variants of each other. */
group?:
- | 'Buttons'
+ | 'Avatar'
+ | 'Breadcrumbs'
+ | 'Button'
| 'Chat'
- | 'Dialogs'
- | 'Inputs'
- | 'Navigation';
+ | 'CheckboxList'
+ | 'Collapsible'
+ | 'CommandPalette'
+ | 'Dialog'
+ | 'DropdownMenu'
+ | 'Field'
+ | 'Grid'
+ | 'Layout'
+ | 'List'
+ | 'MetadataList'
+ | 'Navigation'
+ | 'RadioList'
+ | 'SegmentedControl'
+ | 'Selector'
+ | 'Stack'
+ | 'TabList'
+ | 'Table'
+ | 'Toast'
+ | 'TreeList'
+ | 'Typeahead'
+ | 'Utility';
/** Theming configuration. Documents the stable CSS class names
* rendered by this component that themes can target via `@scope`
* selectors in `defineTheme`. */
@@ -502,4 +525,3 @@ export interface BlockTemplateDoc extends BaseTemplateDoc {
}
export type TemplateDoc = PageTemplateDoc | BlockTemplateDoc;
-
diff --git a/packages/core/src/theme/MediaTheme.doc.mjs b/packages/core/src/theme/MediaTheme.doc.mjs
new file mode 100644
index 0000000000..1c57fdd260
--- /dev/null
+++ b/packages/core/src/theme/MediaTheme.doc.mjs
@@ -0,0 +1,14 @@
+/** @type {import('../docs-types').ComponentDoc} */
+
+export const docs = {
+ name: 'MediaTheme',
+ group: 'Utility',
+ keywords: ['theme', 'dark-mode', 'light-mode', 'media', 'prefers-color-scheme'],
+ usage: {
+ description: 'Applies a theme that adapts to the system light/dark preference via prefers-color-scheme.',
+ },
+ props: [
+ {name: 'mode', type: "'dark' | 'light'", required: true, description: 'Surface luminance context — dark for light text on dark backgrounds, light for dark text on light backgrounds.'},
+ {name: 'children', type: 'ReactNode', required: true, description: 'Content to render in the media context.'},
+ ],
+};
diff --git a/packages/core/src/theme/SyntaxTheme.doc.mjs b/packages/core/src/theme/SyntaxTheme.doc.mjs
new file mode 100644
index 0000000000..667492202a
--- /dev/null
+++ b/packages/core/src/theme/SyntaxTheme.doc.mjs
@@ -0,0 +1,14 @@
+/** @type {import('../docs-types').ComponentDoc} */
+
+export const docs = {
+ name: 'SyntaxTheme',
+ group: 'Utility',
+ keywords: ['syntax', 'highlighting', 'code', 'theme'],
+ usage: {
+ description: 'Applies syntax highlighting colors to XDSCodeBlock components.',
+ },
+ props: [
+ {name: 'theme', type: 'SyntaxTheme', required: true, description: 'Syntax highlighting theme to apply to child code components.'},
+ {name: 'children', type: 'ReactNode', required: true, description: 'Content to render with the syntax theme.'},
+ ],
+};
diff --git a/packages/core/src/theme/XDSTheme.doc.mjs b/packages/core/src/theme/XDSTheme.doc.mjs
new file mode 100644
index 0000000000..edd27e8588
--- /dev/null
+++ b/packages/core/src/theme/XDSTheme.doc.mjs
@@ -0,0 +1,15 @@
+/** @type {import('../docs-types').ComponentDoc} */
+
+export const docs = {
+ name: 'Theme',
+ group: 'Utility',
+ keywords: ['theme', 'theming', 'provider', 'color-scheme'],
+ usage: {
+ description: 'Wraps a subtree with a specific XDS theme. Use at the app root or around sections that need a different visual treatment.',
+ },
+ props: [
+ {name: 'theme', type: 'XDSDefinedTheme', required: true, description: 'Theme created by defineTheme().'},
+ {name: 'mode', type: "'light' | 'dark' | 'system'", default: "'system'", description: 'Color mode — system follows OS preference.'},
+ {name: 'children', type: 'ReactNode', required: true, description: 'Content to render with the theme.'},
+ ],
+};