Skip to content

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

TypeScript

fix(core): document full themeProps() selector surface and guard it (#3741) (#3887)

AKff77e1ca9fc7
diff --git a/.changeset/theming-targets-guard.md b/.changeset/theming-targets-guard.md
new file mode 100644
index 0000000000..fdc622184a
--- /dev/null
+++ b/.changeset/theming-targets-guard.md
@@ -0,0 +1,13 @@
+---
+'@astryxdesign/core': patch
+---
+
+[fix] Document the full themeProps() selector surface and guard it against drift (#3741)
+
+`theming.targets` is the documented CSS surface of a component — the stable `astryx-*` classes it renders and the visual props it reflects as data attributes. It was hand-authored while the truth lived in `themeProps()` calls in the source, and nothing kept the two in agreement, so it drifted twice (#3652, #3680) and was drifted again.
+
+Eight components were under-documenting their surface: `Table` documented 4 of the 9 classes it renders (`astryx-table`, `-scroll-wrapper`, `-header`, `-body`, `-footer` were all missing), and `AvatarGroup`, `CommandPalette`, `InputGroup`, `Outline` and `ProgressBar` each hid one. `AspectRatio`, `Card` and `EmptyState` documented their visual props in `docs` but not in `docsZh`. An undocumented class is an unthemeable element: theme authors and codegen read `targets[]` to learn which selectors exist.
+
+`themingTargets.test.ts` now parses every `themeProps()` call site with the TypeScript AST and fails when a rendered class or a passed prop key is missing from `targets[]` — in both the `docs` and `docsZh` blocks. It sits next to `derivedVarRegistry.test.ts`, which already validates the sibling `vars`/`derived` fields of the same `theming` block; `targets` was the one field with no machine check. The policy is subset, not equality: docs may list more than the source passes, since components forward props they don't themselves reflect.
+
+@AKnassa
diff --git a/packages/core/src/AvatarGroup/AvatarGroup.doc.mjs b/packages/core/src/AvatarGroup/AvatarGroup.doc.mjs
index f20777a081..37809bf8f9 100644
--- a/packages/core/src/AvatarGroup/AvatarGroup.doc.mjs
+++ b/packages/core/src/AvatarGroup/AvatarGroup.doc.mjs
@@ -24,6 +24,7 @@ export const docs = {
theming: {
targets: [
{className: 'astryx-avatar-group', visualProps: ['size']},
+ {className: 'astryx-avatar-group-overflow'},
],
},
description: 'Stacked avatar display with overlapping layout and optional overflow indicator. Children are Avatar elements.',
diff --git a/packages/core/src/Card/Card.doc.mjs b/packages/core/src/Card/Card.doc.mjs
index 24a414dcd8..f3fee77eed 100644
--- a/packages/core/src/Card/Card.doc.mjs
+++ b/packages/core/src/Card/Card.doc.mjs
@@ -131,7 +131,7 @@ export const docsZh = {
theming: {
container: true,
targets: [
- {className: 'astryx-card'},
+ {className: 'astryx-card', visualProps: ['variant']},
],
vars: [
{name: '--_card-radius', description: 'Border radius of the card', default: 'var(--radius-container)', private: true},
diff --git a/packages/core/src/CommandPalette/CommandPalette.doc.mjs b/packages/core/src/CommandPalette/CommandPalette.doc.mjs
index 7a6cd96133..f6da27b2a2 100644
--- a/packages/core/src/CommandPalette/CommandPalette.doc.mjs
+++ b/packages/core/src/CommandPalette/CommandPalette.doc.mjs
@@ -142,6 +142,7 @@ export const docs = {
],
theming: {
targets: [
+ {className: 'astryx-command-palette-empty'},
{className: 'astryx-command-palette-footer'},
{className: 'astryx-command-palette-group'},
{className: 'astryx-command-palette-input'},
diff --git a/packages/core/src/EmptyState/EmptyState.doc.mjs b/packages/core/src/EmptyState/EmptyState.doc.mjs
index 7fa8645557..4ee505e8c9 100644
--- a/packages/core/src/EmptyState/EmptyState.doc.mjs
+++ b/packages/core/src/EmptyState/EmptyState.doc.mjs
@@ -140,7 +140,7 @@ export const docsZh = {
],
theming: {
targets: [
- {className: 'astryx-empty-state'},
+ {className: 'astryx-empty-state', visualProps: ['variant']},
],
},
usage: {
diff --git a/packages/core/src/InputGroup/InputGroup.doc.mjs b/packages/core/src/InputGroup/InputGroup.doc.mjs
index a42d78cf21..91150921ae 100644
--- a/packages/core/src/InputGroup/InputGroup.doc.mjs
+++ b/packages/core/src/InputGroup/InputGroup.doc.mjs
@@ -20,6 +20,7 @@ export const docs = {
theming: {
targets: [
{className: 'astryx-input-group', visualProps: ['size', 'status']},
+ {className: 'astryx-input-group-text'},
],
},
description:
diff --git a/packages/core/src/Outline/Outline.doc.mjs b/packages/core/src/Outline/Outline.doc.mjs
index 922729481e..5d0dc984c8 100644
--- a/packages/core/src/Outline/Outline.doc.mjs
+++ b/packages/core/src/Outline/Outline.doc.mjs
@@ -30,6 +30,7 @@ export const docs = {
theming: {
targets: [
{className: 'astryx-outline', visualProps: ['density']},
+ {className: 'astryx-outline-indicator'},
{className: 'astryx-outline-item', visualProps: ['level'], states: ['active']},
],
},
@@ -163,6 +164,7 @@ export const docsZh = {
theming: {
targets: [
{className: 'astryx-outline', visualProps: ['density']},
+ {className: 'astryx-outline-indicator'},
{className: 'astryx-outline-item', visualProps: ['level'], states: ['active']},
],
},
diff --git a/packages/core/src/ProgressBar/ProgressBar.doc.mjs b/packages/core/src/ProgressBar/ProgressBar.doc.mjs
index bd47c90a61..e789d9fbf9 100644
--- a/packages/core/src/ProgressBar/ProgressBar.doc.mjs
+++ b/packages/core/src/ProgressBar/ProgressBar.doc.mjs
@@ -73,6 +73,7 @@ export const docs = {
targets: [
{className: 'astryx-progressbar', visualProps: ['variant']},
{className: 'astryx-progressbar-fill', visualProps: ['variant']},
+ {className: 'astryx-progressbar-track'},
],
},
usage: {
@@ -159,6 +160,7 @@ export const docsZh = {
targets: [
{className: 'astryx-progressbar', visualProps: ['variant']},
{className: 'astryx-progressbar-fill', visualProps: ['variant']},
+ {className: 'astryx-progressbar-track'},
],
},
usage: {
diff --git a/packages/core/src/Table/Table.doc.mjs b/packages/core/src/Table/Table.doc.mjs
index 377ff8efd0..3bd7b0f2e0 100644
--- a/packages/core/src/Table/Table.doc.mjs
+++ b/packages/core/src/Table/Table.doc.mjs
@@ -25,6 +25,11 @@ export const docs = {
theming: {
targets: [
{className: 'astryx-base-table'},
+ {className: 'astryx-table'},
+ {className: 'astryx-table-scroll-wrapper'},
+ {className: 'astryx-table-header'},
+ {className: 'astryx-table-body'},
+ {className: 'astryx-table-footer'},
{className: 'astryx-table-row'},
{className: 'astryx-table-cell'},
{className: 'astryx-table-header-cell'},
diff --git a/packages/core/src/theme/themingTargets.test.ts b/packages/core/src/theme/themingTargets.test.ts
new file mode 100644
index 0000000000..f5aeb6a0d5
--- /dev/null
+++ b/packages/core/src/theme/themingTargets.test.ts
@@ -0,0 +1,353 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/* 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.
+ * @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).
+ *
+ * `theming.targets` is the documented CSS surface of a component: the stable
+ * `astryx-*` classes it renders and the visual props it reflects as data
+ * attributes. It is hand-authored, while the truth lives in `themeProps()`
+ * calls in the source. Nothing kept the two in agreement.
+ *
+ * Drift is not cosmetic. `targets` is what theme authors and codegen read to
+ * learn which selectors exist; an undocumented class is an unthemeable element.
+ *
+ * Policy is SUBSET, not equality: every class rendered by `themeProps()` must be
+ * documented, and every prop key passed to it must appear in that target's
+ * `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.
+ */
+
+import {describe, it, expect} from 'vitest';
+import {readdirSync, readFileSync} from 'node:fs';
+import {join} from 'node:path';
+import ts from 'typescript';
+import {stableClassName} from '../naming';
+
+const SRC_DIR = join(__dirname, '..');
+
+// ---------------------------------------------------------------------------
+// Source scanning: find themeProps() call sites via the TypeScript AST
+// ---------------------------------------------------------------------------
+
+interface ThemeTargetSite {
+ /** Full stable class, e.g. 'astryx-progressbar-fill'. */
+ className: string;
+ /** Keys of the object literal passed as the 2nd arg (may be empty). */
+ propKeys: string[];
+ /** True when the 2nd arg exists but its keys can't be read statically. */
+ isOpaque: boolean;
+}
+
+/**
+ * Extract every `themeProps('name', {...})` call from a source file.
+ *
+ * Uses the AST rather than a regex because the call sites use every object
+ * form: shorthand (`{variant}`), renamed (`{variant: fillVariant}` — the KEY is
+ * the prop, not the value), and multi-line. A regex reading identifiers after
+ * `:` would record `fillVariant`, a prop that does not exist.
+ */
+function extractThemeTargets(
+ sourceText: string,
+ fileName = 'source.tsx',
+): ThemeTargetSite[] {
+ const sourceFile = ts.createSourceFile(
+ fileName,
+ sourceText,
+ ts.ScriptTarget.Latest,
+ /* setParentNodes */ true,
+ fileName.endsWith('.tsx') ? ts.ScriptKind.TSX : ts.ScriptKind.TS,
+ );
+
+ const sites: ThemeTargetSite[] = [];
+
+ const visit = (node: ts.Node): void => {
+ if (
+ ts.isCallExpression(node) &&
+ ts.isIdentifier(node.expression) &&
+ node.expression.text === 'themeProps'
+ ) {
+ const [nameArg, propsArg] = node.arguments;
+
+ // Only string-literal component names are resolvable. A dynamic name
+ // can't be checked statically; skip rather than guess.
+ if (nameArg != null && ts.isStringLiteralLike(nameArg)) {
+ const site: ThemeTargetSite = {
+ className: stableClassName(nameArg.text),
+ propKeys: [],
+ isOpaque: false,
+ };
+
+ if (propsArg != null) {
+ if (ts.isObjectLiteralExpression(propsArg)) {
+ for (const prop of propsArg.properties) {
+ if (ts.isSpreadAssignment(prop)) {
+ // {...rest} — keys unknown at parse time.
+ site.isOpaque = true;
+ continue;
+ }
+ const name = prop.name;
+ if (name == null) {
+ site.isOpaque = true;
+ continue;
+ }
+ if (ts.isIdentifier(name) || ts.isStringLiteralLike(name)) {
+ site.propKeys.push(name.text);
+ } else {
+ // Computed key: themeProps('x', {[k]: v})
+ site.isOpaque = true;
+ }
+ }
+ } else {
+ // A variable or call passed as the props bag.
+ site.isOpaque = true;
+ }
+ }
+
+ sites.push(site);
+ }
+ }
+
+ ts.forEachChild(node, visit);
+ };
+
+ visit(sourceFile);
+ return sites;
+}
+
+// ---------------------------------------------------------------------------
+// The extractor must be right before its verdicts mean anything.
+// ---------------------------------------------------------------------------
+
+describe('extractThemeTargets', () => {
+ it('reads a bare call with no props', () => {
+ expect(extractThemeTargets(`themeProps('progressbar-track')`)).toEqual([
+ {className: 'astryx-progressbar-track', propKeys: [], isOpaque: false},
+ ]);
+ });
+
+ it('reads shorthand props', () => {
+ expect(extractThemeTargets(`themeProps('progressbar', {variant})`)).toEqual(
+ [
+ {
+ className: 'astryx-progressbar',
+ propKeys: ['variant'],
+ isOpaque: false,
+ },
+ ],
+ );
+ });
+
+ it('records the KEY, not the value, when a prop is renamed', () => {
+ // The trap a regex falls into: `fillVariant` is a local, not a prop.
+ expect(
+ extractThemeTargets(
+ `themeProps('progressbar-fill', {variant: fillVariant})`,
+ ),
+ ).toEqual([
+ {
+ className: 'astryx-progressbar-fill',
+ propKeys: ['variant'],
+ isOpaque: false,
+ },
+ ]);
+ });
+
+ it('reads multi-line object literals', () => {
+ const src = `
+ const p = themeProps('outline', {
+ variant,
+ size: resolvedSize,
+ });
+ `;
+ expect(extractThemeTargets(src)).toEqual([
+ {
+ className: 'astryx-outline',
+ propKeys: ['variant', 'size'],
+ isOpaque: false,
+ },
+ ]);
+ });
+
+ it('reads a call whose result is immediately accessed', () => {
+ // Table does `themeProps('table').className` — still a rendered class.
+ expect(extractThemeTargets(`themeProps('table').className`)).toEqual([
+ {className: 'astryx-table', propKeys: [], isOpaque: false},
+ ]);
+ });
+
+ it('finds every call in a file', () => {
+ const src = `
+ <div {...themeProps('card', {variant})}>
+ <span {...themeProps('card-header')} />
+ </div>
+ `;
+ expect(extractThemeTargets(src).map(s => s.className)).toEqual([
+ 'astryx-card',
+ 'astryx-card-header',
+ ]);
+ });
+
+ it('marks a spread props bag opaque rather than guessing its keys', () => {
+ const [site] = extractThemeTargets(`themeProps('card', {...rest})`);
+ expect(site.isOpaque).toBe(true);
+ expect(site.propKeys).toEqual([]);
+ });
+
+ it('marks a non-literal props bag opaque', () => {
+ const [site] = extractThemeTargets(`themeProps('card', visualProps)`);
+ expect(site.isOpaque).toBe(true);
+ });
+
+ it('ignores a dynamic component name it cannot resolve', () => {
+ expect(extractThemeTargets(`themeProps(name, {variant})`)).toEqual([]);
+ });
+
+ it('ignores an unrelated function of a similar shape', () => {
+ expect(extractThemeTargets(`stylex.props('card', {variant})`)).toEqual([]);
+ });
+});
+
+// ---------------------------------------------------------------------------
+// Discovery: every component dir's rendered classes vs its documented targets
+// ---------------------------------------------------------------------------
+
+interface DocTarget {
+ className: string;
+ visualProps?: string[];
+ states?: string[];
+}
+
+type DocBlock = {theming?: {targets?: DocTarget[]}};
+type ComponentDocModule = {docs?: DocBlock; docsZh?: DocBlock};
+
+interface ComponentInfo {
+ dir: string;
+ sites: ThemeTargetSite[];
+ /** The doc blocks that carry theming.targets, by the key they live under. */
+ docBlocks: {key: 'docs' | 'docsZh'; targets: DocTarget[]}[];
+}
+
+function discoverComponents(): ComponentInfo[] {
+ const results: ComponentInfo[] = [];
+ const dirs = readdirSync(SRC_DIR, {withFileTypes: true})
+ .filter(d => d.isDirectory())
+ .map(d => d.name);
+
+ for (const dir of dirs) {
+ const dirPath = join(SRC_DIR, dir);
+ const dirEntries = readdirSync(dirPath);
+
+ const sourceFiles = dirEntries.filter(
+ f =>
+ (f.endsWith('.tsx') || f.endsWith('.ts')) &&
+ !f.includes('.test.') &&
+ !f.endsWith('.d.ts'),
+ );
+
+ const sites: ThemeTargetSite[] = [];
+ for (const f of sourceFiles) {
+ const filePath = join(dirPath, f);
+ sites.push(
+ ...extractThemeTargets(readFileSync(filePath, 'utf-8'), filePath),
+ );
+ }
+ if (sites.length === 0) {
+ continue;
+ }
+
+ // Match the on-disk listing rather than existsSync: on case-insensitive
+ // filesystems existsSync would match a differently-cased doc file that CI
+ // never checks. (Same guard as derivedVarRegistry.test.ts.)
+ if (!dirEntries.includes(`${dir}.doc.mjs`)) {
+ continue;
+ }
+
+ let mod: ComponentDocModule;
+ try {
+ mod = require(join(dirPath, `${dir}.doc.mjs`)) as ComponentDocModule;
+ } catch {
+ continue;
+ }
+
+ const docBlocks: ComponentInfo['docBlocks'] = [];
+ 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.
+ if (targets != null) {
+ docBlocks.push({key, targets});
+ }
+ }
+ if (docBlocks.length === 0) {
+ continue;
+ }
+
+ results.push({dir, sites, docBlocks});
+ }
+ return results;
+}
+
+// ---------------------------------------------------------------------------
+// The guard
+// ---------------------------------------------------------------------------
+
+describe('theming.targets matches the themeProps() call sites', () => {
+ const components = discoverComponents();
+
+ it('finds components to check', () => {
+ // A refactor that renames themeProps must not silently disable this file.
+ expect(components.length).toBeGreaterThan(0);
+ });
+
+ for (const {dir, sites, docBlocks} of components) {
+ const renderedClasses = [...new Set(sites.map(s => s.className))].sort();
+
+ for (const {key, targets} of docBlocks) {
+ const documented = new Set(targets.map(t => t.className));
+
+ it(`${dir} (${key}): every rendered class is documented`, () => {
+ const undocumented = renderedClasses.filter(c => !documented.has(c));
+ expect(
+ undocumented,
+ `${dir} renders ${undocumented.length} astryx-* class(es) that ` +
+ `${dir}.doc.mjs ${key}.theming.targets does not document: ` +
+ `${undocumented.join(', ')}. An undocumented class is an ` +
+ `unthemeable element — theme authors and codegen read targets[] ` +
+ `to learn which selectors exist. Add {className: '...'} entries.`,
+ ).toEqual([]);
+ });
+
+ it(`${dir} (${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);
+ if (target == null) {
+ continue; // Reported by the class test above.
+ }
+ const known = new Set([
+ ...(target.visualProps || []),
+ ...(target.states || []),
+ ]);
+ for (const propKey of site.propKeys) {
+ if (!known.has(propKey)) {
+ missing.push(`${site.className}: ${propKey}`);
+ }
+ }
+ }
+ expect(
+ [...new Set(missing)],
+ `${dir} passes prop keys to themeProps() that ${dir}.doc.mjs ` +
+ `${key}.theming.targets does not list under visualProps/states. ` +
+ `Each one is a [data-*] selector consumers cannot discover.`,
+ ).toEqual([]);
+ });
+ }
+ }
+});