Skip to content

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

TypeScript

fix(docsite): transparent cards and responsive grid on package page (#2039)

Cindy Zhanga3cd2a0c2544
diff --git a/apps/docsite/scripts/generate-data.mjs b/apps/docsite/scripts/generate-data.mjs
index e35ccdf6e6..2c2c7bee4b 100644
--- a/apps/docsite/scripts/generate-data.mjs
+++ b/apps/docsite/scripts/generate-data.mjs
@@ -452,6 +452,118 @@ export const componentCount = ${totalCount};
return {allComponents, totalCount};
}
+function generateGroupedComponentRegistry(allComponents) {
+ console.log('Generating grouped component registry...');
+
+ const results = {};
+
+ for (const [pkgName, entries] of Object.entries(allComponents)) {
+ const utilities = [];
+ const groups = new Map();
+ const ungrouped = [];
+
+ const parentDocsWithComponents = new Set();
+ for (const e of entries) {
+ if (e.parentDoc && !e.name.startsWith('use') && !e.hidden) {
+ parentDocsWithComponents.add(e.parentDoc);
+ }
+ }
+
+ for (const entry of entries) {
+ if (entry.hidden) continue;
+ const isHook = entry.name.startsWith('use');
+
+ if (
+ entry.group === 'Utilities' ||
+ (isHook && !entry.parentDoc && entry.directory === 'hooks')
+ ) {
+ utilities.push({name: entry.name, href: `/components/${entry.name}`});
+ continue;
+ }
+ if (entry.group) {
+ if (!groups.has(entry.group)) groups.set(entry.group, []);
+ groups
+ .get(entry.group)
+ .push({name: entry.name, href: `/components/${entry.name}`, description: entry.description});
+ continue;
+ }
+ if (isHook && !entry.parentDoc && entry.directory !== 'hooks') {
+ const dir = entry.directory;
+ if (!groups.has(dir)) groups.set(dir, []);
+ groups
+ .get(dir)
+ .push({name: entry.name, href: `/components/${entry.name}`, description: entry.description});
+ continue;
+ }
+ if (
+ isHook &&
+ entry.parentDoc &&
+ parentDocsWithComponents.has(entry.parentDoc)
+ ) {
+ const parent = entry.parentDoc;
+ if (!groups.has(parent)) groups.set(parent, []);
+ groups
+ .get(parent)
+ .push({name: entry.name, href: `/components/${entry.name}`, description: entry.description});
+ continue;
+ }
+ if (isHook) {
+ utilities.push({name: entry.name, href: `/components/${entry.name}`});
+ continue;
+ }
+ ungrouped.push({name: entry.name, href: `/components/${entry.name}`, description: entry.description});
+ }
+
+ const items = [];
+ for (const [label, members] of groups) {
+ members.sort((a, b) => a.name.localeCompare(b.name));
+ if (members.length === 1) {
+ items.push({sortKey: members[0].name, item: {type: 'entry', name: members[0].name, href: members[0].href, description: members[0].description}});
+ } else {
+ const canonical = members.find(m => m.name === label) || members[0];
+ items.push({sortKey: label, item: {type: 'group', label, description: canonical.description, entries: members.map(m => ({name: m.name, href: m.href}))}});
+ }
+ }
+ for (const entry of ungrouped) {
+ items.push({sortKey: entry.name, item: {type: 'entry', name: entry.name, href: entry.href, description: entry.description}});
+ }
+ items.sort((a, b) => a.sortKey.localeCompare(b.sortKey));
+
+ results[pkgName] = {
+ items: items.map(i => i.item),
+ utilities: utilities.sort((a, b) => a.name.localeCompare(b.name)),
+ };
+ }
+
+ const content = `// Auto-generated by scripts/generate-data.mjs — do not edit
+
+export interface GroupedEntry {
+ type: 'entry';
+ name: string;
+ href: string;
+ description: string;
+}
+
+export interface GroupedGroup {
+ type: 'group';
+ label: string;
+ description: string;
+ entries: Array<{name: string; href: string}>;
+}
+
+export type ComponentItem = GroupedEntry | GroupedGroup;
+
+export interface GroupedComponents {
+ items: ComponentItem[];
+ utilities: Array<{name: string; href: string}>;
+}
+
+export const groupedComponents: Record<string, GroupedComponents> = ${JSON.stringify(results, null, 2)};
+`;
+ writeRegistry('groupedComponentRegistry.ts', content);
+ return Object.keys(results).length;
+}
+
// ── 3. Block Registry ──────────────────────────────────────────────────
async function generateBlockRegistry() {
@@ -874,7 +986,8 @@ async function main() {
const packages = generatePackageRegistry();
const themeCount = generateThemeRegistry(packages);
- const {totalCount: componentCount} = await generateComponentRegistry();
+ const {allComponents, totalCount: componentCount} = await generateComponentRegistry();
+ generateGroupedComponentRegistry(allComponents);
const {blockCount, showcaseCount} = await generateBlockRegistry();
const {templateCount} = await generateTemplateRegistry();
const {docsCount} = await generateDocsRegistry();
diff --git a/apps/docsite/src/app/(docs)/packages/[name]/ComponentPreviewCard.tsx b/apps/docsite/src/app/(docs)/packages/[name]/ComponentPreviewCard.tsx
new file mode 100644
index 0000000000..e50fb4d180
--- /dev/null
+++ b/apps/docsite/src/app/(docs)/packages/[name]/ComponentPreviewCard.tsx
@@ -0,0 +1,166 @@
+'use client';
+
+import {
+ useRef,
+ useState,
+ useEffect,
+ useCallback,
+ Suspense,
+ type ComponentType,
+} from 'react';
+import * as stylex from '@stylexjs/stylex';
+import {XDSText} from '@xds/core/Text';
+import {XDSVStack} from '@xds/core/Layout';
+import {XDSClickableCard} from '@xds/core/ClickableCard';
+import {XDSSkeleton} from '@xds/core/Skeleton';
+import {showcaseRegistry} from '../../../../generated/showcaseRegistry';
+
+const FIXED_SCALE = 0.5;
+
+const styles = stylex.create({
+ thumbnail: {
+ width: '100%',
+ aspectRatio: '16/10',
+ overflow: 'hidden',
+ position: 'relative' as const,
+ borderRadius: 'var(--radius-container)',
+ backgroundColor: 'var(--color-background-muted)',
+ contentVisibility: 'auto',
+ containIntrinsicSize: 'auto 300px 187px',
+ },
+ scaler: {
+ position: 'absolute' as const,
+ top: 0,
+ left: 0,
+ height: '200%',
+ transformOrigin: 'top left',
+ pointerEvents: 'none' as const,
+ overflow: 'hidden',
+ display: 'flex',
+ alignItems: 'center',
+ justifyContent: 'center',
+ },
+ placeholder: {
+ width: '100%',
+ aspectRatio: '16/10',
+ display: 'flex',
+ alignItems: 'center',
+ justifyContent: 'center',
+ backgroundColor: 'var(--color-background-muted)',
+ borderRadius: 'var(--radius-container)',
+ },
+ textContent: {
+ padding: '0 var(--spacing-2) var(--spacing-1)',
+ },
+});
+
+function ComponentThumbnail({name}: {name: string}) {
+ const containerRef = useRef<HTMLDivElement>(null);
+ const [renderWidth, setRenderWidth] = useState(0);
+ const [isVisible, setIsVisible] = useState(false);
+ const [Component, setComponent] = useState<ComponentType | null>(null);
+ const [error, setError] = useState(false);
+
+ const updateWidth = useCallback(() => {
+ if (containerRef.current) {
+ setRenderWidth(containerRef.current.offsetWidth / FIXED_SCALE);
+ }
+ }, []);
+
+ useEffect(() => {
+ const loader = showcaseRegistry[name];
+ if (!loader) {
+ setError(true);
+ return;
+ }
+ loader()
+ .then(mod => setComponent(() => mod.default))
+ .catch(() => setError(true));
+ }, [name]);
+
+ useEffect(() => {
+ const el = containerRef.current;
+ if (!el) return;
+ const observer = new IntersectionObserver(
+ ([entry]) => setIsVisible(entry.isIntersecting),
+ {rootMargin: '200px'},
+ );
+ observer.observe(el);
+ return () => observer.disconnect();
+ }, []);
+
+ useEffect(() => {
+ updateWidth();
+ const el = containerRef.current;
+ if (!el) return;
+ const ro = new ResizeObserver(updateWidth);
+ ro.observe(el);
+ return () => ro.disconnect();
+ }, [updateWidth]);
+
+ if (error) {
+ return (
+ <div {...stylex.props(styles.placeholder)}>
+ <XDSText type="supporting" color="secondary">
+ {name}
+ </XDSText>
+ </div>
+ );
+ }
+
+ return (
+ <div ref={containerRef} {...stylex.props(styles.thumbnail)} inert>
+ {renderWidth > 0 && isVisible && Component && (
+ <div
+ {...stylex.props(styles.scaler)}
+ style={{width: renderWidth, transform: `scale(${FIXED_SCALE})`}}>
+ <Suspense fallback={<XDSSkeleton width="100%" height="100%" />}>
+ <Component />
+ </Suspense>
+ </div>
+ )}
+ </div>
+ );
+}
+
+interface ComponentPreviewCardProps {
+ name: string;
+ href: string;
+ description: string;
+ groupSize: number;
+}
+
+export function ComponentPreviewCard({
+ name,
+ href,
+ description,
+ groupSize,
+}: ComponentPreviewCardProps) {
+ return (
+ <XDSClickableCard
+ label={name}
+ href={href}
+ variant="transparent"
+ padding={0}>
+ <XDSVStack gap={2}>
+ <ComponentThumbnail name={name} />
+ <div {...stylex.props(styles.textContent)}>
+ <XDSVStack gap={0.5}>
+ <XDSText type="body" weight="bold">
+ {name}
+ {groupSize > 1 ? (
+ <XDSText type="supporting" color="secondary">
+ {' '}
+ +{groupSize - 1}
+ </XDSText>
+ ) : null}
+ </XDSText>
+ <XDSText type="supporting" color="secondary">
+ {description}
+ </XDSText>
+ </XDSVStack>
+ </div>
+ </XDSVStack>
+ </XDSClickableCard>
+ );
+}
diff --git a/apps/docsite/src/app/(docs)/packages/[name]/page.tsx b/apps/docsite/src/app/(docs)/packages/[name]/page.tsx
index 9ed89cd0b8..20b546cbb6 100644
--- a/apps/docsite/src/app/(docs)/packages/[name]/page.tsx
+++ b/apps/docsite/src/app/(docs)/packages/[name]/page.tsx
@@ -10,15 +10,13 @@ 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 {XDSBadge} from '@xds/core/Badge';
import {XDSGrid} from '@xds/core/Grid';
-import {XDSClickableCard} from '@xds/core/ClickableCard';
import {XDSDivider} from '@xds/core';
import {packages} from '../../../../generated/packageRegistry';
import {
- components,
- type ComponentEntry,
-} from '../../../../generated/componentRegistry';
+ groupedComponents,
+ type ComponentItem,
+} from '../../../../generated/groupedComponentRegistry';
import {
ThemePackagePage,
type InstallStep,
@@ -30,6 +28,7 @@ import {matchaTheme} from '@xds/theme-matcha/built';
import type {XDSDefinedTheme} from '@xds/core/theme';
import {PackageHeading} from './PackageHeading';
import {PackageStubPage} from './PackageStubPage';
+import {ComponentPreviewCard} from './ComponentPreviewCard';
function slugToPackageName(slug: string): string {
return `@xds/${slug}`;
@@ -92,7 +91,7 @@ export default async function PackagePage({
const isTheme = pkg.name.includes('theme-');
const isComponentPkg = pkg.name === '@xds/core';
- const pkgComponents = components[pkg.name] || [];
+ const grouped = groupedComponents[pkg.name];
if (isTheme) {
const theme = THEME_MAP[pkg.name];
@@ -135,20 +134,19 @@ export default async function PackagePage({
<XDSDivider />
- <ComponentPackageContent components={pkgComponents} />
+ <ComponentPackageContent items={grouped?.items ?? []} />
</XDSVStack>
</XDSSection>
);
}
-function ComponentPackageContent({
- components: pkgComponents,
-}: {
- components: ComponentEntry[];
-}) {
- const topLevel = pkgComponents.filter(c => !c.parentDoc);
+function ComponentPackageContent({items}: {items: ComponentItem[]}) {
+ const totalCount = items.reduce(
+ (sum, item) => sum + (item.type === 'group' ? item.entries.length : 1),
+ 0,
+ );
- if (topLevel.length === 0) {
+ if (items.length === 0) {
return (
<XDSText type="body" color="secondary">
No components documented yet.
@@ -158,26 +156,22 @@ function ComponentPackageContent({
return (
<XDSVStack gap={4}>
- <XDSHeading level={2}>Components ({topLevel.length})</XDSHeading>
- <XDSGrid columns={3} gap={4} minChildWidth={200}>
- {topLevel.map(c => (
- <XDSClickableCard
- key={c.name}
- label={c.name}
- href={`/components/${c.name}`}
- padding={4}>
- <XDSVStack gap={1}>
- <XDSText type="body" weight="bold">
- {c.name}
- </XDSText>
- {c.group && <XDSBadge label={c.group} />}
- <XDSText type="supporting" color="secondary">
- {c.description.slice(0, 100)}
- {c.description.length > 100 ? '…' : ''}
- </XDSText>
- </XDSVStack>
- </XDSClickableCard>
- ))}
+ <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>
);
diff --git a/apps/docsite/src/components/DocsShell.tsx b/apps/docsite/src/components/DocsShell.tsx
index 209545fad5..edb48f69d8 100644
--- a/apps/docsite/src/components/DocsShell.tsx
+++ b/apps/docsite/src/components/DocsShell.tsx
@@ -11,6 +11,8 @@ import type {ComponentEntry} from '../generated/componentRegistry';
import type {PackageMeta} from '../generated/packageRegistry';
import type {DocTopic} from '../generated/docsRegistry';
import type {TemplateEntry} from '../generated/templateRegistry';
+import type {ComponentItem} from '../generated/groupedComponentRegistry';
+import {groupedComponents} from '../generated/groupedComponentRegistry';
interface DocsShellProps {
children: React.ReactNode;
@@ -30,98 +32,15 @@ const foundationsSort = (a: DocTopic, b: DocTopic) => {
// ── Component sidebar builder ──────────────────────────────────────────
-type SidebarItem =
- | {type: 'entry'; name: string; href: string}
- | {
- type: 'group';
- label: string;
- entries: Array<{name: string; href: string}>;
- };
+type SidebarItem = ComponentItem;
-function buildComponentSidebar(entries: ComponentEntry[]): {
+function buildComponentSidebar(): {
componentItems: SidebarItem[];
utilities: Array<{name: string; href: string}>;
} {
- const utilities: Array<{name: string; href: string}> = [];
- const groups = new Map<string, Array<{name: string; href: string}>>();
- const ungrouped: Array<{name: string; href: string}> = [];
-
- const parentDocsWithComponents = new Set<string>();
- for (const e of entries) {
- if (e.parentDoc && !e.name.startsWith('use') && !e.hidden) {
- parentDocsWithComponents.add(e.parentDoc);
- }
- }
-
- for (const entry of entries) {
- if (entry.hidden) continue;
- const isHook = entry.name.startsWith('use');
-
- if (
- entry.group === 'Utilities' ||
- (isHook && !entry.parentDoc && entry.directory === 'hooks')
- ) {
- utilities.push({name: entry.name, href: `/components/${entry.name}`});
- continue;
- }
- if (entry.group) {
- if (!groups.has(entry.group)) groups.set(entry.group, []);
- groups
- .get(entry.group)!
- .push({name: entry.name, href: `/components/${entry.name}`});
- continue;
- }
- if (isHook && !entry.parentDoc && entry.directory !== 'hooks') {
- const dir = entry.directory;
- if (!groups.has(dir)) groups.set(dir, []);
- groups
- .get(dir)!
- .push({name: entry.name, href: `/components/${entry.name}`});
- continue;
- }
- if (
- isHook &&
- entry.parentDoc &&
- parentDocsWithComponents.has(entry.parentDoc)
- ) {
- const parent = entry.parentDoc;
- if (!groups.has(parent)) groups.set(parent, []);
- groups
- .get(parent)!
- .push({name: entry.name, href: `/components/${entry.name}`});
- continue;
- }
- if (isHook) {
- utilities.push({name: entry.name, href: `/components/${entry.name}`});
- continue;
- }
- ungrouped.push({name: entry.name, href: `/components/${entry.name}`});
- }
-
- const items: Array<{sortKey: string; item: SidebarItem}> = [];
- for (const [label, members] of groups) {
- members.sort((a, b) => a.name.localeCompare(b.name));
- if (members.length === 1) {
- items.push({
- sortKey: members[0].name,
- item: {type: 'entry', ...members[0]},
- });
- } else {
- items.push({
- sortKey: label,
- item: {type: 'group', label, entries: members},
- });
- }
- }
- for (const entry of ungrouped) {
- items.push({sortKey: entry.name, item: {type: 'entry', ...entry}});
- }
- items.sort((a, b) => a.sortKey.localeCompare(b.sortKey));
-
- return {
- componentItems: items.map(i => i.item),
- utilities: utilities.sort((a, b) => a.name.localeCompare(b.name)),
- };
+ const grouped = groupedComponents['@xds/core'];
+ if (!grouped) return {componentItems: [], utilities: []};
+ return {componentItems: grouped.items, utilities: grouped.utilities};
}
// ── Wordmark ───────────────────────────────────────────────────────────
@@ -155,8 +74,7 @@ export function DocsShell({
}: DocsShellProps) {
const pathname = usePathname();
- const coreComponents = components['@xds/core'] || [];
- const {componentItems, utilities} = buildComponentSidebar(coreComponents);
+ const {componentItems, utilities} = buildComponentSidebar();
// Classify packages
const isTheme = (p: PackageMeta) => p.name.includes('theme-');