An open source design system that's fully customizable and agent ready
TypeScript
feat(docsite): show a component's stability in its page header (#9032)
Xinzi Zhou29f74ec174e3
diff --git a/apps/docsite/scripts/generate-data.mjs b/apps/docsite/scripts/generate-data.mjsindex 122e6244a5..10abc6875a 100644--- a/apps/docsite/scripts/generate-data.mjs+++ b/apps/docsite/scripts/generate-data.mjs@@ -61,6 +61,7 @@ import {integrationPackagesForTarget,} from '../src/lib/integrationTargets.mjs';import {expandWorkspaceDirs} from '../../../scripts/lib/workspace-globs.mjs';+import {componentStability} from './lib/component-stability.mjs';import {projectThemingDoc} from './lib/theming-doc.mjs';import {searchLinkTables} from '../src/lib/searchLinks.mjs';import {exampleAnchorId} from '../src/lib/exampleAnchor.mjs';@@ -642,6 +643,7 @@ async function generateComponentRegistry() {? projectThemingDoc(sanitizeForJson(d.theming)): null,playground: d.playground ? sanitizeForJson(d.playground) : null,+ stability: d.stability,};break;}@@ -753,6 +755,7 @@ async function generateComponentRegistry() {: doc.playground? sanitizeForJson(doc.playground): (parentMeta.playground ?? null),+ stability: componentStability(pkg.name, doc, parentMeta),});}} else if (doc.components && doc.components.length > 0) {@@ -789,6 +792,7 @@ async function generateComponentRegistry() {relatedComponents: null,relatedHooks: null,playground,+ stability: componentStability(pkg.name, doc),});}for (const sub of doc.components) {@@ -871,6 +875,7 @@ async function generateComponentRegistry() {: sub.playground? sanitizeForJson(sub.playground): playground,+ stability: componentStability(pkg.name, sub, doc),});}} else if (doc.params) {@@ -906,6 +911,7 @@ async function generateComponentRegistry() {relatedComponents: doc.relatedComponents || null,relatedHooks: doc.relatedHooks || null,playground: null,+ stability: componentStability(pkg.name, doc),});} else {// Simple/standalone component@@ -937,6 +943,7 @@ async function generateComponentRegistry() {relatedComponents: null,relatedHooks: null,playground,+ stability: componentStability(pkg.name, doc),});}}@@ -1188,6 +1195,11 @@ export interface ComponentEntry {hidden: boolean;/** Whether this component is ready for the stable documentation line. */isReady: boolean;+ /** \`'lab'\` for a component of the Lab package (spec:AST-017 FR27),+ * \`'experimental'\` for a surface whose doc, or whose family's doc,+ * declares \`stability: 'experimental'\` (spec:AST-017 FR21), and null for+ * a stable one. */+ stability: 'experimental' | 'lab' | null;registry: {slug?: string; aliases?: string[]} | null;parentDoc: string | null;props: PropDoc[];diff --git a/apps/docsite/scripts/lib/component-stability.mjs b/apps/docsite/scripts/lib/component-stability.mjsnew file mode 100644index 0000000000..ec6050a81f--- /dev/null+++ b/apps/docsite/scripts/lib/component-stability.mjs@@ -0,0 +1,35 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/**+ * @file Projects a component's stability into the docsite registry.+ * @input A component's owning package and the docs that can declare its+ * stability.+ * @output The `stability` field of a generated component entry.+ * @position Imported by generate-data.mjs.+ */++/**+ * The private, canary-only Lab package, where spec:AST-017 FR27 keeps every+ * whole experimental component.+ */+export const LAB_PACKAGE_NAME = '@astryxdesign/lab';++/**+ * A component entry's stability: `'lab'` for every component of the Lab+ * package; otherwise `'experimental'` when its own doc or its family's doc+ * declares `stability: 'experimental'` (spec:AST-017 FR21); otherwise null,+ * a stable component.+ *+ * @param {string} packageName The component's owning package.+ * @param {...({stability?: unknown} | null | undefined)} docs Its own doc,+ * then its family's doc when it is part of a family.+ * @returns {'experimental' | 'lab' | null}+ */+export function componentStability(packageName, ...docs) {+ if (packageName === LAB_PACKAGE_NAME) {+ return 'lab';+ }+ return docs.some(doc => doc?.stability === 'experimental')+ ? 'experimental'+ : null;+}diff --git a/apps/docsite/src/__tests__/component-stability.test.ts b/apps/docsite/src/__tests__/component-stability.test.tsnew file mode 100644index 0000000000..04ad031218--- /dev/null+++ b/apps/docsite/src/__tests__/component-stability.test.ts@@ -0,0 +1,53 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/**+ * @file Component stability projection tests.+ * @input componentStability() and the generated component registry+ * @output Regression coverage for the stability a component page header shows+ * @position Build-time docsite data verification+ * Run: pnpm -F @astryxdesign/docsite test+ */++import {describe, expect, it} from 'vitest';+import {+ LAB_PACKAGE_NAME,+ componentStability,+} from '../../scripts/lib/component-stability.mjs';+import {components} from '../generated/componentRegistry';++describe('component stability', () => {+ it('is lab for a Lab component, experimental when its docs say so, otherwise stable', () => {+ const experimental = {stability: 'experimental'};+ expect(componentStability(LAB_PACKAGE_NAME, {})).toBe('lab');+ expect(componentStability(LAB_PACKAGE_NAME, experimental)).toBe('lab');+ expect(componentStability('@astryxdesign/core', experimental)).toBe(+ 'experimental',+ );+ // A part of an experimental family is experimental.+ expect(componentStability('@astryxdesign/core', {}, experimental)).toBe(+ 'experimental',+ );+ expect(componentStability('@astryxdesign/core', {}, null)).toBeNull();+ expect(componentStability('@astryxdesign/charts', {})).toBeNull();+ });++ it('reaches the generated registry', () => {+ for (const [packageName, entries] of Object.entries(components)) {+ for (const entry of entries) {+ if (packageName === LAB_PACKAGE_NAME) {+ expect(entry.stability, entry.name).toBe('lab');+ } else {+ expect(entry.stability, entry.name).not.toBe('lab');+ }+ }+ }+ // An experimental prop does not make its stable component experimental.+ const drawer = components['@astryxdesign/core'].find(+ entry => entry.name === 'Drawer',+ );+ expect(drawer?.props.some(prop => prop.stability === 'experimental')).toBe(+ true,+ );+ expect(drawer?.stability).toBeNull();+ });+});diff --git a/apps/docsite/src/components/component-detail/ComponentDetailClient.tsx b/apps/docsite/src/components/component-detail/ComponentDetailClient.tsxindex e929cdf4ec..66e8186f23 100644--- a/apps/docsite/src/components/component-detail/ComponentDetailClient.tsx+++ b/apps/docsite/src/components/component-detail/ComponentDetailClient.tsx@@ -4,7 +4,8 @@/*** @file Composes a generated component's overview, examples, and detail tabs.- * @input Component metadata, package metadata, and its showcase block.+ * @input Component metadata (including its stability), package metadata, and+ * its showcase block.* @output The interactive component detail article with stable example targets.* @position Client content for /components/[name].*/@@ -12,6 +13,7 @@import * as stylex from '@stylexjs/stylex';import {Suspense} from 'react';import {useSearchParams, useRouter, usePathname} from 'next/navigation';+import {Badge, type BadgeVariant} from '@astryxdesign/core/Badge';import {Heading, Text} from '@astryxdesign/core/Text';import {VStack} from '@astryxdesign/core/Layout';import {Section} from '@astryxdesign/core/Section';@@ -101,6 +103,15 @@ interface ComponentDetailClientProps {showcase: BlockEntry | undefined;}+/** The header badge for each stability other than stable, which shows none. */+const STABILITY_BADGES: Record<+ NonNullable<ComponentEntry['stability']>,+ {label: string; variant: BadgeVariant}+> = {+ experimental: {label: 'Experimental', variant: 'orange'},+ lab: {label: 'Lab', variant: 'purple'},+};+function OverviewContent({comp,pkg,@@ -390,6 +401,8 @@ export function ComponentDetailClient({accessibilityRequirements.length > 0 ||accessibilityThemeCoverage.length > 0;const hasTabs = hasPlayground || hasThemingTab || hasAccessibilityTab;+ const stabilityBadge =+ comp.stability != null ? STABILITY_BADGES[comp.stability] : null;return (<Section@@ -406,6 +419,15 @@ export function ComponentDetailClient({{!comp.isReady ? 'Canary · ' : ''}{pkg}{pkgVersion ? ` v${pkgVersion}` : ''} · {comp.moduleName}+ {stabilityBadge && (+ <>+ {' '}+ <Badge+ label={stabilityBadge.label}+ variant={stabilityBadge.variant}+ />+ </>+ )}{!comp.isReady && pkg ? ` · npm install ${pkg}@canary` : ''}</Text></VStack>