anim-engine 0.3.2 → 0.5.0

package/dist/animation/create-animation.d.ts

@@ -1,2 +1,14 @@
 import { AnimationOptions, Animation } from '../domain';
+/**
+ * Creates an animation instance that can be played, paused, stopped,
+ * and queried for its current state.
+ *
+ * Accepts either a single tween configuration (from → to over a duration)
+ * or a keyframe animation with multiple keyframes, each with optional
+ * easing and gaps.
+ *
+ * @param options - The animation configuration, either {@link SingleTweenOptions}
+ *   or {@link KeyframeAnimationOptions}.
+ * @returns An {@link Animation} instance for controlling the animation.
+ */
 export declare const createAnimation: (options: AnimationOptions) => Animation;

package/dist/animation/create-animation.js

@@ -1,21 +1,32 @@
 import { resolveEasing } from "../domain/easing.js";
-import { getTicker } from "../domain/ticker.js";
 import { resolveValue } from "../domain/resolve-value.js";
+import { getTicker } from "../ticker/get-ticker.js";
 import { createKeyframeRunner, createTweenRunner } from "./runner.js";
 //#region src/animation/create-animation.ts
 var isKeyframeMode = (options) => {
 	return "keyframes" in options && Array.isArray(options.keyframes);
 };
+/**
+* Creates an animation instance that can be played, paused, stopped,
+* and queried for its current state.
+*
+* Accepts either a single tween configuration (from → to over a duration)
+* or a keyframe animation with multiple keyframes, each with optional
+* easing and gaps.
+*
+* @param options - The animation configuration, either {@link SingleTweenOptions}
+*   or {@link KeyframeAnimationOptions}.
+* @returns An {@link Animation} instance for controlling the animation.
+*/
 var createAnimation = (options) => {
 	if (isKeyframeMode(options)) return createKeyframeAnimation(options);
 	return createSingleTween(options);
 };
-var createSingleTween = ({ onStarted, onUpdate, onProgress, onEnded, from: rawFrom, to: rawTo, durationMs: rawDurationMs, ease: easeName = "inOutSine" }) => {
+var createSingleTween = ({ from: rawFrom, to: rawTo, durationMs: rawDurationMs, ease: easeName = "inOutSine", onStarted, onUpdate, onProgress, onEnded, ticker = getTicker() }) => {
 	let cachedDurationMs = resolveValue(rawDurationMs);
 	let status = "stopped";
 	const hasDynamicProperty = typeof rawFrom === "function" || typeof rawTo === "function" || typeof rawDurationMs === "function";
 	let resolvePromise;
-	const ticker = getTicker();
 	const handleEnded = () => {
 		status = "stopped";
 		ticker.remove(runner);
@@ -41,7 +52,6 @@ var createSingleTween = ({ onStarted, onUpdate, onProgress, onEnded, from: rawFr
 	};
 	runner = buildRunner();
 	const play = () => {
-		if (status === "dead") throw new Error("Cannot play a dead animation");
 		if (hasDynamicProperty) runner = buildRunner();
 		else runner.reset();
 		const promise = new Promise((resolve) => {
@@ -76,11 +86,6 @@ var createSingleTween = ({ onStarted, onUpdate, onProgress, onEnded, from: rawFr
 		resolvePromise?.();
 		resolvePromise = void 0;
 	};
-	const kill = () => {
-		status = "dead";
-		ticker.remove(runner);
-		resolvePromise = void 0;
-	};
 	const setProgress = (value) => {
 		if (status === "playing") pause();
 		runner.evaluate(Math.max(0, Math.min(1, value)));
@@ -91,9 +96,8 @@ var createSingleTween = ({ onStarted, onUpdate, onProgress, onEnded, from: rawFr
 		resume,
 		stop,
 		skipToEnd,
-		kill,
-		get currentValue() {
-			return runner.currentValue;
+		get value() {
+			return runner.value;
 		},
 		get velocity() {
 			return runner.velocity;
@@ -110,7 +114,7 @@ var createSingleTween = ({ onStarted, onUpdate, onProgress, onEnded, from: rawFr
 		}
 	};
 };
-var createKeyframeAnimation = ({ keyframes: rawKeyframes, onStarted, onUpdate, onProgress, onEnded }) => {
+var createKeyframeAnimation = ({ keyframes: rawKeyframes, onStarted, onUpdate, onProgress, onEnded, ticker = getTicker() }) => {
 	const resolveKeyframeGaps = () => {
 		let total = 0;
 		for (let i = 1; i < rawKeyframes.length; i++) total += resolveValue(rawKeyframes[i].gap ?? 0);
@@ -120,7 +124,6 @@ var createKeyframeAnimation = ({ keyframes: rawKeyframes, onStarted, onUpdate, o
 	let status = "stopped";
 	let resolvePromise;
 	const hasDynamicProperty = rawKeyframes.some((kf) => typeof kf.value === "function" || typeof kf.gap === "function");
-	const ticker = getTicker();
 	const handleEnded = () => {
 		status = "stopped";
 		ticker.remove(runner);
@@ -144,7 +147,6 @@ var createKeyframeAnimation = ({ keyframes: rawKeyframes, onStarted, onUpdate, o
 	};
 	runner = buildRunner();
 	const play = () => {
-		if (status === "dead") throw new Error("Cannot play a dead animation");
 		if (hasDynamicProperty) {
 			runner = buildRunner();
 			cachedDurationMs = resolveKeyframeGaps();
@@ -181,11 +183,6 @@ var createKeyframeAnimation = ({ keyframes: rawKeyframes, onStarted, onUpdate, o
 		resolvePromise?.();
 		resolvePromise = void 0;
 	};
-	const kill = () => {
-		status = "dead";
-		ticker.remove(runner);
-		resolvePromise = void 0;
-	};
 	const setProgress = (value) => {
 		if (status === "playing") pause();
 		runner.evaluate(Math.max(0, Math.min(1, value)));
@@ -196,9 +193,8 @@ var createKeyframeAnimation = ({ keyframes: rawKeyframes, onStarted, onUpdate, o
 		resume,
 		stop,
 		skipToEnd,
-		kill,
-		get currentValue() {
-			return runner.currentValue;
+		get value() {
+			return runner.value;
 		},
 		get velocity() {
 			return runner.velocity;

package/dist/animation/create-single-tween.d.ts

@@ -28,8 +28,7 @@ export type Animation = {
     resume: () => void;
     stop: () => void;
     skipToEnd: () => void;
-    kill: () => void;
-    currentValue: number;
+    value: number;
     velocity: number;
     progress: number;
     setProgress: (value: number) => void;

package/dist/animation/index.d.ts

@@ -0,0 +1 @@
+export { createAnimation } from './create-animation';

package/dist/animation/runner.d.ts

@@ -3,7 +3,7 @@ export type Runner = {
     (deltaMs: number): boolean;
     evaluate: (progress: number) => number;
     reset: () => void;
-    currentValue: number;
+    value: number;
     velocity: number;
     progress: number;
     onStarted: (() => void) | undefined;

package/dist/animation/runner.js

@@ -4,13 +4,13 @@ var noOp = () => {};
 var createTweenRunner = ({ from, to, durationMs, easeFn, onStarted, onUpdate = noOp, onProgress = noOp, onEnded }) => {
 	const state = {
 		progress: 0,
-		currentValue: from,
+		value: from,
 		velocity: 0
 	};
 	let runner;
 	const step = (deltaMs) => {
 		const completed = updateTween(state, deltaMs, durationMs, easeFn, from, to);
-		onUpdate(state.currentValue, state.velocity);
+		onUpdate(state.value, state.velocity);
 		onProgress(state.progress);
 		if (completed) onEnded();
 		return completed;
@@ -19,26 +19,26 @@ var createTweenRunner = ({ from, to, durationMs, easeFn, onStarted, onUpdate = n
 		const clamped = Math.max(0, Math.min(1, progress));
 		state.progress = clamped;
 		if (clamped >= 1) {
-			state.currentValue = to;
+			state.value = to;
 			state.velocity = 0;
 		} else {
 			const range = to - from;
-			state.currentValue = from + range * easeFn(clamped);
+			state.value = from + range * easeFn(clamped);
 			state.velocity = 0;
 		}
-		onUpdate(state.currentValue, state.velocity);
-		return state.currentValue;
+		onUpdate(state.value, state.velocity);
+		return state.value;
 	};
 	const reset = () => {
 		state.progress = 0;
-		state.currentValue = from;
+		state.value = from;
 		state.velocity = 0;
 	};
 	runner = step;
 	runner.evaluate = evaluate;
 	runner.reset = reset;
-	Object.defineProperty(runner, "currentValue", {
-		get: () => state.currentValue,
+	Object.defineProperty(runner, "value", {
+		get: () => state.value,
 		configurable: true
 	});
 	Object.defineProperty(runner, "velocity", {
@@ -71,7 +71,7 @@ var createKeyframeRunner = ({ keyframes, onStarted, onUpdate = noOp, onProgress
 	for (let i = 0; i < segments.length; i++) prefixSum.push(prefixSum[i] + segments[i].durationMs);
 	const totalDurationMs = prefixSum[prefixSum.length - 1];
 	const invTotalDuration = totalDurationMs > 0 ? 1 / totalDurationMs : 1;
-	let currentValue = keyframes[0].value;
+	let value = keyframes[0].value;
 	let velocity = 0;
 	let globalProgress = 0;
 	let currentSegmentIndex = 0;
@@ -83,22 +83,22 @@ var createKeyframeRunner = ({ keyframes, onStarted, onUpdate = noOp, onProgress
 		segmentElapsed += deltaMs;
 		segmentProgress += deltaMs / segment.durationMs;
 		if (segmentProgress >= 1) segmentProgress = 1;
-		const previousValue = currentValue;
+		const previousValue = value;
 		const eased = segment.easeFn(segmentProgress);
-		currentValue = segment.from + segment.range * eased;
+		value = segment.from + segment.range * eased;
 		if (segmentProgress >= 1) {
-			currentValue = segment.to;
+			value = segment.to;
 			velocity = 0;
-		} else velocity = (currentValue - previousValue) / (deltaMs / 1e3);
+		} else velocity = (value - previousValue) / (deltaMs / 1e3);
 		const elapsedTotal = prefixSum[currentSegmentIndex] + segmentElapsed;
 		globalProgress = Math.min(elapsedTotal * invTotalDuration, 1);
 		onProgress(globalProgress);
-		onUpdate(currentValue, velocity);
+		onUpdate(value, velocity);
 		if (segmentProgress >= 1) if (currentSegmentIndex < segments.length - 1) {
 			currentSegmentIndex++;
 			segmentElapsed = 0;
 			segmentProgress = 0;
-			currentValue = segments[currentSegmentIndex].from;
+			value = segments[currentSegmentIndex].from;
 			velocity = 0;
 			globalProgress = Math.min(prefixSum[currentSegmentIndex] * invTotalDuration, 1);
 			onProgress(globalProgress);
@@ -125,18 +125,18 @@ var createKeyframeRunner = ({ keyframes, onStarted, onUpdate = noOp, onProgress
 		const segProgress = segDuration > 0 ? (elapsed - segStart) / segDuration : 1;
 		const clampedSegProgress = Math.max(0, Math.min(1, segProgress));
 		const eased = segment.easeFn(clampedSegProgress);
-		currentValue = segment.from + segment.range * eased;
+		value = segment.from + segment.range * eased;
 		velocity = 0;
 		globalProgress = clamped;
 		currentSegmentIndex = segIdx;
 		segmentElapsed = elapsed - segStart;
 		segmentProgress = clampedSegProgress;
-		onUpdate(currentValue, velocity);
+		onUpdate(value, velocity);
 		onProgress(clamped);
-		return currentValue;
+		return value;
 	};
 	const reset = () => {
-		currentValue = keyframes[0].value;
+		value = keyframes[0].value;
 		velocity = 0;
 		globalProgress = 0;
 		currentSegmentIndex = 0;
@@ -146,8 +146,8 @@ var createKeyframeRunner = ({ keyframes, onStarted, onUpdate = noOp, onProgress
 	runner = update;
 	runner.evaluate = evaluate;
 	runner.reset = reset;
-	Object.defineProperty(runner, "currentValue", {
-		get: () => currentValue,
+	Object.defineProperty(runner, "value", {
+		get: () => value,
 		configurable: true
 	});
 	Object.defineProperty(runner, "velocity", {

package/dist/animation/update.d.ts

@@ -1,7 +1,7 @@
 import { EaseFunction } from '../domain';
 export type TweenState = {
     progress: number;
-    currentValue: number;
+    value: number;
     velocity: number;
 };
 /**

package/dist/animation/update.js

@@ -7,15 +7,15 @@
 var updateTween = (state, deltaMs, durationMs, easeFn, from, to) => {
 	const thisFrameProgress = deltaMs / durationMs;
 	state.progress = Math.min(state.progress + thisFrameProgress, 1);
-	const previousValue = state.currentValue;
+	const previousValue = state.value;
 	if (state.progress >= 1) {
-		state.currentValue = to;
+		state.value = to;
 		state.velocity = 0;
 		return true;
 	}
 	const eased = easeFn(state.progress);
-	state.currentValue = from + (to - from) * eased;
-	state.velocity = (state.currentValue - previousValue) / (deltaMs / 1e3);
+	state.value = from + (to - from) * eased;
+	state.velocity = (state.value - previousValue) / (deltaMs / 1e3);
 	return false;
 };
 //#endregion

package/dist/domain/animation.d.ts

@@ -1,40 +1,155 @@
 import { EaseFunction, EaseName } from './easing';
 import { DynamicValue } from './resolve-value';
-export type AnimationStatus = "playing" | "paused" | "stopped" | "dead";
+import { ExternalTicker } from './ticker';
+/**
+ * The status of an animation, which can be "playing", "paused", or "stopped".
+ * - "playing": The animation is currently running.
+ * - "paused": The animation is temporarily halted but can be resumed.
+ * - "stopped": The animation has finished or has been stopped and is available for garbage collection if no external references remain.
+ */
+export type AnimationStatus = "playing" | "paused" | "stopped";
+/**
+ * Options for creating a single tween animation, which interpolates between a starting and ending value over a specified duration with optional easing.
+ */
 export type SingleTweenOptions = {
+    /**
+     * The starting value of the animation. Can be a number or a function that returns a number.
+     */
     from: DynamicValue;
+    /**
+     * The ending value of the animation. Can be a number or a function that returns a number.
+     */
     to: DynamicValue;
+    /**
+     * The duration of the animation in milliseconds. Can be a number or a function that returns a number.
+     */
     durationMs: DynamicValue;
+    /**
+     * The easing function or name to use for the animation.
+     */
     ease?: EaseName | EaseFunction;
+    /**
+     * Callback fired when the animation starts.
+     */
     onStarted?: () => void;
+    /**
+     * Callback fired on each animation update with the current value and velocity.
+     */
     onUpdate?: (value: number, velocity: number) => void;
+    /**
+     * Callback fired on each animation update with the current progress (0 to 1).
+     */
     onProgress?: (progress: number) => void;
+    /**
+     * Callback fired when the animation ends.
+     */
     onEnded?: () => void;
+    /**
+     * Optional external ticker to drive the animation.
+     */
+    ticker?: ExternalTicker;
 };
+/**
+ * Object for describing a single keyframe.
+ */
 export type Keyframe = {
+    /**
+     * The value of the keyframe. Can be a number or a function that returns a number.
+     */
     value: DynamicValue;
+    /**
+     * The easing function or name to use for the keyframe.
+     */
     ease?: EaseName | EaseFunction;
+    /**
+     * The gap before the keyframe in milliseconds. Can be a number or a function that returns a number.
+     */
     gap?: DynamicValue;
 };
+/**
+ * Options for creating a keyframe animation, which consists of multiple keyframes each with their own value, easing, and optional gap.
+ */
 export type KeyframeAnimationOptions = {
+    /**
+     * The keyframes for the animation. Each keyframe defines a value, optional easing, and optional gap in milliseconds.
+     */
     keyframes: Keyframe[];
+    /**
+     * Callback fired when the animation starts.
+     */
     onStarted?: () => void;
+    /**
+     * Callback fired on each animation update with the current value and velocity.
+     */
     onUpdate?: (value: number, velocity: number) => void;
+    /**
+     * Callback fired on each animation update with the current progress (0 to 1).
+     */
     onProgress?: (progress: number) => void;
+    /**
+     * Callback fired when the animation ends.
+     */
     onEnded?: () => void;
+    /**
+     * Optional external ticker to drive the animation.
+     */
+    ticker?: ExternalTicker;
 };
+/**
+ * Options for creating an animation, which can be either a single tween or a keyframe animation type.
+ */
 export type AnimationOptions = SingleTweenOptions | KeyframeAnimationOptions;
+/**
+ * Represents an animation instance that can be controlled and queried for its state.
+ */
 export type Animation = {
+    /**
+     * Plays the animation from the current state and returns a promise that resolves when the animation ends.
+     */
     play: () => Promise<void>;
+    /**
+     * Pauses the animation if it is currently playing.
+     */
     pause: () => void;
+    /**
+     * Resumes the animation if it is currently paused.
+     */
     resume: () => void;
+    /**
+     * Stops the animation and resets its state.
+     */
     stop: () => void;
+    /**
+     * Skips the animation to its end state immediately.
+     */
     skipToEnd: () => void;
-    kill: () => void;
-    currentValue: number;
+    /**
+     * The current value of the animation.
+     */
+    value: number;
+    /**
+     * The current velocity of the animation.
+     */
     velocity: number;
+    /**
+     * The current progress of the animation, represented as a number between 0 and 1.
+     */
     progress: number;
+    /**
+     * Sets the progress of the animation to a specific value between 0 and 1. If the animation is playing, it will be paused.
+     */
     setProgress: (value: number) => void;
+    /**
+     * The current status of the animation, which can be "playing", "paused", or "stopped".
+     * - "playing": The animation is currently running.
+     * - "paused": The animation is temporarily halted but can be resumed.
+     * - "stopped": The animation has finished or has been stopped and is available for garbage collection if no external references remain.
+     */
     status: AnimationStatus;
+    /**
+     * The total duration of the animation in milliseconds. This value is determined by the animation's configuration and keyframes.
+     * For single tween animations, this is the specified duration. For keyframe animations, this is the sum of all keyframe gaps and durations.
+     * Note that if the animation has dynamic values for duration or gaps, this value may change when the animation is played and the dynamic values are read.
+     */
     durationMs: number;
 };

package/dist/domain/color.d.ts

@@ -0,0 +1,14 @@
+/**
+ * A tuple representing an RGBA color with each channel as a float in the range [0, 1].
+ * Ordered as [red, green, blue, alpha].
+ */
+export type RgbaTuple = readonly [number, number, number, number];
+/**
+ * A function that linearly interpolates between two RGBA colors in Oklab color space.
+ *
+ * @param from - The starting color as an RgbaTuple.
+ * @param to - The ending color as an RgbaTuple.
+ * @param progress - A number between 0 and 1 representing the interpolation progress.
+ * @returns The interpolated color as an RgbaTuple.
+ */
+export type LerpRgba = (from: RgbaTuple, to: RgbaTuple, progress: number) => RgbaTuple;

package/dist/domain/easing.d.ts

@@ -1,4 +1,16 @@
+/**
+ * A function that maps a progress value `t` in [0, 1] to an eased output value.
+ * Values outside [0, 1] may be returned for overshooting easings like elastic or back.
+ */
 export type EaseFunction = (t: number) => number;
+/**
+ * Resolves an easing identifier or function into a concrete {@link EaseFunction}.
+ * If a function is passed, it is returned as-is. If a name is passed, the
+ * corresponding built-in easing function is looked up.
+ *
+ * @param ease - An easing name or a custom easing function.
+ * @returns The resolved easing function.
+ */
 export declare const resolveEasing: (ease: EaseName | EaseFunction) => EaseFunction;
 /** All 31 named easing identifiers, ordered by type. */
 export declare const EASE_NAMES: readonly ["linear", "inQuad", "outQuad", "inOutQuad", "inCubic", "outCubic", "inOutCubic", "inQuart", "outQuart", "inOutQuart", "inQuint", "outQuint", "inOutQuint", "inSine", "outSine", "inOutSine", "inExpo", "outExpo", "inOutExpo", "inCirc", "outCirc", "inOutCirc", "inBack", "outBack", "inOutBack", "inElastic", "outElastic", "inOutElastic", "inBounce", "outBounce", "inOutBounce"];

package/dist/domain/easing.js

@@ -1,4 +1,12 @@
 //#region src/domain/easing.ts
+/**
+* Resolves an easing identifier or function into a concrete {@link EaseFunction}.
+* If a function is passed, it is returned as-is. If a name is passed, the
+* corresponding built-in easing function is looked up.
+*
+* @param ease - An easing name or a custom easing function.
+* @returns The resolved easing function.
+*/
 var resolveEasing = (ease) => typeof ease === "function" ? ease : EASING_FUNCTIONS[ease];
 var pow = Math.pow;
 var sqrt = Math.sqrt;
@@ -18,40 +26,6 @@ var bounceOut = (x) => {
 	else if (x < 2.5 / d1) return n1 * (x -= 2.25 / d1) * x + .9375;
 	else return n1 * (x -= 2.625 / d1) * x + .984375;
 };
-/** All 31 named easing identifiers, ordered by type. */
-var EASE_NAMES = [
-	"linear",
-	"inQuad",
-	"outQuad",
-	"inOutQuad",
-	"inCubic",
-	"outCubic",
-	"inOutCubic",
-	"inQuart",
-	"outQuart",
-	"inOutQuart",
-	"inQuint",
-	"outQuint",
-	"inOutQuint",
-	"inSine",
-	"outSine",
-	"inOutSine",
-	"inExpo",
-	"outExpo",
-	"inOutExpo",
-	"inCirc",
-	"outCirc",
-	"inOutCirc",
-	"inBack",
-	"outBack",
-	"inOutBack",
-	"inElastic",
-	"outElastic",
-	"inOutElastic",
-	"inBounce",
-	"outBounce",
-	"inOutBounce"
-];
 var EASING_FUNCTIONS = {
 	linear: (x) => x,
 	inQuad: (x) => x * x,
@@ -152,4 +126,4 @@ var cubicBezier = (p1x, p1y, p2x, p2y) => {
 	};
 };
 //#endregion
-export { EASE_NAMES, EASING_FUNCTIONS, cubicBezier, resolveEasing };
+export { EASING_FUNCTIONS, cubicBezier, resolveEasing };

package/dist/domain/index.d.ts

@@ -1,10 +1,10 @@
 export type { AnimationStatus } from './animation';
-export type { InterpolationStatus, Interpolation } from './interpolation';
+export type { InterpolationStatus, Interpolation, LerpOptions, SmoothDampOptions, SpringOptions, } from './interpolation';
 export type { EaseName, EaseFunction } from './easing';
 export { EASE_NAMES, cubicBezier, EASING_FUNCTIONS, resolveEasing } from './easing';
-export { getTicker } from './ticker';
-export type { Ticker, TickHandler } from './ticker';
+export type { Ticker, TickHandler, ExternalTicker } from './ticker';
 export { resolveValue } from './resolve-value';
 export type { DynamicValue } from './resolve-value';
 export type { Animation, AnimationOptions, SingleTweenOptions, KeyframeAnimationOptions, Keyframe, } from './animation';
-export type { TimelineLayer, Timeline } from './timeline';
+export type { TimelineLayer, Timeline, TimelineCallbacks } from './timeline';
+export type { RgbaTuple, LerpRgba } from './color';