Skip to content

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