@astryxdesign/core 0.7.5 → 0.7.6-canary.00507ba

package/dist/theme/themeMotion.js

@@ -0,0 +1,177 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file themeMotion.ts
+ * @input A theme's motion configuration: the knobs (`tempo`, `character`),
+ *   the existing `MotionScaleConfig`, or both
+ * @output The resolved knobs, the motion tokens they generate, and
+ *   `resolveThemeMotion`, the internal resolver the animator and server code
+ *   read (`spec:AST-108` FR1, FR2, FR5, FR6)
+ * @position Theme utility; consumed by resolveThemeValues.ts. Pure: no DOM,
+ *   no import-time work, safe on the server.
+ *
+ * `tempo` scales every motion duration token, clamped to 0.75–1.5.
+ * `character` picks the entrance and move curves. Every theme follows each
+ * person's Reduce Motion setting (`reducedMotion` resolves to `'system'`).
+ * No spring reads the knobs yet. With the defaults (tempo 1, `'standard'`, `'system'`) every token is
+ * today's.
+ *
+ * A `MotionScaleConfig` keeps generating its duration tokens, and its fields
+ * win over `tempo` (FR5); explicit `tokens` win over both in
+ * resolveThemeValues.
+ *
+ * SYNC: When modified, update:
+ * - /packages/core/src/theme/themeMotion.test.ts
+ * - /packages/core/src/theme/resolveThemeValues.ts
+ * - /packages/core/src/theme/defineTheme.ts (the `motion` field's docs)
+ */
+
+import { expandMotionScale } from "./expandMotionScale.js";
+import { resolveKnobs } from "./motionKnobs.js";
+import { durationDefaults, easeDefaults } from "./tokens.stylex.js";
+import { resolveTokenReferences } from "./tokenReferences.js";
+export { TEMPO_RANGE } from "./motionKnobs.js";
+
+/**
+ * A theme's `motion`: the knobs, the existing `MotionScaleConfig`, or both.
+ * A `MotionScaleConfig`'s fields win over `tempo` for the durations they set.
+ */
+
+/**
+ * The entrance and move curve at each character. `'standard'` is the theme's
+ * `--ease-standard`, so a theme that overrides that easing keeps its entrances
+ * on it.
+ */
+export const CHARACTER_EASE = {
+  crisp: 'cubic-bezier(0, 0, 0.2, 1)',
+  standard: null,
+  expressive: 'cubic-bezier(0.3, 1.2, 0.5, 1)'
+};
+
+/** The knobs of `config`, defaults filled in, `tempo` clamped. */
+export function resolveMotionKnobs(config) {
+  return resolveKnobs(config);
+}
+function isScaleConfig(config) {
+  return 'fast' in config && 'medium' in config && 'ratio' in config;
+}
+
+/** A duration token's value in ms (`'175ms'` → 175). */
+function msOf(value) {
+  return Number.parseFloat(value);
+}
+
+/**
+ * The private custom property a theme with a `tempo` writes beside its
+ * duration tokens: the press release fade (`utils/interactionOverlay.stylex.ts`)
+ * multiplies its clock by it.
+ */
+export const MOTION_TEMPO_PROPERTY = '--_astryx-motion-tempo';
+
+/** The duration tokens at `tempo`: today's values times it, to the ms. */
+export function durationTokensAt(tempo) {
+  const tokens = {};
+  for (const [name, value] of Object.entries(durationDefaults)) {
+    tokens[name] = `${Math.round(msOf(value) * tempo)}ms`;
+  }
+  return tokens;
+}
+
+/**
+ * The private custom property holding a duration token's value before
+ * `tempo` scaled it (`--duration-slow` → `--_astryx-pre-tempo-duration-slow`).
+ * Busy loops (Spinner, Skeleton) read it, falling back to the token, so their
+ * timing follows a duration scale or an explicit token but never `tempo`
+ * (FR4). Private, like every property the knobs add beside the core tokens
+ * (`architecture:theme-tokens` INV1).
+ */
+export function preTempoName(token) {
+  return token.replace(/^--duration-/, '--_astryx-pre-tempo-duration-');
+}
+
+/**
+ * The motion tokens `config` generates (FR2, FR5): `--duration-*` times
+ * `tempo`, with a `MotionScaleConfig`'s own durations winning, and the
+ * job-named `--ease-entrance` and `--ease-move` at the theme's character.
+ * A knob the config leaves out writes nothing, so a theme extending another
+ * keeps the base's value for it; a knob it sets is written even at its
+ * default, so a child can set a base's tempo back to 1.
+ */
+export function expandThemeMotion(config) {
+  const knobs = resolveMotionKnobs(config);
+  const tokens = {};
+  if (knobs.tempoIsSet) {
+    Object.assign(tokens, durationTokensAt(knobs.tempo));
+    for (const [name, value] of Object.entries(durationDefaults)) {
+      tokens[preTempoName(name)] = value;
+    }
+    // The press release fade, a fixed clock in the stylesheet, scales by the
+    // tempo itself (FR4; `component:Button` FR15), read where it plays.
+    tokens[MOTION_TEMPO_PROPERTY] = String(knobs.tempo);
+  }
+  if (isScaleConfig(config)) {
+    const scale = expandMotionScale(config);
+    Object.assign(tokens, scale);
+    if (knobs.tempoIsSet) {
+      for (const [name, value] of Object.entries(scale)) {
+        if (name.startsWith('--duration-')) {
+          tokens[preTempoName(name)] = value;
+        }
+      }
+    }
+  }
+  const scaleEasing = isScaleConfig(config) && config.easing != null ? config.easing : null;
+  const ease = CHARACTER_EASE[knobs.character] ?? (config.character != null ? scaleEasing ?? easeDefaults['--ease-standard'] : scaleEasing);
+  if (ease != null) {
+    tokens['--ease-entrance'] = ease;
+    tokens['--ease-move'] = ease;
+  }
+  return tokens;
+}
+
+/** What `resolveThemeMotion` returns for a theme. */
+
+/**
+ * A theme's motion values, for the animator and for server code (FR6): the
+ * knobs, and the duration and easing tokens they resolve to with the theme's
+ * explicit tokens applied. A token written as a reference (`var(--name)`)
+ * resolves through the theme's tokens, as `resolveThemeTokens` resolves it
+ * (`architecture:theme-tokens` INV6). Pure: it reads only `theme`.
+ */
+export function resolveThemeMotion(theme) {
+  // A defined theme's motion is its axes': its own merged with its base's.
+  const config = theme.__axes?.motion ?? theme.motion;
+  const knobs = resolveMotionKnobs(config);
+  const generated = config ? expandThemeMotion(config) : {};
+  // The graph the references resolve through: the defaults, the knobs'
+  // tokens, then the theme's own (a light/dark pair is not a motion value, so
+  // only plain strings take part).
+  const graph = {
+    ...durationDefaults,
+    ...easeDefaults,
+    ...generated
+  };
+  for (const tokens of [theme.localTokens, theme.tokens]) {
+    for (const [name, value] of Object.entries(tokens ?? {})) {
+      if (typeof value === 'string') {
+        graph[name] = value;
+      }
+    }
+  }
+  const explicit = name => typeof theme.tokens?.[name] === 'string' || name in generated;
+  const resolved = resolveTokenReferences(graph);
+  const durations = {};
+  for (const name of Object.keys(durationDefaults)) {
+    durations[name] = resolved[name];
+  }
+  const standard = resolved['--ease-standard'];
+  return {
+    knobs,
+    durations,
+    easings: {
+      '--ease-standard': standard,
+      '--ease-entrance': explicit('--ease-entrance') ? resolved['--ease-entrance'] : standard,
+      '--ease-move': explicit('--ease-move') ? resolved['--ease-move'] : standard
+    }
+  };
+}

package/dist/theme/tokenReferences.d.ts

@@ -0,0 +1,31 @@
+/**
+ * @file tokenReferences.ts
+ * @input A flat map of token names to raw CSS values
+ * @output `resolveTokenReferences`, which follows `var(--name[, fallback])`
+ *   references through the map, and the CSS parsing helpers it shares
+ *   (`splitTopLevelComma`, `findMatchingParen`)
+ * @position Theme utility with no imports: tokens.ts resolves a theme's token
+ *   graph on it (evaluating color functions as it goes), and themeMotion.ts
+ *   resolves motion tokens written as references on it. Pure; safe on the
+ *   server.
+ *
+ * SYNC: When modified, update:
+ * - /packages/core/src/theme/tokens.ts
+ * - /packages/core/src/theme/themeMotion.ts
+ */
+/**
+ * Split the arguments of a CSS function body on the first top-level comma.
+ * Handles nested functions such as rgba(), color-mix(), var(), and quoted strings.
+ */
+export declare function splitTopLevelComma(input: string): [string, string] | null;
+/** Index of the `)` matching the `(` at `openIndex`, or -1 when unbalanced. */
+export declare function findMatchingParen(input: string, openIndex: number): number;
+/**
+ * Resolves every value in `raw` to a concrete one: each `var(--name[,
+ * fallback])` is replaced by `name`'s resolved value, or by its fallback when
+ * `raw` has no `name`, and is kept as written when neither exists or the
+ * references form a cycle. `evaluate` then runs on each substituted value
+ * (tokens.ts evaluates CSS color functions there).
+ */
+export declare function resolveTokenReferences(raw: Readonly<Record<string, string>>, evaluate?: (expr: string) => string): Record<string, string>;
+//# sourceMappingURL=tokenReferences.d.ts.map

package/dist/theme/tokenReferences.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tokenReferences.d.ts","sourceRoot":"","sources":["../../src/theme/tokenReferences.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;GAcG;AAEH;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI,CAwCzE;AAED,+EAA+E;AAC/E,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAc1E;AAED;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CACpC,GAAG,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,EACrC,QAAQ,GAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAqB,GAChD,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAyDxB"}

package/dist/theme/tokenReferences.js

@@ -0,0 +1,132 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file tokenReferences.ts
+ * @input A flat map of token names to raw CSS values
+ * @output `resolveTokenReferences`, which follows `var(--name[, fallback])`
+ *   references through the map, and the CSS parsing helpers it shares
+ *   (`splitTopLevelComma`, `findMatchingParen`)
+ * @position Theme utility with no imports: tokens.ts resolves a theme's token
+ *   graph on it (evaluating color functions as it goes), and themeMotion.ts
+ *   resolves motion tokens written as references on it. Pure; safe on the
+ *   server.
+ *
+ * SYNC: When modified, update:
+ * - /packages/core/src/theme/tokens.ts
+ * - /packages/core/src/theme/themeMotion.ts
+ */
+
+/**
+ * Split the arguments of a CSS function body on the first top-level comma.
+ * Handles nested functions such as rgba(), color-mix(), var(), and quoted strings.
+ */
+export function splitTopLevelComma(input) {
+  let depth = 0;
+  let quote = null;
+  let isEscaped = false;
+  for (let i = 0; i < input.length; i++) {
+    const char = input[i];
+    if (quote !== null) {
+      if (isEscaped) {
+        isEscaped = false;
+      } else if (char === '\\') {
+        isEscaped = true;
+      } else if (char === quote) {
+        quote = null;
+      }
+      continue;
+    }
+    if (char === '"' || char === "'") {
+      quote = char;
+      continue;
+    }
+    if (char === '(') {
+      depth++;
+      continue;
+    }
+    if (char === ')') {
+      depth = Math.max(0, depth - 1);
+      continue;
+    }
+    if (char === ',' && depth === 0) {
+      return [input.slice(0, i).trim(), input.slice(i + 1).trim()];
+    }
+  }
+  return null;
+}
+
+/** Index of the `)` matching the `(` at `openIndex`, or -1 when unbalanced. */
+export function findMatchingParen(input, openIndex) {
+  let depth = 0;
+  for (let i = openIndex; i < input.length; i++) {
+    const char = input[i];
+    if (char === '(') {
+      depth++;
+    } else if (char === ')') {
+      depth--;
+      if (depth === 0) {
+        return i;
+      }
+    }
+  }
+  return -1;
+}
+
+/**
+ * Resolves every value in `raw` to a concrete one: each `var(--name[,
+ * fallback])` is replaced by `name`'s resolved value, or by its fallback when
+ * `raw` has no `name`, and is kept as written when neither exists or the
+ * references form a cycle. `evaluate` then runs on each substituted value
+ * (tokens.ts evaluates CSS color functions there).
+ */
+export function resolveTokenReferences(raw, evaluate = expr => expr) {
+  const cache = {};
+
+  // `seen` tracks the reference chain, so a cycle resolves to the literal
+  // reference instead of recursing forever.
+  const substitute = (expr, seen) => {
+    const start = expr.indexOf('var(');
+    if (start === -1) {
+      return expr;
+    }
+    const openIndex = start + 'var'.length;
+    const closeIndex = findMatchingParen(expr, openIndex);
+    if (closeIndex === -1) {
+      return expr;
+    }
+    const inner = expr.slice(openIndex + 1, closeIndex);
+    const commaSplit = splitTopLevelComma(inner);
+    const name = (commaSplit ? commaSplit[0] : inner).trim();
+    const fallback = commaSplit ? commaSplit[1] : null;
+    let replacement;
+    if (seen.has(name)) {
+      replacement = expr.slice(start, closeIndex + 1);
+    } else if (name in raw) {
+      seen.add(name);
+      replacement = reference(name, seen);
+      seen.delete(name);
+    } else if (fallback !== null) {
+      replacement = substitute(fallback.trim(), seen);
+    } else {
+      replacement = expr.slice(start, closeIndex + 1);
+    }
+    const rest = substitute(expr.slice(closeIndex + 1), seen);
+    return expr.slice(0, start) + replacement + rest;
+  };
+  const reference = (name, seen) => {
+    if (name in cache) {
+      return cache[name];
+    }
+    const value = raw[name];
+    if (value === undefined) {
+      return '';
+    }
+    const resolved = evaluate(value.includes('var(') ? substitute(value, seen) : value);
+    cache[name] = resolved;
+    return resolved;
+  };
+  for (const name of Object.keys(raw)) {
+    reference(name, new Set());
+  }
+  return cache;
+}

package/dist/theme/tokens.d.ts

@@ -15,6 +15,7 @@
  *
  * SYNC: When modified, update:
  * - /packages/core/src/theme/useTheme.ts
+ * - /packages/core/src/theme/tokenReferences.ts (the `var()` resolver)
  * - /packages/core/src/theme/index.ts
  */
 import { type DefinedTheme, type TokenName } from './defineTheme.js';

package/dist/theme/tokens.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tokens.d.ts","sourceRoot":"","sources":["../../src/theme/tokens.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EAEL,KAAK,YAAY,EACjB,KAAK,SAAS,EAEf,MAAM,eAAe,CAAC;AAIvB,kFAAkF;AAClF,MAAM,MAAM,iBAAiB,GAAG,OAAO,GAAG,MAAM,CAAC;AAEjD,4DAA4D;AAC5D,MAAM,WAAW,yBAAyB;IACxC,kGAAkG;IAClG,IAAI,EAAE,iBAAiB,CAAC;CACzB;AAED,2DAA2D;AAC3D,MAAM,WAAW,wBAAyB,SAAQ,yBAAyB;IACzE,mFAAmF;IACnF,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,SAAS,GAAG,CAAC,MAAM,GAAG,EAAE,CAAC,GAAG,MAAM,CAEhE;AAED,sFAAsF;AACtF,eAAO,MAAM,SAAS,EAAE,MAAM,CAAC,SAAS,EAAE,MAAM,CAElB,CAAC;AAqT/B;;;;;;;;;;;;;GAaG;AACH,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,YAAY,GAAG,IAAI,GAAG,SAAS,EACtC,OAAO,EAAE,yBAAyB,GACjC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CA8CxB;AAED,2EAA2E;AAC3E,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,YAAY,GAAG,IAAI,GAAG,SAAS,EACtC,IAAI,EAAE,SAAS,GAAG,CAAC,MAAM,GAAG,EAAE,CAAC,EAC/B,OAAO,EAAE,wBAAwB,GAChC,MAAM,CAGR"}
+{"version":3,"file":"tokens.d.ts","sourceRoot":"","sources":["../../src/theme/tokens.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EAEL,KAAK,YAAY,EACjB,KAAK,SAAS,EAEf,MAAM,eAAe,CAAC;AASvB,kFAAkF;AAClF,MAAM,MAAM,iBAAiB,GAAG,OAAO,GAAG,MAAM,CAAC;AAEjD,4DAA4D;AAC5D,MAAM,WAAW,yBAAyB;IACxC,kGAAkG;IAClG,IAAI,EAAE,iBAAiB,CAAC;CACzB;AAED,2DAA2D;AAC3D,MAAM,WAAW,wBAAyB,SAAQ,yBAAyB;IACzE,mFAAmF;IACnF,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,SAAS,GAAG,CAAC,MAAM,GAAG,EAAE,CAAC,GAAG,MAAM,CAEhE;AAED,sFAAsF;AACtF,eAAO,MAAM,SAAS,EAAE,MAAM,CAAC,SAAS,EAAE,MAAM,CAElB,CAAC;AAgK/B;;;;;;;;;;;;;GAaG;AACH,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,YAAY,GAAG,IAAI,GAAG,SAAS,EACtC,OAAO,EAAE,yBAAyB,GACjC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CA8CxB;AAED,2EAA2E;AAC3E,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,YAAY,GAAG,IAAI,GAAG,SAAS,EACtC,IAAI,EAAE,SAAS,GAAG,CAAC,MAAM,GAAG,EAAE,CAAC,EAC/B,OAAO,EAAE,wBAAwB,GAChC,MAAM,CAGR"}

package/dist/theme/tokens.js

@@ -17,12 +17,14 @@
  *
  * SYNC: When modified, update:
  * - /packages/core/src/theme/useTheme.ts
+ * - /packages/core/src/theme/tokenReferences.ts (the `var()` resolver)
  * - /packages/core/src/theme/index.ts
  */
 
 import { tokenDefaults } from "./defineTheme.js";
 import { parseColor, formatColor } from "../utils/color.js";
 import { generatedScopedStatusRoleDefaults } from "./generateThemeRules.js";
+import { findMatchingParen, resolveTokenReferences, splitTopLevelComma } from "./tokenReferences.js";
 
 /** Resolved color mode used when choosing the side of light/dark token values. */
 
@@ -54,45 +56,6 @@ export function tokenVar(name) {
 /** Flat map of every known Astryx token name to its `var(--token-name)` reference. */
 export const tokenVars = Object.fromEntries(Object.keys(tokenDefaults).map(name => [name, tokenVar(name)]));
 
-/**
- * Split the arguments of a CSS function body on the first top-level comma.
- * Handles nested functions such as rgba(), color-mix(), var(), and quoted strings.
- */
-function splitTopLevelComma(input) {
-  let depth = 0;
-  let quote = null;
-  let isEscaped = false;
-  for (let i = 0; i < input.length; i++) {
-    const char = input[i];
-    if (quote !== null) {
-      if (isEscaped) {
-        isEscaped = false;
-      } else if (char === '\\') {
-        isEscaped = true;
-      } else if (char === quote) {
-        quote = null;
-      }
-      continue;
-    }
-    if (char === '"' || char === "'") {
-      quote = char;
-      continue;
-    }
-    if (char === '(') {
-      depth++;
-      continue;
-    }
-    if (char === ')') {
-      depth = Math.max(0, depth - 1);
-      continue;
-    }
-    if (char === ',' && depth === 0) {
-      return [input.slice(0, i).trim(), input.slice(i + 1).trim()];
-    }
-  }
-  return null;
-}
-
 /** Parse a CSS light-dark(light, dark) function into its two argument values. */
 function parseLightDark(value) {
   const trimmed = value.trim();
@@ -129,27 +92,11 @@ function resolveXDSTokenValue(value, mode) {
 // Generated themes emit derived tokens as references to other tokens rather
 // than baked-in values, so a scoped CSS override of a base token re-themes the
 // subtree that references it. The CSS cascade resolves those references, but
-// non-CSS consumers (canvas, SVG, data-viz) need the concrete value. These
-// helpers replay the same resolution in JS: follow `var()` references through
-// the resolved token map (iteratively, guarding against cycles) and evaluate
-// the CSS color functions used by the theme generator against those values.
-
-/** Index of the `)` matching the `(` at `openIndex`, or -1 when unbalanced. */
-function findMatchingParen(input, openIndex) {
-  let depth = 0;
-  for (let i = openIndex; i < input.length; i++) {
-    const char = input[i];
-    if (char === '(') {
-      depth++;
-    } else if (char === ')') {
-      depth--;
-      if (depth === 0) {
-        return i;
-      }
-    }
-  }
-  return -1;
-}
+// non-CSS consumers (canvas, SVG, data-viz) need the concrete value. The same
+// resolution replays in JS: tokenReferences.ts follows `var()` references
+// through the resolved token map (guarding against cycles), and these helpers
+// evaluate the CSS color functions used by the theme generator against those
+// values.
 
 /** Split a color-mix component into its color and optional percentage. */
 function parseMixComponent(part) {
@@ -262,73 +209,6 @@ function evaluateColorFunctions(expr) {
   return expr.slice(0, idx) + replacement + evaluateColorFunctions(expr.slice(closeIndex + 1));
 }
 
-/**
- * Substitute `var(--name[, fallback])` references with their resolved values.
- * `seen` tracks the reference chain so cycles resolve to the literal reference
- * instead of recursing forever.
- */
-function substituteVars(expr, raw, cache, seen) {
-  const start = expr.indexOf('var(');
-  if (start === -1) {
-    return expr;
-  }
-  const openIndex = start + 'var'.length;
-  const closeIndex = findMatchingParen(expr, openIndex);
-  if (closeIndex === -1) {
-    return expr;
-  }
-  const inner = expr.slice(openIndex + 1, closeIndex);
-  const commaSplit = splitTopLevelComma(inner);
-  const name = (commaSplit ? commaSplit[0] : inner).trim();
-  const fallback = commaSplit ? commaSplit[1] : null;
-  let replacement;
-  if (seen.has(name)) {
-    replacement = expr.slice(start, closeIndex + 1);
-  } else if (name in raw) {
-    seen.add(name);
-    replacement = resolveReference(name, raw, cache, seen);
-    seen.delete(name);
-  } else if (fallback !== null) {
-    replacement = substituteVars(fallback.trim(), raw, cache, seen);
-  } else {
-    replacement = expr.slice(start, closeIndex + 1);
-  }
-  const rest = substituteVars(expr.slice(closeIndex + 1), raw, cache, seen);
-  return expr.slice(0, start) + replacement + rest;
-}
-
-/** Fully resolve a single expression: substitute references, then evaluate colors. */
-function resolveExpression(expr, raw, cache, seen) {
-  if (!expr.includes('var(') && !expr.includes('color-mix(')) {
-    return expr;
-  }
-  const substituted = substituteVars(expr, raw, cache, seen);
-  return evaluateColorFunctions(substituted);
-}
-
-/** Resolve one token by name, memoizing the result in `cache`. */
-function resolveReference(name, raw, cache, seen) {
-  if (name in cache) {
-    return cache[name];
-  }
-  const value = raw[name];
-  if (value === undefined) {
-    return '';
-  }
-  const resolved = resolveExpression(value, raw, cache, seen);
-  cache[name] = resolved;
-  return resolved;
-}
-
-/** Resolve every reference/color function in a raw token map to concrete values. */
-function resolveReferences(raw) {
-  const cache = {};
-  for (const name of Object.keys(raw)) {
-    resolveReference(name, raw, cache, new Set());
-  }
-  return cache;
-}
-
 /**
  * Resolve all Astryx token values for a theme and effective color mode.
  *
@@ -352,7 +232,7 @@ export function resolveThemeTokens(theme, options) {
     resolved[key] = resolveXDSTokenValue(value, mode);
   }
   if (theme == null) {
-    return resolveReferences(resolved);
+    return resolveTokenReferences(resolved, evaluateColorFunctions);
   }
 
   // A theme's local tokens resolve its references to them, then leave the
@@ -378,7 +258,7 @@ export function resolveThemeTokens(theme, options) {
       }
     }
   }
-  return Object.fromEntries(Object.entries(resolveReferences(resolved)).filter(([key]) => !localKeys.has(key)));
+  return Object.fromEntries(Object.entries(resolveTokenReferences(resolved, evaluateColorFunctions)).filter(([key]) => !localKeys.has(key)));
 }
 
 /** Resolve one Astryx token value for a theme and effective color mode. */

package/dist/theme/tokens.stylex.d.ts

@@ -340,10 +340,22 @@ export declare const durationVars: stylex.VarGroup<Readonly<{
 export type DurationVarName = keyof typeof durationDefaults;
 export declare const easeDefaults: {
     readonly '--ease-standard': "cubic-bezier(0.24, 1, 0.4, 1)";
+    /**
+     * Entrances: a layer or element arriving. A theme's `character` sets it
+     * (spec:AST-108 FR2); at `'standard'` it equals --ease-standard.
+     */
+    readonly '--ease-entrance': "cubic-bezier(0.24, 1, 0.4, 1)";
+    /**
+     * Moves: an element changing place or size on screen. A theme's
+     * `character` sets it; at `'standard'` it equals --ease-standard.
+     */
+    readonly '--ease-move': "cubic-bezier(0.24, 1, 0.4, 1)";
     readonly '--ease-exit': "cubic-bezier(0.3, 0, 0.6, 0.6)";
 };
 export declare const easeVars: stylex.VarGroup<Readonly<{
     readonly '--ease-standard': "cubic-bezier(0.24, 1, 0.4, 1)";
+    readonly '--ease-entrance': "cubic-bezier(0.24, 1, 0.4, 1)";
+    readonly '--ease-move': "cubic-bezier(0.24, 1, 0.4, 1)";
     readonly '--ease-exit': "cubic-bezier(0.3, 0, 0.6, 0.6)";
 }>, symbol>;
 export type EaseVarName = keyof typeof easeDefaults;

package/dist/theme/tokens.stylex.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tokens.stylex.d.ts","sourceRoot":"","sources":["../../src/theme/tokens.stylex.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,MAAM,MAAM,kBAAkB,CAAC;AAM3C,eAAO,MAAM,aAAa;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAsJhB,CAAC;AAEX,eAAO,MAAM,SAAS;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;WAAmC,CAAC;AAS1D,eAAO,MAAM,eAAe;;;;;;;;;;;;;;;;CAgBlB,CAAC;AAEX,eAAO,MAAM,WAAW;;;;;;;;;;;;;;;;WAAqC,CAAC;AAM9D,eAAO,MAAM,YAAY;;;;CAIf,CAAC;AAEX,eAAO,MAAM,QAAQ;;;;WAAkC,CAAC;AAMxD,eAAO,MAAM,cAAc;;CAEjB,CAAC;AAEX,eAAO,MAAM,UAAU;;WAAoC,CAAC;AAE5D,MAAM,MAAM,aAAa,GAAG,MAAM,OAAO,cAAc,CAAC;AAWxD,eAAO,MAAM,aAAa;;;;;CAKhB,CAAC;AAEX,eAAO,MAAM,SAAS;;;;;WAAmC,CAAC;AAM1D,eAAO,MAAM,cAAc;;;;;;;;CAWjB,CAAC;AAEX,eAAO,MAAM,UAAU;;;;;;;;WAAoC,CAAC;AAQ5D,eAAO,MAAM,cAAc;;;;;;;;;CAejB,CAAC;AAEX,eAAO,MAAM,UAAU;;;;;;;;;WAAoC,CAAC;AAU5D,eAAO,MAAM,gBAAgB;;;;;;;;;;CAUnB,CAAC;AAEX,eAAO,MAAM,YAAY;;;;;;;;;;WAAsC,CAAC;AAEhE,MAAM,MAAM,eAAe,GAAG,MAAM,OAAO,gBAAgB,CAAC;AAU5D,eAAO,MAAM,YAAY;;;CAGf,CAAC;AAEX,eAAO,MAAM,QAAQ;;;WAAkC,CAAC;AAExD,MAAM,MAAM,WAAW,GAAG,MAAM,OAAO,YAAY,CAAC;AAKpD,eAAO,MAAM,kBAAkB;;;;CAMrB,CAAC;AAEX,eAAO,MAAM,cAAc;;;;WAAwC,CAAC;AAMpE,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;CAcnB,CAAC;AAEX,eAAO,MAAM,YAAY;;;;;;;;;;;;;WAAsC,CAAC;AAMhE,eAAO,MAAM,kBAAkB;;;;;CAKrB,CAAC;AAEX,eAAO,MAAM,cAAc;;;;;WAAwC,CAAC;AAMpE,MAAM,MAAM,YAAY,GAAG,MAAM,OAAO,aAAa,CAAC;AACtD,MAAM,MAAM,cAAc,GAAG,MAAM,OAAO,eAAe,CAAC;AAC1D,MAAM,MAAM,WAAW,GAAG,MAAM,OAAO,YAAY,CAAC;AACpD,MAAM,MAAM,aAAa,GAAG,MAAM,OAAO,cAAc,CAAC;AACxD,MAAM,MAAM,aAAa,GAAG,MAAM,OAAO,cAAc,CAAC;AACxD,MAAM,MAAM,iBAAiB,GAAG,MAAM,OAAO,kBAAkB,CAAC;AAChE,MAAM,MAAM,eAAe,GAAG,MAAM,OAAO,gBAAgB,CAAC;AAC5D,MAAM,MAAM,iBAAiB,GAAG,MAAM,OAAO,kBAAkB,CAAC;AAehE,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA0DpB,CAAC;AAEX,eAAO,MAAM,aAAa;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;WAAuC,CAAC;AAElE,MAAM,MAAM,gBAAgB,GAAG,MAAM,OAAO,iBAAiB,CAAC"}
+{"version":3,"file":"tokens.stylex.d.ts","sourceRoot":"","sources":["../../src/theme/tokens.stylex.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,MAAM,MAAM,kBAAkB,CAAC;AAM3C,eAAO,MAAM,aAAa;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAsJhB,CAAC;AAEX,eAAO,MAAM,SAAS;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;WAAmC,CAAC;AAS1D,eAAO,MAAM,eAAe;;;;;;;;;;;;;;;;CAgBlB,CAAC;AAEX,eAAO,MAAM,WAAW;;;;;;;;;;;;;;;;WAAqC,CAAC;AAM9D,eAAO,MAAM,YAAY;;;;CAIf,CAAC;AAEX,eAAO,MAAM,QAAQ;;;;WAAkC,CAAC;AAMxD,eAAO,MAAM,cAAc;;CAEjB,CAAC;AAEX,eAAO,MAAM,UAAU;;WAAoC,CAAC;AAE5D,MAAM,MAAM,aAAa,GAAG,MAAM,OAAO,cAAc,CAAC;AAWxD,eAAO,MAAM,aAAa;;;;;CAKhB,CAAC;AAEX,eAAO,MAAM,SAAS;;;;;WAAmC,CAAC;AAM1D,eAAO,MAAM,cAAc;;;;;;;;CAWjB,CAAC;AAEX,eAAO,MAAM,UAAU;;;;;;;;WAAoC,CAAC;AAQ5D,eAAO,MAAM,cAAc;;;;;;;;;CAejB,CAAC;AAEX,eAAO,MAAM,UAAU;;;;;;;;;WAAoC,CAAC;AAU5D,eAAO,MAAM,gBAAgB;;;;;;;;;;CAUnB,CAAC;AAEX,eAAO,MAAM,YAAY;;;;;;;;;;WAAsC,CAAC;AAEhE,MAAM,MAAM,eAAe,GAAG,MAAM,OAAO,gBAAgB,CAAC;AAU5D,eAAO,MAAM,YAAY;;IAEvB;;;OAGG;;IAEH;;;OAGG;;;CAGK,CAAC;AAEX,eAAO,MAAM,QAAQ;;;;;WAAkC,CAAC;AAExD,MAAM,MAAM,WAAW,GAAG,MAAM,OAAO,YAAY,CAAC;AAKpD,eAAO,MAAM,kBAAkB;;;;CAMrB,CAAC;AAEX,eAAO,MAAM,cAAc;;;;WAAwC,CAAC;AAMpE,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;CAcnB,CAAC;AAEX,eAAO,MAAM,YAAY;;;;;;;;;;;;;WAAsC,CAAC;AAMhE,eAAO,MAAM,kBAAkB;;;;;CAKrB,CAAC;AAEX,eAAO,MAAM,cAAc;;;;;WAAwC,CAAC;AAMpE,MAAM,MAAM,YAAY,GAAG,MAAM,OAAO,aAAa,CAAC;AACtD,MAAM,MAAM,cAAc,GAAG,MAAM,OAAO,eAAe,CAAC;AAC1D,MAAM,MAAM,WAAW,GAAG,MAAM,OAAO,YAAY,CAAC;AACpD,MAAM,MAAM,aAAa,GAAG,MAAM,OAAO,cAAc,CAAC;AACxD,MAAM,MAAM,aAAa,GAAG,MAAM,OAAO,cAAc,CAAC;AACxD,MAAM,MAAM,iBAAiB,GAAG,MAAM,OAAO,kBAAkB,CAAC;AAChE,MAAM,MAAM,eAAe,GAAG,MAAM,OAAO,gBAAgB,CAAC;AAC5D,MAAM,MAAM,iBAAiB,GAAG,MAAM,OAAO,kBAAkB,CAAC;AAehE,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA0DpB,CAAC;AAEX,eAAO,MAAM,aAAa;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;WAAuC,CAAC;AAElE,MAAM,MAAM,gBAAgB,GAAG,MAAM,OAAO,iBAAiB,CAAC"}

package/dist/theme/tokens.stylex.js

@@ -455,10 +455,22 @@ export const durationVars = {
 
 export const easeDefaults = {
   '--ease-standard': 'cubic-bezier(0.24, 1, 0.4, 1)',
+  /**
+   * Entrances: a layer or element arriving. A theme's `character` sets it
+   * (spec:AST-108 FR2); at `'standard'` it equals --ease-standard.
+   */
+  '--ease-entrance': 'cubic-bezier(0.24, 1, 0.4, 1)',
+  /**
+   * Moves: an element changing place or size on screen. A theme's
+   * `character` sets it; at `'standard'` it equals --ease-standard.
+   */
+  '--ease-move': 'cubic-bezier(0.24, 1, 0.4, 1)',
   '--ease-exit': 'cubic-bezier(0.3, 0, 0.6, 0.6)'
 };
 export const easeVars = {
   "--ease-standard": "var(--ease-standard)",
+  "--ease-entrance": "var(--ease-entrance)",
+  "--ease-move": "var(--ease-move)",
   "--ease-exit": "var(--ease-exit)",
   __varGroupHash__: "xf09i69"
 };

package/dist/utils/focusReturn.d.ts

@@ -1,3 +1,15 @@
+/**
+ * @file focusReturn.ts
+ * @input The document's current active element and the shared interaction
+ *   modality.
+ * @output Whether focus is currently "detached" — on nothing in particular —
+ *   and a focus move whose ring follows the last input.
+ * @position Utility; used by overlay triggers (e.g. DateInput, DateTimeInput)
+ *   that return focus to their control when the overlay closes, but only when
+ *   the dismiss did not already move focus somewhere the user chose, and by
+ *   overlays (Dialog, DropdownMenu) that move focus programmatically.
+ */
+import { type InteractionModality } from './interactionModality.js';
 /**
  * True when focus rests on nothing in particular — no active element, or the
  * document body / root element.
@@ -21,8 +33,12 @@ export declare function isFocusDetached(doc?: Document): boolean;
  * autofocus target, the control that opened a Dialog, or a menu trigger the
  * caller renders. Pass `options` (for example `preventScroll`) as to `focus()`.
  *
+ * `modality` defaults to the page's last input. A caller moving focus inside a
+ * second document (a same-origin iframe, a Document Picture-in-Picture window)
+ * passes that document's, which it tracks with `trackInteractionModalityIn`.
+ *
  * Make sure modality tracking is active (`useInteractionModalityTracking()`)
  * in the component that calls this.
  */
-export declare function focusForLastInput(element: HTMLElement, options?: FocusOptions): void;
+export declare function focusForLastInput(element: HTMLElement, options?: FocusOptions, modality?: InteractionModality): void;
 //# sourceMappingURL=focusReturn.d.ts.map

package/dist/utils/focusReturn.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"focusReturn.d.ts","sourceRoot":"","sources":["../../src/utils/focusReturn.ts"],"names":[],"mappings":"AAgBA;;;;;;;;;;;;;GAaG;AACH,wBAAgB,eAAe,CAAC,GAAG,GAAE,QAAmB,GAAG,OAAO,CAKjE;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,WAAW,EACpB,OAAO,CAAC,EAAE,YAAY,GACrB,IAAI,CAwBN"}
+{"version":3,"file":"focusReturn.d.ts","sourceRoot":"","sources":["../../src/utils/focusReturn.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;GAUG;AAEH,OAAO,EAEL,KAAK,mBAAmB,EACzB,MAAM,uBAAuB,CAAC;AAE/B;;;;;;;;;;;;;GAaG;AACH,wBAAgB,eAAe,CAAC,GAAG,GAAE,QAAmB,GAAG,OAAO,CAKjE;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,WAAW,EACpB,OAAO,CAAC,EAAE,YAAY,EACtB,QAAQ,GAAE,mBAA8C,GACvD,IAAI,CA2BN"}

package/dist/utils/focusReturn.js

@@ -41,14 +41,21 @@ export function isFocusDetached(doc = document) {
  * autofocus target, the control that opened a Dialog, or a menu trigger the
  * caller renders. Pass `options` (for example `preventScroll`) as to `focus()`.
  *
+ * `modality` defaults to the page's last input. A caller moving focus inside a
+ * second document (a same-origin iframe, a Document Picture-in-Picture window)
+ * passes that document's, which it tracks with `trackInteractionModalityIn`.
+ *
  * Make sure modality tracking is active (`useInteractionModalityTracking()`)
  * in the component that calls this.
  */
-export function focusForLastInput(element, options) {
+export function focusForLastInput(element, options, modality = getInteractionModality()) {
   // A text-entry field paints its own focus treatment to show where typing
-  // goes, and an extra blur there can run validation or mark it touched.
-  const isTextEntry = element instanceof HTMLInputElement || element instanceof HTMLTextAreaElement || element instanceof HTMLSelectElement || element.isContentEditable;
-  if (isTextEntry || getInteractionModality() !== 'pointer') {
+  // goes, and an extra blur there can run validation or mark it touched. The
+  // field's own window: one in an iframe or a Picture-in-Picture window is
+  // never an instance of the page's constructors.
+  const view = element.ownerDocument.defaultView ?? window;
+  const isTextEntry = element instanceof view.HTMLInputElement || element instanceof view.HTMLTextAreaElement || element instanceof view.HTMLSelectElement || element.isContentEditable;
+  if (isTextEntry || modality !== 'pointer') {
     if (options === undefined) {
       element.focus();
     } else {