Skip to content

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.tsx
index 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.tsx
new file mode 100644
index 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.tsx
new file mode 100644
index 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.tsx
new file mode 100644
index 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.tsx
new file mode 100644
index 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.tsx
new file mode 100644
index 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>
+ );
+}