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

package/src/theme/motionKnobs.ts

@@ -0,0 +1,82 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file motionKnobs.ts
+ * @input A theme's motion knobs (`tempo`, `character`)
+ * @output Their types and `resolveMotionKnobs`, which fills in the defaults
+ *   and clamps `tempo` (`spec:AST-108` FR1). `reducedMotion` is not a public
+ *   knob until `'always'` ships: every theme resolves to `'system'`
+ * @position Theme utility with no imports: themeMotion.ts builds the motion
+ *   tokens on it, and the motion foundation reads a theme's knobs through it
+ *   without loading the token stylesheet. Pure; safe on the server and in
+ *   plain Node.
+ *
+ * SYNC: When modified, update:
+ * - /packages/core/src/theme/themeMotion.ts (re-exports these)
+ * - /packages/core/src/theme/themeMotion.test.ts
+ */
+
+/** How lively a theme's motion feels. */
+export type MotionCharacter = 'crisp' | 'standard' | 'expressive';
+
+/**
+ * Whose Reduce Motion setting a theme follows: `'system'`, each person's own.
+ * Internal: no theme sets it until `'always'` ships (`spec:AST-108` FR6).
+ */
+export type ThemeReducedMotion = 'system';
+
+/** The motion knobs a theme sets (`spec:AST-108` FR1). */
+export interface ThemeMotionKnobs {
+  /**
+   * Scales every motion duration: 1 is Astryx's own, 0.75 the quickest and
+   * 1.5 the slowest (values outside are clamped). Default 1.
+   */
+  tempo?: number;
+  /**
+   * `'crisp'` decelerates without overshoot, `'standard'` is Astryx's own,
+   * `'expressive'` overshoots slightly on entrances and moves. Exits and
+   * fades never overshoot. Default `'standard'`.
+   */
+  character?: MotionCharacter;
+}
+
+/** The knobs with their defaults filled in and `tempo` clamped. */
+export interface ResolvedMotionKnobs {
+  readonly tempo: number;
+  readonly character: MotionCharacter;
+  readonly reducedMotion: ThemeReducedMotion;
+  /**
+   * Whether the theme sets `tempo` itself. A `MotionScaleConfig` alone
+   * implies a tempo for its CSS durations only; the animator's springs stay
+   * at tempo 1 unless this is true (FR5).
+   */
+  readonly tempoIsSet: boolean;
+}
+
+/** The range `tempo` is clamped to. */
+export const TEMPO_RANGE = {min: 0.75, max: 1.5} as const;
+
+const CHARACTERS: ReadonlyArray<MotionCharacter> = [
+  'crisp',
+  'standard',
+  'expressive',
+];
+
+/** The knobs of `config`, defaults filled in, `tempo` clamped. */
+export function resolveKnobs(
+  config: ThemeMotionKnobs | undefined,
+): ResolvedMotionKnobs {
+  const tempoIsSet =
+    typeof config?.tempo === 'number' && Number.isFinite(config.tempo);
+  const tempo = tempoIsSet
+    ? Math.min(
+        TEMPO_RANGE.max,
+        Math.max(TEMPO_RANGE.min, config.tempo as number),
+      )
+    : 1;
+  const character =
+    config?.character != null && CHARACTERS.includes(config.character)
+      ? config.character
+      : 'standard';
+  return {tempo, character, reducedMotion: 'system', tempoIsSet};
+}

package/src/theme/resolveThemeValues.ts

@@ -31,8 +31,14 @@ import {
   generateTypeScaleComponents,
   type TypeScaleConfig,
 } from './expandTypeScale';
-import {expandMotionScale, type MotionScaleConfig} from './expandMotionScale';
+import {
+  expandThemeMotion,
+  preTempoName,
+  type MotionCharacter,
+  type ThemeMotionConfig,
+} from './themeMotion';
 import {expandRadiusScale, type RadiusScaleConfig} from './expandRadiusScale';
+import {easeDefaults} from './tokens.stylex';
 import {expandColorScale, type ColorScaleConfig} from './expandColorScale';
 import {deepMergeComponents} from './mergeComponents';
 
@@ -54,8 +60,8 @@ export interface ThemeValuesInput {
   color?: ColorScaleConfig;
   /** Radius scale configuration. */
   radius?: RadiusScaleConfig;
-  /** Motion scale configuration. */
-  motion?: MotionScaleConfig;
+  /** Motion: the three knobs, a motion scale configuration, or both. */
+  motion?: ThemeMotionConfig;
   /** Syntax highlighting theme. */
   syntax?: SyntaxThemeDefinition;
   /** Explicit token overrides — highest precedence. */
@@ -271,7 +277,20 @@ export function buildFontFamilyTokens(
 export function resolveThemeValues(
   input: ThemeValuesInput,
   seed?: ThemeValuesSeed,
-  {strictTokens = false}: {strictTokens?: boolean} = {},
+  {
+    strictTokens = false,
+    inheritedCharacter,
+    standardBeneath,
+  }: {
+    strictTokens?: boolean;
+    /**
+     * The motion character in effect beneath this layer, from a base theme or
+     * the theme an adaptation rule belongs to, for a layer that sets none.
+     */
+    inheritedCharacter?: MotionCharacter;
+    /** The --ease-standard beneath a layer resolved without a seed: a rule's theme's. */
+    standardBeneath?: string;
+  } = {},
 ): ResolvedThemeValues {
   const tokens: Record<string, string> = {...seed?.tokens};
 
@@ -293,9 +312,19 @@ export function resolveThemeValues(
     Object.assign(tokens, expandRadiusScale(input.radius));
   }
 
-  // 4. Motion-generated tokens
+  // 4. Motion-generated tokens (spec:AST-108 FR2, FR5). A layer that writes
+  // durations also writes the copies busy loops read (FR4), so an enclosing
+  // theme's tempo copies never stand in for its own: without a tempo of its
+  // own, they are its durations.
   if (input.motion) {
-    Object.assign(tokens, expandMotionScale(input.motion));
+    const motion = expandThemeMotion(input.motion);
+    Object.assign(tokens, motion);
+    for (const [name, value] of Object.entries(motion)) {
+      const preTempo = preTempoName(name);
+      if (preTempo !== name && !(preTempo in motion)) {
+        tokens[preTempo] = value;
+      }
+    }
   }
 
   // 5. Font family tokens
@@ -314,9 +343,42 @@ export function resolveThemeValues(
   // 7. Explicit token overrides — highest precedence within this input layer.
   // A generated axis in the same root or adaptation value cannot beat them.
   if (input.tokens) {
+    const own = input.tokens as Partial<Record<string, TokenValue>>;
     for (const [key, value] of Object.entries(input.tokens)) {
       if (value !== undefined) {
         tokens[key] = resolveTokenValue(value, {strict: strictTokens});
+        // An explicit duration beats tempo, so a busy loop reading the
+        // pre-tempo value reads it too (spec:AST-108 FR4).
+        const preTempo = preTempoName(key);
+        if (preTempo !== key && own[preTempo] === undefined) {
+          tokens[preTempo] = tokens[key];
+        }
+      }
+    }
+  }
+
+  // At 'standard', --ease-entrance and --ease-move equal the resolved
+  // --ease-standard (spec:AST-108 FR2): the layer's own, else the one beneath
+  // it. A layer that sets them itself, or whose character, its own or the one
+  // it inherits, picks its own curve, keeps them.
+  const own: Partial<Record<string, TokenValue>> = input.tokens ?? {};
+  const ownCharacter =
+    input.motion != null && 'character' in input.motion
+      ? input.motion.character
+      : undefined;
+  const character = ownCharacter ?? inheritedCharacter;
+  if (
+    ownCharacter === 'standard' ||
+    (own['--ease-standard'] !== undefined &&
+      (character === undefined || character === 'standard'))
+  ) {
+    const standard =
+      tokens['--ease-standard'] ??
+      standardBeneath ??
+      easeDefaults['--ease-standard'];
+    for (const name of ['--ease-entrance', '--ease-move']) {
+      if (own[name] === undefined) {
+        tokens[name] = standard;
       }
     }
   }

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(