An open source design system that's fully customizable and agent ready
TypeScript
fix(TreeList): make the variant axis themeable, and guard every axis like it (#5091)
Cindy Zhang255e810cf9a8
diff --git a/.changeset/extensible-axes-guard.md b/.changeset/extensible-axes-guard.mdnew file mode 100644index 0000000000..9f70da58e0--- /dev/null+++ b/.changeset/extensible-axes-guard.md@@ -0,0 +1,11 @@+---+'@astryxdesign/core': patch+---++[fix] TreeList's `variant` axis is themeable, and a new guard keeps every extensible axis honest. `TreeListVariantMap` invites theme packages to add variants — its own JSDoc shows the module augmentation — but `themeProps('tree-list', {density})` never passed `variant`, so a custom variant type-checked, rendered, and produced no selector to style. It is passed now, and documented in the target's `visualProps` so `astryx theme build` stops calling it an unknown prop.++`packages/core/src/theme/extensibleAxes.test.ts` is the third theming-drift guard, beside the ones covering `targets` and `vars`/`derived`. Those two check what a component renders against what it documents; neither looked at the open prop unions, which is why this went unnoticed. For every `*Map` that types a component prop, it now asserts the three places that have to agree: the interface is declared in the index a consumer augments (a re-export is invisible to both module augmentation and the CLI), the prop is reflected through `themeProps`, and it is documented as a visual prop. It reads the TypeScript AST rather than the type checker, and holds the map's OWNER accountable — a component forwarding `actionVariant` or `statusVariant` to the component that owns the map is not separately responsible for it.++Registry maps that widen a set of NAMES rather than a visual prop (`IndicatorMap`, `IndicatorFamilyMap`) are out of scope by construction, not by allowlist: the guard only considers maps whose alias types a prop on a `*Props` interface.++@cixzhangdiff --git a/packages/core/src/TreeList/TreeList.doc.mjs b/packages/core/src/TreeList/TreeList.doc.mjsindex 7e27a26bbf..ad62615b91 100644--- a/packages/core/src/TreeList/TreeList.doc.mjs+++ b/packages/core/src/TreeList/TreeList.doc.mjs@@ -24,7 +24,7 @@ export const docs = {},theming: {targets: [- {className: 'astryx-tree-list', visualProps: ['density']},+ {className: 'astryx-tree-list', visualProps: ['density', 'variant']},{className: 'astryx-tree-list-item', visualProps: ['density'], states: ['selected', 'disabled']},{className: 'astryx-tree-list-chevron', states: ['state']},{className: 'astryx-tree-list-item-label', states: ['selected']},@@ -104,7 +104,7 @@ export const docsZh = {group: 'TreeList',theming: {targets: [- {className: 'astryx-tree-list', visualProps: ['density']},+ {className: 'astryx-tree-list', visualProps: ['density', 'variant']},{className: 'astryx-tree-list-item', visualProps: ['density'], states: ['selected', 'disabled']},{className: 'astryx-tree-list-chevron', states: ['state']},{className: 'astryx-tree-list-item-label', states: ['selected']},diff --git a/packages/core/src/TreeList/TreeList.tsx b/packages/core/src/TreeList/TreeList.tsxindex 70cc8cc4d7..c79c18b529 100644--- a/packages/core/src/TreeList/TreeList.tsx+++ b/packages/core/src/TreeList/TreeList.tsx@@ -332,7 +332,7 @@ export function TreeList({ref={ref}data-testid={testId}{...mergeProps(- themeProps('tree-list', {density}),+ themeProps('tree-list', {density, variant}),stylex.props(styles.root, xstyle),className,style,diff --git a/packages/core/src/theme/extensibleAxes.test.ts b/packages/core/src/theme/extensibleAxes.test.tsnew file mode 100644index 0000000000..db1543d419--- /dev/null+++ b/packages/core/src/theme/extensibleAxes.test.ts@@ -0,0 +1,365 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/* eslint-disable @typescript-eslint/no-require-imports */+/**+ * @file Guards the EXTENSIBLE prop axes — the `*Map` interfaces a theme+ * augments — against the theming surface that has to carry them.+ * @input Component sources (*.tsx/*.ts) and their `{Name}.doc.mjs` files.+ * @output Vitest failures naming each map whose axis a theme cannot reach.+ * @position Third sibling of derivedVarRegistry.test.ts (`vars`, `derived`) and+ * themingTargets.test.ts (`targets`). Those two check what a component+ * RENDERS against what it DOCUMENTS. Neither one looks at the open prop+ * unions, so nothing did.+ *+ * An extensible axis is a promise made in three places at once, and it is only+ * kept if all three agree:+ *+ * 1. `export interface FooVariantMap` in `Foo/index.ts` — the augmentation+ * point. A consumer writes `declare module '@astryxdesign/core/Foo'`+ * against THAT subpath, and `astryx theme build` looks for the literal+ * interface there when it emits `<theme>.variants.d.ts`. A map declared+ * in a sibling file and only re-exported is invisible to both.+ * 2. `themeProps('foo', {variant})` — the axis reaching the DOM. Without it+ * a custom variant renders no selector, so there is nothing to style.+ * 3. `visualProps: ['variant']` on the doc's theming target — discovery, and+ * the reason `theme build` does not reject `'foo': {'variant:custom': …}`+ * as an unknown prop.+ *+ * Miss (2) and the type says yes while the CSS says nothing: TreeList shipped+ * `TreeListVariantMap`, with a module-augmentation example in its own JSDoc,+ * while `themeProps('tree-list', {density})` never passed `variant` — so an+ * augmented variant type-checked, rendered, and could not be themed.+ */++import {describe, it, expect} from 'vitest';+import {readdirSync, readFileSync, existsSync} from 'node:fs';+import {join, relative} from 'node:path';+import ts from 'typescript';+import {stableClassName} from '../naming';++const SRC_DIR = join(__dirname, '..');++// ---------------------------------------------------------------------------+// Source scanning+// ---------------------------------------------------------------------------++/**+ * An extensible axis, keyed by the map that owns it.+ *+ * The OWNER is the component whose index declares the interface — that is the+ * subpath a consumer augments and the component that has to reflect the prop.+ * Other components may declare a prop of the same type (`AlertDialog`'s+ * `actionVariant: ButtonVariant`, every field's `statusVariant`); they forward+ * the value to the owner and are not separately accountable for it.+ */+interface ExtensibleAxis {+ /** Component directory under src/ whose index declares the map. */+ dir: string;+ /** Interface name, e.g. 'TreeListVariantMap'. */+ mapName: string;+ /** The prop it types, read off the interface name, e.g. 'variant'. */+ prop: string;+}++function sourceFilesUnder(dir: string, out: string[] = []): string[] {+ for (const entry of readdirSync(dir, {withFileTypes: true})) {+ const full = join(dir, entry.name);+ if (entry.isDirectory()) {+ if (entry.name === 'node_modules' || entry.name === '__tests__') {continue;}+ sourceFilesUnder(full, out);+ } else if (/\.tsx?$/.test(entry.name) && !entry.name.includes('.test.')) {+ out.push(full);+ }+ }+ return out;+}++function parse(file: string): ts.SourceFile {+ return ts.createSourceFile(+ file,+ readFileSync(file, 'utf8'),+ ts.ScriptTarget.Latest,+ true,+ file.endsWith('.tsx') ? ts.ScriptKind.TSX : ts.ScriptKind.TS,+ );+}++/**+ * Every `type Alias = keyof SomethingMap` in the tree, as alias -> map name.+ * This is the shape that makes a union OPEN: augmenting the interface widens+ * the alias, which is the whole mechanism a theme package uses.+ */+function collectKeyofAliases(files: string[]): Map<string, string> {+ const aliases = new Map<string, string>();++ /** `keyof FooMap`, and the `keyof FooMap & string` narrowing form. */+ const mapBehind = (type: ts.TypeNode): string | null => {+ if (ts.isIntersectionTypeNode(type)) {+ for (const member of type.types) {+ const found = mapBehind(member);+ if (found != null) {return found;}+ }+ return null;+ }+ if (+ ts.isTypeOperatorNode(type) &&+ type.operator === ts.SyntaxKind.KeyOfKeyword &&+ ts.isTypeReferenceNode(type.type) &&+ ts.isIdentifier(type.type.typeName) &&+ type.type.typeName.text.endsWith('Map')+ ) {+ return type.type.typeName.text;+ }+ return null;+ };++ for (const file of files) {+ const visit = (node: ts.Node): void => {+ if (ts.isTypeAliasDeclaration(node)) {+ const map = mapBehind(node.type);+ if (map != null) {aliases.set(node.name.text, map);}+ }+ ts.forEachChild(node, visit);+ };+ visit(parse(file));+ }+ return aliases;+}++/**+ * Maps whose alias types a prop on some `*Props` interface — i.e. the open+ * union is a COMPONENT PROP, which is what makes it a theming axis.+ *+ * This is the line between the two kinds of augmentable map in the tree.+ * `ButtonVariantMap` widens `<Button variant>`, a visual prop that reaches the+ * DOM and gets styled. `IndicatorMap` widens the set of registered indicator+ * NAMES — a different extension mechanism (the theme's `indicators` field,+ * swapping a React component), with no selector and no visual prop. Holding+ * the second to the theming contract below would be a category error.+ */+function mapsTypingAProp(+ files: string[],+ aliases: Map<string, string>,+): Set<string> {+ const used = new Set<string>();+ for (const file of files) {+ const visit = (node: ts.Node): void => {+ if (ts.isInterfaceDeclaration(node) && node.name.text.endsWith('Props')) {+ for (const member of node.members) {+ if (!ts.isPropertySignature(member) || member.type == null) {continue;}+ const typeNode = ts.isArrayTypeNode(member.type)+ ? member.type.elementType+ : member.type;+ if (+ ts.isTypeReferenceNode(typeNode) &&+ ts.isIdentifier(typeNode.typeName)+ ) {+ const map = aliases.get(typeNode.typeName.text);+ if (map != null) {used.add(map);}+ }+ }+ }+ ts.forEachChild(node, visit);+ };+ visit(parse(file));+ }+ return used;+}++/**+ * Every map that is (a) an open union — some `type X = keyof <Map>` exists, so+ * augmenting it widens a real type — and (b) declared in a component index.+ *+ * The prop name is read off the interface, which is the same convention+ * `astryx theme build` uses to find an augmentation point:+ * `<Prefix><Prop>Map`. `TextColorMap` -> Text, `color`.+ * `AvatarStatusDotVariantMap` -> Avatar, `variant`.+ */+function collectExtensibleAxes(+ files: string[],+ aliases: Map<string, string>,+ propMaps: Set<string>,+): ExtensibleAxis[] {+ const open = propMaps;+ const axes: ExtensibleAxis[] = [];+ for (const file of files) {+ if (!/\/index\.tsx?$/.test(file)) {continue;}+ const dir = relative(SRC_DIR, file).split('/')[0];+ const visit = (node: ts.Node): void => {+ if (+ ts.isInterfaceDeclaration(node) &&+ node.name.text.endsWith('Map') &&+ open.has(node.name.text)+ ) {+ const bare = node.name.text.slice(0, -'Map'.length);+ // The trailing PascalCase word is the prop.+ const match = /([A-Z][a-z0-9]*)$/.exec(bare);+ if (match == null) {return;}+ const prop = match[1].charAt(0).toLowerCase() + match[1].slice(1);+ axes.push({dir, mapName: node.name.text, prop});+ }+ ts.forEachChild(node, visit);+ };+ visit(parse(file));+ }+ return axes;+}++/** Every `themeProps('name', {...})` site, as class -> the prop keys it passes. */+function collectThemePropsSites(files: string[]): Map<string, Set<string>> {+ const sites = new Map<string, Set<string>>();+ for (const file of files) {+ const visit = (node: ts.Node): void => {+ if (+ ts.isCallExpression(node) &&+ ts.isIdentifier(node.expression) &&+ node.expression.text === 'themeProps'+ ) {+ const [nameArg, propsArg] = node.arguments;+ if (nameArg != null && ts.isStringLiteralLike(nameArg)) {+ const cls = stableClassName(nameArg.text);+ const keys = sites.get(cls) ?? new Set<string>();+ if (propsArg != null && ts.isObjectLiteralExpression(propsArg)) {+ for (const prop of propsArg.properties) {+ const name = prop.name;+ if (+ name != null &&+ (ts.isIdentifier(name) || ts.isStringLiteralLike(name))+ ) {+ keys.add(name.text);+ }+ }+ }+ sites.set(cls, keys);+ }+ }+ ts.forEachChild(node, visit);+ };+ visit(parse(file));+ }+ return sites;+}++// ---------------------------------------------------------------------------+// Docs+// ---------------------------------------------------------------------------++interface DocTarget {+ className: string;+ visualProps: string[];+}++function collectDocTargets(dir: string): Map<string, DocTarget[]> {+ const byDir = new Map<string, DocTarget[]>();+ const walk = (current: string): void => {+ for (const entry of readdirSync(current, {withFileTypes: true})) {+ const full = join(current, entry.name);+ if (entry.isDirectory()) {+ if (entry.name === 'node_modules' || entry.name === '__tests__') {+ continue;+ }+ walk(full);+ } else if (entry.name.endsWith('.doc.mjs')) {+ const componentDir = relative(SRC_DIR, full).split('/')[0];+ let doc;+ try {+ doc = require(full).docs;+ } catch {+ continue;+ }+ const targets = (doc?.theming?.targets ?? [])+ .filter(+ (t: unknown): t is {className: string} =>+ typeof (t as {className?: unknown})?.className === 'string',+ )+ .map((t: {className: string; visualProps?: string[]}) => ({+ className: t.className,+ visualProps: t.visualProps ?? [],+ }));+ byDir.set(componentDir, [+ ...(byDir.get(componentDir) ?? []),+ ...targets,+ ]);+ }+ }+ };+ walk(dir);+ return byDir;+}++// ---------------------------------------------------------------------------++const files = sourceFilesUnder(SRC_DIR);+const aliases = collectKeyofAliases(files);+const propMaps = mapsTypingAProp(files, aliases);+const axes = collectExtensibleAxes(files, aliases, propMaps);+const themePropsSites = collectThemePropsSites(files);+const docTargets = collectDocTargets(SRC_DIR);++/** The target a component's own name maps to, e.g. TreeList -> astryx-tree-list. */+function ownTargets(axis: ExtensibleAxis): DocTarget[] {+ return docTargets.get(axis.dir) ?? [];+}++describe('extensible prop axes are reachable by a theme', () => {+ it('finds the axes at all (guards the guard)', () => {+ // If the AST walk silently stopped matching, every assertion below would+ // pass on an empty list.+ expect(axes.length).toBeGreaterThan(10);+ expect(axes.map(a => a.mapName)).toContain('ButtonVariantMap');+ });++ it('every open prop union is declared in an index a consumer can augment', () => {+ // Module augmentation only widens the module where the interface is+ // DECLARED, and the CLI greps the public subpath for that literal+ // declaration. A map in a sibling file, re-exported, satisfies neither:+ // `declare module '@astryxdesign/core/<Component>'` would create a new,+ // unrelated interface and `theme build` would emit no augmentation.+ // `collectExtensibleAxes` only reads indexes, so anything open and+ // declared elsewhere is missing from `axes` entirely — compare against+ // every open map in the tree to catch that.+ const declaredInAnIndex = new Set(axes.map(a => a.mapName));+ const notAugmentable = [...propMaps].filter(m => !declaredInAnIndex.has(m));+ expect(+ notAugmentable,+ 'these maps type an open union but are not declared in a component index, ' ++ 'so no consumer can augment them at @astryxdesign/core/<Component>',+ ).toEqual([]);+ });++ it.each(axes.map(a => [`${a.dir}.${a.prop} (${a.mapName})`, a] as const))(+ '%s reaches the DOM through themeProps',+ (_label, axis) => {+ // The axis is extensible, so a consumer can add a value we have never+ // seen. The only way their CSS can select it is if the component+ // reflects the prop.+ const targets = ownTargets(axis);+ const reflected = targets.some(t =>+ themePropsSites.get(t.className)?.has(axis.prop),+ );+ expect(+ reflected,+ `${axis.dir} lets a theme add \`${axis.prop}\` values via ${axis.mapName}, but no ` ++ `themeProps() call passes \`${axis.prop}\` — a custom value renders no selector, ` ++ `so it cannot be styled. Pass it: themeProps('<target>', {${axis.prop}}).`,+ ).toBe(true);+ },+ );++ it.each(axes.map(a => [`${a.dir}.${a.prop} (${a.mapName})`, a] as const))(+ '%s is documented as a visual prop',+ (_label, axis) => {+ // Undocumented, it is undiscoverable — and `theme build` rejects+ // `'<target>': {'<prop>:custom': …}` as an unknown prop, because its+ // known-prop set is built from exactly this field.+ const targets = ownTargets(axis);+ const documented = targets.some(t => t.visualProps.includes(axis.prop));+ expect(+ documented,+ `${axis.dir} lets a theme add \`${axis.prop}\` values via ${axis.mapName}, but no ` ++ `theming target documents \`${axis.prop}\` in visualProps — a theme author cannot ` ++ `discover the axis, and \`astryx theme build\` warns "Unknown prop" on it.`,+ ).toBe(true);+ },+ );+});