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.mjsindex 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 + loadersconst 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.tsxindex 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.tsxindex 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.tsxindex 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>);}