Skip to content

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.mjs
index 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;
+}
+
// ── Main
async 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.ts
index 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.tsx
index 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.tsx
new file mode 100644
index 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 />;
+}