@number10/jsx-core 5.0.0

package/dist/animation/useSpring.js

@@ -0,0 +1,149 @@
+import { computed } from "@preact/signals-core";
+import { useRef, getCurrentCtx, useEffect } from "../hooks.js";
+import { animatedSignal } from "./animated-signal.js";
+import { SPRING_PRESETS, SpringPhysics } from "./spring-physics.js";
+function useSpring(initialValue, config, onComplete) {
+  const resolvedConfig = typeof config === "string" ? SPRING_PRESETS[config] : config ?? SPRING_PRESETS.default;
+  const valueSignal = useRef(null);
+  if (valueSignal.current === null) {
+    valueSignal.current = animatedSignal(initialValue);
+  }
+  const ctx = getCurrentCtx();
+  const scheduler = ctx?.surface?.scheduler ?? null;
+  const state = useRef({ value: initialValue, velocity: 0 });
+  const target = useRef({ value: initialValue });
+  const physics = useRef(new SpringPhysics(resolvedConfig));
+  const schedulerRef = useRef(null);
+  const wasAtRest = useRef(true);
+  if (scheduler && schedulerRef.current !== scheduler) {
+    schedulerRef.current = scheduler;
+  }
+  const setValueRef = useRef(
+    null
+  );
+  if (!setValueRef.current) {
+    setValueRef.current = (newTarget) => {
+      const nextTarget = typeof newTarget === "function" ? newTarget(target.current.value) : newTarget;
+      target.current.value = nextTarget;
+    };
+  }
+  useEffect(() => {
+    const currentScheduler = schedulerRef.current;
+    if (!currentScheduler) {
+      console.warn("useSpring: HostScheduler not found in surface context");
+      return;
+    }
+    const updateListener = (delta) => {
+      const currentTarget = target.current.value;
+      const currentState = state.current;
+      const atRest = physics.current.isAtRest(currentState, currentTarget);
+      if (wasAtRest.current && !atRest) {
+        resolvedConfig.onStart?.();
+      }
+      if (atRest && !wasAtRest.current && onComplete) {
+        onComplete();
+      }
+      wasAtRest.current = atRest;
+      if (atRest) {
+        const snapped = physics.current.snapIfAtRest(currentState, currentTarget);
+        if (snapped.value !== currentState.value && valueSignal.current) {
+          state.current = snapped;
+          valueSignal.current.value = snapped.value;
+        }
+        return;
+      }
+      const deltaSeconds = delta / 1e3;
+      const newState = physics.current.step(currentState, currentTarget, deltaSeconds);
+      resolvedConfig.onUpdate?.(newState.value);
+      if (valueSignal.current) {
+        state.current = newState;
+        valueSignal.current.value = newState.value;
+      }
+    };
+    const handle = currentScheduler.onFrame(updateListener);
+    return () => {
+      handle.cancel();
+    };
+  }, []);
+  if (!valueSignal.current) {
+    throw new Error("useSpring: Failed to initialize animated signal");
+  }
+  return [
+    valueSignal.current,
+    setValueRef.current
+  ];
+}
+function useSprings(initialValues, config) {
+  const keys = Object.keys(initialValues);
+  const springsMap = useRef(/* @__PURE__ */ new Map());
+  const schedulerRef = useRef(null);
+  const resolvedConfig = typeof config === "string" ? SPRING_PRESETS[config] : config ?? SPRING_PRESETS.default;
+  keys.forEach((key) => {
+    if (!springsMap.current.has(key)) {
+      const initialValue = initialValues[key];
+      const signal = animatedSignal(initialValue);
+      const target = { value: initialValue };
+      const state = { value: initialValue, velocity: 0 };
+      const physics = new SpringPhysics(resolvedConfig);
+      springsMap.current.set(key, { signal, target, state, physics });
+    }
+  });
+  const ctx = getCurrentCtx();
+  const scheduler = ctx?.surface?.scheduler ?? null;
+  if (scheduler && schedulerRef.current !== scheduler) {
+    schedulerRef.current = scheduler;
+  }
+  useEffect(() => {
+    const currentScheduler = schedulerRef.current;
+    if (!currentScheduler) {
+      console.warn("useSprings: HostScheduler not found in surface context");
+      return;
+    }
+    const updateListener = (delta) => {
+      const deltaSeconds = delta / 1e3;
+      springsMap.current.forEach((spring) => {
+        const currentTarget = spring.target.value;
+        const currentState = spring.state;
+        if (spring.physics.isAtRest(currentState, currentTarget)) {
+          const snapped = spring.physics.snapIfAtRest(currentState, currentTarget);
+          if (snapped.value !== currentState.value) {
+            spring.state = snapped;
+            spring.signal.value = snapped.value;
+          }
+          return;
+        }
+        const newState = spring.physics.step(currentState, currentTarget, deltaSeconds);
+        spring.state = newState;
+        spring.signal.value = newState.value;
+      });
+    };
+    const handle = currentScheduler.onFrame(updateListener);
+    return () => {
+      handle.cancel();
+    };
+  }, []);
+  const signals = {};
+  keys.forEach((key) => {
+    const spring = springsMap.current.get(key);
+    if (spring) {
+      signals[key] = spring.signal;
+    }
+  });
+  const setValues = (values) => {
+    Object.entries(values).forEach(([key, value]) => {
+      const spring = springsMap.current.get(key);
+      if (spring) {
+        const nextTarget = typeof value === "function" ? value(spring.target.value) : value;
+        spring.target.value = nextTarget;
+      }
+    });
+  };
+  return [signals, setValues];
+}
+export {
+  SPRING_PRESETS,
+  computed,
+  useSpring,
+  useSprings
+};
+//# sourceMappingURL=useSpring.js.map

package/dist/animation/useSpring.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useSpring.js","sources":["../../src/animation/useSpring.ts"],"sourcesContent":["/**\n * Spring animation hook\n * Provides physics-based animations using signals for direct updates.\n * Uses HostScheduler.onFrame() — no renderer-specific tick source needed.\n *\n * @migration(audit:surface-access) Phase 7 — moved to @number10/jsx-core ✅\n */\nimport { computed, type Signal } from '@preact/signals-core'\nimport { getCurrentCtx, useEffect, useRef, type HookContext } from '../hooks'\nimport type { HostScheduler } from '../host-adapter'\nimport { animatedSignal, type AnimatedSignal } from './animated-signal'\nimport {\n  SPRING_PRESETS,\n  SpringPhysics,\n  type SpringConfig,\n  type SpringState,\n} from './spring-physics'\n\n/**\n * Spring animation hook\n * Creates an animated signal that smoothly transitions to target values\n *\n * @param initialValue - Initial value\n * @param config - Spring configuration or preset name\n * @param onComplete - Optional callback when spring reaches rest\n * @returns Tuple of [animated signal, setter function]\n *\n * @example\n * ```tsx\n * // ✓ SAFE - leaf node\n * const [x, setX] = useSpring(0, 'wobbly')\n * <View x={x} width={50} height={50} backgroundColor={0xff0000} />\n *\n * // ✓ SAFE - transform properties\n * const [scale, setScale] = useSpring(1, 'default')\n * <View scale={scale}><Text text=\"Hello\" /></View>\n *\n * // ✗ UNSAFE - container with percentage children\n * const [width, setWidth] = useSpring(200, 'wobbly')\n * <View width={width}><NineSlice width=\"100%\" /></View> // BREAKS!\n * ```\n */\nexport function useSpring(\n  initialValue: number,\n  config?: SpringConfig | keyof typeof SPRING_PRESETS,\n  onComplete?: () => void\n): [AnimatedSignal, (target: number | ((prev: number) => number)) => void] {\n  // Resolve config\n  const resolvedConfig =\n    typeof config === 'string' ? SPRING_PRESETS[config] : (config ?? SPRING_PRESETS.default)\n\n  // Create animated signal\n  const valueSignal = useRef<AnimatedSignal | null>(null)\n  if (valueSignal.current === null) {\n    valueSignal.current = animatedSignal(initialValue)\n  }\n\n  // Capture scheduler from surface context during render\n  const ctx = getCurrentCtx() as HookContext | null\n  const scheduler = ctx?.surface?.scheduler ?? null\n\n  // Physics state\n  const state = useRef<SpringState>({ value: initialValue, velocity: 0 })\n  const target = useRef<Signal<number>>({ value: initialValue } as Signal<number>)\n  const physics = useRef(new SpringPhysics(resolvedConfig))\n  const schedulerRef = useRef<HostScheduler | null>(null)\n  const wasAtRest = useRef<boolean>(true)\n\n  // Update scheduler ref if it changes\n  if (scheduler && schedulerRef.current !== scheduler) {\n    schedulerRef.current = scheduler\n  }\n\n  // Setter function — stable reference via ref (avoids effect re-runs)\n  const setValueRef = useRef<((newTarget: number | ((prev: number) => number)) => void) | null>(\n    null\n  )\n  if (!setValueRef.current) {\n    setValueRef.current = (newTarget: number | ((prev: number) => number)) => {\n      const nextTarget =\n        typeof newTarget === 'function' ? newTarget(target.current.value) : newTarget\n      target.current.value = nextTarget\n    }\n  }\n\n  useEffect(() => {\n    const currentScheduler = schedulerRef.current\n    if (!currentScheduler) {\n      console.warn('useSpring: HostScheduler not found in surface context')\n      return\n    }\n\n    // Physics update loop\n    const updateListener = (delta: number) => {\n      const currentTarget = target.current.value\n      const currentState = state.current\n\n      // Check if at rest\n      const atRest = physics.current.isAtRest(currentState, currentTarget)\n\n      // Fire onStart when transitioning from rest to active\n      if (wasAtRest.current && !atRest) {\n        ;(resolvedConfig as SpringConfig).onStart?.()\n      }\n\n      // Call onComplete if just reached rest\n      if (atRest && !wasAtRest.current && onComplete) {\n        onComplete()\n      }\n      wasAtRest.current = atRest\n\n      // Skip if already at rest\n      if (atRest) {\n        // Snap to target\n        const snapped = physics.current.snapIfAtRest(currentState, currentTarget)\n        if (snapped.value !== currentState.value && valueSignal.current) {\n          state.current = snapped\n          valueSignal.current.value = snapped.value\n        }\n        return\n      }\n\n      // Perform physics step\n      const deltaSeconds = delta / 1000\n      const newState = physics.current.step(currentState, currentTarget, deltaSeconds)\n\n      // Fire onUpdate with current value every frame while active\n      ;(resolvedConfig as SpringConfig).onUpdate?.(newState.value)\n\n      // Update state and signal\n      if (valueSignal.current) {\n        state.current = newState\n        valueSignal.current.value = newState.value\n      }\n    }\n\n    const handle = currentScheduler.onFrame(updateListener)\n    return () => {\n      handle.cancel()\n    }\n  }, [])\n\n  if (!valueSignal.current) {\n    throw new Error('useSpring: Failed to initialize animated signal')\n  }\n\n  return [\n    valueSignal.current,\n    setValueRef.current as (target: number | ((prev: number) => number)) => void,\n  ]\n}\n\n/**\n * Multi-spring animation hook\n * Creates multiple animated signals that share the same configuration\n * @param initialValues - Object with initial values\n * @param config - Spring configuration or preset name\n * @returns Tuple of [animated signals object, setter function]\n *\n * @example\n * ```tsx\n * const [pos, setPos] = useSprings({ x: 0, y: 0 }, 'wobbly')\n * <View x={pos.x} y={pos.y} />\n * setPos({ x: 100, y: 200 })\n * ```\n */\nexport function useSprings<T extends Record<string, number>>(\n  initialValues: T,\n  config?: SpringConfig | keyof typeof SPRING_PRESETS\n): [\n  { [K in keyof T]: AnimatedSignal },\n  (values: Partial<{ [K in keyof T]: number | ((prev: number) => number) }>) => void,\n] {\n  const keys = Object.keys(initialValues) as (keyof T)[]\n  const springsMap = useRef<\n    Map<\n      keyof T,\n      {\n        signal: AnimatedSignal\n        target: { value: number }\n        state: SpringState\n        physics: SpringPhysics\n      }\n    >\n  >(new Map())\n  const schedulerRef = useRef<HostScheduler | null>(null)\n\n  // Resolve config\n  const resolvedConfig =\n    typeof config === 'string' ? SPRING_PRESETS[config] : (config ?? SPRING_PRESETS.default)\n\n  // Initialize springs manually (can't use hooks in loops!)\n  keys.forEach((key) => {\n    if (!springsMap.current.has(key)) {\n      const initialValue = initialValues[key] as number\n      const signal = animatedSignal(initialValue)\n      const target = { value: initialValue }\n      const state = { value: initialValue, velocity: 0 }\n      const physics = new SpringPhysics(resolvedConfig)\n      springsMap.current.set(key, { signal, target, state, physics })\n    }\n  })\n\n  // Capture scheduler from surface context during render\n  const ctx = getCurrentCtx() as HookContext | null\n  const scheduler = ctx?.surface?.scheduler ?? null\n\n  if (scheduler && schedulerRef.current !== scheduler) {\n    schedulerRef.current = scheduler\n  }\n\n  // Setup physics update loop\n  useEffect(() => {\n    const currentScheduler = schedulerRef.current\n    if (!currentScheduler) {\n      console.warn('useSprings: HostScheduler not found in surface context')\n      return\n    }\n\n    const updateListener = (delta: number) => {\n      const deltaSeconds = delta / 1000\n\n      springsMap.current.forEach((spring) => {\n        const currentTarget = spring.target.value\n        const currentState = spring.state\n\n        // Skip if already at rest\n        if (spring.physics.isAtRest(currentState, currentTarget)) {\n          const snapped = spring.physics.snapIfAtRest(currentState, currentTarget)\n          if (snapped.value !== currentState.value) {\n            spring.state = snapped\n            spring.signal.value = snapped.value\n          }\n          return\n        }\n\n        // Perform physics step\n        const newState = spring.physics.step(currentState, currentTarget, deltaSeconds)\n        spring.state = newState\n        spring.signal.value = newState.value\n      })\n    }\n\n    const handle = currentScheduler.onFrame(updateListener)\n    return () => {\n      handle.cancel()\n    }\n  }, [])\n\n  // Build result object\n  const signals = {} as { [K in keyof T]: AnimatedSignal }\n  keys.forEach((key) => {\n    const spring = springsMap.current.get(key)\n    if (spring) {\n      signals[key] = spring.signal\n    }\n  })\n\n  // Setter function\n  const setValues = (values: Partial<{ [K in keyof T]: number | ((prev: number) => number) }>) => {\n    Object.entries(values).forEach(([key, value]) => {\n      const spring = springsMap.current.get(key as keyof T)\n      if (spring) {\n        const nextTarget = typeof value === 'function' ? value(spring.target.value) : value\n        spring.target.value = nextTarget as number\n      }\n    })\n  }\n\n  return [signals, setValues]\n}\n\n/**\n * Export presets for convenience\n */\nexport { computed, SPRING_PRESETS }\n"],"names":[],"mappings":"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"}

package/dist/animation/useTween.cjs

@@ -0,0 +1,208 @@
+"use strict";
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const hooks = require("../hooks.cjs");
+const animatedSignal = require("./animated-signal.cjs");
+const easing = require("./easing.cjs");
+const tween = require("./tween.cjs");
+const TWEEN_PRESETS = {
+  /** Standard transition (300ms, quadOut) */
+  default: { duration: 300, ease: easing.Easing.quadOut },
+  /** Quick transition (150ms, quadOut) */
+  fast: { duration: 150, ease: easing.Easing.quadOut },
+  /** Slow, deliberate transition (600ms, quadOut) */
+  slow: { duration: 600, ease: easing.Easing.quadOut },
+  /** Slightly bouncy quick transition (200ms, backOut) */
+  snappy: { duration: 200, ease: easing.Easing.backOut },
+  /** Elastic feel (400ms, elasticOut) */
+  elastic: { duration: 400, ease: easing.Easing.elasticOut },
+  /** Snap to value instantly (0ms) — useful for reset patterns */
+  instant: { duration: 0 }
+};
+function useTween(initialValue, config, onComplete) {
+  const resolvedBaseConfig = typeof config === "string" ? TWEEN_PRESETS[config] : config ?? TWEEN_PRESETS.default;
+  const resolvedTo = resolvedBaseConfig.to;
+  const isLooping = resolvedBaseConfig.loop !== void 0 && resolvedBaseConfig.loop !== false;
+  const valueSignal = hooks.useRef(null);
+  if (valueSignal.current === null) {
+    valueSignal.current = animatedSignal.animatedSignal(initialValue);
+  }
+  const ctx = hooks.getCurrentCtx();
+  const schedulerRef = hooks.useRef(ctx?.surface?.scheduler ?? null);
+  if (ctx?.surface?.scheduler && schedulerRef.current !== ctx.surface.scheduler) {
+    schedulerRef.current = ctx.surface.scheduler;
+  }
+  const currentTarget = hooks.useRef(resolvedTo ?? initialValue);
+  const tweenCleanupRef = hooks.useRef(null);
+  const setValueRef = hooks.useRef(
+    null
+  );
+  if (!setValueRef.current) {
+    setValueRef.current = (newTarget) => {
+      const resolved = typeof newTarget === "function" ? newTarget(currentTarget.current) : newTarget;
+      currentTarget.current = resolved;
+      startTween();
+    };
+  }
+  const startTween = () => {
+    const scheduler = schedulerRef.current;
+    if (!scheduler) {
+      if (valueSignal.current) {
+        valueSignal.current.value = currentTarget.current;
+      }
+      return;
+    }
+    tweenCleanupRef.current?.();
+    const signal = valueSignal.current;
+    if (!signal) return;
+    const resolvedConfig = resolvedBaseConfig;
+    const steps = resolvedConfig.steps ?? [
+      {
+        to: currentTarget.current,
+        duration: resolvedConfig.duration ?? 300,
+        ease: resolvedConfig.ease
+      }
+    ];
+    const onAllStepsComplete = () => {
+      if (isLooping && resolvedTo !== void 0) {
+        signal.value = initialValue;
+        currentTarget.current = resolvedTo;
+        startTween();
+        return;
+      }
+      onComplete?.();
+    };
+    let stepIndex = 0;
+    let currentHandle = null;
+    resolvedConfig.onStart?.();
+    const runNextStep = () => {
+      if (stepIndex >= steps.length) {
+        onAllStepsComplete();
+        return;
+      }
+      const step = steps[stepIndex];
+      if (!step) return;
+      const startValue = signal.value;
+      currentHandle = tween.createTween(
+        { value: startValue },
+        {
+          to: { value: step.to },
+          duration: step.duration,
+          ease: step.ease ?? easing.Easing.quadOut,
+          onUpdate: (t) => {
+            signal.value = t.value;
+            resolvedConfig.onUpdate?.(t.value);
+          },
+          onComplete: () => {
+            stepIndex++;
+            runNextStep();
+          }
+        },
+        scheduler
+      );
+    };
+    runNextStep();
+    tweenCleanupRef.current = () => {
+      currentHandle?.stop();
+    };
+  };
+  hooks.useEffect(() => {
+    if (currentTarget.current !== initialValue) {
+      startTween();
+    }
+    return () => {
+      tweenCleanupRef.current?.();
+      tweenCleanupRef.current = null;
+    };
+  }, []);
+  if (!valueSignal.current) {
+    throw new Error("useTween: Failed to initialize animated signal");
+  }
+  return [
+    valueSignal.current,
+    setValueRef.current
+  ];
+}
+function useTweens(initialValues, config, onComplete) {
+  const keys = Object.keys(initialValues);
+  const resolvedConfig = typeof config === "string" ? TWEEN_PRESETS[config] : config ?? TWEEN_PRESETS.default;
+  const tweenMap = hooks.useRef(
+    /* @__PURE__ */ new Map()
+  );
+  keys.forEach((key) => {
+    if (!tweenMap.current.has(key)) {
+      const initialValue = initialValues[key];
+      tweenMap.current.set(key, {
+        signal: animatedSignal.animatedSignal(initialValue),
+        target: { value: initialValue }
+      });
+    }
+  });
+  const ctx = hooks.getCurrentCtx();
+  const scheduler = ctx?.surface?.scheduler ?? null;
+  const schedulerRef = hooks.useRef(scheduler);
+  if (scheduler && schedulerRef.current !== scheduler) {
+    schedulerRef.current = scheduler;
+  }
+  const handlesRef = hooks.useRef([]);
+  const setValues = (values) => {
+    const currentScheduler = schedulerRef.current;
+    const entries = Object.entries(values).filter(([, v]) => v !== void 0);
+    if (!currentScheduler) {
+      entries.forEach(([key, val]) => {
+        const entry = tweenMap.current.get(key);
+        if (entry) {
+          entry.signal.value = typeof val === "function" ? val(entry.target.value) : val;
+          entry.target.value = entry.signal.value;
+        }
+      });
+      return;
+    }
+    handlesRef.current.forEach((h) => h.stop());
+    handlesRef.current = [];
+    let completedCount = 0;
+    const totalAnimations = entries.length;
+    entries.forEach(([key, val]) => {
+      const entry = tweenMap.current.get(key);
+      if (!entry) return;
+      const toValue = typeof val === "function" ? val(entry.target.value) : val;
+      entry.target.value = toValue;
+      const handle = tween.createTween(
+        { value: entry.signal.value },
+        {
+          to: { value: toValue },
+          duration: resolvedConfig.duration ?? 300,
+          ease: resolvedConfig.ease ?? easing.Easing.quadOut,
+          onUpdate: (t) => {
+            entry.signal.value = t.value;
+          },
+          onComplete: () => {
+            completedCount++;
+            if (completedCount >= totalAnimations) {
+              onComplete?.();
+            }
+          }
+        },
+        currentScheduler
+      );
+      handlesRef.current.push(handle);
+    });
+  };
+  hooks.useEffect(() => {
+    return () => {
+      handlesRef.current.forEach((h) => h.stop());
+      handlesRef.current = [];
+    };
+  }, []);
+  const signals = {};
+  keys.forEach((key) => {
+    const entry = tweenMap.current.get(key);
+    if (entry) {
+      signals[key] = entry.signal;
+    }
+  });
+  return [signals, setValues];
+}
+exports.TWEEN_PRESETS = TWEEN_PRESETS;
+exports.useTween = useTween;
+exports.useTweens = useTweens;
+//# sourceMappingURL=useTween.cjs.map

package/dist/animation/useTween.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"useTween.cjs","sources":["../../src/animation/useTween.ts"],"sourcesContent":["/**\n * Tween animation hook — declarative time-based animations via signals.\n *\n * Counterpart to useSpring. Uses createTween internally, driven by\n * HostScheduler.onFrame(). Returns an AnimatedSignal that components\n * can bind to JSX props for direct VDOM-bypassing updates.\n *\n * @example\n * ```tsx\n * const [x, setX] = useTween(0, { duration: 500, ease: Easing.quadOut })\n * <View x={x} />\n * setX(200) // animates from current to 200 over 500ms\n *\n * // Multi-step:\n * const [scale, setScale] = useTween(1, {\n *   steps: [\n *     { to: 1.3, duration: 150, ease: Easing.quadOut },\n *     { to: 1.0, duration: 150, ease: Easing.backOut },\n *   ]\n * })\n * ```\n */\n\nimport { getCurrentCtx, useEffect, useRef, type HookContext } from '../hooks'\nimport type { HostScheduler } from '../host-adapter'\nimport { animatedSignal, type AnimatedSignal } from './animated-signal'\nimport { Easing, type EasingFn } from './easing'\nimport { createTween } from './tween'\n\n// ---------------------------------------------------------------------------\n// Types\n// ---------------------------------------------------------------------------\n\n/** Configuration for a single tween step in a multi-step animation */\nexport interface TweenAnimationStep {\n  /** Target value */\n  to: number\n  /** Duration in ms */\n  duration: number\n  /** Easing function (default: quadOut) */\n  ease?: EasingFn | undefined\n}\n\n/** Configuration for useTween */\nexport interface TweenConfig {\n  /** Duration in ms (default: 300) */\n  duration?: number | undefined\n  /** Easing function (default: Easing.quadOut) */\n  ease?: EasingFn | undefined\n  /** Multi-step tween sequence (overrides duration/ease) */\n  steps?: TweenAnimationStep[] | undefined\n  /**\n   * Target value — auto-starts the tween from initialValue to `to`.\n   * No need to call the setter for the first animation.\n   *\n   * When combined with `loop`, the animation restarts from initialValue\n   * to `to` on each completion.\n   */\n  to?: number | undefined\n  /**\n   * Loop the animation. When `true`, restarts from initialValue to `to`\n   * each time the tween completes. Use with `to` for auto-starting loops.\n   *\n   * @example\n   * ```tsx\n   * // Continuous rotation — no effect, no ref, no onComplete needed\n   * const [rotation] = useTween(0, { to: Math.PI * 2, duration: 8000, ease: Easing.linear, loop: true })\n   * <View rotation={rotation} />\n   * ```\n   */\n  loop?: boolean | { reverse?: boolean } | undefined\n  /**\n   * Called once when the tween starts (including on restart/loop).\n   * Fires BEFORE the first frame is rendered.\n   */\n  onStart?: (() => void) | undefined\n  /**\n   * Called on every frame with the current interpolated value.\n   * Useful for syncing non-signal state (logging, analytics).\n   */\n  onUpdate?: ((value: number) => void) | undefined\n}\n\n/**\n * Preset tween configurations for common animation durations.\n *\n * @example\n * ```tsx\n * const [x, setX] = useTween(0, TWEEN_PRESETS.snappy)\n * setX(200)\n * ```\n */\nexport const TWEEN_PRESETS = {\n  /** Standard transition (300ms, quadOut) */\n  default: { duration: 300, ease: Easing.quadOut } as TweenConfig,\n  /** Quick transition (150ms, quadOut) */\n  fast: { duration: 150, ease: Easing.quadOut } as TweenConfig,\n  /** Slow, deliberate transition (600ms, quadOut) */\n  slow: { duration: 600, ease: Easing.quadOut } as TweenConfig,\n  /** Slightly bouncy quick transition (200ms, backOut) */\n  snappy: { duration: 200, ease: Easing.backOut } as TweenConfig,\n  /** Elastic feel (400ms, elasticOut) */\n  elastic: { duration: 400, ease: Easing.elasticOut } as TweenConfig,\n  /** Snap to value instantly (0ms) — useful for reset patterns */\n  instant: { duration: 0 } as TweenConfig,\n} as const\n\n/**\n * Type for tween preset keys\n */\nexport type TweenPreset = keyof typeof TWEEN_PRESETS\n\n// ---------------------------------------------------------------------------\n// useTween\n// ---------------------------------------------------------------------------\n\n/**\n * Creates an animated signal that transitions to target values\n * over a fixed duration with configurable easing.\n *\n * @param initialValue - Initial value\n * @param config - Duration, easing, or multi-step config\n * @param onComplete - Optional callback when animation completes\n * @returns Tuple of [animated signal, setter function]\n */\nexport function useTween(\n  initialValue: number,\n  config?: TweenConfig | TweenPreset,\n  onComplete?: () => void\n): [AnimatedSignal, (target: number | ((prev: number) => number)) => void] {\n  // Resolve config — supports preset names\n  const resolvedBaseConfig: TweenConfig =\n    typeof config === 'string' ? TWEEN_PRESETS[config] : (config ?? TWEEN_PRESETS.default)\n\n  const resolvedTo = resolvedBaseConfig.to\n  const isLooping = resolvedBaseConfig.loop !== undefined && resolvedBaseConfig.loop !== false\n\n  const valueSignal = useRef<AnimatedSignal | null>(null)\n  if (valueSignal.current === null) {\n    valueSignal.current = animatedSignal(initialValue)\n  }\n\n  // Capture scheduler from surface context\n  const ctx = getCurrentCtx() as HookContext | null\n  const schedulerRef = useRef<HostScheduler | null>(ctx?.surface?.scheduler ?? null)\n\n  // Update scheduler ref if it changes\n  if (ctx?.surface?.scheduler && schedulerRef.current !== ctx.surface.scheduler) {\n    schedulerRef.current = ctx.surface.scheduler\n  }\n\n  // Auto-start: if `to` is specified, use it as the initial target\n  const currentTarget = useRef<number>(resolvedTo ?? initialValue)\n  const tweenCleanupRef = useRef<(() => void) | null>(null)\n\n  // Stable setter — avoids re-running effects that depend on it\n  const setValueRef = useRef<((newTarget: number | ((prev: number) => number)) => void) | null>(\n    null\n  )\n  if (!setValueRef.current) {\n    setValueRef.current = (newTarget: number | ((prev: number) => number)): void => {\n      const resolved =\n        typeof newTarget === 'function' ? newTarget(currentTarget.current) : newTarget\n      currentTarget.current = resolved\n      startTween()\n    }\n  }\n\n  const startTween = (): void => {\n    const scheduler = schedulerRef.current\n    if (!scheduler) {\n      // Fallback: set value immediately\n      if (valueSignal.current) {\n        valueSignal.current.value = currentTarget.current\n      }\n      return\n    }\n\n    // Cleanup previous tween\n    tweenCleanupRef.current?.()\n\n    const signal = valueSignal.current\n    if (!signal) return\n\n    const resolvedConfig = resolvedBaseConfig\n\n    // Build step array\n    const steps: TweenAnimationStep[] = resolvedConfig.steps ?? [\n      {\n        to: currentTarget.current,\n        duration: resolvedConfig.duration ?? 300,\n        ease: resolvedConfig.ease,\n      },\n    ]\n\n    // Completion handler — supports loop restart\n    const onAllStepsComplete = (): void => {\n      if (isLooping && resolvedTo !== undefined) {\n        // Reset signal to initialValue and restart tween\n        signal.value = initialValue\n        currentTarget.current = resolvedTo\n        startTween()\n        return\n      }\n      onComplete?.()\n    }\n\n    let stepIndex = 0\n    let currentHandle: ReturnType<typeof createTween> | null = null\n\n    // Fire onStart when the first step begins\n    resolvedConfig.onStart?.()\n\n    const runNextStep = (): void => {\n      if (stepIndex >= steps.length) {\n        onAllStepsComplete()\n        return\n      }\n\n      const step = steps[stepIndex]\n      if (!step) return\n\n      const startValue = signal.value\n\n      currentHandle = createTween(\n        { value: startValue },\n        {\n          to: { value: step.to },\n          duration: step.duration,\n          ease: step.ease ?? Easing.quadOut,\n          onUpdate: (t) => {\n            signal.value = t.value\n            resolvedConfig.onUpdate?.(t.value)\n          },\n          onComplete: () => {\n            stepIndex++\n            runNextStep()\n          },\n        },\n        scheduler\n      )\n    }\n\n    runNextStep()\n\n    tweenCleanupRef.current = () => {\n      currentHandle?.stop()\n    }\n  }\n\n  // Start initial animation if target differs from initial\n  useEffect(() => {\n    if (currentTarget.current !== initialValue) {\n      startTween()\n    }\n\n    return () => {\n      tweenCleanupRef.current?.()\n      tweenCleanupRef.current = null\n    }\n  }, [])\n\n  if (!valueSignal.current) {\n    throw new Error('useTween: Failed to initialize animated signal')\n  }\n\n  return [\n    valueSignal.current,\n    setValueRef.current as (target: number | ((prev: number) => number)) => void,\n  ]\n}\n\n// ---------------------------------------------------------------------------\n// useTweens — multi-value tween hook\n// ---------------------------------------------------------------------------\n\n/**\n * Multi-tween animation hook.\n *\n * Creates multiple animated signals that share the same tween configuration.\n * Counterpart to `useSprings`.\n *\n * @param initialValues - Object with initial numeric values\n * @param config - Tween config or preset name (shared across all properties)\n * @param onComplete - Called when ALL tweens complete (fires once per setValues call)\n * @returns Tuple of [animated signals object, setter function]\n *\n * @example\n * ```tsx\n * const [pos, setPos] = useTweens({ x: 0, y: 0 }, 'snappy')\n * <View x={pos.x} y={pos.y} />\n * setPos({ x: 100, y: 200 })  // both animate to target simultaneously\n * ```\n */\nexport function useTweens<T extends Record<string, number>>(\n  initialValues: T,\n  config?: TweenConfig | TweenPreset,\n  onComplete?: () => void\n): [\n  { [K in keyof T]: AnimatedSignal },\n  (values: Partial<{ [K in keyof T]: number | ((prev: number) => number) }>) => void,\n] {\n  const keys = Object.keys(initialValues) as (keyof T)[]\n\n  // Resolve config — supports preset names\n  const resolvedConfig: TweenConfig =\n    typeof config === 'string' ? TWEEN_PRESETS[config] : (config ?? TWEEN_PRESETS.default)\n\n  // Initialize signals and targets\n  const tweenMap = useRef<Map<keyof T, { signal: AnimatedSignal; target: { value: number } }>>(\n    new Map()\n  )\n\n  keys.forEach((key) => {\n    if (!tweenMap.current.has(key)) {\n      const initialValue = initialValues[key] as number\n      tweenMap.current.set(key, {\n        signal: animatedSignal(initialValue),\n        target: { value: initialValue },\n      })\n    }\n  })\n\n  // Capture scheduler from surface context\n  const ctx = getCurrentCtx() as HookContext | null\n  const scheduler = ctx?.surface?.scheduler ?? null\n  const schedulerRef = useRef<HostScheduler | null>(scheduler)\n  if (scheduler && schedulerRef.current !== scheduler) {\n    schedulerRef.current = scheduler\n  }\n\n  // Track active tween handles for cleanup\n  const handlesRef = useRef<ReturnType<typeof createTween>[]>([])\n\n  // Setter function\n  const setValues = (\n    values: Partial<{ [K in keyof T]: number | ((prev: number) => number) }>\n  ): void => {\n    const currentScheduler = schedulerRef.current\n\n    // Filter out undefined values (Partial may include them)\n    const entries = Object.entries(values).filter(([, v]) => v !== undefined) as [\n      string,\n      number | ((prev: number) => number),\n    ][]\n\n    if (!currentScheduler) {\n      // Fallback: set values immediately\n      entries.forEach(([key, val]) => {\n        const entry = tweenMap.current.get(key as keyof T)\n        if (entry) {\n          entry.signal.value = typeof val === 'function' ? val(entry.target.value) : val\n          entry.target.value = entry.signal.value\n        }\n      })\n      return\n    }\n\n    // Cleanup previous tweens\n    handlesRef.current.forEach((h) => h.stop())\n    handlesRef.current = []\n\n    let completedCount = 0\n    const totalAnimations = entries.length\n\n    entries.forEach(([key, val]) => {\n      const entry = tweenMap.current.get(key as keyof T)\n      if (!entry) return\n\n      const toValue = typeof val === 'function' ? val(entry.target.value) : val\n      entry.target.value = toValue\n\n      const handle = createTween(\n        { value: entry.signal.value },\n        {\n          to: { value: toValue },\n          duration: resolvedConfig.duration ?? 300,\n          ease: resolvedConfig.ease ?? Easing.quadOut,\n          onUpdate: (t) => {\n            entry.signal.value = t.value\n          },\n          onComplete: () => {\n            completedCount++\n            if (completedCount >= totalAnimations) {\n              onComplete?.()\n            }\n          },\n        },\n        currentScheduler\n      )\n\n      handlesRef.current.push(handle)\n    })\n  }\n\n  // Cleanup on unmount\n  useEffect(() => {\n    return () => {\n      handlesRef.current.forEach((h) => h.stop())\n      handlesRef.current = []\n    }\n  }, [])\n\n  // Build result object\n  const signals = {} as { [K in keyof T]: AnimatedSignal }\n  keys.forEach((key) => {\n    const entry = tweenMap.current.get(key)\n    if (entry) {\n      signals[key] = entry.signal\n    }\n  })\n\n  return [signals, setValues]\n}\n"],"names":["Easing","useRef","animatedSignal","getCurrentCtx","createTween","useEffect"],"mappings":"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"}

package/dist/animation/useTween.d.ts

@@ -0,0 +1,116 @@
+import { AnimatedSignal } from './animated-signal';
+import { EasingFn } from './easing';
+/** Configuration for a single tween step in a multi-step animation */
+export interface TweenAnimationStep {
+    /** Target value */
+    to: number;
+    /** Duration in ms */
+    duration: number;
+    /** Easing function (default: quadOut) */
+    ease?: EasingFn | undefined;
+}
+/** Configuration for useTween */
+export interface TweenConfig {
+    /** Duration in ms (default: 300) */
+    duration?: number | undefined;
+    /** Easing function (default: Easing.quadOut) */
+    ease?: EasingFn | undefined;
+    /** Multi-step tween sequence (overrides duration/ease) */
+    steps?: TweenAnimationStep[] | undefined;
+    /**
+     * Target value — auto-starts the tween from initialValue to `to`.
+     * No need to call the setter for the first animation.
+     *
+     * When combined with `loop`, the animation restarts from initialValue
+     * to `to` on each completion.
+     */
+    to?: number | undefined;
+    /**
+     * Loop the animation. When `true`, restarts from initialValue to `to`
+     * each time the tween completes. Use with `to` for auto-starting loops.
+     *
+     * @example
+     * ```tsx
+     * // Continuous rotation — no effect, no ref, no onComplete needed
+     * const [rotation] = useTween(0, { to: Math.PI * 2, duration: 8000, ease: Easing.linear, loop: true })
+     * <View rotation={rotation} />
+     * ```
+     */
+    loop?: boolean | {
+        reverse?: boolean;
+    } | undefined;
+    /**
+     * Called once when the tween starts (including on restart/loop).
+     * Fires BEFORE the first frame is rendered.
+     */
+    onStart?: (() => void) | undefined;
+    /**
+     * Called on every frame with the current interpolated value.
+     * Useful for syncing non-signal state (logging, analytics).
+     */
+    onUpdate?: ((value: number) => void) | undefined;
+}
+/**
+ * Preset tween configurations for common animation durations.
+ *
+ * @example
+ * ```tsx
+ * const [x, setX] = useTween(0, TWEEN_PRESETS.snappy)
+ * setX(200)
+ * ```
+ */
+export declare const TWEEN_PRESETS: {
+    /** Standard transition (300ms, quadOut) */
+    readonly default: TweenConfig;
+    /** Quick transition (150ms, quadOut) */
+    readonly fast: TweenConfig;
+    /** Slow, deliberate transition (600ms, quadOut) */
+    readonly slow: TweenConfig;
+    /** Slightly bouncy quick transition (200ms, backOut) */
+    readonly snappy: TweenConfig;
+    /** Elastic feel (400ms, elasticOut) */
+    readonly elastic: TweenConfig;
+    /** Snap to value instantly (0ms) — useful for reset patterns */
+    readonly instant: TweenConfig;
+};
+/**
+ * Type for tween preset keys
+ */
+export type TweenPreset = keyof typeof TWEEN_PRESETS;
+/**
+ * Creates an animated signal that transitions to target values
+ * over a fixed duration with configurable easing.
+ *
+ * @param initialValue - Initial value
+ * @param config - Duration, easing, or multi-step config
+ * @param onComplete - Optional callback when animation completes
+ * @returns Tuple of [animated signal, setter function]
+ */
+export declare function useTween(initialValue: number, config?: TweenConfig | TweenPreset, onComplete?: () => void): [AnimatedSignal, (target: number | ((prev: number) => number)) => void];
+/**
+ * Multi-tween animation hook.
+ *
+ * Creates multiple animated signals that share the same tween configuration.
+ * Counterpart to `useSprings`.
+ *
+ * @param initialValues - Object with initial numeric values
+ * @param config - Tween config or preset name (shared across all properties)
+ * @param onComplete - Called when ALL tweens complete (fires once per setValues call)
+ * @returns Tuple of [animated signals object, setter function]
+ *
+ * @example
+ * ```tsx
+ * const [pos, setPos] = useTweens({ x: 0, y: 0 }, 'snappy')
+ * <View x={pos.x} y={pos.y} />
+ * setPos({ x: 100, y: 200 })  // both animate to target simultaneously
+ * ```
+ */
+export declare function useTweens<T extends Record<string, number>>(initialValues: T, config?: TweenConfig | TweenPreset, onComplete?: () => void): [
+    {
+        [K in keyof T]: AnimatedSignal;
+    },
+    (values: Partial<{
+        [K in keyof T]: number | ((prev: number) => number);
+    }>) => void
+];
+//# sourceMappingURL=useTween.d.ts.map

package/dist/animation/useTween.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useTween.d.ts","sourceRoot":"","sources":["../../src/animation/useTween.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAIH,OAAO,EAAkB,KAAK,cAAc,EAAE,MAAM,mBAAmB,CAAA;AACvE,OAAO,EAAU,KAAK,QAAQ,EAAE,MAAM,UAAU,CAAA;AAOhD,sEAAsE;AACtE,MAAM,WAAW,kBAAkB;IACjC,mBAAmB;IACnB,EAAE,EAAE,MAAM,CAAA;IACV,qBAAqB;IACrB,QAAQ,EAAE,MAAM,CAAA;IAChB,yCAAyC;IACzC,IAAI,CAAC,EAAE,QAAQ,GAAG,SAAS,CAAA;CAC5B;AAED,iCAAiC;AACjC,MAAM,WAAW,WAAW;IAC1B,oCAAoC;IACpC,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IAC7B,gDAAgD;IAChD,IAAI,CAAC,EAAE,QAAQ,GAAG,SAAS,CAAA;IAC3B,0DAA0D;IAC1D,KAAK,CAAC,EAAE,kBAAkB,EAAE,GAAG,SAAS,CAAA;IACxC;;;;;;OAMG;IACH,EAAE,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IACvB;;;;;;;;;;OAUG;IACH,IAAI,CAAC,EAAE,OAAO,GAAG;QAAE,OAAO,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,SAAS,CAAA;IAClD;;;OAGG;IACH,OAAO,CAAC,EAAE,CAAC,MAAM,IAAI,CAAC,GAAG,SAAS,CAAA;IAClC;;;OAGG;IACH,QAAQ,CAAC,EAAE,CAAC,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC,GAAG,SAAS,CAAA;CACjD;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,aAAa;IACxB,2CAA2C;sBACS,WAAW;IAC/D,wCAAwC;mBACS,WAAW;IAC5D,mDAAmD;mBACF,WAAW;IAC5D,wDAAwD;qBACL,WAAW;IAC9D,uCAAuC;sBACgB,WAAW;IAClE,gEAAgE;sBACpC,WAAW;CAC/B,CAAA;AAEV;;GAEG;AACH,MAAM,MAAM,WAAW,GAAG,MAAM,OAAO,aAAa,CAAA;AAMpD;;;;;;;;GAQG;AACH,wBAAgB,QAAQ,CACtB,YAAY,EAAE,MAAM,EACpB,MAAM,CAAC,EAAE,WAAW,GAAG,WAAW,EAClC,UAAU,CAAC,EAAE,MAAM,IAAI,GACtB,CAAC,cAAc,EAAE,CAAC,MAAM,EAAE,MAAM,GAAG,CAAC,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,CAAC,KAAK,IAAI,CAAC,CA6IzE;AAMD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,SAAS,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EACxD,aAAa,EAAE,CAAC,EAChB,MAAM,CAAC,EAAE,WAAW,GAAG,WAAW,EAClC,UAAU,CAAC,EAAE,MAAM,IAAI,GACtB;IACD;SAAG,CAAC,IAAI,MAAM,CAAC,GAAG,cAAc;KAAE;IAClC,CAAC,MAAM,EAAE,OAAO,CAAC;SAAG,CAAC,IAAI,MAAM,CAAC,GAAG,MAAM,GAAG,CAAC,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,CAAC;KAAE,CAAC,KAAK,IAAI;CACnF,CAgHA"}