An open source design system that's fully customizable and agent ready
TypeScript
fix(docsite): expand compound components into sub-component entries (#1948)
Cindy Zhang2df678887401
diff --git a/apps/docsite/scripts/generate-data.mjs b/apps/docsite/scripts/generate-data.mjsindex e7735248db..6c1f376e56 100644--- a/apps/docsite/scripts/generate-data.mjs+++ b/apps/docsite/scripts/generate-data.mjs@@ -19,7 +19,7 @@import * as fs from 'node:fs';import * as path from 'node:path';-import {fileURLToPath} from 'node:url';+import {fileURLToPath, pathToFileURL} from 'node:url';const __dirname = path.dirname(fileURLToPath(import.meta.url));const DOCSITE_ROOT = path.resolve(__dirname, '..');@@ -164,7 +164,7 @@ export const packages: PackageMeta[] = ${JSON.stringify(packages, null, 2)};// ── 2. Component Registry ──────────────────────────────────────────────-function generateComponentRegistry() {+async function generateComponentRegistry() {console.log('Generating component registry...');// Auto-discover component packages: any package with a src/ dir containing@@ -176,14 +176,12 @@ function generateComponentRegistry() {const srcDir = path.join(REPO_ROOT, dir, 'src');if (!fs.existsSync(srcDir)) continue;const pkgJson = JSON.parse(fs.readFileSync(path.join(REPO_ROOT, dir, 'package.json'), 'utf-8'));- // Check if any file anywhere under src/ is a .doc.mjsconst allDocFiles = findDocFilesRecursive(srcDir);if (allDocFiles.length > 0) {componentPackages.push({name: pkgJson.name, srcDir});}}- // Only skip dirs that never contain doc filesconst SKIP_DIRS = new Set(['utils', '__tests__', 'node_modules']);const allComponents = {};let totalCount = 0;@@ -192,31 +190,75 @@ function generateComponentRegistry() {if (!fs.existsSync(pkg.srcDir)) continue;const components = [];+ // Two passes: first collect standalone docs, then add sub-components only if+ // they don't duplicate a standalone entry. Standalone docs are more authoritative.+ const standaloneNames = new Set();+ const pendingSubComponents = [];+for (const entry of fs.readdirSync(pkg.srcDir, {withFileTypes: true})) {if (!entry.isDirectory() || SKIP_DIRS.has(entry.name)) continue;const dirPath = path.join(pkg.srcDir, entry.name);-- // Collect ALL .doc.mjs files in this directory (not just the first)const docFiles = fs.readdirSync(dirPath).filter(f => f.endsWith('.doc.mjs'));if (docFiles.length === 0) continue;for (const docFileName of docFiles) {const docFile = path.join(dirPath, docFileName);- const meta = readDocMeta(docFile);-- // Use docs.name as the canonical name, fall back to filename stem- const fileNameStem = docFileName.replace('.doc.mjs', '').replace(/^XDS/, '');- const name = meta.name || fileNameStem;-- components.push({- name,- directory: entry.name,- group: meta.group,- description: meta.description,- keywords: meta.keywords,- hidden: meta.hidden,- });++ let doc;+ try {+ const mod = await import(pathToFileURL(docFile).href);+ doc = mod.docs;+ if (!doc) continue;+ } catch (err) {+ console.warn(` warn: failed to import ${docFileName}: ${err.message}`);+ continue;+ }++ const group = doc.group || null;+ const keywords = doc.keywords || [];+ const hidden = doc.hidden ?? false;+ const topDescription = doc.usage?.description || doc.description || '';++ if (doc.components && doc.components.length > 0) {+ // Compound component — queue sub-components for second pass+ for (const sub of doc.components) {+ const subName = (sub.name || '').replace(/^XDS/, '');+ if (!subName) continue;+ pendingSubComponents.push({+ name: subName,+ displayName: sub.name || subName,+ directory: entry.name,+ group,+ description: sub.description || topDescription,+ keywords,+ hidden,+ parentDoc: doc.name,+ });+ }+ } else {+ // Simple/standalone component — add directly+ const name = doc.name || docFileName.replace('.doc.mjs', '').replace(/^XDS/, '');+ standaloneNames.add(name);+ components.push({+ name,+ displayName: name.startsWith('use') ? name : `XDS${name}`,+ directory: entry.name,+ group,+ description: topDescription,+ keywords,+ hidden,+ parentDoc: null,+ });+ }+ }+ }++ // Second pass: add sub-components only if no standalone doc exists+ for (const sub of pendingSubComponents) {+ if (!standaloneNames.has(sub.name)) {+ standaloneNames.add(sub.name); // prevent duplicates from multiple compound docs+ components.push(sub);}}@@ -230,18 +272,22 @@ function generateComponentRegistry() {const content = `// Auto-generated by scripts/generate-data.mjs — do not editexport interface ComponentEntry {- /** Canonical name from docs.name (e.g. 'Button', 'useClickableContainer') */+ /** Component name without XDS prefix (e.g. 'Button', 'TableRow', 'useClickableContainer') */name: string;- /** Source directory containing this component (e.g. 'Button', 'hooks') */+ /** Full display name (e.g. 'XDSButton', 'XDSTableRow', 'useClickableContainer') */+ displayName: string;+ /** Source directory containing this component (e.g. 'Button', 'hooks', 'Table') */directory: string;- /** Sidebar group from docs.group (e.g. 'Actions', 'Chat') */+ /** Sidebar group from docs.group (e.g. 'Actions', 'Chat', 'Table') */group: string | null;- /** Short description (first ~200 chars of docs.usage.description) */+ /** Short description */description: string;/** Search keywords from docs.keywords */keywords: string[];/** Whether this component is marked hidden in its doc */hidden: boolean;+ /** For sub-components, the parent doc name (e.g. 'Table' for TableRow). null for top-level. */+ parentDoc: string | null;}export const components: Record<string, ComponentEntry[]> = ${JSON.stringify(allComponents, null, 2)};@@ -445,7 +491,7 @@ async function main() {console.log('Generating docsite data...\n');const packages = generatePackageRegistry();- const {totalCount: componentCount} = generateComponentRegistry();+ const {totalCount: componentCount} = await generateComponentRegistry();const {blockCount, showcaseCount} = await generateBlockRegistry();const {templateCount} = await generateTemplateRegistry();const {docsCount} = await generateDocsRegistry();diff --git a/apps/docsite/src/__tests__/data-extraction.test.ts b/apps/docsite/src/__tests__/data-extraction.test.tsindex e8cdc2d14a..bf24574aa3 100644--- a/apps/docsite/src/__tests__/data-extraction.test.ts+++ b/apps/docsite/src/__tests__/data-extraction.test.ts@@ -21,7 +21,6 @@ describe('packageRegistry', () => {expect(names).toContain('@xds/cli');expect(names).toContain('@xds/theme-default');expect(names).toContain('@xds/theme-neutral');- // Private packages should not appearexpect(names).not.toContain('@xds/lab');expect(names).not.toContain('@xds/build');expect(names).not.toContain('@xds/theme-brutalist');@@ -50,7 +49,7 @@ describe('packageRegistry', () => {describe('componentRegistry', () => {it('discovers components in @xds/core', () => {expect(components['@xds/core']).toBeDefined();- expect(components['@xds/core'].length).toBeGreaterThan(50);+ expect(components['@xds/core'].length).toBeGreaterThan(100);});it('component count matches sum of all packages', () => {@@ -61,44 +60,103 @@ describe('componentRegistry', () => {expect(componentCount).toBe(sum);});- it('components are scoped to their package', () => {+ it('components have all required fields', () => {for (const [pkgName, comps] of Object.entries(components)) {expect(pkgName).toMatch(/^@xds\//);- expect(Array.isArray(comps)).toBe(true);for (const comp of comps) {expect(comp.name).toBeTruthy();- expect(typeof comp.description).toBe('string');+ expect(comp.displayName).toBeTruthy();expect(typeof comp.directory).toBe('string');+ expect(typeof comp.description).toBe('string');+ expect(Array.isArray(comp.keywords)).toBe(true);+ expect(typeof comp.hidden).toBe('boolean');+ // parentDoc is string | null+ expect(+ comp.parentDoc === null || typeof comp.parentDoc === 'string',+ ).toBe(true);}}});- it('known components are present', () => {- const coreNames = components['@xds/core'].map(c => c.name);- expect(coreNames).toContain('Button');- expect(coreNames).toContain('Text');- expect(coreNames).toContain('Card');- expect(coreNames).toContain('Table');+ // ── Sub-component expansion ────────────────────────────────────────++ it('expands compound components into sub-component entries', () => {+ const core = components['@xds/core'];+ // Table has sub-components: Table, BaseTable, TableRow, TableCell, TableHeaderCell, etc.+ const tableComponents = core.filter(c => c.parentDoc === 'Table');+ expect(tableComponents.length).toBeGreaterThanOrEqual(5);+ const tableNames = tableComponents.map(c => c.name);+ expect(tableNames).toContain('Table');+ expect(tableNames).toContain('TableRow');+ expect(tableNames).toContain('TableCell');+ expect(tableNames).toContain('TableHeaderCell');+ });++ it('sub-components share the parent group and directory', () => {+ const core = components['@xds/core'];+ const dialogSubs = core.filter(c => c.parentDoc === 'Dialog');+ expect(dialogSubs.length).toBeGreaterThanOrEqual(2);+ for (const sub of dialogSubs) {+ expect(sub.group).toBe('Dialog');+ expect(sub.directory).toBe('Dialog');+ }+ });++ it('sub-components have their own descriptions', () => {+ const core = components['@xds/core'];+ const dialogHeader = core.find(c => c.name === 'DialogHeader');+ expect(dialogHeader).toBeDefined();+ expect(dialogHeader!.description.length).toBeGreaterThan(10);+ // Description should be specific to DialogHeader, not the parent Dialog+ expect(dialogHeader!.description.toLowerCase()).toContain('header');+ });++ it('Chat has many sub-components (standalone docs take priority over compound entries)', () => {+ const core = components['@xds/core'];+ // Chat compound doc has 14 sub-components, but ChatToolCalls has its own+ // standalone doc so it appears with parentDoc: null instead of parentDoc: 'Chat'+ const chatSubs = core.filter(c => c.parentDoc === 'Chat');+ expect(chatSubs.length).toBeGreaterThanOrEqual(12);+ const chatNames = chatSubs.map(c => c.name);+ expect(chatNames).toContain('ChatMessage');+ expect(chatNames).toContain('ChatComposer');+ expect(chatNames).toContain('ChatSendButton');++ // ChatToolCalls should exist but as a standalone entry+ const toolCalls = core.find(c => c.name === 'ChatToolCalls');+ expect(toolCalls).toBeDefined();+ // It's standalone (has its own doc.mjs), not a sub-component+ expect(toolCalls!.parentDoc).toBeNull();+ });++ it('simple components have null parentDoc', () => {+ const core = components['@xds/core'];+ const button = core.find(c => c.name === 'Button');+ expect(button).toBeDefined();+ expect(button!.parentDoc).toBeNull();});- it('name comes from docs.name, not directory name', () => {+ it('displayName has XDS prefix for components, not for hooks', () => {const core = components['@xds/core'];- // CodeBlock dir has file XDSCodeBlock.doc.mjs with docs.name = 'CodeBlock'- const codeBlock = core.find(c => c.name === 'CodeBlock');- expect(codeBlock).toBeDefined();- expect(codeBlock?.directory).toBe('CodeBlock');+ const button = core.find(c => c.name === 'Button');+ expect(button?.displayName).toBe('XDSButton');- // hooks dir has multiple docs with names like 'useClickableContainer'- const hookComponent = core.find(c => c.name === 'useClickableContainer');- expect(hookComponent).toBeDefined();- expect(hookComponent?.directory).toBe('hooks');+ const hookComp = core.find(c => c.name === 'useClickableContainer');+ expect(hookComp?.displayName).toBe('useClickableContainer');++ // Sub-component hooks also keep their name+ const tableHook = core.find(c => c.name === 'useXDSTableSelection');+ if (tableHook) {+ expect(tableHook.displayName).toMatch(/^use/);+ }});+ // ── Discovery coverage ─────────────────────────────────────────────+it('discovers hooks (not skipped)', () => {const core = components['@xds/core'];const hooks = core.filter(c => c.directory === 'hooks');expect(hooks.length).toBeGreaterThan(8);- // Verify names are the hook names, not 'hooks'for (const hook of hooks) {expect(hook.name).toMatch(/^use[A-Z]/);}@@ -112,37 +170,34 @@ describe('componentRegistry', () => {expect(names).toContain('MediaTheme');});- it('discovers multiple docs per directory (Chat has multiple)', () => {- const core = components['@xds/core'];- const chatComponents = core.filter(c => c.directory === 'Chat');- // Chat dir has ChatDictationButton (hidden) + ChatToolCalls (visible) + main Chat doc- expect(chatComponents.length).toBeGreaterThanOrEqual(2);- });-it('hidden components are included with hidden flag', () => {const core = components['@xds/core'];const names = core.map(c => c.name);- // All components should be present regardless of hidden flagexpect(names).toContain('ChatDictationButton');expect(names).toContain('NavMenuItem');- // Currently no components are hiddenconst hiddenCount = core.filter(c => c.hidden).length;expect(hiddenCount).toBe(0);});- it('components have group assignments', () => {- const withGroups = components['@xds/core'].filter(c => c.group !== null);- expect(withGroups.length).toBeGreaterThan(- components['@xds/core'].length * 0.3,- );- });-it('no duplicate component names within a package', () => {for (const [, comps] of Object.entries(components)) {const names = comps.map(c => c.name);- expect(new Set(names).size).toBe(names.length);+ const dupes = names.filter((n, i) => names.indexOf(n) !== i);+ expect(dupes).toEqual([]);}});++ it('known compound docs are expanded, not emitted as single entries', () => {+ const core = components['@xds/core'];+ const names = core.map(c => c.name);+ // These are parent doc names that should NOT appear as component names+ // because they were expanded into sub-components+ // (unless the sub-component itself is named the same, like Table → XDSTable → Table)+ // Verify the sub-components exist instead+ expect(names).toContain('DialogHeader'); // from Dialog compound doc+ expect(names).toContain('SideNavItem'); // from SideNav compound doc+ expect(names).toContain('TopNavItem'); // from TopNav compound doc+ });});// ── Block Registry ─────────────────────────────────────────────────────@@ -173,12 +228,10 @@ describe('blockRegistry', () => {});it('aspect ratios are parsed correctly (no eval)', () => {- // 16/9 should parse to ~1.777const wideBlocks = blocks.filter(b => Math.abs(b.aspectRatio - 16 / 9) < 0.01,);expect(wideBlocks.length).toBeGreaterThan(0);- // 4/3 should parse to ~1.333const standardBlocks = blocks.filter(b => Math.abs(b.aspectRatio - 4 / 3) < 0.01,);