@astryxdesign/core 0.7.5 → 0.7.6-canary.0bd3b37

package/src/theme/themeAdaptations.ts

@@ -27,6 +27,7 @@
 import type {ComponentStyleMap, TokenName, TokenValue} from './defineTheme';
 import type {TypographyConfig, TypographyRole} from './types';
 import type {MotionScaleConfig} from './expandMotionScale';
+import type {ThemeMotionConfig, ThemeMotionKnobs} from './themeMotion';
 import type {RadiusScaleConfig} from './expandRadiusScale';
 import type {ColorScaleConfig} from './expandColorScale';
 import {resolveThemeValues, type ThemeValuesInput} from './resolveThemeValues';
@@ -133,8 +134,11 @@ export interface ThemeAdaptationValue {
   color?: Partial<ColorScaleConfig>;
   /** Radius axis overrides, completed from root metadata. */
   radius?: Partial<RadiusScaleConfig>;
-  /** Motion axis overrides, completed from root metadata. */
-  motion?: Partial<MotionScaleConfig>;
+  /**
+   * Motion axis overrides, completed from root metadata: scale fields, or the
+   * `tempo` and `character` knobs (spec:AST-108 FR5).
+   */
+  motion?: Partial<MotionScaleConfig> & ThemeMotionKnobs;
   /** Portable semantic-token writes. */
   tokens?: Partial<Record<TokenName, TokenValue>>;
   /** Replacements for exact theme-local names enrolled by the root lineage. */
@@ -176,7 +180,7 @@ export interface ThemeGenerativeAxes {
   typography?: TypographyConfig;
   color?: ColorScaleConfig;
   radius?: RadiusScaleConfig;
-  motion?: MotionScaleConfig;
+  motion?: ThemeMotionConfig;
 }
 
 /** One rule lowered to concrete CSS writes. */
@@ -570,13 +574,41 @@ function completeRadius(
 }
 
 function completeMotion(
-  root: MotionScaleConfig | undefined,
-  rule: Partial<MotionScaleConfig>,
+  root: ThemeMotionConfig | undefined,
+  rule: Partial<MotionScaleConfig> & ThemeMotionKnobs,
   path: string,
-): MotionScaleConfig {
-  const fast = rule.fast ?? root?.fast;
-  const medium = rule.medium ?? root?.medium;
-  const ratio = rule.ratio ?? root?.ratio;
+): ThemeMotionConfig {
+  // Not a public field, but a plain-JS caller may still pass it.
+  if ((rule as {reducedMotion?: unknown}).reducedMotion !== undefined) {
+    throw new Error(
+      `${path}.reducedMotion is a theme-wide setting: set it on the theme's own ` +
+        `motion, not in an adaptation rule.`,
+    );
+  }
+  const tempo = rule.tempo ?? root?.tempo;
+  const character = rule.character ?? root?.character;
+  const knobs: ThemeMotionKnobs = {
+    ...(tempo !== undefined ? {tempo} : {}),
+    ...(character !== undefined ? {character} : {}),
+  };
+  if (knobs.tempo !== undefined) {
+    assertFiniteNumber(knobs.tempo, `${path}.tempo`);
+  }
+  const rootScale: Partial<MotionScaleConfig> =
+    root != null && 'fast' in root ? root : {};
+  const writesScale =
+    rule.fast !== undefined ||
+    rule.medium !== undefined ||
+    rule.ratio !== undefined ||
+    rule.slow !== undefined ||
+    rule.easing !== undefined;
+  if (!writesScale && 'fast' in rootScale === false) {
+    // Knobs only, over a root with no scale: the knobs generate the tokens.
+    return knobs;
+  }
+  const fast = rule.fast ?? rootScale.fast;
+  const medium = rule.medium ?? rootScale.medium;
+  const ratio = rule.ratio ?? rootScale.ratio;
   if (fast === undefined || medium === undefined || ratio === undefined) {
     throw new Error(
       `${path} must supply \`fast\`, \`medium\`, and \`ratio\` unless each missing field exists on the effective root motion axis.`,
@@ -585,17 +617,18 @@ function completeMotion(
   assertFiniteNumber(fast, `${path}.fast`);
   assertFiniteNumber(medium, `${path}.medium`);
   assertFiniteNumber(ratio, `${path}.ratio`);
-  const slow = rule.slow ?? root?.slow;
+  const slow = rule.slow ?? rootScale.slow;
   if (slow !== undefined) {
     assertFiniteNumber(slow, `${path}.slow`);
   }
-  const easing = rule.easing ?? root?.easing;
+  const easing = rule.easing ?? rootScale.easing;
   return {
     fast,
     medium,
     ratio,
     ...(slow !== undefined ? {slow} : {}),
     ...(easing !== undefined ? {easing} : {}),
+    ...knobs,
   };
 }
 
@@ -990,7 +1023,14 @@ export function resolveThemeAdaptationRules(
       // acceptance to preserve, so a malformed token is rejected here rather
       // than emitted. The root path stays lenient for compatibility.
       // SYNC: packages/core/src/theme/resolveThemeValues.ts (resolveTokenValue)
-      {strictTokens: true},
+      // A rule without motion of its own keeps the theme's character, so its
+      // explicit --ease-standard leaves that character's curves alone; one
+      // at 'standard' matches the theme's --ease-standard.
+      {
+        strictTokens: true,
+        inheritedCharacter: axes.motion?.character,
+        standardBeneath: rootTokens['--ease-standard'],
+      },
     );
     for (const [name, value] of Object.entries(resolved.tokens)) {
       assertConcreteLeaf(

package/src/theme/themeMotion.ts

@@ -0,0 +1,221 @@
+// 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, type MotionScaleConfig} from './expandMotionScale';
+import {
+  resolveKnobs,
+  type MotionCharacter,
+  type ResolvedMotionKnobs,
+  type ThemeMotionKnobs,
+} from './motionKnobs';
+import {durationDefaults, easeDefaults} from './tokens.stylex';
+import {resolveTokenReferences} from './tokenReferences';
+
+export {
+  TEMPO_RANGE,
+  type MotionCharacter,
+  type ResolvedMotionKnobs,
+  type ThemeMotionKnobs,
+  type ThemeReducedMotion,
+} from './motionKnobs';
+
+/**
+ * A theme's `motion`: the knobs, the existing `MotionScaleConfig`, or both.
+ * A `MotionScaleConfig`'s fields win over `tempo` for the durations they set.
+ */
+export type ThemeMotionConfig =
+  ThemeMotionKnobs | (MotionScaleConfig & ThemeMotionKnobs);
+
+/**
+ * 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)',
+} as const satisfies Record<MotionCharacter, string | null>;
+
+/** The knobs of `config`, defaults filled in, `tempo` clamped. */
+export function resolveMotionKnobs(
+  config: ThemeMotionConfig | undefined,
+): ResolvedMotionKnobs {
+  return resolveKnobs(config);
+}
+
+function isScaleConfig(
+  config: ThemeMotionConfig,
+): config is MotionScaleConfig & ThemeMotionKnobs {
+  return 'fast' in config && 'medium' in config && 'ratio' in config;
+}
+
+/** A duration token's value in ms (`'175ms'` → 175). */
+function msOf(value: string): number {
+  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: number): Record<string, string> {
+  const tokens: Record<string, string> = {};
+  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: string): string {
+  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: ThemeMotionConfig,
+): Record<string, string> {
+  const knobs = resolveMotionKnobs(config);
+  const tokens: Record<string, string> = {};
+  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. */
+export interface ThemeMotion {
+  /** The knobs, defaults filled in. */
+  readonly knobs: ResolvedMotionKnobs;
+  /** Every `--duration-*` token's value. */
+  readonly durations: Readonly<Record<string, string>>;
+  /** `--ease-standard`, `--ease-entrance` and `--ease-move`. */
+  readonly easings: Readonly<Record<string, string>>;
+}
+
+/**
+ * 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: {
+  readonly motion?: ThemeMotionConfig;
+  readonly __axes?: {readonly motion?: ThemeMotionConfig};
+  readonly tokens?: Readonly<Record<string, unknown>>;
+  readonly localTokens?: Readonly<Record<string, unknown>>;
+}): ThemeMotion {
+  // 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: Record<string, string> = {
+    ...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: string): boolean =>
+    typeof theme.tokens?.[name] === 'string' || name in generated;
+  const resolved = resolveTokenReferences(graph);
+  const durations: Record<string, string> = {};
+  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/src/theme/tokenReferences.ts

@@ -0,0 +1,149 @@
+// 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: string): [string, string] | null {
+  let depth = 0;
+  let quote: '"' | "'" | null = 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: string, openIndex: number): number {
+  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: Readonly<Record<string, string>>,
+  evaluate: (expr: string) => string = expr => expr,
+): Record<string, string> {
+  const cache: Record<string, string> = {};
+
+  // `seen` tracks the reference chain, so a cycle resolves to the literal
+  // reference instead of recursing forever.
+  const substitute = (expr: string, seen: Set<string>): string => {
+    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: string;
+    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: string, seen: Set<string>): string => {
+    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<string>());
+  }
+  return cache;
+}

package/src/theme/tokens.stylex.ts

@@ -323,6 +323,16 @@ export type DurationVarName = keyof typeof durationDefaults;
 
 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)',
 } as const;