@astryxdesign/core 0.1.4 → 0.1.5-canary.76e6697

package/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([]);
+      });
+    }
+  }
+});

package/src/theme/tokens.test.ts

@@ -20,9 +20,7 @@ const testTheme = defineTheme({
 
 describe('tokenVar', () => {
   it('returns a CSS var() reference for known token names', () => {
-    expect(tokenVar('--color-text-primary')).toBe(
-      'var(--color-text-primary)',
-    );
+    expect(tokenVar('--color-text-primary')).toBe('var(--color-text-primary)');
   });
 
   it('returns a CSS var() reference for custom token names', () => {
@@ -32,9 +30,7 @@ describe('tokenVar', () => {
 
 describe('tokenVars', () => {
   it('contains var() references for known tokens', () => {
-    expect(tokenVars['--color-text-primary']).toBe(
-      'var(--color-text-primary)',
-    );
+    expect(tokenVars['--color-text-primary']).toBe('var(--color-text-primary)');
     expect(tokenVars['--spacing-4']).toBe('var(--spacing-4)');
   });
 });
@@ -87,9 +83,9 @@ describe('resolveThemeTokens', () => {
 
 describe('resolveThemeToken', () => {
   it('resolves one token', () => {
-    expect(
-      resolveThemeToken(testTheme, '--color-accent', {mode: 'dark'}),
-    ).toBe('#FF5555');
+    expect(resolveThemeToken(testTheme, '--color-accent', {mode: 'dark'})).toBe(
+      '#FF5555',
+    );
   });
 
   it('returns fallback for unknown token names', () => {
@@ -107,3 +103,180 @@ describe('resolveThemeToken', () => {
     ).toBe('');
   });
 });
+
+describe('resolveThemeTokens — reference resolution', () => {
+  it('resolves a token that references another token to a raw value', () => {
+    const theme = defineTheme({
+      name: 'ref',
+      tokens: {
+        '--color-accent': ['#0058D2', '#BBC2FF'],
+        '--color-text-accent': 'var(--color-accent)',
+      },
+    });
+
+    const light = resolveThemeTokens(theme, {mode: 'light'});
+    const dark = resolveThemeTokens(theme, {mode: 'dark'});
+
+    expect(light['--color-text-accent']).toBe('#0058D2');
+    expect(dark['--color-text-accent']).toBe('#BBC2FF');
+  });
+
+  it('resolves reference chains iteratively', () => {
+    const theme = defineTheme({
+      name: 'chain',
+      tokens: {
+        '--color-accent': ['#112233', '#445566'],
+        '--color-icon-accent': 'var(--color-accent)',
+        '--color-text-accent': 'var(--color-icon-accent)',
+      },
+    });
+
+    const light = resolveThemeTokens(theme, {mode: 'light'});
+    expect(light['--color-icon-accent']).toBe('#112233');
+    expect(light['--color-text-accent']).toBe('#112233');
+  });
+
+  it('uses the var() fallback when the referenced token is unknown', () => {
+    const theme = defineTheme({
+      name: 'fallback',
+      tokens: {
+        '--color-text-accent': 'var(--not-a-token, #ABCDEF)',
+      },
+    });
+
+    const tokens = resolveThemeTokens(theme, {mode: 'light'});
+    expect(tokens['--color-text-accent']).toBe('#ABCDEF');
+  });
+
+  it('leaves an unresolvable reference as a literal var()', () => {
+    const theme = defineTheme({
+      name: 'unresolvable',
+      tokens: {
+        '--color-text-accent': 'var(--not-a-token)',
+      },
+    });
+
+    const tokens = resolveThemeTokens(theme, {mode: 'light'});
+    expect(tokens['--color-text-accent']).toBe('var(--not-a-token)');
+  });
+
+  it('does not loop forever on a reference cycle', () => {
+    const theme = defineTheme({
+      name: 'cycle',
+      tokens: {
+        '--color-text-accent': 'var(--color-icon-accent)',
+        '--color-icon-accent': 'var(--color-text-accent)',
+      },
+    });
+
+    const tokens = resolveThemeTokens(theme, {mode: 'light'});
+    // The cycle collapses to a literal reference rather than hanging.
+    expect(tokens['--color-text-accent']).toContain('var(');
+    expect(tokens['--color-icon-accent']).toContain('var(');
+  });
+});
+
+describe('resolveThemeTokens — CSS color functions', () => {
+  it('evaluates color-mix with transparent to an rgba() value', () => {
+    const theme = defineTheme({
+      name: 'mix',
+      tokens: {
+        '--color-accent': ['#0058D2', '#BBC2FF'],
+        '--color-accent-muted':
+          'color-mix(in srgb, var(--color-accent) 20%, transparent)',
+      },
+    });
+
+    const light = resolveThemeTokens(theme, {mode: 'light'});
+    const dark = resolveThemeTokens(theme, {mode: 'dark'});
+
+    expect(light['--color-accent-muted']).toBe('rgba(0, 88, 210, 0.2)');
+    expect(dark['--color-accent-muted']).toBe('rgba(187, 194, 255, 0.2)');
+  });
+
+  it('resolves the muted token inside a light-dark() tuple per mode', () => {
+    const theme = defineTheme({
+      name: 'ld-mix',
+      tokens: {
+        '--color-accent': ['#FF0000', '#00FF00'],
+        '--color-accent-muted': [
+          'color-mix(in srgb, var(--color-accent) 20%, transparent)',
+          'color-mix(in srgb, var(--color-accent) 25%, transparent)',
+        ],
+      },
+    });
+
+    const light = resolveThemeTokens(theme, {mode: 'light'});
+    const dark = resolveThemeTokens(theme, {mode: 'dark'});
+
+    expect(light['--color-accent-muted']).toBe('rgba(255, 0, 0, 0.2)');
+    expect(dark['--color-accent-muted']).toBe('rgba(0, 255, 0, 0.25)');
+  });
+
+  it('mixes two opaque colors by weight', () => {
+    const theme = defineTheme({
+      name: 'two-color',
+      tokens: {
+        '--color-neutral': 'color-mix(in srgb, #000000, #FFFFFF)',
+      },
+    });
+
+    const tokens = resolveThemeTokens(theme, {mode: 'light'});
+    expect(tokens['--color-neutral']).toBe('#808080');
+  });
+
+  it('mixes two opaque colors with an explicit percentage', () => {
+    const theme = defineTheme({
+      name: 'weighted',
+      tokens: {
+        '--color-neutral': 'color-mix(in srgb, #000000 25%, #FFFFFF)',
+      },
+    });
+
+    const tokens = resolveThemeTokens(theme, {mode: 'light'});
+    expect(tokens['--color-neutral']).toBe('#BFBFBF');
+  });
+
+  it('preserves an unsupported color space rather than guessing', () => {
+    const theme = defineTheme({
+      name: 'oklab',
+      tokens: {
+        '--color-accent': ['#0058D2', '#BBC2FF'],
+        '--color-neutral':
+          'color-mix(in oklab, var(--color-accent), black 15%)',
+      },
+    });
+
+    const tokens = resolveThemeTokens(theme, {mode: 'light'});
+    // var() still resolves; the unsupported mix stays as a color-mix() expression.
+    expect(tokens['--color-neutral']).toContain('color-mix(in oklab');
+    expect(tokens['--color-neutral']).toContain('#0058D2');
+  });
+});
+
+describe('resolveThemeTokens — generated themes end to end', () => {
+  it('resolves derived accent tokens from defineTheme({color}) to raw values', () => {
+    const theme = defineTheme({name: 'brand', color: {accent: '#0064E0'}});
+
+    const light = resolveThemeTokens(theme, {mode: 'light'});
+    const dark = resolveThemeTokens(theme, {mode: 'dark'});
+
+    const isConcreteColor = (value: string): boolean => /^(#|rgb)/.test(value);
+
+    for (const key of [
+      '--color-accent',
+      '--color-text-accent',
+      '--color-icon-accent',
+      '--color-accent-muted',
+    ]) {
+      expect(isConcreteColor(light[key])).toBe(true);
+      expect(isConcreteColor(dark[key])).toBe(true);
+      expect(light[key]).not.toContain('var(');
+      expect(light[key]).not.toContain('color-mix');
+    }
+
+    // The derived accent tokens resolve to the base accent.
+    expect(light['--color-text-accent']).toBe(light['--color-accent']);
+    expect(light['--color-icon-accent']).toBe(light['--color-accent']);
+  });
+});