An open source design system that's fully customizable and agent ready
TypeScript
feat(docsite): render live showcase previews on component detail pages (#1982)
Cindy Zhang9c614decaf0b
diff --git a/apps/docsite/scripts/generate-data.mjs b/apps/docsite/scripts/generate-data.mjsindex 2f49036f5e..119eaf7888 100644--- a/apps/docsite/scripts/generate-data.mjs+++ b/apps/docsite/scripts/generate-data.mjs@@ -680,6 +680,70 @@ ${entries}return themePackages.length;}+// ── 7. Showcase Registry ───────────────────────────────────────────────++function generateShowcaseRegistry() {+ console.log('Generating showcase registry...');++ const BLOCKS_DIR = path.join(CLI_ROOT, 'templates', 'blocks');+ const SHOWCASE_OUT = path.join(OUT_DIR, 'showcases');++ // Clean and recreate+ if (fs.existsSync(SHOWCASE_OUT)) {+ fs.rmSync(SHOWCASE_OUT, {recursive: true});+ }+ fs.mkdirSync(SHOWCASE_OUT, {recursive: true});++ const docFiles = findDocFilesRecursive(BLOCKS_DIR);+ const entries = [];++ for (const docPath of docFiles) {+ const content = fs.readFileSync(docPath, 'utf-8');+ if (!/isShowcase:\s*true/.test(content)) continue;++ const efMatch = content.match(/exampleFor:\s*['"]([^'"]+)['"]/);+ if (!efMatch) continue;++ const exampleFor = efMatch[1];+ const basename = path.basename(docPath, '.doc.mjs');+ const tsxSrc = path.join(path.dirname(docPath), basename + '.tsx');+ if (!fs.existsSync(tsxSrc)) continue;++ // Copy the TSX file into generated/showcases/+ const destFile = `${basename}.tsx`;+ fs.copyFileSync(tsxSrc, path.join(SHOWCASE_OUT, destFile));++ entries.push({exampleFor, basename, destFile});+ }++ // Deduplicate: one showcase per component (first wins)+ const seen = new Set();+ const uniqueEntries = entries.filter(e => {+ if (seen.has(e.exampleFor)) return false;+ seen.add(e.exampleFor);+ return true;+ });++ // Generate the registry with dynamic imports+ const importLines = uniqueEntries.map(+ e => ` '${e.exampleFor}': () => import('./showcases/${e.basename}'),`+ ).join('\n');++ const registryContent = `// Auto-generated by scripts/generate-data.mjs — do not edit+import type {ComponentType} from 'react';++type ShowcaseLoader = () => Promise<{default: ComponentType}>;++export const showcaseRegistry: Record<string, ShowcaseLoader> = {+${importLines}+};+`;++ writeRegistry('showcaseRegistry.ts', registryContent);+ console.log(` copied ${entries.length} showcase files (${uniqueEntries.length} unique components)`);+ return uniqueEntries.length;+}+// ── Mainasync function main() {@@ -691,11 +755,12 @@ async function main() {const {blockCount, showcaseCount} = await generateBlockRegistry();const {templateCount} = await generateTemplateRegistry();const {docsCount} = await generateDocsRegistry();+ const showcaseCopied = generateShowcaseRegistry();console.log(`\nSummary:`);console.log(` ${packages.length} packages`);console.log(` ${componentCount} components`);- console.log(` ${blockCount} blocks (${showcaseCount} showcases)`);+ console.log(` ${blockCount} blocks (${showcaseCount} showcases, ${showcaseCopied} copied)`);console.log(` ${templateCount} templates`);console.log(` ${docsCount} doc topics`);console.log(` ${themeCount} themes`);diff --git a/apps/docsite/src/__tests__/data-extraction.test.ts b/apps/docsite/src/__tests__/data-extraction.test.tsindex 330592670b..0feff7a78f 100644--- a/apps/docsite/src/__tests__/data-extraction.test.ts+++ b/apps/docsite/src/__tests__/data-extraction.test.ts@@ -12,6 +12,7 @@ import {components, componentCount} from '../generated/componentRegistry';import {blocks, blockCount, showcaseCount} from '../generated/blockRegistry';import {templates, templateCount} from '../generated/templateRegistry';import {docTopics, docsCount} from '../generated/docsRegistry';+import {showcaseRegistry} from '../generated/showcaseRegistry';// ── Package Registry ───────────────────────────────────────────────────@@ -492,3 +493,45 @@ describe('themeRegistry', () => {}});});++// ── Showcase Registry ──────────────────────────────────────────────────++describe('showcaseRegistry', () => {+ it('has showcase loaders for many components', () => {+ const keys = Object.keys(showcaseRegistry);+ expect(keys.length).toBeGreaterThan(100);+ });++ it('every entry is a function (dynamic import loader)', () => {+ for (const [key, loader] of Object.entries(showcaseRegistry)) {+ expect(typeof loader).toBe('function');+ }+ });++ it('has showcases for known components', () => {+ expect(showcaseRegistry['Button']).toBeDefined();+ expect(showcaseRegistry['Dialog']).toBeDefined();+ expect(showcaseRegistry['Table']).toBeDefined();+ expect(showcaseRegistry['Card']).toBeDefined();+ });++ it('no duplicate keys (one showcase per component)', () => {+ const keys = Object.keys(showcaseRegistry);+ expect(new Set(keys).size).toBe(keys.length);+ });++ it('showcase files exist on disk', () => {+ const showcaseDir = new URL('../generated/showcases', import.meta.url);+ const files = fs.readdirSync(showcaseDir);+ expect(files.length).toBeGreaterThan(100);+ expect(files.every(f => f.endsWith('.tsx'))).toBe(true);+ });++ it('showcase file count matches registry entries', () => {+ const showcaseDir = new URL('../generated/showcases', import.meta.url);+ const files = fs.readdirSync(showcaseDir);+ const keys = Object.keys(showcaseRegistry);+ // Files may be more than keys due to dedup, but keys should not exceed files+ expect(keys.length).toBeLessThanOrEqual(files.length);+ });+});diff --git a/apps/docsite/src/app/components/[name]/page.tsx b/apps/docsite/src/app/components/[name]/page.tsxindex 91fc31bd7b..801cfb5a67 100644--- a/apps/docsite/src/app/components/[name]/page.tsx+++ b/apps/docsite/src/app/components/[name]/page.tsx@@ -21,6 +21,7 @@ import {BestPractices} from '../../../components/component-detail/BestPractices'import {Anatomy} from '../../../components/component-detail/Anatomy';import {HookSignature} from '../../../components/component-detail/HookSignature';import {ExampleBlock} from '../../../components/component-detail/ExampleBlock';+import {ShowcasePreview} from '../../../components/component-detail/ShowcasePreview';const allComponents = Object.values(components).flat();@@ -70,9 +71,7 @@ export default async function ComponentPage({{/* Preview */}<XDSCard variant="muted" padding={0}><XDSCenter height={360}>- <XDSText type="supporting" color="secondary">- Preview coming soon- </XDSText>+ <ShowcasePreview name={name} /></XDSCenter></XDSCard>diff --git a/apps/docsite/src/components/component-detail/ShowcasePreview.tsx b/apps/docsite/src/components/component-detail/ShowcasePreview.tsxnew file mode 100644index 0000000000..4903394024--- /dev/null+++ b/apps/docsite/src/components/component-detail/ShowcasePreview.tsx@@ -0,0 +1,47 @@+'use client';++import {useEffect, useState, type ComponentType} from 'react';+import {XDSCenter} from '@xds/core/Center';+import {XDSText} from '@xds/core/Text';+import {XDSSpinner} from '@xds/core/Spinner';+import {showcaseRegistry} from '../../generated/showcaseRegistry';++interface ShowcasePreviewProps {+ name: string;+}++export function ShowcasePreview({name}: ShowcasePreviewProps) {+ const [Component, setComponent] = useState<ComponentType | null>(null);+ const [error, setError] = useState(false);++ useEffect(() => {+ const loader = showcaseRegistry[name];+ if (!loader) {+ setError(true);+ return;+ }+ loader()+ .then(mod => setComponent(() => mod.default))+ .catch(() => setError(true));+ }, [name]);++ if (error) {+ return (+ <XDSCenter height={360}>+ <XDSText type="supporting" color="secondary">+ Preview not available+ </XDSText>+ </XDSCenter>+ );+ }++ if (!Component) {+ return (+ <XDSCenter height={360}>+ <XDSSpinner size="md" />+ </XDSCenter>+ );+ }++ return <Component />;+}