An open source design system that's fully customizable and agent ready
TypeScript
feat(docsite): build component detail page with full doc rendering (#1975)
Cindy Zhang3bcf78ca564b
diff --git a/apps/docsite/src/app/components/[name]/page.tsx b/apps/docsite/src/app/components/[name]/page.tsxindex 2b176be373..91fc31bd7b 100644--- a/apps/docsite/src/app/components/[name]/page.tsx+++ b/apps/docsite/src/app/components/[name]/page.tsx@@ -1,28 +1,30 @@/**- * Page type: component- * Component or hook/utility detail page. Adapts based on content:- * - Visual components: showcase + props + anatomy + examples- * - Hooks/utilities: params + usage (no showcase if none exists)- * - Compound components: also lists sub-components- *- * All data comes from componentRegistry. Sub-components (parentDoc != null)- * are shown on their parent's page, not as standalone routes.+ * Component detail page.+ * Adapts based on content:+ * - Visual components: showcase + usage + anatomy + props + examples+ * - Hooks/utilities: usage + params/returns + examples+ * - Compound components: also lists sub-components with their props*/import {notFound} from 'next/navigation';import {XDSHeading, XDSText} from '@xds/core/Text';-import {XDSVStack, XDSHStack} from '@xds/core/Layout';+import {XDSVStack} from '@xds/core/Layout';import {XDSSection} from '@xds/core/Section';import {XDSCard} from '@xds/core/Card';-import {XDSBadge} from '@xds/core/Badge';+import {XDSCenter} from '@xds/core/Center';import {XDSDivider} from '@xds/core';+import {XDSCodeBlock} from '@xds/core/CodeBlock';import {components} from '../../../generated/componentRegistry';+import {blocks} from '../../../generated/blockRegistry';+import {PropsTable} from '../../../components/component-detail/PropsTable';+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';const allComponents = Object.values(components).flat();export function generateStaticParams() {- // Generate routes for top-level components only.- // Sub-components are rendered on their parent's page.return allComponents.filter(c => !c.parentDoc).map(c => ({name: c.name}));}@@ -40,54 +42,135 @@ export default async function ComponentPage({comps.includes(comp),)?.[0];+ const isHook = comp.params != null;++ const componentBlocks = blocks.filter(b => b.exampleFor === name);+ const showcase = componentBlocks.find(b => b.isShowcase);+ const examples = componentBlocks.filter(b => !b.isShowcase);++ const importPath = `import {${comp.moduleName}} from '${pkg}/${comp.directory}'`;+return (- <XDSSection maxWidth="md" padding={6}>- <XDSVStack gap={6}>+ <XDSSection+ maxWidth={960}+ padding={8}+ variant="transparent"+ style={{marginInline: 'auto'}}>+ <XDSVStack gap={8}>{/* Header */}<XDSVStack gap={2}>- <XDSText type="supporting" color="secondary" weight="bold">- {comp.moduleName}- </XDSText>- <XDSHeading level={1}>{comp.name}</XDSHeading>- <XDSText type="body" color="secondary">- {comp.description}+ <XDSText type="display-1">{comp.moduleName}</XDSText>+ <XDSText type="supporting" color="secondary">+ {pkg} · {comp.directory}</XDSText>- <XDSHStack gap={2}>- {comp.group && <XDSBadge label={comp.group} />}- {pkg && <XDSBadge label={pkg} variant="info" />}- </XDSHStack></XDSVStack>- {/* TODO: showcase section — render if blockRegistry has a showcase for this component */}+ <XDSDivider />- {/* TODO: props table — render from pipeline data */}+ {/* Preview */}+ <XDSCard variant="muted" padding={0}>+ <XDSCenter height={360}>+ <XDSText type="supporting" color="secondary">+ Preview coming soon+ </XDSText>+ </XDSCenter>+ </XDSCard>- {/* TODO: anatomy — render if doc has anatomy data */}+ {/* Usage + Best Practices */}+ {comp.usage && (+ <XDSVStack gap={8}>+ <XDSHeading level={2}>Usage</XDSHeading>+ <XDSText type="large" weight="normal">+ {comp.usage.description}+ </XDSText>++ {comp.usage.bestPractices &&+ comp.usage.bestPractices.length > 0 && (+ <BestPractices practices={comp.usage.bestPractices} />+ )}++ {comp.usage.anatomy && comp.usage.anatomy.length > 0 && (+ <Anatomy elements={comp.usage.anatomy} />+ )}+ </XDSVStack>+ )}- {/* TODO: examples — render from blockRegistry matches */}+ {/* Hook params/returns */}+ {isHook && comp.params && comp.returns && (+ <HookSignature params={comp.params} returns={comp.returns} />+ )}++ {/* Import */}+ <XDSVStack gap={2}>+ <XDSHeading level={3}>Import</XDSHeading>+ <XDSCodeBlock code={importPath} language="ts" hasCopyButton />+ </XDSVStack>++ {/* Props */}+ {!isHook && comp.props.length > 0 && (+ <XDSVStack gap={3}>+ <XDSHeading level={2}>Props</XDSHeading>+ <PropsTable props={comp.props} />+ </XDSVStack>+ )}{/* Sub-components */}{subComponents.length > 0 && (<><XDSDivider />- <XDSVStack gap={4}>- <XDSHeading level={2}>- Sub-components ({subComponents.length})- </XDSHeading>- <XDSVStack gap={3}>- {subComponents.map(sub => (- <XDSCard key={sub.name} padding={4}>- <XDSVStack gap={1}>- <XDSText type="body" weight="bold">- {sub.moduleName}- </XDSText>- <XDSText type="supporting" color="secondary">- {sub.description}- </XDSText>- </XDSVStack>- </XDSCard>- ))}+ <XDSVStack gap={6}>+ <XDSVStack gap={2}>+ <XDSHeading level={2}>Sub-components</XDSHeading>+ <XDSText type="large" weight="normal">+ {comp.moduleName.replace(/^XDS/, '')} is a compound component+ with {subComponents.length} sub-component+ {subComponents.length === 1 ? '' : 's'}.+ </XDSText></XDSVStack>+ {subComponents.map(sub => (+ <XDSVStack key={sub.name} gap={3}>+ <XDSVStack gap={1}>+ <XDSHeading level={3}>{sub.moduleName}</XDSHeading>+ <XDSText type="body" color="secondary">+ {sub.description}+ </XDSText>+ </XDSVStack>+ {sub.props.length > 0 && <PropsTable props={sub.props} />}+ </XDSVStack>+ ))}+ </XDSVStack>+ </>+ )}++ {/* Examples */}+ {examples.length > 0 && (+ <>+ <XDSDivider />+ <XDSVStack gap={6}>+ <XDSHeading level={2}>Examples</XDSHeading>+ <XDSText type="large" weight="normal">+ Common configurations, variations, and states.+ </XDSText>+ </XDSVStack>+ <XDSVStack gap={8}>+ {examples.map(block => (+ <ExampleBlock key={block.dirName} block={block} />+ ))}+ </XDSVStack>+ </>+ )}++ {/* Showcase source */}+ {showcase && (+ <>+ <XDSDivider />+ <XDSVStack gap={2}>+ <XDSHeading level={3}>Showcase source</XDSHeading>+ <XDSCodeBlock+ code={showcase.source}+ language="tsx"+ hasCopyButton+ /></XDSVStack></>)}diff --git a/apps/docsite/src/components/component-detail/Anatomy.tsx b/apps/docsite/src/components/component-detail/Anatomy.tsxnew file mode 100644index 0000000000..6b37eb873a--- /dev/null+++ b/apps/docsite/src/components/component-detail/Anatomy.tsx@@ -0,0 +1,52 @@+'use client';++import {XDSHeading} from '@xds/core/Text';+import {XDSVStack} from '@xds/core/Layout';+import {XDSSection} from '@xds/core/Section';+import {XDSTable, pixel} from '@xds/core/Table';+import {XDSBadge} from '@xds/core/Badge';+import type {AnatomyElement} from '../../generated/componentRegistry';++interface AnatomyProps {+ elements: AnatomyElement[];+}++export function Anatomy({elements}: AnatomyProps) {+ if (elements.length === 0) return null;++ const data = elements.map(el => ({+ name: el.name as unknown,+ required: el.required as unknown,+ description: el.description as unknown,+ })) as Record<string, unknown>[];++ return (+ <XDSSection>+ <XDSVStack gap={2}>+ <XDSHeading level={3}>Anatomy</XDSHeading>+ <XDSTable+ data={data}+ columns={[+ {+ key: 'name',+ header: 'Element',+ width: pixel(140),+ },+ {+ key: 'required',+ header: '',+ width: pixel(80),+ renderCell: (item: Record<string, unknown>) =>+ item.required === true ? (+ <XDSBadge label="required" variant="info" />+ ) : null,+ },+ {key: 'description', header: 'Description'},+ ]}+ density="spacious"+ dividers="rows"+ />+ </XDSVStack>+ </XDSSection>+ );+}diff --git a/apps/docsite/src/components/component-detail/BestPractices.tsx b/apps/docsite/src/components/component-detail/BestPractices.tsxnew file mode 100644index 0000000000..c64521ff1f--- /dev/null+++ b/apps/docsite/src/components/component-detail/BestPractices.tsx@@ -0,0 +1,22 @@+import {XDSHeading} from '@xds/core/Text';+import {XDSVStack} from '@xds/core/Layout';+import {XDSSection} from '@xds/core/Section';+import {BestPracticesBlock} from '../docs/BestPracticesBlock';+import type {BestPractice} from '../../generated/componentRegistry';++interface BestPracticesProps {+ practices: BestPractice[];+}++export function BestPractices({practices}: BestPracticesProps) {+ if (practices.length === 0) return null;++ return (+ <XDSSection>+ <XDSVStack gap={2}>+ <XDSHeading level={3}>Best practices</XDSHeading>+ <BestPracticesBlock items={practices} />+ </XDSVStack>+ </XDSSection>+ );+}diff --git a/apps/docsite/src/components/component-detail/ExampleBlock.tsx b/apps/docsite/src/components/component-detail/ExampleBlock.tsxnew file mode 100644index 0000000000..25adc072f3--- /dev/null+++ b/apps/docsite/src/components/component-detail/ExampleBlock.tsx@@ -0,0 +1,33 @@+'use client';++import {XDSCard} from '@xds/core/Card';+import {XDSVStack} from '@xds/core/Layout';+import {XDSText} from '@xds/core/Text';+import {XDSCodeBlock} from '@xds/core/CodeBlock';+import type {BlockEntry} from '../../generated/blockRegistry';++interface ExampleBlockProps {+ block: BlockEntry;+}++export function ExampleBlock({block}: ExampleBlockProps) {+ 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>+ );+}diff --git a/apps/docsite/src/components/component-detail/HookSignature.tsx b/apps/docsite/src/components/component-detail/HookSignature.tsxnew file mode 100644index 0000000000..f2111dba46--- /dev/null+++ b/apps/docsite/src/components/component-detail/HookSignature.tsx@@ -0,0 +1,118 @@+'use client';++import {XDSHeading, XDSText} from '@xds/core/Text';+import {XDSVStack, XDSHStack} from '@xds/core/Layout';+import {XDSSection} from '@xds/core/Section';+import {XDSTable, pixel} from '@xds/core/Table';+import {XDSBadge} from '@xds/core/Badge';+import type {+ HookParamDoc,+ HookReturnDoc,+} from '../../generated/componentRegistry';++interface HookSignatureProps {+ params: HookParamDoc[];+ returns: HookReturnDoc[];+}++function formatParamType(type: string, defaultValue?: string): string {+ if (defaultValue != null) {+ return `${type} (default: ${defaultValue})`;+ }+ return type;+}++export function HookSignature({params, returns}: HookSignatureProps) {+ const paramData = params.map(p => ({+ name: p.name as unknown,+ required: p.required as unknown,+ type: formatParamType(p.type, p.default) as unknown,+ description: (p.description ?? '') as unknown,+ })) as Record<string, unknown>[];++ const returnData = returns.map(r => ({+ name: r.name as unknown,+ type: r.type as unknown,+ description: (r.description ?? '') as unknown,+ })) as Record<string, unknown>[];++ return (+ <XDSVStack gap={6}>+ {params.length > 0 && (+ <XDSSection>+ <XDSVStack gap={2}>+ <XDSHeading level={3}>Parameters</XDSHeading>+ <XDSTable+ data={paramData}+ columns={[+ {+ key: 'name',+ header: 'Param',+ width: pixel(160),+ renderCell: (item: Record<string, unknown>) => (+ <XDSHStack gap={1} vAlign="center">+ <XDSText type="code" weight="bold">+ {item.name as string}+ </XDSText>+ {item.required === true && (+ <XDSBadge label="required" variant="info" />+ )}+ </XDSHStack>+ ),+ },+ {+ key: 'type',+ header: 'Type',+ width: pixel(240),+ renderCell: (item: Record<string, unknown>) => (+ <XDSText type="code" color="secondary">+ {item.type as string}+ </XDSText>+ ),+ },+ {key: 'description', header: 'Description'},+ ]}+ density="spacious"+ dividers="rows"+ />+ </XDSVStack>+ </XDSSection>+ )}+ {returns.length > 0 && (+ <XDSSection>+ <XDSVStack gap={2}>+ <XDSHeading level={3}>Returns</XDSHeading>+ <XDSTable+ data={returnData}+ columns={[+ {+ key: 'name',+ header: 'Field',+ width: pixel(160),+ renderCell: (item: Record<string, unknown>) => (+ <XDSText type="code" weight="bold">+ {item.name as string}+ </XDSText>+ ),+ },+ {+ key: 'type',+ header: 'Type',+ width: pixel(240),+ renderCell: (item: Record<string, unknown>) => (+ <XDSText type="code" color="secondary">+ {item.type as string}+ </XDSText>+ ),+ },+ {key: 'description', header: 'Description'},+ ]}+ density="spacious"+ dividers="rows"+ />+ </XDSVStack>+ </XDSSection>+ )}+ </XDSVStack>+ );+}diff --git a/apps/docsite/src/components/component-detail/PropsTable.tsx b/apps/docsite/src/components/component-detail/PropsTable.tsxnew file mode 100644index 0000000000..df99b25279--- /dev/null+++ b/apps/docsite/src/components/component-detail/PropsTable.tsx@@ -0,0 +1,76 @@+'use client';++import {XDSHeading, XDSText} from '@xds/core/Text';+import {XDSVStack, XDSHStack} from '@xds/core/Layout';+import {XDSSection} from '@xds/core/Section';+import {XDSTable, pixel} from '@xds/core/Table';+import {XDSBadge} from '@xds/core/Badge';+import type {PropDoc} from '../../generated/componentRegistry';++function formatType(type: string, defaultValue?: string): string {+ if (defaultValue != null) {+ return `${type} (default: ${defaultValue})`;+ }+ return type;+}++interface PropsTableProps {+ props: PropDoc[];+ heading?: string;+}++export function PropsTable({props, heading}: PropsTableProps) {+ if (props.length === 0) return null;++ const required = props.filter(p => p.required);+ const optional = props.filter(p => !p.required);+ const sorted = [...required, ...optional];++ const data = sorted.map(prop => ({+ name: prop.name as unknown,+ required: prop.required as unknown,+ type: formatType(prop.type, prop.default) as unknown,+ description: (prop.description ?? '') as unknown,+ })) as Record<string, unknown>[];++ return (+ <XDSSection>+ <XDSVStack gap={2}>+ {heading && <XDSHeading level={4}>{heading}</XDSHeading>}+ <XDSTable+ data={data}+ columns={[+ {+ key: 'name',+ header: 'Prop',+ width: pixel(180),+ renderCell: (item: Record<string, unknown>) => (+ <XDSHStack gap={1} vAlign="center">+ <XDSText type="code" weight="bold">+ {item.name as string}+ </XDSText>+ {item.required === true && (+ <XDSBadge label="required" variant="info" />+ )}+ </XDSHStack>+ ),+ },+ {+ key: 'type',+ header: 'Type',+ width: pixel(240),+ renderCell: (item: Record<string, unknown>) => (+ <XDSText type="code" color="secondary">+ {item.type as string}+ </XDSText>+ ),+ },+ {key: 'description', header: 'Description'},+ ]}+ density="spacious"+ dividers="rows"+ />+ </XDSVStack>+ </XDSSection>+ );+}