Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

feat(docsite): render live example blocks with preview + Description/Code tabs (#1998)

Cindy Zhange905e3af4e6c
diff --git a/apps/docsite/scripts/generate-data.mjs b/apps/docsite/scripts/generate-data.mjs
index f40eb92a92..555163fc4d 100644
--- a/apps/docsite/scripts/generate-data.mjs
+++ b/apps/docsite/scripts/generate-data.mjs
@@ -779,11 +779,15 @@ function generateExampleRegistry() {
fs.copyFileSync(tsxSrc, path.join(EXAMPLES_OUT, `${basename}.tsx`));
+ let source = '';
+ try { source = fs.readFileSync(tsxSrc, 'utf-8'); } catch { /* ignore */ }
+
entries.push({
exampleFor,
basename,
name: nameMatch?.[1] || basename,
description: descMatch?.[1] || '',
+ source,
});
}
@@ -797,7 +801,7 @@ function generateExampleRegistry() {
// Generate registry: component name → array of example metadata + loaders
const componentLines = Object.entries(grouped).map(([comp, examples]) => {
const exampleLines = examples.map(
- e => ` {name: ${JSON.stringify(e.name)}, description: ${JSON.stringify(e.description)}, load: () => import('./examples/${e.basename}')},`
+ e => ` {name: ${JSON.stringify(e.name)}, description: ${JSON.stringify(e.description)}, source: ${JSON.stringify(e.source)}, load: () => import('./examples/${e.basename}')},`
).join('\n');
return ` '${comp}': [\n${exampleLines}\n ],`;
}).join('\n');
@@ -808,6 +812,7 @@ import type {ComponentType} from 'react';
export interface ExampleEntry {
name: string;
description: string;
+ source: string;
load: () => Promise<{default: ComponentType}>;
}
diff --git a/apps/docsite/src/app/components/[name]/page.tsx b/apps/docsite/src/app/components/[name]/page.tsx
index f30326b993..574fb8e092 100644
--- a/apps/docsite/src/app/components/[name]/page.tsx
+++ b/apps/docsite/src/app/components/[name]/page.tsx
@@ -34,7 +34,6 @@ export default async function ComponentPage({
const componentBlocks = blocks.filter(b => b.exampleFor === name);
const showcase = componentBlocks.find(b => b.isShowcase);
- const examples = componentBlocks.filter(b => !b.isShowcase);
return (
<ComponentDetailClient
@@ -43,7 +42,6 @@ export default async function ComponentPage({
pkgVersion={pkgVersion}
subComponents={subComponents}
showcase={showcase}
- examples={examples}
/>
);
}
diff --git a/apps/docsite/src/components/component-detail/ComponentDetailClient.tsx b/apps/docsite/src/components/component-detail/ComponentDetailClient.tsx
index 4094150f3b..6741bce8a0 100644
--- a/apps/docsite/src/components/component-detail/ComponentDetailClient.tsx
+++ b/apps/docsite/src/components/component-detail/ComponentDetailClient.tsx
@@ -22,6 +22,7 @@ import {PlaygroundPropsTable} from './PlaygroundPropsTable';
import type {ComponentEntry} from '../../generated/componentRegistry';
import type {BlockEntry} from '../../generated/blockRegistry';
import {showcaseRegistry} from '../../generated/showcaseRegistry';
+import {exampleRegistry} from '../../generated/exampleRegistry';
interface ComponentDetailClientProps {
comp: ComponentEntry;
@@ -29,15 +30,13 @@ interface ComponentDetailClientProps {
pkgVersion: string | undefined;
subComponents: ComponentEntry[];
showcase: BlockEntry | undefined;
- examples: BlockEntry[];
}
function OverviewContent({
comp,
pkg,
subComponents,
- showcase,
- examples,
+ showcase: _showcase,
hasShowcase,
}: ComponentDetailClientProps & {hasShowcase: boolean}) {
const isHook = comp.params != null;
@@ -97,7 +96,7 @@ function OverviewContent({
</>
)}
- {examples.length > 0 && (
+ {(exampleRegistry[comp.name] || []).length > 0 && (
<>
<XDSDivider />
<XDSVStack gap={6}>
@@ -107,22 +106,12 @@ function OverviewContent({
</XDSText>
</XDSVStack>
<XDSVStack gap={8}>
- {examples.map(block => (
- <ExampleBlock key={block.dirName} block={block} />
+ {(exampleRegistry[comp.name] || []).map((entry, i) => (
+ <ExampleBlock key={i} entry={entry} />
))}
</XDSVStack>
</>
)}
-
- {showcase && (
- <>
- <XDSDivider />
- <XDSVStack gap={2}>
- <XDSHeading level={3}>Showcase source</XDSHeading>
- <XDSCodeBlock code={showcase.source} language="tsx" hasCopyButton />
- </XDSVStack>
- </>
- )}
</XDSVStack>
);
}
@@ -133,7 +122,6 @@ function ComponentDetailInner({
pkgVersion,
subComponents,
showcase,
- examples,
}: ComponentDetailClientProps) {
const searchParams = useSearchParams();
const router = useRouter();
@@ -167,8 +155,8 @@ function ComponentDetailInner({
<XDSVStack gap={2}>
<XDSText type="display-1">{comp.name}</XDSText>
<XDSText type="supporting" color="secondary">
- {pkg} · {comp.moduleName}
- {pkgVersion ? ` v${pkgVersion}` : ''}
+ {pkg}
+ {pkgVersion ? ` v${pkgVersion}` : ''} · {comp.moduleName}
</XDSText>
</XDSVStack>
@@ -186,7 +174,6 @@ function ComponentDetailInner({
pkgVersion={pkgVersion}
subComponents={subComponents}
showcase={showcase}
- examples={examples}
hasShowcase={hasShowcase}
/>
)}
@@ -231,7 +218,6 @@ function ComponentDetailInner({
pkgVersion={pkgVersion}
subComponents={subComponents}
showcase={showcase}
- examples={examples}
hasShowcase={hasShowcase}
/>
</>
diff --git a/apps/docsite/src/components/component-detail/ExampleBlock.tsx b/apps/docsite/src/components/component-detail/ExampleBlock.tsx
index 25adc072f3..5e25fe0384 100644
--- a/apps/docsite/src/components/component-detail/ExampleBlock.tsx
+++ b/apps/docsite/src/components/component-detail/ExampleBlock.tsx
@@ -1,33 +1,91 @@
'use client';
+import {useEffect, useState, type ComponentType} from 'react';
import {XDSCard} from '@xds/core/Card';
-import {XDSVStack} from '@xds/core/Layout';
+import {XDSSection} from '@xds/core/Section';
+import {XDSCenter} from '@xds/core/Center';
import {XDSText} from '@xds/core/Text';
import {XDSCodeBlock} from '@xds/core/CodeBlock';
-import type {BlockEntry} from '../../generated/blockRegistry';
+import {XDSTabList, XDSTab} from '@xds/core/TabList';
+import {XDSSpinner} from '@xds/core/Spinner';
+import type {ExampleEntry} from '../../generated/exampleRegistry';
+
+function LivePreview({entry}: {entry: ExampleEntry}) {
+ const [Component, setComponent] = useState<ComponentType | null>(null);
+ const [error, setError] = useState(false);
+
+ useEffect(() => {
+ entry
+ .load()
+ .then(mod => setComponent(() => mod.default))
+ .catch(() => setError(true));
+ }, [entry]);
+
+ if (error) {
+ return (
+ <XDSCenter style={{minHeight: 200, width: '100%'}}>
+ <XDSText type="supporting" color="secondary">
+ Preview not available
+ </XDSText>
+ </XDSCenter>
+ );
+ }
+
+ if (!Component) {
+ return (
+ <XDSCenter style={{minHeight: 200, width: '100%'}}>
+ <XDSSpinner size="md" />
+ </XDSCenter>
+ );
+ }
+
+ return (
+ <div
+ style={{
+ width: '100%',
+ overflow: 'auto',
+ minHeight: 200,
+ display: 'flex',
+ alignItems: 'center',
+ justifyContent: 'center',
+ }}>
+ <div style={{minWidth: 'fit-content', padding: 'var(--spacing-4)'}}>
+ <Component />
+ </div>
+ </div>
+ );
+}
interface ExampleBlockProps {
- block: BlockEntry;
+ entry: ExampleEntry;
}
-export function ExampleBlock({block}: ExampleBlockProps) {
+export function ExampleBlock({entry}: ExampleBlockProps) {
+ const [tab, setTab] = useState<string>('description');
+
return (
- <XDSCard padding={0}>
- <XDSVStack gap={0}>
- <div style={{padding: 'var(--spacing-3) var(--spacing-4)'}}>
- <XDSVStack gap={1}>
- <XDSText type="body" weight="bold">
- {block.name}
- </XDSText>
- {block.description && (
- <XDSText type="supporting" color="secondary">
- {block.description}
- </XDSText>
- )}
- </XDSVStack>
- </div>
- <XDSCodeBlock code={block.source} language="tsx" hasCopyButton />
- </XDSVStack>
+ <XDSCard padding={3}>
+ <XDSText type="body" weight="medium">
+ {entry.name}
+ </XDSText>
+
+ <LivePreview entry={entry} />
+
+ <XDSSection variant="wash" padding={0} dividers={['top']}>
+ <XDSTabList value={tab} onChange={setTab} size="sm">
+ <XDSTab value="description" label="Description" />
+ <XDSTab value="code" label="Code" />
+ </XDSTabList>
+ </XDSSection>
+ <XDSSection variant="wash">
+ {tab === 'description' ? (
+ <XDSText type="body">
+ {entry.description || 'No description available.'}
+ </XDSText>
+ ) : (
+ <XDSCodeBlock code={entry.source} language="tsx" hasCopyButton />
+ )}
+ </XDSSection>
</XDSCard>
);
}