@astryxdesign/core 0.4.0 → 0.4.1

package/src/serverSafeComponents.test.ts

@@ -0,0 +1,665 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Guards the RSC server/client boundary of every public component (#823).
+ * @input Reads packages/core/package.json export map + every source file under
+ *   packages/core/src, parsed with the TypeScript compiler API
+ * @output Unit tests for the detection rules, plus two invariants tying the
+ *   presence of `'use client'` to what a component's import graph actually needs
+ * @position Cross-cutting meta-test; sibling of scripts/check-use-client.mjs
+ *
+ * `scripts/check-use-client.mjs` enforces one direction only, and only
+ * directly: a file that *imports* a React client API must carry the directive.
+ * It is blind to two things this test covers:
+ *
+ *   1. Components carrying `'use client'` that no longer need it. A stale
+ *      directive is not a lint error, but it pins the component to the client
+ *      bundle and blocks it from ever resolving through a `react-server`
+ *      export condition (#823 Phase 2).
+ *   2. Components that become client-only *transitively* — e.g. a directive-
+ *      free `Badge.tsx` starting to import `Tooltip`. Badge itself imports no
+ *      React client API, so check-use-client.mjs stays silent, yet Badge is no
+ *      longer server-renderable.
+ *
+ * Both invariants below derive the server-safe set from the import graph, so
+ * the safe list is never written down twice — adding a hook (or a client
+ * import) to one of these components fails the test on its own.
+ *
+ * SYNC: When modified, update this header and scripts/check-use-client.mjs if
+ * the client-API list changes.
+ */
+
+import {describe, it, expect} from 'vitest';
+import {readdirSync, readFileSync, existsSync, statSync} from 'node:fs';
+import {createRequire} from 'node:module';
+import {join, dirname, resolve, relative} from 'node:path';
+import ts from 'typescript';
+
+const SRC_DIR = __dirname;
+const PKG_JSON = join(SRC_DIR, '..', 'package.json');
+
+/**
+ * React APIs that only exist in a client component. Kept in sync with
+ * `CLIENT_APIS` in scripts/check-use-client.mjs.
+ */
+const CLIENT_APIS = new Set([
+  'createContext',
+  'useContext',
+  // React 19's context read. `use(promise)` *is* legal on the server, so this
+  // over-approximates — but every `use()` call site in this package reads a
+  // context, which is exactly as client-only as useContext.
+  'use',
+  'useActionState',
+  'useState',
+  'useEffect',
+  'useEffectEvent',
+  'useRef',
+  'useCallback',
+  'useMemo',
+  'useReducer',
+  'useId',
+  'useTransition',
+  'useOptimistic',
+  'useSyncExternalStore',
+  'useLayoutEffect',
+  'useInsertionEffect',
+  'useImperativeHandle',
+  'useDeferredValue',
+  // The one non-hook export in react's client-only set.
+  'startTransition',
+]);
+
+const EXTENSIONS = ['.tsx', '.ts', '.mjs', '.js', '.jsx'];
+
+const isSourceFile = (name: string) =>
+  /\.[jt]sx?$/.test(name) &&
+  !/\.(test|test-violations|stories|doc|perf)\./.test(name) &&
+  !name.endsWith('.d.ts');
+
+/** Resolve a relative import specifier the way a bundler would. */
+function resolveSpecifier(spec: string, fromFile: string): string | null {
+  if (!spec.startsWith('.')) {
+    return null;
+  }
+  const base = resolve(dirname(fromFile), spec);
+  for (const ext of EXTENSIONS) {
+    if (existsSync(base + ext)) {
+      return base + ext;
+    }
+  }
+  if (existsSync(base) && statSync(base).isDirectory()) {
+    for (const ext of EXTENSIONS) {
+      const index = join(base, `index${ext}`);
+      if (existsSync(index)) {
+        return index;
+      }
+    }
+  }
+  return null;
+}
+
+interface ReExport {
+  target: string;
+  exportedName: string;
+  localName: string;
+}
+
+interface ModuleInfo {
+  rel: string;
+  hasUseClient: boolean;
+  clientAPIs: string[];
+  reactDom: string[];
+  moduleMutableState: string[];
+  /** Plain imports: the names pulled, or '*' for default/namespace/side-effect. */
+  imports: {target: string; names: Set<string> | '*'}[];
+  reExports: ReExport[];
+  starReExports: string[];
+  /** True when every top-level statement is an import or a re-export. */
+  isPureBarrel: boolean;
+}
+
+const moduleCache = new Map<string, ModuleInfo>();
+
+/** Every named binding in the clause is `type`-only, so the import is erased. */
+function isTypeOnlyImport(clause: ts.ImportClause): boolean {
+  if (clause.isTypeOnly) {
+    return true;
+  }
+  if (clause.name) {
+    return false;
+  }
+  const bindings = clause.namedBindings;
+  if (!bindings || !ts.isNamedImports(bindings)) {
+    return false;
+  }
+  return (
+    bindings.elements.length > 0 &&
+    bindings.elements.every(element => element.isTypeOnly)
+  );
+}
+
+function isTypeOnlyExport(node: ts.ExportDeclaration): boolean {
+  if (node.isTypeOnly) {
+    return true;
+  }
+  const clause = node.exportClause;
+  if (!clause || !ts.isNamedExports(clause)) {
+    return false;
+  }
+  return (
+    clause.elements.length > 0 &&
+    clause.elements.every(element => element.isTypeOnly)
+  );
+}
+
+function parseModule(file: string): ModuleInfo {
+  const cached = moduleCache.get(file);
+  if (cached) {
+    return cached;
+  }
+  const info = parseSource(readFileSync(file, 'utf-8'), file);
+  moduleCache.set(file, info);
+  return info;
+}
+
+/**
+ * Parse one module's source. Split from {@link parseModule} so the detection
+ * rules can be unit-tested against source strings rather than real files.
+ */
+function parseSource(text: string, file: string): ModuleInfo {
+  const sourceFile = ts.createSourceFile(
+    file,
+    text,
+    ts.ScriptTarget.ESNext,
+    true,
+    ts.ScriptKind.TSX,
+  );
+
+  const info: ModuleInfo = {
+    rel: relative(SRC_DIR, file),
+    hasUseClient: false,
+    clientAPIs: [],
+    reactDom: [],
+    moduleMutableState: [],
+    imports: [],
+    reExports: [],
+    starReExports: [],
+    isPureBarrel: true,
+  };
+
+  // Directive prologue: only comments and blank lines may precede it, which
+  // the parser has already stripped by the time we see `statements`. Walk past
+  // *every* string-literal directive — stopping at the first non-`use client`
+  // one would let `'use strict';` hide the directive behind it.
+  for (const statement of sourceFile.statements) {
+    if (
+      ts.isExpressionStatement(statement) &&
+      ts.isStringLiteral(statement.expression)
+    ) {
+      if (statement.expression.text === 'use client') {
+        info.hasUseClient = true;
+      }
+      continue;
+    }
+    break;
+  }
+
+  /** Local names bound to the react namespace: `import React from 'react'`. */
+  const reactNamespaces = new Set<string>();
+
+  for (const statement of sourceFile.statements) {
+    if (ts.isImportDeclaration(statement)) {
+      const spec = (statement.moduleSpecifier as ts.StringLiteral).text;
+      const clause = statement.importClause;
+      const typeOnly = clause ? isTypeOnlyImport(clause) : false;
+
+      if (spec === 'react' && clause && !clause.isTypeOnly) {
+        const reactBindings = clause.namedBindings;
+        if (reactBindings && ts.isNamedImports(reactBindings)) {
+          for (const element of reactBindings.elements) {
+            const imported = (element.propertyName ?? element.name).text;
+            if (!element.isTypeOnly && CLIENT_APIS.has(imported)) {
+              info.clientAPIs.push(imported);
+            }
+          }
+        }
+        // `import React from 'react'` and `import * as React from 'react'` put
+        // every client API one property access away, where the named scan above
+        // cannot see it. Record the local name; the sweep below finds the uses.
+        if (clause.name) {
+          reactNamespaces.add(clause.name.text);
+        }
+        if (reactBindings && ts.isNamespaceImport(reactBindings)) {
+          reactNamespaces.add(reactBindings.name.text);
+        }
+      }
+      if (!typeOnly && spec.startsWith('react-dom')) {
+        info.reactDom.push(spec);
+      }
+
+      if (!typeOnly) {
+        const target = resolveSpecifier(spec, file);
+        if (target) {
+          let names: Set<string> | '*' = '*';
+          const bindings = clause?.namedBindings;
+          if (bindings && ts.isNamedImports(bindings) && !clause?.name) {
+            names = new Set(
+              bindings.elements
+                .filter(element => !element.isTypeOnly)
+                .map(element => (element.propertyName ?? element.name).text),
+            );
+          }
+          info.imports.push({target, names});
+        }
+      }
+      continue;
+    }
+
+    if (ts.isExportDeclaration(statement) && statement.moduleSpecifier) {
+      const spec = (statement.moduleSpecifier as ts.StringLiteral).text;
+      if (!isTypeOnlyExport(statement)) {
+        const target = resolveSpecifier(spec, file);
+        if (target) {
+          const clause = statement.exportClause;
+          if (clause && ts.isNamedExports(clause)) {
+            for (const element of clause.elements) {
+              if (element.isTypeOnly) {
+                continue;
+              }
+              info.reExports.push({
+                target,
+                exportedName: element.name.text,
+                localName: (element.propertyName ?? element.name).text,
+              });
+            }
+          } else {
+            info.starReExports.push(target);
+          }
+        }
+      }
+      continue;
+    }
+
+    // Anything else is real code, so this module is not a pass-through barrel.
+    info.isPureBarrel = false;
+
+    if (ts.isVariableStatement(statement)) {
+      const isLet = !(statement.declarationList.flags & ts.NodeFlags.Const);
+      for (const decl of statement.declarationList.declarations) {
+        const name = decl.name.getText(sourceFile);
+        if (isLet) {
+          info.moduleMutableState.push(`let ${name}`);
+        } else if (decl.initializer) {
+          const ctor = /^new (Map|Set|WeakMap|WeakSet)\b/.exec(
+            decl.initializer.getText(sourceFile),
+          );
+          if (ctor) {
+            info.moduleMutableState.push(`const ${name} = new ${ctor[1]}()`);
+          }
+        }
+      }
+    }
+  }
+
+  // Value-position `React.useState(...)`. A type reference like
+  // `React.ReactNode` parses as a QualifiedName rather than a
+  // PropertyAccessExpression, so types never reach this branch.
+  if (reactNamespaces.size > 0) {
+    const visit = (node: ts.Node): void => {
+      if (
+        ts.isPropertyAccessExpression(node) &&
+        ts.isIdentifier(node.expression) &&
+        reactNamespaces.has(node.expression.text) &&
+        CLIENT_APIS.has(node.name.text)
+      ) {
+        info.clientAPIs.push(`${node.expression.text}.${node.name.text}`);
+      }
+      ts.forEachChild(node, visit);
+    };
+    ts.forEachChild(sourceFile, visit);
+  }
+
+  return info;
+}
+
+/**
+ * Walk the runtime import graph from `entry` and report every client-only
+ * surface it reaches.
+ *
+ * `packages/core/package.json` declares `sideEffects` as a narrow allowlist
+ * (`*.stylex.ts`, `componentStyles.ts`, `*.css`), so every other module is
+ * side-effect free and a bundler may drop unused re-exports. A pure
+ * pass-through barrel is therefore followed by *used export* rather than
+ * wholesale — otherwise importing `mergeProps` from `../utils` would appear to
+ * drag in every unrelated sibling the barrel happens to re-export.
+ *
+ * @param ownDir When set, `'use client'` directives on files directly inside
+ *   this directory are ignored, so the walk reports what the component's code
+ *   actually *needs* rather than what it is currently *marked* as.
+ */
+function findClientSurfaces(
+  entry: string,
+  ownDir: string | null,
+): {reason: string; file: string; via: string}[] {
+  const problems: {reason: string; file: string; via: string}[] = [];
+  const visited = new Set<string>();
+  const queue: [string, Set<string> | '*', string[]][] = [
+    [entry, '*', [relative(SRC_DIR, entry)]],
+  ];
+
+  while (queue.length > 0) {
+    const [file, names, via] = queue.pop()!;
+    if (!/\.(tsx?|jsx?|mjs)$/.test(file)) {
+      continue;
+    }
+    const key = `${file}|${names === '*' ? '*' : [...names].sort().join(',')}`;
+    if (visited.has(key)) {
+      continue;
+    }
+    visited.add(key);
+
+    const info = parseModule(file);
+    const chain = via.join(' -> ');
+    const insideOwnDir = ownDir !== null && dirname(file) === ownDir;
+
+    if (info.hasUseClient && !insideOwnDir) {
+      problems.push({
+        reason: 'depends on a "use client" module',
+        file: info.rel,
+        via: chain,
+      });
+    }
+    if (info.clientAPIs.length > 0) {
+      const apis = [...new Set(info.clientAPIs)].join(', ');
+      problems.push({
+        reason: `imports ${apis} from react`,
+        file: info.rel,
+        via: chain,
+      });
+    }
+    if (info.reactDom.length > 0) {
+      problems.push({
+        reason: `imports ${info.reactDom.join(', ')}`,
+        file: info.rel,
+        via: chain,
+      });
+    }
+    if (info.moduleMutableState.length > 0) {
+      problems.push({
+        reason: `module-level mutable state (${info.moduleMutableState.join('; ')})`,
+        file: info.rel,
+        via: chain,
+      });
+    }
+
+    const push = (target: string, next: Set<string> | '*') =>
+      queue.push([target, next, [...via, relative(SRC_DIR, target)]]);
+
+    if (info.isPureBarrel && names !== '*') {
+      for (const wanted of names) {
+        const providers = info.reExports.filter(r => r.exportedName === wanted);
+        if (providers.length > 0) {
+          for (const p of providers) {
+            push(p.target, new Set([p.localName]));
+          }
+        } else {
+          for (const t of info.starReExports) {
+            push(t, new Set([wanted]));
+          }
+        }
+      }
+      for (const imp of info.imports) {
+        push(imp.target, imp.names);
+      }
+    } else {
+      for (const imp of info.imports) {
+        push(imp.target, imp.names);
+      }
+      for (const r of info.reExports) {
+        push(r.target, new Set([r.localName]));
+      }
+      for (const t of info.starReExports) {
+        push(t, '*');
+      }
+    }
+  }
+
+  return problems;
+}
+
+interface Component {
+  subpath: string;
+  dir: string;
+  entry: string;
+  /** Source files in the component's own directory that carry the directive. */
+  directiveFiles: string[];
+}
+
+/**
+ * Every component the package exposes as a `./Name` subpath backed by
+ * `./src/Name/index.ts`. Driving off the export map keeps the test aligned
+ * with the package's real public surface.
+ */
+function publicComponents(): Component[] {
+  const pkg = JSON.parse(readFileSync(PKG_JSON, 'utf-8')) as {
+    exports?: Record<string, {source?: string}>;
+  };
+  const components: Component[] = [];
+  for (const [subpath, entryPoint] of Object.entries(pkg.exports ?? {})) {
+    const source = entryPoint?.source;
+    if (!source) {
+      continue;
+    }
+    const match = /^\.\/src\/([^/]+)\/index\.ts$/.exec(source);
+    if (!match) {
+      continue;
+    }
+    const dir = join(SRC_DIR, match[1]);
+    const entry = join(dir, 'index.ts');
+    if (!existsSync(entry)) {
+      continue;
+    }
+    const directiveFiles = readdirSync(dir)
+      .filter(isSourceFile)
+      .filter(name => parseModule(join(dir, name)).hasUseClient)
+      .map(name => `${match[1]}/${name}`);
+    components.push({subpath, dir, entry, directiveFiles});
+  }
+  return components;
+}
+
+const COMPONENTS = publicComponents();
+
+const format = (problems: {reason: string; file: string; via: string}[]) =>
+  [...new Map(problems.map(p => [`${p.file}|${p.reason}`, p])).values()]
+    .map(p => `      ${p.file} ${p.reason}\n        via ${p.via}`)
+    .join('\n');
+
+/** Parse a source string as if it were a file inside `SRC_DIR`. */
+const parse = (source: string) =>
+  parseSource(source, join(SRC_DIR, 'probe.tsx'));
+
+describe('parseSource', () => {
+  it('reads a client API from a named react import', () => {
+    expect(
+      parse(`import {useState} from 'react';\nexport const a = 1;`).clientAPIs,
+    ).toEqual(['useState']);
+  });
+
+  it('reads a client API reached through a default React binding', () => {
+    const info = parse(
+      `import React from 'react';\nexport const a = () => React.useState(0);`,
+    );
+    expect(info.clientAPIs).toEqual(['React.useState']);
+  });
+
+  it('reads a client API reached through a namespace React binding', () => {
+    const info = parse(
+      `import * as React from 'react';\nexport const C = React.createContext(false);`,
+    );
+    expect(info.clientAPIs).toEqual(['React.createContext']);
+  });
+
+  it('reads both halves of a mixed default-and-named react import', () => {
+    const info = parse(
+      `import React, {useRef} from 'react';\nexport const a = () => React.useState(0) && useRef(null);`,
+    );
+    expect(info.clientAPIs.sort()).toEqual(['React.useState', 'useRef']);
+  });
+
+  it('does not flag a React binding used only in type position', () => {
+    const info = parse(
+      `import * as React from 'react';\nexport type P = {a: React.ReactNode; b: React.KeyboardEvent};`,
+    );
+    expect(info.clientAPIs).toEqual([]);
+  });
+
+  it('treats React 19 `use` as a client API', () => {
+    // `use(Context)` is a context read, exactly as client-only as useContext.
+    expect(
+      parse(`import {use} from 'react';\nexport const a = 1;`).clientAPIs,
+    ).toEqual(['use']);
+  });
+
+  it.each(['useActionState', 'useEffectEvent', 'startTransition'])(
+    'treats React 19 `%s` as a client API',
+    api => {
+      expect(
+        parse(`import {${api}} from 'react';\nexport const a = 1;`).clientAPIs,
+      ).toEqual([api]);
+    },
+  );
+
+  it('reads a client API imported under an alias', () => {
+    expect(
+      parse(
+        `import {useActionState as useSubmitState} from 'react';\nexport const a = 1;`,
+      ).clientAPIs,
+    ).toEqual(['useActionState']);
+  });
+
+  it('reads useEffectEvent reached through a default React binding', () => {
+    expect(
+      parse(
+        `import React from 'react';\nexport const a = () => React.useEffectEvent(() => {});`,
+      ).clientAPIs,
+    ).toEqual(['React.useEffectEvent']);
+  });
+
+  it('sees `use client` behind another prologue directive', () => {
+    expect(
+      parse(`'use strict';\n'use client';\nexport const a = 1;`).hasUseClient,
+    ).toBe(true);
+  });
+
+  it('ignores a `use client` string that follows real code', () => {
+    expect(parse(`export const a = 1;\n'use client';`).hasUseClient).toBe(
+      false,
+    );
+  });
+});
+
+describe('CLIENT_APIS', () => {
+  it('covers every client-only hook the react-server build omits', () => {
+    // React's own builds are the ground truth for "works on the server": the
+    // react-server condition maps to a deliberate allowlist, and the exports
+    // it drops are exactly the client-only surface. Every hook-shaped export
+    // in the client build but not the server build must be in CLIENT_APIS,
+    // or both invariants below go blind to it. The subset holds in one
+    // direction only: `use`, useId, useMemo and useCallback are server-legal
+    // but deliberately over-approximated as client APIs above.
+    const nodeRequire = createRequire(import.meta.url);
+    const cjs = join(dirname(nodeRequire.resolve('react/package.json')), 'cjs');
+    const exportsOf = (file: string) =>
+      new Set(
+        [
+          ...readFileSync(join(cjs, file), 'utf-8').matchAll(
+            /exports\.(\w+)\s*=/g,
+          ),
+        ].map(m => m[1]),
+      );
+    const client = exportsOf('react.production.js');
+    const server = exportsOf('react.react-server.production.js');
+    const missing = [...client].filter(
+      name =>
+        (/^use[A-Z]/.test(name) || name === 'startTransition') &&
+        !server.has(name) &&
+        !CLIENT_APIS.has(name),
+    );
+    expect(
+      missing,
+      `\nreact marks these exports client-only (absent from its react-server\n` +
+        `build) but CLIENT_APIS does not list them. Add them here and to\n` +
+        `scripts/check-use-client.mjs:\n  ${missing.join(', ')}\n`,
+    ).toEqual([]);
+  });
+
+  it('stays in sync with scripts/check-use-client.mjs', () => {
+    const script = readFileSync(
+      join(SRC_DIR, '..', '..', '..', 'scripts', 'check-use-client.mjs'),
+      'utf-8',
+    );
+    const literal = /const CLIENT_APIS = \[([\s\S]*?)\];/.exec(script);
+    const names =
+      literal === null
+        ? []
+        : [
+            ...literal[1]
+              .split('\n')
+              .filter(line => !line.trim().startsWith('//'))
+              .join('\n')
+              .matchAll(/'([^']+)'/g),
+          ].map(m => m[1]);
+    expect(new Set(names)).toEqual(CLIENT_APIS);
+  });
+});
+
+describe('RSC server/client boundary (#823)', () => {
+  it('finds the public component entry points', () => {
+    // The export map lists 100+ component subpaths; a floor this close to the
+    // real count catches a resolution bug that silently shrinks the covered set
+    // and turns both invariants below into no-ops.
+    expect(COMPONENTS.length).toBeGreaterThan(95);
+  });
+
+  it('does not mark server-safe components as "use client"', () => {
+    const stale: string[] = [];
+    for (const component of COMPONENTS) {
+      if (component.directiveFiles.length === 0) {
+        continue;
+      }
+      // Ignore this component's own directives so the graph reports what its
+      // code needs, not what it is currently labelled.
+      const problems = findClientSurfaces(component.entry, component.dir);
+      if (problems.length === 0) {
+        stale.push(
+          `  ${component.subpath} is server-safe but still carries 'use client' in: ${component.directiveFiles.join(', ')}`,
+        );
+      }
+    }
+    expect(
+      stale.join('\n'),
+      `\nThese components import no client-only surface, so the directive pins them\n` +
+        `to the client bundle for nothing. Remove it (source file *and* index.ts):\n`,
+    ).toBe('');
+  });
+
+  it('keeps directive-free components free of client-only imports', () => {
+    const leaked: string[] = [];
+    for (const component of COMPONENTS) {
+      if (component.directiveFiles.length > 0) {
+        continue;
+      }
+      const problems = findClientSurfaces(component.entry, null);
+      if (problems.length > 0) {
+        leaked.push(`  ${component.subpath}:\n${format(problems)}`);
+      }
+    }
+    expect(
+      leaked.join('\n'),
+      `\nThese components ship without 'use client', so they are server modules —\n` +
+        `but they reach a client-only surface. Either drop the client dependency or\n` +
+        `restore the directive. scripts/check-use-client.mjs cannot see this:\n`,
+    ).toBe('');
+  });
+});

package/src/theme/defineTheme.ts

@@ -42,6 +42,7 @@ import {
   colorDefaults,
   spacingDefaults,
   sizeDefaults,
+  focusDefaults,
   radiusDefaults,
   shadowDefaults,
   durationDefaults,
@@ -74,6 +75,7 @@ export type CoreTokenName =
   | keyof typeof colorDefaults
   | keyof typeof spacingDefaults
   | keyof typeof sizeDefaults
+  | keyof typeof focusDefaults
   | keyof typeof radiusDefaults
   | keyof typeof shadowDefaults
   | keyof typeof durationDefaults
@@ -377,6 +379,7 @@ export const tokenDefaults: Record<string, string> = {
   ...colorDefaults,
   ...spacingDefaults,
   ...sizeDefaults,
+  ...focusDefaults,
   ...radiusDefaults,
   ...shadowDefaults,
   ...durationDefaults,

package/src/theme/generateThemeRules.test.ts

@@ -23,6 +23,23 @@ const defaultInput = {
   },
 };
 
+describe('focus outline tokens', () => {
+  it('emits a focus ring override into the theme scope', () => {
+    const theme = defineTheme({
+      name: 'brand',
+      tokens: {
+        '--focus-outline-color': '#FF00FF',
+        '--focus-outline-width': '4px',
+      },
+    });
+
+    const {component} = generateThemeCSS(theme);
+
+    expect(component).toContain('--focus-outline-color: #FF00FF;');
+    expect(component).toContain('--focus-outline-width: 4px;');
+  });
+});
+
 describe('generateThemeRules', () => {
   const theme = defineTheme(defaultInput);
   const rules = generateThemeRules(theme);