An open source design system that's fully customizable and agent ready
TypeScript
feat(docsite): extract full component docs and block source at build time (#1965)
Cindy Zhangc37e5afc0bbf
diff --git a/apps/docsite/scripts/generate-data.mjs b/apps/docsite/scripts/generate-data.mjsindex 42b047dcfd..2f49036f5e 100644--- a/apps/docsite/scripts/generate-data.mjs+++ b/apps/docsite/scripts/generate-data.mjs@@ -169,11 +169,17 @@ export const packages: PackageMeta[] = ${JSON.stringify(packages, null, 2)};// ── 2. Component Registry ──────────────────────────────────────────────+/** Sanitize a doc object for JSON serialization (strip functions, symbols, etc.) */+function sanitizeForJson(obj) {+ return JSON.parse(JSON.stringify(obj, (key, value) => {+ if (typeof value === 'function' || typeof value === 'symbol') return undefined;+ return value;+ }));+}+async function generateComponentRegistry() {console.log('Generating component registry...');- // Auto-discover component packages: any package with a src/ dir containing- // subdirectories that have .doc.mjs files.const packageDirs = discoverPackageDirs();const componentPackages = [];@@ -195,8 +201,6 @@ async 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 = [];@@ -224,9 +228,10 @@ async function generateComponentRegistry() {const keywords = doc.keywords || [];const hidden = doc.hidden ?? false;const topDescription = doc.usage?.description || doc.description || '';+ const usage = doc.usage ? sanitizeForJson(doc.usage) : null;+ const theming = doc.theming ? sanitizeForJson(doc.theming) : null;if (doc.components && doc.components.length > 0) {- // Compound component — queue sub-components for second passfor (const sub of doc.components) {const subName = (sub.name || '').replace(/^XDS/, '');if (!subName) continue;@@ -239,10 +244,38 @@ async function generateComponentRegistry() {keywords,hidden,parentDoc: doc.name,+ props: Array.isArray(sub.props) ? sanitizeForJson(sub.props) : [],+ usage,+ theming,+ params: null,+ returns: null,+ relatedComponents: null,+ relatedHooks: null,});}+ } else if (doc.params) {+ // HookDoc — standalone hook+ const name = doc.name || docFileName.replace('.doc.mjs', '');+ standaloneNames.add(name);+ components.push({+ name,+ moduleName: name,+ directory: entry.name,+ group,+ description: topDescription,+ keywords,+ hidden,+ parentDoc: null,+ props: [],+ usage,+ theming: null,+ params: Array.isArray(doc.params) ? sanitizeForJson(doc.params) : [],+ returns: Array.isArray(doc.returns) ? sanitizeForJson(doc.returns) : [],+ relatedComponents: doc.relatedComponents || null,+ relatedHooks: doc.relatedHooks || null,+ });} else {- // Simple/standalone component — add directly+ // Simple/standalone componentconst name = doc.name || docFileName.replace('.doc.mjs', '').replace(/^XDS/, '');standaloneNames.add(name);components.push({@@ -254,15 +287,21 @@ async function generateComponentRegistry() {keywords,hidden,parentDoc: null,+ props: Array.isArray(doc.props) ? sanitizeForJson(doc.props) : [],+ usage,+ theming,+ params: null,+ returns: null,+ relatedComponents: null,+ relatedHooks: null,});}}}- // Second pass: add sub-components only if no standalone doc existsfor (const sub of pendingSubComponents) {if (!standaloneNames.has(sub.name)) {- standaloneNames.add(sub.name); // prevent duplicates from multiple compound docs+ standaloneNames.add(sub.name);components.push(sub);}}@@ -276,23 +315,93 @@ async function generateComponentRegistry() {const content = `// Auto-generated by scripts/generate-data.mjs — do not edit+export interface PropDoc {+ name: string;+ type: string;+ description: string;+ default?: string;+ required?: boolean;+}++export interface BestPractice {+ guidance: boolean;+ description: string;+}++export interface AnatomyElement {+ name: string;+ required: boolean;+ description: string;+}++export interface UsageDoc {+ description: string;+ bestPractices?: BestPractice[];+ anatomy?: AnatomyElement[];+ features?: string[];+ accessibility?: string[];+ keyboard?: string;+ notes?: string[];+}++export interface ThemingTarget {+ className: string;+ visualProps?: string[];+ states?: string[];+}++export interface ComponentVar {+ name: string;+ description: string;+ default: string;+ derived?: boolean;+ formula?: string;+ private?: boolean;+}++export interface DerivedVar {+ property: string;+ vars?: string[];+ expand?: 'container';+}++export interface ThemingDoc {+ container?: boolean;+ targets: ThemingTarget[];+ vars?: ComponentVar[];+ derived?: DerivedVar[];+}++export interface HookParamDoc {+ name: string;+ type: string;+ description: string;+ default?: string;+ required?: boolean;+}++export interface HookReturnDoc {+ name: string;+ type: string;+ description: string;+}+export interface ComponentEntry {- /** Component name without XDS prefix (e.g. 'Button', 'TableRow', 'useClickableContainer') */name: string;- /** Actual exported module name (e.g. 'XDSButton', 'XDSTableRow', 'useClickableContainer') */moduleName: string;- /** Source directory containing this component (e.g. 'Button', 'hooks', 'Table') */directory: string;- /** Sidebar group from docs.group (e.g. 'Actions', 'Chat', 'Table') */group: string | null;- /** 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;+ props: PropDoc[];+ usage: UsageDoc | null;+ theming: ThemingDoc | null;+ params: HookParamDoc[] | null;+ returns: HookReturnDoc[] | null;+ relatedComponents: string[] | null;+ relatedHooks: string[] | null;}export const components: Record<string, ComponentEntry[]> = ${JSON.stringify(allComponents, null, 2)};@@ -345,6 +454,11 @@ async function generateBlockRegistry() {}} catch { /* ignore */ }+ let source = '';+ try {+ source = fs.readFileSync(tsxPath, 'utf-8');+ } catch { /* ignore */ }+blocks.push({dirName: basename,name: meta.name || basename,@@ -354,6 +468,7 @@ async function generateBlockRegistry() {aspectRatio,componentsUsed,category: relCategory,+ source,});}@@ -374,6 +489,8 @@ export interface BlockEntry {componentsUsed: string[];/** Category path, e.g. 'components/Button' */category: string;+ /** Raw TSX source code for live rendering */+ source: string;}export const blocks: BlockEntry[] = ${JSON.stringify(blocks, null, 2)};diff --git a/apps/docsite/src/__tests__/data-extraction.test.ts b/apps/docsite/src/__tests__/data-extraction.test.tsindex fcbda600ca..330592670b 100644--- a/apps/docsite/src/__tests__/data-extraction.test.ts+++ b/apps/docsite/src/__tests__/data-extraction.test.ts@@ -217,6 +217,76 @@ describe('componentRegistry', () => {expect(names).toContain('SideNavItem'); // from SideNav compound docexpect(names).toContain('TopNavItem'); // from TopNav compound doc});++ // ── Full doc extraction ──────────────────────────────────────────++ it('extracts props for standalone components', () => {+ const core = components['@xds/core'];+ const button = core.find(c => c.name === 'Button');+ expect(button).toBeDefined();+ expect(button!.props.length).toBeGreaterThan(5);+ const labelProp = button!.props.find(p => p.name === 'label');+ expect(labelProp).toBeDefined();+ expect(labelProp!.type).toBe('string');+ expect(labelProp!.required).toBe(true);+ });++ it('extracts props for sub-components in compound docs', () => {+ const core = components['@xds/core'];+ const dialog = core.find(c => c.name === 'Dialog');+ expect(dialog).toBeDefined();+ expect(dialog!.props.length).toBeGreaterThan(3);+ const isOpenProp = dialog!.props.find(p => p.name === 'isOpen');+ expect(isOpenProp).toBeDefined();+ expect(isOpenProp!.required).toBe(true);+ });++ it('extracts usage with bestPractices and anatomy', () => {+ const core = components['@xds/core'];+ const button = core.find(c => c.name === 'Button');+ expect(button!.usage).toBeDefined();+ expect(button!.usage!.description.length).toBeGreaterThan(20);+ expect(button!.usage!.bestPractices).toBeDefined();+ expect(button!.usage!.bestPractices!.length).toBeGreaterThanOrEqual(3);+ expect(button!.usage!.anatomy).toBeDefined();+ expect(button!.usage!.anatomy!.length).toBeGreaterThanOrEqual(2);+ });++ it('extracts theming data', () => {+ const core = components['@xds/core'];+ const button = core.find(c => c.name === 'Button');+ expect(button!.theming).toBeDefined();+ expect(button!.theming!.targets.length).toBeGreaterThanOrEqual(1);+ expect(button!.theming!.targets[0].className).toBe('xds-button');+ expect(button!.theming!.vars).toBeDefined();+ expect(button!.theming!.vars!.length).toBeGreaterThanOrEqual(1);+ });++ it('extracts hook params and returns', () => {+ const core = components['@xds/core'];+ const hook = core.find(c => c.name === 'useMediaQuery');+ expect(hook).toBeDefined();+ expect(hook!.params).toBeDefined();+ expect(hook!.params!.length).toBeGreaterThanOrEqual(1);+ expect(hook!.params![0].name).toBe('query');+ expect(hook!.returns).toBeDefined();+ expect(hook!.returns!.length).toBeGreaterThanOrEqual(1);+ });++ it('components without props have empty props array', () => {+ const core = components['@xds/core'];+ for (const comp of core) {+ expect(Array.isArray(comp.props)).toBe(true);+ }+ });++ it('most standalone components have usage data', () => {+ const core = components['@xds/core'];+ const standalone = core.filter(c => c.parentDoc === null);+ const withUsage = standalone.filter(c => c.usage != null);+ // At least 80% should have usage docs+ expect(withUsage.length / standalone.length).toBeGreaterThan(0.8);+ });});// ── Block Registry ─────────────────────────────────────────────────────@@ -294,6 +364,21 @@ describe('blockRegistry', () => {);expect(blocksWithComponents.length).toBeGreaterThan(blocks.length * 0.5);});++ it('blocks include TSX source code', () => {+ for (const block of blocks) {+ expect(typeof block.source).toBe('string');+ expect(block.source.length).toBeGreaterThan(0);+ }+ });++ it('showcase sources contain valid JSX', () => {+ const showcases = blocks.filter(b => b.isShowcase);+ for (const s of showcases) {+ // Every showcase should have an export default function+ expect(s.source).toMatch(/export default function/);+ }+ });});// ── Template Registry ──────────────────────────────────────────────────