@astryxdesign/core 0.5.2-canary.2da7a39 → 0.5.2-canary.2e51213

package/src/theme/generateThemeRules.ts

@@ -345,7 +345,10 @@ export function generateThemeRules(theme: DefinedTheme): string[] {
   const val = (key: string): string => tokens[key] || `var(${key})`;
 
   // 1. Token block — CSS custom properties on :scope
-  const tokenEntries = Object.entries(tokens);
+  const tokenEntries = [
+    ...Object.entries(tokens),
+    ...Object.entries(theme.localTokens ?? {}),
+  ];
   if (tokenEntries.length > 0) {
     const declarations = tokenEntries
       .map(([prop, value]) => `    ${prop}: ${value};`)

package/src/theme/localTokens.ts

@@ -0,0 +1,272 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+import type {ComponentStyleMap, DefinedTheme, TokenValue} from './defineTheme';
+import type {ResolvedOnMedia} from './onMediaTokens';
+
+const LOCAL_TOKEN_PREFIX = '--astryx-theme-';
+const THEME_NAME_PATTERN = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;
+const LOCAL_TOKEN_SUFFIX_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+const CSS_VAR_PATTERN = /var\(\s*(--[^,\s)]+)/gi;
+
+export interface ResolvedLocalTokenContract {
+  localTokens: Record<string, string>;
+  owners: Record<string, string>;
+  lineage: string[];
+}
+
+function hasOwn(object: object, key: PropertyKey): boolean {
+  return Object.prototype.hasOwnProperty.call(object, key);
+}
+
+function isExactLocalTokenName(name: string, owner: string): boolean {
+  const prefix = `${LOCAL_TOKEN_PREFIX}${owner}-`;
+  return (
+    name.startsWith(prefix) &&
+    LOCAL_TOKEN_SUFFIX_PATTERN.test(name.slice(prefix.length))
+  );
+}
+
+function resolveTokenValue(value: TokenValue, path: string): string {
+  if (typeof value === 'string') {
+    return value;
+  }
+  if (
+    Array.isArray(value) &&
+    value.length === 2 &&
+    typeof value[0] === 'string' &&
+    typeof value[1] === 'string'
+  ) {
+    return `light-dark(${value[0]}, ${value[1]})`;
+  }
+  throw new Error(
+    `${path} must be a CSS string or a [light, dark] string tuple.`,
+  );
+}
+
+function collectLocalReferences(value: unknown, refs: Set<string>): void {
+  if (typeof value === 'string') {
+    CSS_VAR_PATTERN.lastIndex = 0;
+    for (
+      let match = CSS_VAR_PATTERN.exec(value);
+      match;
+      match = CSS_VAR_PATTERN.exec(value)
+    ) {
+      const name = match[1];
+      if (name.startsWith(LOCAL_TOKEN_PREFIX)) {
+        refs.add(name);
+      }
+    }
+    return;
+  }
+  if (Array.isArray(value)) {
+    for (const item of value) {
+      collectLocalReferences(item, refs);
+    }
+    return;
+  }
+  if (value && typeof value === 'object') {
+    for (const nested of Object.values(value)) {
+      collectLocalReferences(nested, refs);
+    }
+  }
+}
+
+function assertNoLocalTokenCycles(localTokens: Record<string, string>): void {
+  const dependencies = new Map<string, string[]>();
+  for (const [name, value] of Object.entries(localTokens)) {
+    const refs = new Set<string>();
+    collectLocalReferences(value, refs);
+    dependencies.set(
+      name,
+      [...refs].filter(reference => hasOwn(localTokens, reference)),
+    );
+  }
+
+  const visiting = new Set<string>();
+  const visited = new Set<string>();
+  const visit = (name: string, path: string[]): void => {
+    if (visiting.has(name)) {
+      const start = path.indexOf(name);
+      const cycle = [...path.slice(start), name].join(' -> ');
+      throw new Error(`Theme-local token cycle detected: ${cycle}.`);
+    }
+    if (visited.has(name)) {
+      return;
+    }
+    visiting.add(name);
+    for (const dependency of dependencies.get(name) ?? []) {
+      visit(dependency, [...path, name]);
+    }
+    visiting.delete(name);
+    visited.add(name);
+  };
+
+  for (const name of Object.keys(localTokens)) {
+    visit(name, []);
+  }
+}
+
+function assertDeclaredReferences(
+  localTokens: Record<string, string>,
+  components: ComponentStyleMap | undefined,
+  onDark: ResolvedOnMedia | undefined,
+  onLight: ResolvedOnMedia | undefined,
+): void {
+  const refs = new Set<string>();
+  collectLocalReferences(localTokens, refs);
+  collectLocalReferences(components, refs);
+  collectLocalReferences(onDark?.components, refs);
+  collectLocalReferences(onLight?.components, refs);
+
+  for (const reference of refs) {
+    if (!hasOwn(localTokens, reference)) {
+      throw new Error(
+        `Theme-local token reference "${reference}" has no declaration in the enrolled theme lineage.`,
+      );
+    }
+  }
+}
+
+function assertInheritedContract(
+  themeName: string,
+  base: DefinedTheme,
+): asserts base is DefinedTheme & {
+  localTokens: Record<string, string>;
+  __localTokenOwners: Record<string, string>;
+  __localTokenLineage: string[];
+} {
+  const lineage = base.__localTokenLineage;
+  if (
+    !Array.isArray(lineage) ||
+    lineage.length === 0 ||
+    lineage[lineage.length - 1] !== base.name ||
+    lineage.some(name => typeof name !== 'string' || name.length === 0)
+  ) {
+    throw new Error(
+      `defineTheme("${themeName}"): the base theme has invalid theme-local token lineage metadata.`,
+    );
+  }
+  if (
+    !base.localTokens ||
+    typeof base.localTokens !== 'object' ||
+    Array.isArray(base.localTokens) ||
+    !base.__localTokenOwners ||
+    typeof base.__localTokenOwners !== 'object' ||
+    Array.isArray(base.__localTokenOwners)
+  ) {
+    throw new Error(
+      `defineTheme("${themeName}"): the base theme has incomplete theme-local token metadata.`,
+    );
+  }
+
+  for (const [name, value] of Object.entries(base.localTokens)) {
+    const owner = base.__localTokenOwners[name];
+    if (
+      typeof value !== 'string' ||
+      !owner ||
+      !lineage.includes(owner) ||
+      !isExactLocalTokenName(name, owner)
+    ) {
+      throw new Error(
+        `defineTheme("${themeName}"): inherited local token "${name}" does not match its exact lineage metadata.`,
+      );
+    }
+  }
+  for (const name of Object.keys(base.__localTokenOwners)) {
+    if (!hasOwn(base.localTokens, name)) {
+      throw new Error(
+        `defineTheme("${themeName}"): inherited local-token owner metadata names undeclared token "${name}".`,
+      );
+    }
+  }
+}
+
+/**
+ * Resolve and validate the opt-in theme-local token contract.
+ *
+ * Themes that omit `localTokens` and do not extend an enrolled base bypass this
+ * function's reserved-namespace checks so legacy token behavior stays intact.
+ */
+export function resolveLocalTokenContract(
+  input: {
+    name: string;
+    localTokens?: Record<string, TokenValue>;
+  },
+  base: DefinedTheme | undefined,
+  tokens: Record<string, string>,
+  components: ComponentStyleMap | undefined,
+  onDark: ResolvedOnMedia | undefined,
+  onLight: ResolvedOnMedia | undefined,
+): ResolvedLocalTokenContract | undefined {
+  const directlyEnrolled = hasOwn(input, 'localTokens');
+  const inherited = base?.__localTokenLineage !== undefined;
+
+  if (!directlyEnrolled && !inherited) {
+    return undefined;
+  }
+
+  if (directlyEnrolled && !THEME_NAME_PATTERN.test(input.name)) {
+    throw new Error(
+      `defineTheme("${input.name}"): themes using localTokens require a stable lower-kebab name.`,
+    );
+  }
+
+  if (inherited && base) {
+    assertInheritedContract(input.name, base);
+  }
+
+  const localTokens = {...base?.localTokens};
+  const owners = {...base?.__localTokenOwners};
+  const declarations = input.localTokens;
+
+  if (
+    directlyEnrolled &&
+    (declarations === null ||
+      declarations === undefined ||
+      typeof declarations !== 'object' ||
+      Array.isArray(declarations))
+  ) {
+    throw new Error(
+      `defineTheme("${input.name}"): localTokens must be a token map.`,
+    );
+  }
+
+  for (const [name, value] of Object.entries(declarations ?? {})) {
+    const inheritedOwner = owners[name];
+    if (!inheritedOwner) {
+      const expectedPrefix = `${LOCAL_TOKEN_PREFIX}${input.name}-`;
+      if (!isExactLocalTokenName(name, input.name)) {
+        throw new Error(
+          `defineTheme("${input.name}"): local token "${name}" must use the exact namespace "${expectedPrefix}" followed by a lowercase kebab-case purpose.`,
+        );
+      }
+      owners[name] = input.name;
+    }
+    localTokens[name] = resolveTokenValue(
+      value,
+      `defineTheme("${input.name}").localTokens["${name}"]`,
+    );
+  }
+
+  for (const name of Object.keys(localTokens)) {
+    if (!owners[name]) {
+      throw new Error(
+        `defineTheme("${input.name}"): inherited local token "${name}" has no owner metadata.`,
+      );
+    }
+    if (hasOwn(tokens, name)) {
+      throw new Error(
+        `defineTheme("${input.name}"): token "${name}" cannot be declared in both tokens and localTokens.`,
+      );
+    }
+  }
+
+  assertDeclaredReferences(localTokens, components, onDark, onLight);
+  assertNoLocalTokenCycles(localTokens);
+
+  return {
+    localTokens,
+    owners,
+    lineage: [...(base?.__localTokenLineage ?? []), input.name],
+  };
+}

package/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,15 +24,36 @@
  * `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';
 import {readdirSync, readFileSync} from 'node:fs';
-import {join, relative} from 'node:path';
+import {basename, 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,47 @@ function docFilesDocumenting(classNames: Set<string>): string[] {
       }
     }
   };
-  walk(SRC_DIR);
+  walk(srcDir);
   return matches;
 }
 
-function discoverComponents(): ComponentInfo[] {
+/**
+ * Every directory under `srcDir`, at any depth, relative to `srcDir`.
+ *
+ * Not just the top level: a component's sources are not always its own direct
+ * children — Table's plugins render from `Table/plugins/<name>/`. Scanning only
+ * the top level exempted every one of those from this guard, which is the same
+ * silent-exemption shape #3741 was filed about.
+ *
+ * Takes `srcDir` rather than closing over a module constant so it serves both
+ * packages, which is what the Lab enrollment above needs.
+ */
+function sourceDirs(srcDir: string): string[] {
+  const out: string[] = [];
+  const walk = (rel: string): void => {
+    for (const entry of readdirSync(join(srcDir, rel), {
+      withFileTypes: true,
+    })) {
+      if (entry.isDirectory()) {
+        const child = rel === '' ? entry.name : join(rel, entry.name);
+        out.push(child);
+        walk(child);
+      }
+    }
+  };
+  walk('');
+  return out;
+}
+
+function discoverComponents(
+  srcDir: string,
+  packageName: ComponentInfo['packageName'],
+  requiredDirs: ReadonlySet<string> = new Set(),
+): 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);
+  for (const dir of sourceDirs(srcDir)) {
+    const dirPath = join(srcDir, dir);
     const dirEntries = readdirSync(dirPath);
 
     const sourceFiles = dirEntries.filter(
@@ -387,9 +443,13 @@ function discoverComponents(): ComponentInfo[] {
     // Both paths 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.)
-    const docFiles = dirEntries.includes(`${dir}.doc.mjs`)
-      ? [join(dirPath, `${dir}.doc.mjs`)]
-      : docFilesDocumenting(new Set(sites.map(s => s.className)));
+    // `basename`, not `dir`: a nested source dir is a path
+    // (`Table/plugins/foo`), and its own doc file is named for the last
+    // segment.
+    const ownDoc = `${basename(dir)}.doc.mjs`;
+    const docFiles = dirEntries.includes(ownDoc)
+      ? [join(dirPath, ownDoc)]
+      : docFilesDocumenting(srcDir, new Set(sites.map(s => s.className)));
     if (docFiles.length === 0) {
       continue;
     }
@@ -404,18 +464,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 +490,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 +548,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);

package/src/utils/interactionModality.test.ts

@@ -0,0 +1,83 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file interactionModality.test.ts
+ * @input The interaction-modality utility loaded more than once
+ * @output Verifies document-wide listener and modality state continuity
+ * @position Unit coverage for interactionModality.ts
+ */
+
+import {afterEach, describe, expect, it, vi} from 'vitest';
+
+const isolatedDocument = document.implementation.createHTMLDocument();
+
+async function loadTracker() {
+  vi.resetModules();
+  return import('./interactionModality');
+}
+
+afterEach(() => {
+  vi.unstubAllGlobals();
+  vi.restoreAllMocks();
+});
+
+describe('interactionModality', () => {
+  it('does not touch the document when the module loads', async () => {
+    vi.stubGlobal('document', isolatedDocument);
+    const addEventListener = vi.spyOn(isolatedDocument, 'addEventListener');
+
+    await loadTracker();
+
+    expect(addEventListener).not.toHaveBeenCalled();
+  });
+
+  it('shares one listener pair and tracks input between consumers', async () => {
+    vi.stubGlobal('document', isolatedDocument);
+    const addEventListener = vi.spyOn(isolatedDocument, 'addEventListener');
+    const removeEventListener = vi.spyOn(
+      isolatedDocument,
+      'removeEventListener',
+    );
+    const firstModule = await loadTracker();
+    const secondModule = await loadTracker();
+
+    const firstConsumer =
+      firstModule.__startInteractionModalityTrackingForTest();
+    const secondConsumer =
+      secondModule.__startInteractionModalityTrackingForTest();
+
+    expect(
+      addEventListener.mock.calls.filter(([type]) => type === 'pointerdown'),
+    ).toHaveLength(1);
+    expect(
+      addEventListener.mock.calls.filter(([type]) => type === 'keydown'),
+    ).toHaveLength(1);
+
+    isolatedDocument.dispatchEvent(new Event('pointerdown'));
+    expect(secondModule.getInteractionModality()).toBe('pointer');
+
+    firstConsumer();
+    secondConsumer();
+    isolatedDocument.dispatchEvent(new KeyboardEvent('keydown', {key: 'Tab'}));
+    expect(firstModule.getInteractionModality()).toBe('keyboard');
+    expect(removeEventListener).not.toHaveBeenCalled();
+
+    secondModule.__startInteractionModalityTrackingForTest()();
+    expect(
+      addEventListener.mock.calls.filter(([type]) => type === 'pointerdown'),
+    ).toHaveLength(1);
+    expect(
+      addEventListener.mock.calls.filter(([type]) => type === 'keydown'),
+    ).toHaveLength(1);
+  });
+
+  it('uses the keyboard-safe default without a document', async () => {
+    vi.stubGlobal('document', undefined);
+    const serverModule = await loadTracker();
+
+    expect(serverModule.getInteractionModality()).toBe('keyboard');
+    expect(() =>
+      serverModule.__startInteractionModalityTrackingForTest()(),
+    ).not.toThrow();
+  });
+});