Skip to content

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.mjs
index 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.mjs
new file mode 100644
index 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.ts
new file mode 100644
index 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.tsx
index 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>