Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

feat(docsite): simplify /packages/core page to match CLI stub layout (#2446)

Kenton Quatman611f4c62bc3d
diff --git a/apps/docsite/src/app/(docs)/packages/[name]/PackageHeading.tsx b/apps/docsite/src/app/(docs)/packages/[name]/PackageHeading.tsx
index f649d8c366..40425555d5 100644
--- a/apps/docsite/src/app/(docs)/packages/[name]/PackageHeading.tsx
+++ b/apps/docsite/src/app/(docs)/packages/[name]/PackageHeading.tsx
@@ -20,6 +20,7 @@ interface PackageHeadingProps {
description?: string;
version?: string;
installSteps?: InstallStep[];
+ cta?: {label: string; href: string};
}
export function PackageHeading({
@@ -27,6 +28,7 @@ export function PackageHeading({
description,
version,
installSteps,
+ cta,
}: PackageHeadingProps) {
const steps = installSteps ?? [
{label: 'Install the package', code: `npm install ${packageName}`},
@@ -46,28 +48,33 @@ export function PackageHeading({
)}
<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 gap={2}>
+ {cta && (
+ <XDSButton label={cta.label} href={cta.href} variant="secondary" />
+ )}
+ <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>
</XDSHStack>
{description && (
<XDSText type="body" color="secondary">
diff --git a/apps/docsite/src/app/(docs)/packages/[name]/PackageStubPage.tsx b/apps/docsite/src/app/(docs)/packages/[name]/PackageStubPage.tsx
index e9203ece64..44a5eb8f17 100644
--- a/apps/docsite/src/app/(docs)/packages/[name]/PackageStubPage.tsx
+++ b/apps/docsite/src/app/(docs)/packages/[name]/PackageStubPage.tsx
@@ -21,22 +21,42 @@ interface PackageStubPageProps {
version?: string;
readme: string | null;
installSteps?: InstallStep[];
+ cta?: {label: string; href: string};
+ /** Markdown section headings (## level) to strip from the README */
+ stripSections?: string[];
}
export function PackageStubPage({
name,
+ description,
version,
readme,
installSteps,
+ cta,
+ stripSections,
}: PackageStubPageProps) {
- const body = readme ? readme.replace(/^# .+\n+/, '') : null;
+ let body = readme ? readme.replace(/^# .+\n+/, '') : null;
+
+ if (body && stripSections && stripSections.length > 0) {
+ for (const section of stripSections) {
+ // Remove ## Section through to the next ## or end of string
+ const pattern = new RegExp(
+ `## ${section.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\n[\\s\\S]*?(?=\\n## |$)`,
+ );
+ body = body.replace(pattern, '');
+ }
+ // Clean up extra blank lines
+ body = body.replace(/\n{3,}/g, '\n\n').trim();
+ }
return (
<XDSVStack gap={8} xstyle={styles.container}>
<PackageHeading
packageName={name}
version={version}
+ description={description}
installSteps={installSteps}
+ cta={cta}
/>
{body ? (
<XDSMarkdown headingLevelStart={3} contentWidth={800}>
diff --git a/apps/docsite/src/app/(docs)/packages/[name]/page.tsx b/apps/docsite/src/app/(docs)/packages/[name]/page.tsx
index dc72cb9b1a..911536febc 100644
--- a/apps/docsite/src/app/(docs)/packages/[name]/page.tsx
+++ b/apps/docsite/src/app/(docs)/packages/[name]/page.tsx
@@ -3,28 +3,18 @@
/**
* Page type: package
* Adapts based on the package type:
- * - component-pkg (@xds/core): component grid from componentRegistry
+ * - component-pkg (@xds/core): stub page with CTA to browse components
* - theme-pkg (@xds/theme-*): redirects to the canonical /themes/<name>
* page on the themes side of the site (one URL per theme).
* - generic (@xds/cli, etc.): README rendered via XDSMarkdown
*/
import {notFound, redirect} from 'next/navigation';
-import {XDSHeading, XDSText} from '@xds/core/Text';
-import {XDSVStack} from '@xds/core/Layout';
import {XDSSection} from '@xds/core/Section';
-import {XDSGrid} from '@xds/core/Grid';
-import {XDSDivider} from '@xds/core';
import {packages} from '../../../../generated/packageRegistry';
-import {
- groupedComponents,
- type ComponentItem,
-} from '../../../../generated/groupedComponentRegistry';
import {type InstallStep} from './PackageHeading';
import {themeObjects} from '../../../../generated/themeRegistry';
-import {PackageHeading} from './PackageHeading';
import {PackageStubPage} from './PackageStubPage';
-import {ComponentPreviewCard} from './ComponentPreviewCard';
function slugToPackageName(slug: string): string {
return `@xds/${slug}`;
@@ -64,6 +54,27 @@ function getInstallSteps(pkgName: string): InstallStep[] {
];
}
+/** Sections to remove from the @xds/core README on the package page. */
+const CORE_STRIP_SECTIONS = [
+ 'Quick Start',
+ 'Resources',
+ 'XDS CLI',
+];
+
+/**
+ * Rewrite the @xds/core README intro to incorporate the package description
+ * and remove the now-dead Quick Start cross-reference.
+ */
+function rewriteCoreReadme(readme: string | null): string | null {
+ if (!readme) {
+ return null;
+ }
+ return readme.replace(
+ /Core UI components, theme system, and utilities for the XDS design system\..*?(?=\n)/,
+ 'Accessible, themeable React components with built-in spacing, dark mode, and StyleX styling — the core building blocks of the XDS design system.',
+ );
+}
+
export function generateStaticParams() {
return packages.map(p => ({name: p.name.replace('@xds/', '')}));
}
@@ -82,7 +93,6 @@ export default async function PackagePage({
const isTheme = pkg.name.includes('theme-');
const isComponentPkg = pkg.name === '@xds/core';
- const grouped = groupedComponents[pkg.name];
// Theme packages live on /themes/<name> — the canonical surface for
// each theme, hosting the full ThemeShowcasePreview alongside the
@@ -109,55 +119,14 @@ export default async function PackagePage({
return (
<XDSSection maxWidth="lg" padding={6}>
- <XDSVStack gap={6}>
- <PackageHeading
- packageName={pkg.name}
- version={pkg.version}
- description={pkg.description}
- installSteps={getInstallSteps(pkg.name)}
- />
-
- <XDSDivider />
-
- <ComponentPackageContent items={grouped?.items ?? []} />
- </XDSVStack>
+ <PackageStubPage
+ name={pkg.name}
+ version={pkg.version}
+ readme={rewriteCoreReadme(pkg.readme)}
+ installSteps={getInstallSteps(pkg.name)}
+ cta={{label: 'View Components', href: '/components/Button'}}
+ stripSections={CORE_STRIP_SECTIONS}
+ />
</XDSSection>
);
}
-
-function ComponentPackageContent({items}: {items: ComponentItem[]}) {
- const totalCount = items.reduce(
- (sum, item) => sum + (item.type === 'group' ? item.entries.length : 1),
- 0,
- );
-
- if (items.length === 0) {
- return (
- <XDSText type="body" color="secondary">
- No components documented yet.
- </XDSText>
- );
- }
-
- return (
- <XDSVStack gap={4}>
- <XDSHeading level={2}>Components ({totalCount})</XDSHeading>
- <XDSGrid columns={{minWidth: 260}} gap={4} rowGap={6}>
- {items.map(item => {
- const name = item.type === 'group' ? item.label : item.name;
- const href = item.type === 'group' ? item.entries[0].href : item.href;
- const groupSize = item.type === 'group' ? item.entries.length : 1;
- return (
- <ComponentPreviewCard
- key={name}
- name={name}
- href={href}
- description={item.description}
- groupSize={groupSize}
- />
- );
- })}
- </XDSGrid>
- </XDSVStack>
- );
-}