Skip to content

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.mjs
index 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 pass
for (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 component
const 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 exists
for (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.ts
index 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 doc
expect(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 ──────────────────────────────────────────────────