An open source design system that's fully customizable and agent ready
TypeScript
docsite: pass DocsShell a small nav model instead of the full registries (#9907)
Cindy Zhangd3ec2efe3935
diff --git a/apps/docsite/src/__tests__/docs-nav.test.ts b/apps/docsite/src/__tests__/docs-nav.test.tsnew file mode 100644index 0000000000..71e05f41c9--- /dev/null+++ b/apps/docsite/src/__tests__/docs-nav.test.ts@@ -0,0 +1,79 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/**+ * @file Docs nav model: the (docs) layout gives DocsShell a small projection of+ * the registries. DocsShell is a client component, so React serializes its+ * props into every docs page, and the modules it imports ship to the browser.+ */++import {readFileSync} from 'node:fs';+import {join} from 'node:path';+import {describe, it, expect} from 'vitest';+import {packages} from '../generated/packageRegistry';+import {docTopics} from '../generated/docsRegistry';+import {flattenComponentSidebarEntries} from '../components/componentSidebarData';+import {getDocsNav, type DocsNavItem} from '../components/docsNav';++function flattenNavEntries(items: DocsNavItem[]) {+ return items.flatMap(item => (item.type === 'entry' ? [item] : item.entries));+}++describe('docs nav model', () => {+ const nav = getDocsNav();++ it('keeps every package and doc topic, in registry order', () => {+ expect(nav.packages).toEqual(+ packages.map(({name, displayName, canaryOnly}) => ({+ name,+ displayName,+ canaryOnly,+ })),+ );+ expect(nav.docTopics).toEqual(+ docTopics.map(({topic, title, category}) => ({topic, title, category})),+ );+ });++ it('keeps every component sidebar entry, in sidebar order', () => {+ const navEntries = [+ ...flattenNavEntries(nav.componentItems),+ ...nav.utilities,+ ...nav.canaryCategories.flatMap(category => [+ ...flattenNavEntries(category.componentItems),+ ...category.utilities,+ ]),+ ];+ expect(navEntries).toEqual(+ flattenComponentSidebarEntries().map(+ ({type, name, displayName, href, packageName}) => ({+ type,+ name,+ displayName,+ href,+ packageName,+ }),+ ),+ );+ });++ it('stays small enough to inline into every docs page', () => {+ // The full registries are megabytes. The nav model is a few tens of KB.+ expect(JSON.stringify(nav).length).toBeLessThan(100_000);+ });++ it('keeps registry modules out of the DocsShell client bundle', () => {+ const source = readFileSync(+ join(__dirname, '../components/DocsShell.tsx'),+ 'utf8',+ );+ const dataImports = [+ ...source.matchAll(+ /^import\s+(type\s+)?[^;]*?from\s+'(\.\.\/generated\/[^']+|\.\/componentSidebarData|\.\/docsNav)';/gm,+ ),+ ];+ expect(dataImports.length).toBeGreaterThan(0);+ for (const [statement, typeOnly] of dataImports) {+ expect(typeOnly, statement).toBeTruthy();+ }+ });+});diff --git a/apps/docsite/src/app/(docs)/layout.tsx b/apps/docsite/src/app/(docs)/layout.tsxindex d3877581c8..915fd1b57c 100644--- a/apps/docsite/src/app/(docs)/layout.tsx+++ b/apps/docsite/src/app/(docs)/layout.tsx@@ -3,8 +3,7 @@import {DocsShell} from '../../components/DocsShell';import {SiteFooter} from '../../components/SiteFooter';import {getCopyrightYear} from '../../lib/copyrightYear';-import {packages} from '../../generated/packageRegistry';-import {docTopics} from '../../generated/docsRegistry';+import {getDocsNav} from '../../components/docsNav';export default async function DocsLayout({children,@@ -14,7 +13,7 @@ export default async function DocsLayout({const year = await getCopyrightYear();return (- <DocsShell packages={packages} docTopics={docTopics}>+ <DocsShell nav={getDocsNav()}>{children}<SiteFooter year={year} /></DocsShell>diff --git a/apps/docsite/src/components/DocsShell.tsx b/apps/docsite/src/components/DocsShell.tsxindex aaa14f21da..09ffcade59 100644--- a/apps/docsite/src/components/DocsShell.tsx+++ b/apps/docsite/src/components/DocsShell.tsx@@ -4,7 +4,7 @@/*** @file DocsShell.tsx- * @input Route metadata, component registry, and the rendered AppShell header+ * @input Route metadata, the server-built docs nav model, and the AppShell header* @output Docs navigation with a stable sidebar offset before hydration* @position Docsite-only shell*/@@ -20,18 +20,17 @@ import {Icon} from '@astryxdesign/core/Icon';import {SharedTopNav} from './SharedTopNav';import {HeaderHeightSeed} from './HeaderHeightSeed';import {DocsBanner} from './InternalDocsPrompt';-import type {PackageMeta} from '../generated/packageRegistry';-import type {DocTopic} from '../generated/docsRegistry';-import {- getComponentSidebarData,- type ComponentSidebarEntry,- type ComponentSidebarItem,-} from './componentSidebarData';+import type {+ DocsNav,+ DocsNavEntry,+ DocsNavItem,+ DocsNavPackage,+ DocsNavTopic,+} from './docsNav';interface DocsShellProps {children: React.ReactNode;- packages: PackageMeta[];- docTopics: DocTopic[];+ nav: DocsNav;}const styles = stylex.create({@@ -53,7 +52,7 @@ function CanaryCategoryMarker() {}/** Foundations: tokens first, then alphabetical */-const foundationsSort = (a: DocTopic, b: DocTopic) => {+const foundationsSort = (a: DocsNavTopic, b: DocsNavTopic) => {if (a.topic === 'tokens') {return -1;}@@ -65,18 +64,18 @@ const foundationsSort = (a: DocTopic, b: DocTopic) => {// ── Shell ──────────────────────────────────────────────────────────────-export function DocsShell({children, packages, docTopics}: DocsShellProps) {+export function DocsShell({children, nav}: DocsShellProps) {const pathname = usePathname();const [componentQuery, setComponentQuery] = useState('');- const {componentItems, utilities, canaryCategories} =- getComponentSidebarData();+ const {packages, docTopics, componentItems, utilities, canaryCategories} =+ nav;const q = componentQuery.trim().toLowerCase();// When searching, flatten every readiness category to individual entries so// results are all at the same level with no nesting.- const flatSearchResults = useMemo<ComponentSidebarEntry[]>(() => {+ const flatSearchResults = useMemo<DocsNavEntry[]>(() => {if (!q) {return [];}@@ -103,7 +102,7 @@ export function DocsShell({children, packages, docTopics}: DocsShellProps) {}, [canaryCategories, utilities, q]);// Classify packages- const isTheme = (p: PackageMeta) => p.name.includes('theme-');+ const isTheme = (p: DocsNavPackage) => p.name.includes('theme-');const libraryPackages = packages.filter(p => !isTheme(p) && !p.canaryOnly);const canaryPackages = packages.filter(p => !isTheme(p) && p.canaryOnly);@@ -134,7 +133,7 @@ export function DocsShell({children, packages, docTopics}: DocsShellProps) {/>);- const renderComponentItems = (items: ComponentSidebarItem[]) =>+ const renderComponentItems = (items: DocsNavItem[]) =>items.map(item =>item.type === 'entry' ? (<SideNavItemdiff --git a/apps/docsite/src/components/docsNav.ts b/apps/docsite/src/components/docsNav.tsnew file mode 100644index 0000000000..56923de3c9--- /dev/null+++ b/apps/docsite/src/components/docsNav.ts@@ -0,0 +1,109 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/**+ * @file docsNav.ts+ * @input Generated package and docs registries, component sidebar data+ * @output The docs sidebar model with only the fields DocsShell reads+ * @position Server-side projection that the (docs) layout passes to DocsShell+ *+ * SYNC: When DocsShell reads another registry field, add it here.+ */++import {packages, type PackageMeta} from '../generated/packageRegistry';+import {docTopics, type DocTopic} from '../generated/docsRegistry';+import {+ getComponentSidebarData,+ type ComponentSidebarEntry,+ type ComponentSidebarGroup,+ type ComponentSidebarItem,+} from './componentSidebarData';++export type DocsNavPackage = Pick<+ PackageMeta,+ 'name' | 'displayName' | 'canaryOnly'+>;++export type DocsNavTopic = Pick<DocTopic, 'topic' | 'title' | 'category'>;++export type DocsNavEntry = Pick<+ ComponentSidebarEntry,+ 'type' | 'name' | 'displayName' | 'href' | 'packageName'+>;++export interface DocsNavGroup extends Pick<+ ComponentSidebarGroup,+ 'type' | 'label' | 'displayName' | 'packageName'+> {+ entries: DocsNavEntry[];+}++export type DocsNavItem = DocsNavEntry | DocsNavGroup;++export interface DocsNavCanaryCategory {+ packageName: string;+ displayName: string;+ componentItems: DocsNavItem[];+ utilities: DocsNavEntry[];+}++export interface DocsNav {+ packages: DocsNavPackage[];+ docTopics: DocsNavTopic[];+ componentItems: DocsNavItem[];+ utilities: DocsNavEntry[];+ canaryCategories: DocsNavCanaryCategory[];+}++function toNavEntry({+ type,+ name,+ displayName,+ href,+ packageName,+}: ComponentSidebarEntry): DocsNavEntry {+ return {type, name, displayName, href, packageName};+}++function toNavItem(item: ComponentSidebarItem): DocsNavItem {+ if (item.type === 'entry') {+ return toNavEntry(item);+ }+ const {type, label, displayName, packageName, entries} = item;+ return {+ type,+ label,+ displayName,+ packageName,+ entries: entries.map(toNavEntry),+ };+}++/**+ * React serializes the props of a client component into every page that+ * renders it. The registries hold full readmes, changelogs, and doc sections,+ * so the shell gets this small projection and not the registries.+ */+export function getDocsNav(): DocsNav {+ const {componentItems, utilities, canaryCategories} =+ getComponentSidebarData();+ return {+ packages: packages.map(({name, displayName, canaryOnly}) => ({+ name,+ displayName,+ canaryOnly,+ })),+ docTopics: docTopics.map(({topic, title, category}) => ({+ topic,+ title,+ category,+ })),+ componentItems: componentItems.map(toNavItem),+ utilities: utilities.map(toNavEntry),+ canaryCategories: canaryCategories.map(category => ({+ packageName: category.packageName,+ displayName: category.displayName,+ componentItems: category.componentItems.map(toNavItem),+ utilities: category.utilities.map(toNavEntry),+ })),+ };+}