Skip to content

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

TypeScript

test(theme): guard participating Lab theming targets (#5717)

Cindy Zhange4f8e4ea3390
diff --git a/packages/core/src/theme/themingTargets.test.ts b/packages/core/src/theme/themingTargets.test.ts
index 11ba11453a..28f75d0997 100644
--- a/packages/core/src/theme/themingTargets.test.ts
+++ b/packages/core/src/theme/themingTargets.test.ts
@@ -3,8 +3,10 @@
/* eslint-disable @typescript-eslint/no-require-imports */
/**
* @file Guards `theming.targets` against the real `themeProps()` call sites (#3741).
- * @input Component sources (*.tsx/*.ts) and their `{Name}.doc.mjs` files.
- * @output Vitest failures naming each undocumented class / visual prop.
+ * @input Core/Lab component sources (*.tsx/*.ts), their `{Name}.doc.mjs`
+ * files, and the Lab promotion-candidate manifest.
+ * @output Vitest failures naming each undocumented class / visual prop on the
+ * stable Core surface or a capability-participating Lab component.
* @position Sibling of derivedVarRegistry.test.ts, which already validates the
* OTHER fields of the same `theming` block (`vars`, `derived`). `targets` was
* the one field with no machine check, so it drifted — twice (#3652, #3680).
@@ -22,6 +24,11 @@
* `visualProps` or `states`. Docs may list MORE than the source passes —
* components forward props they don't themselves reflect (Timestamp passes
* `{format}` but documents `type`/`color`/`format`), and that is intentional.
+ *
+ * Lab is capability-based: a component participates when it already declares
+ * `theming.targets` or enters the existing promotion-candidate manifest. Other
+ * Lab components remain free to iterate with runtime hooks that are not yet a
+ * documented public theming promise.
*/
import {describe, it, expect} from 'vitest';
@@ -30,7 +37,23 @@ import {join, relative} from 'node:path';
import ts from 'typescript';
import {stableClassName} from '../naming';
-const SRC_DIR = join(__dirname, '..');
+const CORE_SRC_DIR = join(__dirname, '..');
+const LAB_SRC_DIR = join(__dirname, '../../../lab/src');
+const LAB_PROMOTION_MANIFEST = join(
+ __dirname,
+ '../../../../internal/lab-readiness/manifest.mjs',
+);
+
+interface LabPromotionCandidate {
+ sourceDir: string;
+}
+
+const {CANDIDATES: labPromotionCandidates} = require(
+ LAB_PROMOTION_MANIFEST,
+) as {CANDIDATES: LabPromotionCandidate[]};
+const LAB_PROMOTION_DIRS = new Set(
+ labPromotionCandidates.map(candidate => candidate.sourceDir),
+);
// ---------------------------------------------------------------------------
// Source scanning: find themeProps() call sites via the TypeScript AST
@@ -314,6 +337,7 @@ type DocBlock = {theming?: {targets?: DocTarget[]}};
type ComponentDocModule = {docs?: DocBlock; docsZh?: DocBlock};
interface ComponentInfo {
+ packageName: 'core' | 'lab';
dir: string;
sites: ThemeTargetSite[];
/** The doc blocks that carry theming.targets, by the key they live under. */
@@ -328,7 +352,10 @@ interface ComponentInfo {
* Reads the file as text rather than requiring it: this runs for directories
* that have no doc of their own, so most candidates are misses.
*/
-function docFilesDocumenting(classNames: Set<string>): string[] {
+function docFilesDocumenting(
+ srcDir: string,
+ classNames: Set<string>,
+): string[] {
const matches: string[] = [];
const walk = (dir: string): void => {
for (const entry of readdirSync(dir, {withFileTypes: true})) {
@@ -346,18 +373,22 @@ function docFilesDocumenting(classNames: Set<string>): string[] {
}
}
};
- walk(SRC_DIR);
+ walk(srcDir);
return matches;
}
-function discoverComponents(): ComponentInfo[] {
+function discoverComponents(
+ srcDir: string,
+ packageName: ComponentInfo['packageName'],
+ requiredDirs: ReadonlySet<string> = new Set(),
+): ComponentInfo[] {
const results: ComponentInfo[] = [];
- const dirs = readdirSync(SRC_DIR, {withFileTypes: true})
+ const dirs = readdirSync(srcDir, {withFileTypes: true})
.filter(d => d.isDirectory())
.map(d => d.name);
for (const dir of dirs) {
- const dirPath = join(SRC_DIR, dir);
+ const dirPath = join(srcDir, dir);
const dirEntries = readdirSync(dirPath);
const sourceFiles = dirEntries.filter(
@@ -389,10 +420,7 @@ function discoverComponents(): ComponentInfo[] {
// doc file that CI never checks. (Same guard as derivedVarRegistry.test.ts.)
const docFiles = dirEntries.includes(`${dir}.doc.mjs`)
? [join(dirPath, `${dir}.doc.mjs`)]
- : docFilesDocumenting(new Set(sites.map(s => s.className)));
- if (docFiles.length === 0) {
- continue;
- }
+ : docFilesDocumenting(srcDir, new Set(sites.map(s => s.className)));
const docBlocks: ComponentInfo['docBlocks'] = [];
for (const docFile of docFiles) {
@@ -404,18 +432,23 @@ function discoverComponents(): ComponentInfo[] {
}
for (const key of ['docs', 'docsZh'] as const) {
const targets = mod[key]?.theming?.targets;
- // Only blocks that already document a theming surface are held to it —
- // a doc with no theming block at all is a separate (documentation) gap.
+ // A normal Core or Lab component enrolls by declaring a theming
+ // surface. Promotion candidates are also enrolled here so a missing
+ // block is a failure rather than a silently skipped readiness gap.
if (targets != null) {
- docBlocks.push({key, file: relative(SRC_DIR, docFile), targets});
+ docBlocks.push({key, file: relative(srcDir, docFile), targets});
}
}
}
- if (docBlocks.length === 0) {
+ const participates =
+ packageName === 'core'
+ ? docBlocks.length > 0
+ : requiredDirs.has(dir) || docBlocks.length > 0;
+ if (!participates) {
continue;
}
- results.push({dir, sites, docBlocks});
+ results.push({packageName, dir, sites, docBlocks});
}
return results;
}
@@ -425,24 +458,57 @@ function discoverComponents(): ComponentInfo[] {
// ---------------------------------------------------------------------------
describe('theming.targets matches the themeProps() call sites', () => {
- const components = discoverComponents();
+ const components = [
+ ...discoverComponents(CORE_SRC_DIR, 'core'),
+ ...discoverComponents(LAB_SRC_DIR, 'lab', LAB_PROMOTION_DIRS),
+ ];
+
+ it('finds participating Core and Lab components', () => {
+ // A refactor that renames themeProps or drops the Lab package from this
+ // inventory must not silently disable either side of the guard.
+ expect(components.some(component => component.packageName === 'core')).toBe(
+ true,
+ );
+ expect(components.some(component => component.packageName === 'lab')).toBe(
+ true,
+ );
+ });
- it('finds components to check', () => {
- // A refactor that renames themeProps must not silently disable this file.
- expect(components.length).toBeGreaterThan(0);
+ it('enrolls every Lab promotion candidate and explicit theming capability', () => {
+ const labDirs = new Set(
+ components
+ .filter(component => component.packageName === 'lab')
+ .map(component => component.dir),
+ );
+ expect([...LAB_PROMOTION_DIRS].filter(dir => !labDirs.has(dir))).toEqual(
+ [],
+ );
+ expect(LAB_PROMOTION_DIRS.has('CircularProgress')).toBe(false);
+ expect(labDirs.has('CircularProgress')).toBe(true);
+ expect(labDirs.has('Schedule')).toBe(false);
});
- for (const {dir, sites, docBlocks} of components) {
+ for (const {packageName, dir, sites, docBlocks} of components) {
+ const componentLabel = `${packageName}/${dir}`;
const renderedClasses = [...new Set(sites.map(s => s.className))].sort();
+ it(`${componentLabel}: participating components declare theming metadata`, () => {
+ expect(
+ docBlocks,
+ `${componentLabel} participates in the public theming contract but has ` +
+ `no loadable .doc.mjs theming.targets. Lab components participate ` +
+ `when they declare theming.targets or enter the promotion manifest.`,
+ ).not.toHaveLength(0);
+ });
+
for (const {key, file, targets} of docBlocks) {
const documented = new Set(targets.map(t => t.className));
- it(`${dir} (${file} ${key}): every rendered class is documented`, () => {
+ it(`${componentLabel} (${file} ${key}): every rendered class is documented`, () => {
const undocumented = renderedClasses.filter(c => !documented.has(c));
expect(
undocumented,
- `${dir} renders ${undocumented.length} astryx-* class(es) that ` +
+ `${componentLabel} renders ${undocumented.length} astryx-* class(es) that ` +
`${file} ${key}.theming.targets does not document: ` +
`${undocumented.join(', ')}. An undocumented class is an ` +
`unthemeable element — theme authors and codegen read targets[] ` +
@@ -450,7 +516,7 @@ describe('theming.targets matches the themeProps() call sites', () => {
).toEqual([]);
});
- it(`${dir} (${file} ${key}): every visual prop passed to themeProps is documented`, () => {
+ it(`${componentLabel} (${file} ${key}): every visual prop passed to themeProps is documented`, () => {
const missing: string[] = [];
for (const site of sites) {
const target = targets.find(t => t.className === site.className);