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.mjsindex 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.mjsnew file mode 100644index 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.tsnew file mode 100644index 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();+ });+});