Skip to content

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

TypeScript

fix(docsite): generated theming docs keep only the fields the registry types declare (#7376)

Cindy Zhangd60038b04987
diff --git a/apps/docsite/scripts/generate-data.mjs b/apps/docsite/scripts/generate-data.mjs
index 99e960e25c..49523f8cc9 100644
--- a/apps/docsite/scripts/generate-data.mjs
+++ b/apps/docsite/scripts/generate-data.mjs
@@ -40,6 +40,7 @@ import {
import docsiteConfig from '../astryx.config.mjs';
import {integrationContentEnabled} from '../src/lib/integrationTargets.mjs';
import {expandWorkspaceDirs} from '../../../scripts/lib/workspace-globs.mjs';
+import {projectThemingDoc} from './lib/theming-doc.mjs';
import {
buildTypeDefinitionIndex,
collectPropTypeRefs,
@@ -595,7 +596,9 @@ async function generateComponentRegistry() {
isHiddenFromOverview: d.isHiddenFromOverview ?? false,
topDescription: d.usage?.description || d.description || '',
usage: d.usage ? sanitizeForJson(d.usage) : null,
- theming: d.theming ? sanitizeForJson(d.theming) : null,
+ theming: d.theming
+ ? projectThemingDoc(sanitizeForJson(d.theming))
+ : null,
playground: d.playground ? sanitizeForJson(d.playground) : null,
};
break;
@@ -627,7 +630,9 @@ async function generateComponentRegistry() {
const hidden = doc.hidden ?? false;
const topDescription = doc.usage?.description || doc.description || '';
const usage = doc.usage ? sanitizeForJson(doc.usage) : null;
- const theming = doc.theming ? sanitizeForJson(doc.theming) : null;
+ const theming = doc.theming
+ ? projectThemingDoc(sanitizeForJson(doc.theming))
+ : null;
const registry = doc.registry ? sanitizeForJson(doc.registry) : null;
const playground = doc.playground
? sanitizeForJson(doc.playground)
@@ -682,7 +687,7 @@ async function generateComponentRegistry() {
theming: isHookEntry
? null
: doc.theming
- ? sanitizeForJson(doc.theming)
+ ? projectThemingDoc(sanitizeForJson(doc.theming))
: (parentMeta.theming ?? null),
params: isHookEntry
? Array.isArray(doc.params)
diff --git a/apps/docsite/scripts/lib/theming-doc.mjs b/apps/docsite/scripts/lib/theming-doc.mjs
new file mode 100644
index 0000000000..ee2fc77e45
--- /dev/null
+++ b/apps/docsite/scripts/lib/theming-doc.mjs
@@ -0,0 +1,109 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file The shape of a component's `theming` doc as the generated registries
+ * emit it. The docsite's `latest` target reads the PUBLISHED packages' .doc.mjs
+ * files, which can carry fields a later release dropped from `ThemingTarget`
+ * (`deprecatedFor`, removed with the deprecated theming surface); emitting a
+ * doc verbatim then fails the registry typecheck in production only. Project
+ * every theming doc onto the fields the emitted interfaces declare, and drop
+ * the targets a published doc marks as deprecated aliases: generated docs
+ * present only the current theming surface, never an alias as an ordinary
+ * target.
+ */
+
+/** Fields of the emitted `ThemingTarget` interface, in order. */
+export const THEMING_TARGET_FIELDS = ['className', 'visualProps', 'states'];
+
+/** Fields of the emitted `ComponentVar` interface. */
+export const COMPONENT_VAR_FIELDS = [
+ 'name',
+ 'description',
+ 'default',
+ 'derived',
+ 'formula',
+ 'private',
+];
+
+/** Fields of the emitted `DerivedVar` interface. */
+export const DERIVED_VAR_FIELDS = ['property', 'vars', 'expand', 'replaces'];
+
+/** Fields of the emitted `ThemingDoc` interface. */
+export const THEMING_DOC_FIELDS = ['container', 'targets', 'vars', 'derived'];
+
+/**
+ * @template {Record<string, unknown>} T
+ * @param {T} value
+ * @param {readonly string[]} fields
+ * @returns {Partial<T>}
+ */
+function pick(value, fields) {
+ /** @type {Record<string, unknown>} */
+ const out = {};
+ for (const field of fields) {
+ if (value[field] !== undefined) out[field] = value[field];
+ }
+ return /** @type {Partial<T>} */ (out);
+}
+
+/**
+ * Keep only the fields the generated `ThemingDoc` interfaces declare, so a
+ * published doc from an earlier release typechecks against the current
+ * registry. Non-object input is returned as is.
+ * @param {unknown} theming a sanitized (JSON-safe) theming doc
+ * @returns {unknown}
+ */
+export function projectThemingDoc(theming) {
+ if (
+ theming == null ||
+ typeof theming !== 'object' ||
+ Array.isArray(theming)
+ ) {
+ return theming;
+ }
+ const doc = /** @type {Record<string, unknown>} */ (theming);
+ const out = pick(doc, THEMING_DOC_FIELDS);
+ if (Array.isArray(out.targets)) {
+ out.targets = out.targets
+ // A target that names the class superseding it is a deprecated alias
+ // from an earlier release, not part of the current theming surface.
+ .filter(
+ target =>
+ !(
+ target != null &&
+ typeof target === 'object' &&
+ /** @type {Record<string, unknown>} */ (target).deprecatedFor !=
+ null
+ ),
+ )
+ .map(target =>
+ target != null && typeof target === 'object'
+ ? pick(
+ /** @type {Record<string, unknown>} */ (target),
+ THEMING_TARGET_FIELDS,
+ )
+ : target,
+ );
+ }
+ if (Array.isArray(out.vars)) {
+ out.vars = out.vars.map(entry =>
+ entry != null && typeof entry === 'object'
+ ? pick(
+ /** @type {Record<string, unknown>} */ (entry),
+ COMPONENT_VAR_FIELDS,
+ )
+ : entry,
+ );
+ }
+ if (Array.isArray(out.derived)) {
+ out.derived = out.derived.map(entry =>
+ entry != null && typeof entry === 'object'
+ ? pick(
+ /** @type {Record<string, unknown>} */ (entry),
+ DERIVED_VAR_FIELDS,
+ )
+ : entry,
+ );
+ }
+ return out;
+}
diff --git a/apps/docsite/src/__tests__/theming-doc-projection.test.ts b/apps/docsite/src/__tests__/theming-doc-projection.test.ts
new file mode 100644
index 0000000000..c205a7d750
--- /dev/null
+++ b/apps/docsite/src/__tests__/theming-doc-projection.test.ts
@@ -0,0 +1,90 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import {describe, expect, it} from 'vitest';
+import {
+ COMPONENT_VAR_FIELDS,
+ DERIVED_VAR_FIELDS,
+ THEMING_DOC_FIELDS,
+ THEMING_TARGET_FIELDS,
+ projectThemingDoc,
+} from '../../scripts/lib/theming-doc.mjs';
+
+const GENERATOR = path.resolve(__dirname, '../../scripts/generate-data.mjs');
+
+/** The field names of one `export interface <name> {…}` the generator emits. */
+function emittedInterfaceFields(name: string): string[] {
+ const source = fs.readFileSync(GENERATOR, 'utf8');
+ const match = new RegExp(
+ `export interface ${name} \\{([\\s\\S]*?)\\n\\}`,
+ ).exec(source);
+ if (!match) throw new Error(`generate-data.mjs emits no interface ${name}`);
+ return [...match[1].matchAll(/^\s{2}([A-Za-z]+)\??:/gm)].map(m => m[1]);
+}
+
+// The docsite's `latest` target documents the PUBLISHED packages, whose
+// .doc.mjs files can carry theming fields a later release removed. The
+// generated registry must typecheck against the interfaces the generator
+// emits, so the projection's field lists must match those interfaces exactly.
+describe('generated theming docs typecheck against the emitted interfaces', () => {
+ it.each([
+ ['ThemingTarget', THEMING_TARGET_FIELDS],
+ ['ComponentVar', COMPONENT_VAR_FIELDS],
+ ['DerivedVar', DERIVED_VAR_FIELDS],
+ ['ThemingDoc', THEMING_DOC_FIELDS],
+ ])('%s: the projection keeps exactly the emitted fields', (name, fields) => {
+ expect([...fields].sort()).toEqual(emittedInterfaceFields(name).sort());
+ });
+
+ it('drops a published deprecated alias target and any field the current interfaces no longer declare', () => {
+ const published = {
+ container: true,
+ targets: [
+ {className: 'astryx-button', visualProps: ['color'], states: ['hover']},
+ {
+ className: 'astryx-button-old',
+ deprecatedFor: 'astryx-button',
+ states: ['hover'],
+ },
+ ],
+ vars: [
+ {
+ name: '--button-gap',
+ description: 'Gap',
+ default: '4px',
+ since: '0.6',
+ },
+ ],
+ derived: [{property: 'padding', vars: ['--p'], note: 'legacy'}],
+ legacyTargets: [],
+ };
+ expect(projectThemingDoc(published)).toEqual({
+ container: true,
+ targets: [
+ {className: 'astryx-button', visualProps: ['color'], states: ['hover']},
+ ],
+ vars: [{name: '--button-gap', description: 'Gap', default: '4px'}],
+ derived: [{property: 'padding', vars: ['--p']}],
+ });
+ });
+
+ it('returns a current doc unchanged and leaves non-objects alone', () => {
+ const current = {
+ targets: [{className: 'astryx-card'}],
+ vars: [
+ {
+ name: '--card-radius',
+ description: 'Radius',
+ default: '8px',
+ derived: true,
+ formula: 'x',
+ private: false,
+ },
+ ],
+ derived: [{property: 'padding', expand: 'container', replaces: true}],
+ };
+ expect(projectThemingDoc(current)).toEqual(current);
+ expect(projectThemingDoc(null)).toBeNull();
+ });
+});