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.mjsindex 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.tsxnew file mode 100644index 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.tsxindex 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.tsxindex 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 packagesconst isTheme = (p: PackageMeta) => p.name.includes('theme-');