An open source design system that's fully customizable and agent ready
TypeScript
feat(docsite): guide + foundation doc pages with block renderers (#1956)
Cindy Zhang11619155c1f7
diff --git a/apps/docsite/scripts/generate-data.mjs b/apps/docsite/scripts/generate-data.mjsindex 77f048d71b..fcf00bc61a 100644--- a/apps/docsite/scripts/generate-data.mjs+++ b/apps/docsite/scripts/generate-data.mjs@@ -458,23 +458,46 @@ async function generateDocsRegistry() {let title = '';let description = '';let category = '';+ let sections = [];try {const mod = await import(`file://${docPath}`);title = mod.docs?.title || '';description = mod.docs?.description || '';category = mod.docs?.category || '';+ sections = mod.docs?.sections || [];} catch {const meta = readDocMeta(docPath);description = meta.description;}- docTopics.push({topic, title: title || topic, description, category: category || null});+ docTopics.push({topic, title: title || topic, description, category: category || null, sections});}docTopics.sort((a, b) => a.topic.localeCompare(b.topic));const content = `// Auto-generated by scripts/generate-data.mjs — do not edit+export interface ContentBlock {+ type: string;+ text?: string;+ code?: string;+ lang?: string;+ label?: string;+ headers?: string[];+ rows?: string[][];+ items?: string[];+ style?: string;+ topic?: string;+ section?: string;+}++export interface DocSection {+ title: string;+ content: ContentBlock[];+ previewType?: string;+ category?: string;+}+export interface DocTopic {/** URL-friendly slug derived from filename (e.g. 'getting-started') */topic: string;@@ -484,6 +507,8 @@ export interface DocTopic {description: string;/** Navigation category: 'guide' | 'foundations' | null */category: string | null;+ /** Full doc sections with content blocks */+ sections: DocSection[];}export const docTopics: DocTopic[] = ${JSON.stringify(docTopics, null, 2)};diff --git a/apps/docsite/src/app/docs/[topic]/page.tsx b/apps/docsite/src/app/docs/[topic]/page.tsxindex c16704cfd2..0f32fe432c 100644--- a/apps/docsite/src/app/docs/[topic]/page.tsx+++ b/apps/docsite/src/app/docs/[topic]/page.tsx@@ -1,15 +1,13 @@/*** Page type: long-form-doc- * Renders documentation topics from CLI docs/*.doc.mjs.- * Used for: getting-started, typography, color, spacing, shape, icons,- * elevation, motion, principles, styling, tokens, theme.+ * Renders guide and foundation docs from the pipeline.+ * Content blocks (prose, code, table, list) rendered via ContentBlockRenderer.*/import {notFound} from 'next/navigation';-import {XDSHeading, XDSText} from '@xds/core/Text';-import {XDSVStack} from '@xds/core/Layout';import {XDSSection} from '@xds/core/Section';import {docTopics} from '../../../generated/docsRegistry';+import {ReferenceDocView} from '../../../components/docs/ReferenceDocView';export function generateStaticParams() {return docTopics.map(d => ({topic: d.topic}));@@ -25,14 +23,12 @@ export default async function DocPage({if (!topic) notFound();return (- <XDSSection maxWidth="md" padding={6}>- <XDSVStack gap={4}>- <XDSHeading level={1}>{topic.title}</XDSHeading>- <XDSText type="body" color="secondary">- {topic.description}- </XDSText>- {/* TODO: render full doc sections from pipeline */}- </XDSVStack>+ <XDSSection maxWidth="lg" padding={6}>+ <ReferenceDocView+ title={topic.title}+ description={topic.description}+ sections={topic.sections}+ /></XDSSection>);}diff --git a/apps/docsite/src/components/docs/BestPracticesBlock.tsx b/apps/docsite/src/components/docs/BestPracticesBlock.tsxnew file mode 100644index 0000000000..8c5a2be283--- /dev/null+++ b/apps/docsite/src/components/docs/BestPracticesBlock.tsx@@ -0,0 +1,38 @@+'use client';++import {XDSBadge} from '@xds/core/Badge';+import {XDSTable, pixel} from '@xds/core/Table';++interface BestPracticesItem {+ guidance: boolean;+ description: string;+}++export function BestPracticesBlock({items}: {items: BestPracticesItem[]}) {+ const data = items.map(item => ({+ guidance: item.guidance as unknown,+ description: item.description as unknown,+ })) as Record<string, unknown>[];++ return (+ <XDSTable+ data={data}+ columns={[+ {+ key: 'guidance',+ header: 'Guidance',+ width: pixel(100),+ renderCell: (item: Record<string, unknown>) => (+ <XDSBadge+ label={item.guidance ? 'Do' : "Don't"}+ variant={item.guidance ? 'success' : 'error'}+ />+ ),+ },+ {key: 'description', header: 'Practices'},+ ]}+ density="spacious"+ dividers="rows"+ />+ );+}diff --git a/apps/docsite/src/components/docs/CodeBlock.tsx b/apps/docsite/src/components/docs/CodeBlock.tsxnew file mode 100644index 0000000000..3096963f87--- /dev/null+++ b/apps/docsite/src/components/docs/CodeBlock.tsx@@ -0,0 +1,44 @@+'use client';++import * as stylex from '@stylexjs/stylex';+import {XDSVStack} from '@xds/core/Layout';+import {XDSText} from '@xds/core/Text';+import {XDSCodeBlock} from '@xds/core/CodeBlock';+import {XDSCard} from '@xds/core/Card';++const styles = stylex.create({+ root: {width: '100%'},+});++export function CodeBlockRenderer({+ lang,+ code,+ label,+}: {+ lang: string;+ code: string;+ label?: string;+}) {+ return (+ <XDSVStack gap={1}>+ {label && (+ <XDSText type="supporting" color="secondary">+ {label}+ </XDSText>+ )}+ <XDSCard variant="muted" xstyle={styles.root}>+ <XDSCodeBlock+ code={code}+ language={lang}+ hasCopyButton+ style={+ {+ '--color-syntax-background': 'transparent',+ width: '100%',+ } as React.CSSProperties+ }+ />+ </XDSCard>+ </XDSVStack>+ );+}diff --git a/apps/docsite/src/components/docs/ContentBlockRenderer.tsx b/apps/docsite/src/components/docs/ContentBlockRenderer.tsxnew file mode 100644index 0000000000..a3f5dad6a5--- /dev/null+++ b/apps/docsite/src/components/docs/ContentBlockRenderer.tsx@@ -0,0 +1,30 @@+'use client';++import {ProseBlock} from './ProseBlock';+import {CodeBlockRenderer} from './CodeBlock';+import {TableBlock} from './TableBlock';+import {ListBlock} from './ListBlock';+import type {ContentBlock} from '../../generated/docsRegistry';++export function ContentBlockRenderer({block}: {block: ContentBlock}) {+ switch (block.type) {+ case 'prose':+ return <ProseBlock text={block.text ?? ''} />;+ case 'code':+ return (+ <CodeBlockRenderer+ lang={block.lang ?? 'text'}+ code={block.code ?? ''}+ label={block.label}+ />+ );+ case 'table':+ return (+ <TableBlock headers={block.headers ?? []} rows={block.rows ?? []} />+ );+ case 'list':+ return <ListBlock items={block.items ?? []} listStyle={block.style} />;+ default:+ return null;+ }+}diff --git a/apps/docsite/src/components/docs/ListBlock.tsx b/apps/docsite/src/components/docs/ListBlock.tsxnew file mode 100644index 0000000000..bf76c277ec--- /dev/null+++ b/apps/docsite/src/components/docs/ListBlock.tsx@@ -0,0 +1,67 @@+'use client';++import {XDSVStack, XDSHStack} from '@xds/core/Layout';+import {XDSText} from '@xds/core/Text';+import {XDSBadge} from '@xds/core/Badge';+import {XDSTable} from '@xds/core/Table';++export function ListBlock({+ items,+ listStyle,+}: {+ items: string[];+ listStyle?: string;+}) {+ if (listStyle === 'do-dont-merged') {+ const data = items.map((item, i) => {+ const isDo = item.startsWith('do:');+ return {+ _idx: i,+ guidance: isDo ? 'Do' : "Don't",+ isDo,+ text: item.replace(/^(do|dont):/, ''),+ };+ });++ return (+ <XDSTable+ data={data as Record<string, unknown>[]}+ columns={[+ {+ key: 'guidance',+ header: 'Guidance',+ renderCell: (item: Record<string, unknown>) => (+ <XDSBadge+ label={item.guidance as string}+ variant={(item.isDo as boolean) ? 'success' : 'error'}+ />+ ),+ },+ {key: 'text', header: 'Practice'},+ ]}+ density="spacious"+ dividers="rows"+ />+ );+ }++ return (+ <XDSVStack gap={1}>+ {items.map((item, i) => (+ <XDSHStack key={i} gap={2} vAlign="center">+ {listStyle === 'ordered' && (+ <XDSText type="body" color="secondary">+ {i + 1}.+ </XDSText>+ )}+ {listStyle === 'unordered' && (+ <XDSText type="body" color="secondary">+ •+ </XDSText>+ )}+ <XDSText>{item}</XDSText>+ </XDSHStack>+ ))}+ </XDSVStack>+ );+}diff --git a/apps/docsite/src/components/docs/ProseBlock.tsx b/apps/docsite/src/components/docs/ProseBlock.tsxnew file mode 100644index 0000000000..39aee4dba7--- /dev/null+++ b/apps/docsite/src/components/docs/ProseBlock.tsx@@ -0,0 +1,12 @@+'use client';++import * as stylex from '@stylexjs/stylex';+import {XDSText} from '@xds/core/Text';++const styles = stylex.create({+ prose: {maxWidth: 800},+});++export function ProseBlock({text}: {text: string}) {+ return <XDSText xstyle={styles.prose}>{text}</XDSText>;+}diff --git a/apps/docsite/src/components/docs/ReferenceDocView.tsx b/apps/docsite/src/components/docs/ReferenceDocView.tsxnew file mode 100644index 0000000000..d227318d7e--- /dev/null+++ b/apps/docsite/src/components/docs/ReferenceDocView.tsx@@ -0,0 +1,89 @@+'use client';++import * as stylex from '@stylexjs/stylex';+import {XDSText} from '@xds/core/Text';+import {XDSVStack} from '@xds/core/Layout';+import {XDSSection} from '@xds/core/Section';+import {ContentBlockRenderer} from './ContentBlockRenderer';+import {BestPracticesBlock} from './BestPracticesBlock';+import type {DocSection} from '../../generated/docsRegistry';+import type {ReactNode} from 'react';++const styles = stylex.create({+ container: {maxWidth: 1200, marginInline: 'auto'},+ prose: {maxWidth: 800},+});++export type SectionOverrides = Record<+ string,+ (section: DocSection) => ReactNode+>;++function isBestPracticesSection(section: DocSection): boolean {+ return section.content.every(+ b => b.type === 'list' && (b.style === 'do' || b.style === 'dont'),+ );+}++function BestPracticesSection({section}: {section: DocSection}) {+ const items: {guidance: boolean; description: string}[] = [];+ for (const block of section.content) {+ if (+ block.type === 'list' &&+ (block.style === 'do' || block.style === 'dont')+ ) {+ const isDo = block.style === 'do';+ for (const item of block.items ?? []) {+ items.push({guidance: isDo, description: item});+ }+ }+ }+ return (+ <XDSVStack gap={4}>+ <XDSText type="display-3">{section.title}</XDSText>+ <BestPracticesBlock items={items} />+ </XDSVStack>+ );+}++export function ReferenceDocView({+ title,+ description,+ sections,+ sectionOverrides,+}: {+ title: string;+ description: string;+ sections: DocSection[];+ sectionOverrides?: SectionOverrides;+}) {+ return (+ <XDSVStack gap={8} xstyle={styles.container}>+ <XDSVStack gap={2}>+ <XDSText type="display-2">{title}</XDSText>+ <XDSText type="body" color="secondary" xstyle={styles.prose}>+ {description}+ </XDSText>+ </XDSVStack>+ {sections.map(section => {+ const override = sectionOverrides?.[section.title];+ return (+ <XDSSection key={section.title}>+ {override ? (+ override(section)+ ) : isBestPracticesSection(section) ? (+ <BestPracticesSection section={section} />+ ) : (+ <XDSVStack gap={4}>+ <XDSText type="display-3">{section.title}</XDSText>+ {section.content.map((block, i) => (+ <ContentBlockRenderer key={i} block={block} />+ ))}+ </XDSVStack>+ )}+ </XDSSection>+ );+ })}+ </XDSVStack>+ );+}diff --git a/apps/docsite/src/components/docs/TableBlock.tsx b/apps/docsite/src/components/docs/TableBlock.tsxnew file mode 100644index 0000000000..cd30efdf6a--- /dev/null+++ b/apps/docsite/src/components/docs/TableBlock.tsx@@ -0,0 +1,38 @@+'use client';++import {XDSText} from '@xds/core/Text';+import {XDSTable} from '@xds/core/Table';++export function TableBlock({+ headers,+ rows,+}: {+ headers: string[];+ rows: string[][];+}) {+ const data = rows.map((row, i) => {+ const obj: Record<string, unknown> = {_idx: i};+ headers.forEach((h, j) => {+ obj[h] = row[j] ?? '';+ });+ return obj;+ });++ const columns = headers.map(h => ({+ key: h,+ header: h,+ renderCell: (item: Record<string, unknown>) => (+ <XDSText>{item[h] as string}</XDSText>+ ),+ }));++ return (+ <XDSTable+ data={data}+ columns={columns}+ density="spacious"+ dividers="rows"+ hasHover+ />+ );+}