anim-engine 0.1.1

package/dist/ticker/ticker.js

@@ -0,0 +1,74 @@
+//#region src/ticker/ticker.ts
+/**
+* Create a ticker that drives active animations.
+*
+* Does NOT auto-start. The user must explicitly call either:
+* - `start()` — begins a `requestAnimationFrame` loop
+* - `update(deltaMs)` — drive manually from a game loop
+*
+* `add()` and `remove()` register/unregister animations without
+* side effects on the rAF loop.
+*
+* Uses a flat array with undefined-tombstone removal for safe concurrent
+* modification during iteration. Compacted after each frame.
+*/
+var createTicker = () => {
+	const activeAnimations = [];
+	let needsCompact = false;
+	let animationFrameRequestId = void 0;
+	let previousFrameTime = void 0;
+	const start = () => {
+		if (animationFrameRequestId !== void 0) return;
+		previousFrameTime = void 0;
+		const tick = (now) => {
+			if (previousFrameTime !== void 0) {
+				const delta = now - previousFrameTime;
+				update(delta);
+			}
+			previousFrameTime = now;
+			animationFrameRequestId = requestAnimationFrame(tick);
+		};
+		animationFrameRequestId = requestAnimationFrame(tick);
+	};
+	const stop = () => {
+		if (animationFrameRequestId !== void 0) {
+			cancelAnimationFrame(animationFrameRequestId);
+			animationFrameRequestId = void 0;
+		}
+		previousFrameTime = void 0;
+	};
+	const update = (deltaMs) => {
+		for (let i = 0; i < activeAnimations.length; i++) {
+			const anim = activeAnimations[i];
+			if (anim) anim(deltaMs);
+		}
+		if (needsCompact) {
+			let writeIndex = 0;
+			for (let readIndex = 0; readIndex < activeAnimations.length; readIndex++) {
+				const anim = activeAnimations[readIndex];
+				if (anim !== void 0) activeAnimations[writeIndex++] = anim;
+			}
+			activeAnimations.length = writeIndex;
+			needsCompact = false;
+		}
+	};
+	const add = (handler) => {
+		activeAnimations.push(handler);
+	};
+	const remove = (handler) => {
+		const index = activeAnimations.indexOf(handler);
+		if (index >= 0) {
+			activeAnimations[index] = void 0;
+			needsCompact = true;
+		}
+	};
+	return {
+		start,
+		stop,
+		update,
+		add,
+		remove
+	};
+};
+//#endregion
+export { createTicker };

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

@@ -0,0 +1,25 @@
+import { Animation, AnimationStatus } from '../shared/types';
+export type TimelineLayer = {
+    at: number;
+    animation: Animation | Animation[];
+} | {
+    gap: number;
+    animation: Animation | Animation[];
+};
+export type Timeline = {
+    play: () => Promise<Timeline>;
+    pause: () => void;
+    resume: () => void;
+    stop: () => void;
+    skipToEnd: () => void;
+    kill: () => void;
+    setProgress: (value: number) => void;
+    progress: number;
+    status: AnimationStatus;
+    durationMs: number;
+};
+export declare const createTimeline: (layers: TimelineLayer[], options?: {
+    onStarted?: () => void;
+    onProgress?: (progress: number) => void;
+    onEnded?: () => void;
+}) => Timeline;

package/dist/timeline/create-timeline.js

@@ -0,0 +1,139 @@
+import { getTicker } from "../ticker/get-ticker.js";
+//#region src/timeline/create-timeline.ts
+var createTimeline = (layers, options) => {
+	const { onStarted, onProgress, onEnded } = options ?? {};
+	const batches = [];
+	let lastBatchEnd = 0;
+	for (const layer of layers) {
+		const anims = Array.isArray(layer.animation) ? layer.animation : [layer.animation];
+		const startAt = "at" in layer ? layer.at : lastBatchEnd + layer.gap;
+		const endAt = startAt + Math.max(...anims.map((a) => a.durationMs));
+		batches.push({
+			animations: anims,
+			startAt,
+			endAt,
+			started: false
+		});
+		lastBatchEnd = endAt;
+	}
+	batches.sort((a, b) => a.startAt - b.startAt);
+	const totalDurationMs = Math.max(0, ...batches.map((b) => b.endAt));
+	let status = "stopped";
+	let elapsedMs = 0;
+	let resolvePromise;
+	let pendingAnimations = 0;
+	const ticker = getTicker();
+	const play = () => {
+		if (status === "dead") throw new Error("Cannot play a dead timeline");
+		elapsedMs = 0;
+		pendingAnimations = 0;
+		batches.forEach((b) => {
+			b.started = false;
+		});
+		const promise = new Promise((resolve) => {
+			resolvePromise = resolve;
+		});
+		status = "playing";
+		onStarted?.();
+		ticker.add(update);
+		return promise;
+	};
+	const pause = () => {
+		if (status !== "playing") return;
+		status = "paused";
+		ticker.remove(update);
+		for (const batch of batches) if (batch.started) {
+			for (const anim of batch.animations) if (anim.status === "playing") anim.pause();
+		}
+	};
+	const resume = () => {
+		if (status !== "paused") return;
+		status = "playing";
+		for (const batch of batches) if (batch.started) {
+			for (const anim of batch.animations) if (anim.status === "paused") anim.resume();
+		}
+		ticker.add(update);
+	};
+	const stop = () => {
+		if (status !== "playing" && status !== "paused") return;
+		status = "stopped";
+		ticker.remove(update);
+		for (const batch of batches) if (batch.started) for (const anim of batch.animations) anim.stop();
+		resolvePromise?.(timeline);
+		resolvePromise = void 0;
+	};
+	const skipToEnd = () => {
+		status = "stopped";
+		ticker.remove(update);
+		for (const batch of batches) for (const anim of batch.animations) anim.skipToEnd();
+		onEnded?.();
+		resolvePromise?.(timeline);
+		resolvePromise = void 0;
+	};
+	const kill = () => {
+		status = "dead";
+		ticker.remove(update);
+		for (const batch of batches) for (const anim of batch.animations) anim.kill();
+		resolvePromise = void 0;
+	};
+	const update = (deltaMs) => {
+		if (status !== "playing") return;
+		elapsedMs += deltaMs;
+		for (const batch of batches) if (!batch.started && elapsedMs >= batch.startAt) {
+			batch.started = true;
+			pendingAnimations += batch.animations.length;
+			for (const anim of batch.animations) anim.play().then(() => {
+				pendingAnimations--;
+				checkComplete();
+			});
+		}
+		onProgress?.(totalDurationMs > 0 ? Math.min(elapsedMs / totalDurationMs, 1) : 0);
+		if (batches.every((b) => b.started) && pendingAnimations <= 0) finish();
+	};
+	const checkComplete = () => {
+		if (pendingAnimations <= 0 && status === "playing" && batches.every((b) => b.started)) finish();
+	};
+	const finish = () => {
+		status = "stopped";
+		ticker.remove(update);
+		onEnded?.();
+		resolvePromise?.(timeline);
+		resolvePromise = void 0;
+	};
+	const setProgress = (value) => {
+		if (status === "playing") pause();
+		elapsedMs = Math.max(0, Math.min(1, value)) * totalDurationMs;
+		for (const batch of batches) if (elapsedMs < batch.startAt) {
+			for (const anim of batch.animations) anim.setProgress(0);
+			batch.started = false;
+		} else {
+			batch.started = true;
+			const batchElapsed = elapsedMs - batch.startAt;
+			for (const anim of batch.animations) {
+				const localProgress = anim.durationMs > 0 ? Math.min(batchElapsed / anim.durationMs, 1) : 1;
+				anim.setProgress(localProgress);
+			}
+		}
+	};
+	const timeline = {
+		play,
+		pause,
+		resume,
+		stop,
+		skipToEnd,
+		kill,
+		setProgress,
+		get progress() {
+			return totalDurationMs > 0 ? Math.min(elapsedMs / totalDurationMs, 1) : 0;
+		},
+		get status() {
+			return status;
+		},
+		get durationMs() {
+			return totalDurationMs;
+		}
+	};
+	return timeline;
+};
+//#endregion
+export { createTimeline };

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "anim-engine",
+  "version": "0.1.1",
+  "private": false,
+  "description": "JavaScript library for animating numbers",
+  "license": "MIT",
+  "repository": "https://github.com/LukeCarlThompson/anim-engine",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE.txt"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "dev": "npm run lint && npm run test:watch && vite",
+    "build": "npm run lint && npm run test && tsc && vite build",
+    "preview": "vite preview",
+    "check:types": "tsc --noEmit",
+    "lint": "oxlint -c .oxlintrc.json src/",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "storybook": "storybook dev -p 6006",
+    "build-storybook": "npm run lint && npm run test && storybook build",
+    "prepublishOnly": "npm run build",
+    "bench": "vitest bench src/benchmarks/ --run",
+    "bench:baseline": "vitest bench src/benchmarks/ --run --outputJson baselines/benchmark.json",
+    "format": "oxfmt src/",
+    "format:check": "oxfmt --check src/",
+    "fmt": "oxfmt src/"
+  },
+  "devDependencies": {
+    "@storybook/addon-docs": "10.4.6",
+    "@storybook/html": "10.4.6",
+    "@storybook/html-vite": "10.4.6",
+    "gsap": "3.15.0",
+    "oxfmt": "0.57.0",
+    "oxlint": "1.72.0",
+    "storybook": "10.4.6",
+    "typescript": "6.0.3",
+    "vite": "8.1.3",
+    "vite-plugin-dts": "5.0.3",
+    "vitest": "4.1.9"
+  }
+}