An open source design system that's fully customizable and agent ready
TypeScript
feat(docsite): improve package page rendering (#1964)
Cindy Zhang558e2723ce60
diff --git a/apps/docsite/src/app/packages/[name]/PackageHeading.tsx b/apps/docsite/src/app/packages/[name]/PackageHeading.tsxnew file mode 100644index 0000000000..e6612988ff--- /dev/null+++ b/apps/docsite/src/app/packages/[name]/PackageHeading.tsx@@ -0,0 +1,77 @@+'use client';++import {XDSText} from '@xds/core/Text';+import {XDSVStack, XDSHStack} from '@xds/core/Layout';+import {XDSPopover} from '@xds/core/Popover';+import {XDSCodeBlock} from '@xds/core/CodeBlock';+import {XDSButton} from '@xds/core/Button';+import {XDSCard} from '@xds/core/Card';++export interface InstallStep {+ label: string;+ code: string;+ language?: string;+}++interface PackageHeadingProps {+ packageName: string;+ description?: string;+ version?: string;+ installSteps?: InstallStep[];+}++export function PackageHeading({+ packageName,+ description,+ version,+ installSteps,+}: PackageHeadingProps) {+ const steps = installSteps ?? [+ {label: 'Install the package', code: `npm install ${packageName}`},+ {+ label: 'Import',+ code: `import {...} from '${packageName}';`,+ language: 'typescript',+ },+ ];++ return (+ <XDSVStack gap={1}>+ {version && (+ <XDSText type="supporting" color="secondary">+ v{version}+ </XDSText>+ )}+ <XDSHStack vAlign="center" hAlign="between">+ <XDSText type="display-1">{packageName}</XDSText>+ <XDSPopover+ width={360}+ content={+ <XDSVStack gap={3}>+ {steps.map((step, i) => (+ <XDSVStack key={i} gap={1}>+ <XDSText type="body" weight="bold">+ {i + 1}. {step.label}+ </XDSText>+ <XDSCard padding={0}>+ <XDSCodeBlock+ code={step.code}+ language={step.language ?? 'bash'}+ hasCopyButton+ />+ </XDSCard>+ </XDSVStack>+ ))}+ </XDSVStack>+ }>+ <XDSButton label="Install" variant="primary" />+ </XDSPopover>+ </XDSHStack>+ {description && (+ <XDSText type="body" color="secondary">+ {description}+ </XDSText>+ )}+ </XDSVStack>+ );+}diff --git a/apps/docsite/src/app/packages/[name]/PackageStubPage.tsx b/apps/docsite/src/app/packages/[name]/PackageStubPage.tsxnew file mode 100644index 0000000000..cdeda1efd0--- /dev/null+++ b/apps/docsite/src/app/packages/[name]/PackageStubPage.tsx@@ -0,0 +1,50 @@+'use client';++import stylex from '@stylexjs/stylex';+import {XDSVStack} from '@xds/core/Layout';+import {XDSText} from '@xds/core/Text';+import {XDSMarkdown} from '@xds/core/Markdown';+import {PackageHeading, type InstallStep} from './PackageHeading';++const styles = stylex.create({+ container: {+ maxWidth: 800,+ marginInline: 'auto',+ },+});++interface PackageStubPageProps {+ name: string;+ description?: string;+ version?: string;+ readme: string | null;+ installSteps?: InstallStep[];+}++export function PackageStubPage({+ name,+ version,+ readme,+ installSteps,+}: PackageStubPageProps) {+ const body = readme ? readme.replace(/^# .+\n+/, '') : null;++ return (+ <XDSVStack gap={8} xstyle={styles.container}>+ <PackageHeading+ packageName={name}+ version={version}+ installSteps={installSteps}+ />+ {body ? (+ <XDSMarkdown headingLevelStart={3} contentWidth={800}>+ {body}+ </XDSMarkdown>+ ) : (+ <XDSText type="body" color="secondary">+ No README available.+ </XDSText>+ )}+ </XDSVStack>+ );+}diff --git a/apps/docsite/src/app/packages/[name]/page.tsx b/apps/docsite/src/app/packages/[name]/page.tsxindex 76b0604a9a..b1d93fbf68 100644--- a/apps/docsite/src/app/packages/[name]/page.tsx+++ b/apps/docsite/src/app/packages/[name]/page.tsx@@ -8,12 +8,11 @@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 {XDSBadge} from '@xds/core/Badge';import {XDSGrid} from '@xds/core/Grid';import {XDSClickableCard} from '@xds/core/ClickableCard';-import {XDSMarkdown} from '@xds/core/Markdown';import {XDSDivider} from '@xds/core';import {packages} from '../../../generated/packageRegistry';import {@@ -29,6 +28,8 @@ import {neutralTheme} from '@xds/theme-neutral/built';import {dailyTheme} from '@xds/theme-daily/built';import {matchaTheme} from '@xds/theme-matcha/built';import type {XDSDefinedTheme} from '@xds/core/theme';+import {PackageHeading} from './PackageHeading';+import {PackageStubPage} from './PackageStubPage';function slugToPackageName(slug: string): string {return `@xds/${slug}`;@@ -59,6 +60,12 @@ function getInstallSteps(pkgName: string): InstallStep[] {},];}+ if (pkgName.endsWith('/cli')) {+ return [+ {label: 'Install the CLI', code: `npm install -D ${pkgName}`},+ {label: 'Run a command', code: `npx xds component --list`},+ ];+ }return [{label: 'Install the package', code: `npm install ${pkgName}`},{@@ -105,31 +112,30 @@ export default async function PackagePage({}}+ if (!isComponentPkg) {+ return (+ <PackageStubPage+ name={pkg.name}+ version={pkg.version}+ readme={pkg.readme}+ installSteps={getInstallSteps(pkg.name)}+ />+ );+ }+return (<XDSSection maxWidth="lg" padding={6}><XDSVStack gap={6}>- {/* Header — shared across all package types */}- <XDSVStack gap={2}>- <XDSHeading level={1}>{pkg.displayName}</XDSHeading>- <XDSHStack gap={2} vAlign="center">- <XDSText type="supporting" color="secondary">- {pkg.name}- </XDSText>- <XDSBadge label={`v${pkg.version}`} variant="info" />- </XDSHStack>- <XDSText type="body" color="secondary">- {pkg.description}- </XDSText>- </XDSVStack>+ <PackageHeading+ packageName={pkg.name}+ version={pkg.version}+ description={pkg.description}+ installSteps={getInstallSteps(pkg.name)}+ /><XDSDivider />- {/* Content — adapts by package type */}- {isComponentPkg ? (- <ComponentPackageContent components={pkgComponents} />- ) : (- <GenericPackageContent readme={pkg.readme} />- )}+ <ComponentPackageContent components={pkgComponents} /></XDSVStack></XDSSection>);@@ -176,15 +182,3 @@ function ComponentPackageContent({</XDSVStack>);}--function GenericPackageContent({readme}: {readme: string | null}) {- if (!readme) {- return (- <XDSText type="body" color="secondary">- No README available.- </XDSText>- );- }-- return <XDSMarkdown>{readme}</XDSMarkdown>;-}