coily 0.11.0 → 0.12.1

package/dist/index.d.ts

@@ -1,2 +1,2 @@
-import { a as SpringPosition, c as defineSpring, i as Spring, n as createSpringSystem, o as SpringConfig, r as TickerOptions, s as SpringOptions, t as SpringSystem } from "./system-B_kZMcpg.js";
-export { type Spring, type SpringConfig, type SpringOptions, type SpringPosition, type SpringSystem, type TickerOptions, createSpringSystem, defineSpring };
+import { _ as defineSpring, a as Spring2D, c as Spring2DWithOffset, d as SpringPosition, f as SpringTarget, g as SpringState, h as SpringOptions, i as TickerOptions, l as Vector2, m as SpringConfig, n as SpringSystemOptions, o as Spring2DPosition, p as SpringWithOffset, r as createSpringSystem, s as Spring2DTarget, t as SpringSystem, u as Spring } from "./system-CMaMt_7p.js";
+export { type Spring, type Spring2D, type Spring2DPosition, type Spring2DTarget, type Spring2DWithOffset, type SpringConfig, type SpringOptions, type SpringPosition, type SpringState, type SpringSystem, type SpringSystemOptions, type SpringTarget, type SpringWithOffset, type TickerOptions, type Vector2, createSpringSystem, defineSpring };

package/dist/index.js

@@ -1,2 +1,2 @@
-import { r as defineSpring, t as createSpringSystem } from "./system-Dxxv4ee7.js";
+import { r as defineSpring, t as createSpringSystem } from "./system-BD52hyd8.js";
 export { createSpringSystem, defineSpring };

package/dist/nuxt.d.ts

@@ -1,6 +1,9 @@
 import { NuxtModule } from "@nuxt/schema";
 
 //#region src/vue/nuxt.d.ts
+interface CoilyModuleOptions {
+  debug?: boolean;
+}
 declare const coilyModule: NuxtModule;
 //#endregion
-export { coilyModule as default };
+export { CoilyModuleOptions, coilyModule as default };

package/dist/nuxt.js

@@ -1,11 +1,12 @@
 import { addComponent, addImports, addPluginTemplate, defineNuxtModule } from "@nuxt/kit";
 //#region src/vue/nuxt.ts
-const pluginTemplate = `import { createSpringSystem } from 'coily'
+function getPluginTemplate(options) {
+	return `import { createSpringSystem } from 'coily'
 import { provideSpringSystem } from 'coily/vue'
 
 export default defineNuxtPlugin((nuxtApp) => {
   nuxtApp.hook('app:created', (vueApp) => {
-    const system = createSpringSystem()
+    const system = createSpringSystem(${options.debug ? "{ debug: true }" : ""})
     provideSpringSystem(system, vueApp)
 
     if(import.meta.client) {
@@ -13,25 +14,49 @@ export default defineNuxtPlugin((nuxtApp) => {
     }
   })
 })`;
+}
 const coilyModule = defineNuxtModule({
 	meta: {
 		name: "coily",
 		configKey: "coily"
 	},
-	async setup() {
+	defaults: { debug: false },
+	async setup(_options) {
 		addPluginTemplate({
 			name: "coily",
 			filename: "coily.plugin.mjs",
 			mode: "all",
-			getContents: () => pluginTemplate
+			getContents: () => getPluginTemplate(_options)
 		});
-		addImports([{
-			from: "coily/vue",
-			name: "useSpring"
-		}, {
-			from: "coily",
-			name: "defineSpring"
-		}]);
+		addImports([
+			{
+				from: "coily/vue",
+				name: "useSpring"
+			},
+			{
+				from: "coily/vue",
+				name: "useSpring2D"
+			},
+			{
+				from: "coily/vue",
+				name: "SpringRef",
+				type: true
+			},
+			{
+				from: "coily/vue",
+				name: "SpringRef2D",
+				type: true
+			},
+			{
+				from: "coily",
+				name: "defineSpring"
+			},
+			{
+				from: "coily",
+				name: "SpringConfig",
+				type: true
+			}
+		]);
 		addComponent({
 			name: "SpringValue",
 			filePath: "coily/vue",

package/dist/{system-Dxxv4ee7.js → system-BD52hyd8.js}

@@ -1,6 +1,11 @@
 //#region src/motion-set.ts
 var MotionSet = class {
 	#motions = /* @__PURE__ */ new Set();
+	#debug;
+	#lastSize = 0;
+	constructor(debug = false) {
+		this.#debug = debug;
+	}
 	add(motion) {
 		this.#motions.add(motion);
 	}
@@ -10,7 +15,11 @@ var MotionSet = class {
 	tick(dt) {
 		for (const motion of this.#motions) {
 			motion.tick(dt);
-			if (motion.resting) this.#motions.delete(motion);
+			if (motion.isResting) this.#motions.delete(motion);
+		}
+		if (this.#debug && this.#motions.size !== this.#lastSize) {
+			this.#lastSize = this.#motions.size;
+			console.log(`coily: ${this.#lastSize} active motions`);
 		}
 	}
 };
@@ -25,7 +34,13 @@ function invariant(condition, message) {
 /**
 * Immutable spring configuration.
 */
-var SpringConfig = class {
+var SpringConfig = class SpringConfig {
+	static default = new SpringConfig({
+		dampingRatio: 1,
+		duration: 500
+	});
+	/** @internal Incremented by `SpringConfig.assign` to signal mutations. */
+	#version = 0;
 	mass;
 	tension;
 	damping;
@@ -52,10 +67,10 @@ var SpringConfig = class {
 		if (dampingRatio !== void 0) invariant(dampingRatio >= 0, "Damping ratio must be greater than or equal to 0");
 		if (duration !== void 0) invariant(duration > 0, "Duration must be greater than 0");
 		invariant(displacement !== 0, "Displacement must not be 0");
-		invariant(precision > 0, "Precision must be greater than 0");
+		invariant(precision >= 0, "Precision must be greater than or equal to 0");
 		this.precision = precision;
 		this.precisionMultiplier = 10 ** precision;
-		this.restingMagnitude = 1 / this.precisionMultiplier;
+		this.restingMagnitude = .5 / this.precisionMultiplier;
 		const hasM = mass !== void 0;
 		const hasK = tension !== void 0;
 		const hasC = damping !== void 0;
@@ -80,7 +95,7 @@ var SpringConfig = class {
 			this.tension = tension;
 			this.damping = damping;
 		} else if (hasZ && hasT) {
-			const threshold = this.restingMagnitude;
+			const threshold = .005;
 			const x0 = Math.abs(displacement);
 			invariant(x0 > threshold, "displacement must be greater than the precision threshold");
 			let sigmaCoeff;
@@ -107,6 +122,52 @@ var SpringConfig = class {
 		this.criticalDamping = 2 * this.mass * this.naturalFrequency;
 		this.dampingRatio = this.damping / this.criticalDamping;
 	}
+	static version(config) {
+		return config.#version;
+	}
+	static assign(target, source) {
+		target.#version++;
+		const t = target;
+		t.mass = source.mass;
+		t.tension = source.tension;
+		t.damping = source.damping;
+		t.precision = source.precision;
+		t.naturalFrequency = source.naturalFrequency;
+		t.criticalDamping = source.criticalDamping;
+		t.dampingRatio = source.dampingRatio;
+		t.precisionMultiplier = source.precisionMultiplier;
+		t.restingMagnitude = source.restingMagnitude;
+	}
+	/**
+	* Analytically estimates the time remaining for a spring to come to rest,
+	* given the current displacement and velocity.
+	*
+	* Uses the exponential decay envelope common to all three damping regimes.
+	* The decay rate depends on the regime:
+	* - Underdamped (ζ < 1): σ = ζωₙ
+	* - Critically damped (ζ = 1): σ = ωₙ
+	* - Overdamped (ζ > 1): σ = (ζ - √(ζ²-1))ωₙ  (the slower eigenvalue)
+	*
+	* The effective initial amplitude accounts for both displacement and velocity,
+	* since kinetic energy can convert to additional displacement:
+	*   A₀ = |x₀| + |v₀| / ωₙ
+	*
+	* Settling time: t = ln(A₀ / threshold) / σ, with a 2× safety factor
+	* to account for polynomial terms in the critically damped solution.
+	*
+	* Returns the estimated time in milliseconds.
+	*/
+	computeTimeRemaining(state) {
+		const { position, velocity } = state;
+		const a0 = Math.abs(position) + Math.abs(velocity) / this.naturalFrequency;
+		if (a0 <= this.restingMagnitude) return 0;
+		let sigma;
+		if (this.dampingRatio < 1) sigma = this.dampingRatio * this.naturalFrequency;
+		else if (this.dampingRatio === 1) sigma = this.naturalFrequency;
+		else sigma = (this.dampingRatio - Math.sqrt(this.dampingRatio * this.dampingRatio - 1)) * this.naturalFrequency;
+		if (sigma <= 0) return Infinity;
+		return 2 * Math.log(a0 / this.restingMagnitude) / sigma * 1e3;
+	}
 };
 function defineSpring(input) {
 	return new SpringConfig(input);
@@ -174,9 +235,9 @@ var State = class {
 	set velocity(value) {
 		this.#velocity = value;
 	}
-	/** Uses raw (unrounded) values so resting detection isn't affected by output quantization. */
-	get resting() {
-		return Math.abs(this.#velocity) < this.#config.restingMagnitude && Math.abs(this.#position) < this.#config.restingMagnitude;
+	/** A spring is resting when its rounded position and velocity are both zero. */
+	get isResting() {
+		return this.position === 0 && this.velocity === 0;
 	}
 };
 //#endregion
@@ -280,12 +341,15 @@ var Motion = class {
 	#currentSolver = null;
 	#needsUpdate = false;
 	#needsReset = false;
+	#configVersion = 0;
+	#timeRemaining = 0;
 	#emitter;
 	constructor(config, position, velocity) {
 		this.#config = config;
 		this.#state = new State(config, position, velocity);
 		this.#emitter = new Emitter();
 		this.#updateSolver();
+		this.#timeRemaining = this.#config.computeTimeRemaining(this.#state);
 	}
 	get position() {
 		return this.#state.position;
@@ -293,7 +357,7 @@ var Motion = class {
 	set position(value) {
 		this.#state.position = value;
 		this.#needsReset = true;
-		if (!this.#state.resting) this.#emitter.emit("start");
+		if (!this.#state.isResting) this.#emitter.emit("start");
 	}
 	get velocity() {
 		return this.#state.velocity;
@@ -302,16 +366,26 @@ var Motion = class {
 		this.#state.velocity = value;
 		this.#needsReset = true;
 	}
-	get resting() {
-		return this.#state.resting;
+	get timeRemaining() {
+		return this.#timeRemaining;
+	}
+	get isResting() {
+		return this.#state.isResting;
 	}
 	configure(config) {
 		this.#config = config;
 		this.#state.configure(config);
+		this.#configVersion = SpringConfig.version(config);
 		this.#needsUpdate = true;
 	}
 	tick(dt, emit = true) {
 		invariant(this.#currentSolver, "Cannot tick a disposed motion");
+		if (SpringConfig.version(this.#config) !== this.#configVersion) {
+			this.#state.configure(this.#config);
+			this.#configVersion = SpringConfig.version(this.#config);
+			this.#needsUpdate = true;
+		}
+		const needsTimeRemaining = this.#needsUpdate || this.#needsReset;
 		if (this.#needsUpdate) {
 			this.#updateSolver();
 			this.#needsUpdate = false;
@@ -320,10 +394,15 @@ var Motion = class {
 			this.#currentSolver.configure();
 			this.#needsReset = false;
 		}
+		if (needsTimeRemaining) this.#timeRemaining = this.#config.computeTimeRemaining(this.#state);
 		this.#currentSolver.tick(dt);
+		this.#timeRemaining = Math.max(0, this.#timeRemaining - dt * 1e3);
 		if (emit) {
 			this.#emitter.emit("update");
-			if (this.#state.resting) this.#emitter.emit("stop");
+			if (this.#state.isResting) {
+				this.#timeRemaining = 0;
+				this.#emitter.emit("stop");
+			}
 		}
 	}
 	onUpdate(callback) {
@@ -358,37 +437,69 @@ var Motion = class {
 };
 //#endregion
 //#region src/spring.ts
+function normalizeTarget(target) {
+	if (target instanceof Spring) return {
+		spring: target,
+		offset: 0
+	};
+	if (typeof target === "object" && target !== null && "spring" in target && target.spring instanceof Spring) return {
+		spring: target.spring,
+		offset: target.offset ?? 0
+	};
+	return null;
+}
 var Spring = class {
 	#target;
 	#config;
 	#motion;
 	#motions;
+	#leader = null;
+	#offset = 0;
+	#ownsConfig;
+	#unsubLeader = null;
 	constructor(motions, position, config) {
-		let target;
+		this.#motions = motions;
+		let numericTarget;
 		let value;
+		let normalized = null;
 		if (typeof position === "number") {
-			target = position;
+			numericTarget = position;
 			value = position;
 		} else {
-			target = position.target ?? position.value ?? 0;
-			value = position.value ?? target;
+			normalized = normalizeTarget(position.target);
+			if (normalized) {
+				numericTarget = normalized.spring.#target + normalized.spring.#motion.position + normalized.offset;
+				value = position.value ?? numericTarget;
+			} else {
+				numericTarget = position.target ?? position.value ?? 0;
+				value = position.value ?? numericTarget;
+			}
+		}
+		const hasOverride = config !== void 0;
+		this.#ownsConfig = hasOverride || !normalized;
+		if (normalized && !hasOverride) this.#config = normalized.spring.#config;
+		else this.#config = config ?? SpringConfig.default;
+		this.#target = numericTarget;
+		this.#motion = new Motion(this.#config, value - numericTarget, 0);
+		if (!this.#motion.isResting) this.#motions.add(this.#motion);
+		if (normalized) {
+			this.#leader = normalized.spring;
+			this.#offset = normalized.offset;
+			this.#unsubLeader = normalized.spring.onUpdate(() => {
+				this.#setTarget(this.#leader.#target + this.#leader.#motion.position + this.#offset);
+			});
 		}
-		this.#target = target;
-		this.#config = config;
-		this.#motion = new Motion(config, value - target, 0);
-		this.#motions = motions;
-		if (!this.#motion.resting) this.#motions.add(this.#motion);
 	}
 	get target() {
 		return this.#target;
 	}
 	set target(value) {
-		if (value !== this.#target) {
-			this.#motions.add(this.#motion);
-			const currentValue = this.value;
-			this.#target = value;
-			this.#motion.position = currentValue - this.#target;
-			this.#motion.tick(0);
+		if (typeof value === "number") {
+			this.#unfollow();
+			this.#setTarget(value);
+		} else {
+			const normalized = normalizeTarget(value);
+			this.#follow(normalized.spring, normalized.offset);
 		}
 	}
 	get value() {
@@ -409,6 +520,9 @@ var Spring = class {
 		this.#motions.add(this.#motion);
 		this.#motion.velocity = value;
 	}
+	get config() {
+		return this.#config;
+	}
 	get mass() {
 		return this.#config.mass;
 	}
@@ -424,13 +538,45 @@ var Spring = class {
 	get precision() {
 		return this.#config.precision;
 	}
-	get resting() {
-		return this.#motion.resting;
+	set config(value) {
+		if (value) {
+			if (this.#leader && !this.#ownsConfig) {
+				this.#ownsConfig = true;
+				this.#config = new SpringConfig({
+					tension: value.tension,
+					damping: value.damping,
+					mass: value.mass,
+					precision: value.precision
+				});
+				this.#motion.configure(this.#config);
+			} else SpringConfig.assign(this.#config, value);
+			this.#motions.add(this.#motion);
+		} else if (this.#ownsConfig) {
+			this.#ownsConfig = false;
+			this.#config = this.#leader ? this.#leader.#config : SpringConfig.default;
+			this.#motion.configure(this.#config);
+			this.#motions.add(this.#motion);
+		}
 	}
-	configure(config) {
-		this.#config = config;
-		this.#motion.configure(config);
-		this.#motions.add(this.#motion);
+	get timeRemaining() {
+		return this.#motion.timeRemaining;
+	}
+	get isResting() {
+		return this.#motion.isResting;
+	}
+	jumpTo(value) {
+		this.#target = value;
+		this.#motion.position = 0;
+		this.#motion.velocity = 0;
+		this.#motion.tick(0);
+	}
+	dispose() {
+		if (this.#unsubLeader) {
+			this.#unsubLeader();
+			this.#unsubLeader = null;
+		}
+		this.#motions.remove(this.#motion);
+		this.#motion.dispose();
 	}
 	onUpdate(callback) {
 		return this.#motion.onUpdate(callback);
@@ -441,15 +587,230 @@ var Spring = class {
 	onStop(callback) {
 		return this.#motion.onStop(callback);
 	}
+	#setTarget(value) {
+		if (value !== this.#target) {
+			this.#motions.add(this.#motion);
+			const rawValue = this.#target + this.#motion.position;
+			this.#target = value;
+			this.#motion.position = rawValue - this.#target;
+			this.#motion.tick(0);
+		}
+	}
+	#follow(leader, offset) {
+		if (this.#unsubLeader) this.#unsubLeader();
+		this.#leader = leader;
+		this.#offset = offset;
+		if (!this.#ownsConfig) {
+			this.#config = leader.#config;
+			this.#motion.configure(this.#config);
+		}
+		this.#unsubLeader = leader.onUpdate(() => {
+			this.#setTarget(this.#leader.#target + this.#leader.#motion.position + this.#offset);
+		});
+		this.#setTarget(leader.#target + leader.#motion.position + offset);
+	}
+	#unfollow() {
+		if (!this.#leader) return;
+		this.#unsubLeader();
+		this.#unsubLeader = null;
+		this.#leader = null;
+		this.#offset = 0;
+		if (!this.#ownsConfig) {
+			this.#ownsConfig = true;
+			this.#config = new SpringConfig({
+				tension: this.#config.tension,
+				damping: this.#config.damping,
+				mass: this.#config.mass,
+				precision: this.#config.precision
+			});
+			this.#motion.configure(this.#config);
+		}
+	}
+};
+//#endregion
+//#region src/vector2.ts
+function isVector2(value) {
+	return typeof value === "object" && value !== null && "x" in value && typeof value.x === "number";
+}
+//#endregion
+//#region src/spring2d.ts
+function normalizeTarget2D(target) {
+	if (target instanceof Spring2D) return {
+		spring: target,
+		offset: void 0
+	};
+	if (typeof target === "object" && target !== null && "spring" in target && target.spring instanceof Spring2D) return {
+		spring: target.spring,
+		offset: target.offset
+	};
+	return null;
+}
+function toScalarTarget(spring, offset) {
+	return offset ? {
+		spring,
+		offset
+	} : spring;
+}
+function toScalarPos(target, value) {
+	if (typeof target === "number") return value !== void 0 ? {
+		target,
+		value
+	} : target;
+	return {
+		target,
+		value
+	};
+}
+var Spring2D = class Spring2D {
+	#x;
+	#y;
+	#value = {
+		x: 0,
+		y: 0
+	};
+	#velocity = {
+		x: 0,
+		y: 0
+	};
+	constructor(motions, position, config) {
+		let xPos;
+		let yPos;
+		if (isVector2(position)) {
+			xPos = position.x;
+			yPos = position.y;
+		} else {
+			const normalized = normalizeTarget2D(position.target);
+			if (normalized) {
+				const lx = normalized.spring.#x;
+				const ly = normalized.spring.#y;
+				const xTarget = toScalarTarget(lx, normalized.offset?.x);
+				const yTarget = toScalarTarget(ly, normalized.offset?.y);
+				xPos = toScalarPos(xTarget, position.value?.x);
+				yPos = toScalarPos(yTarget, position.value?.y);
+			} else if (isVector2(position.target)) {
+				const t = position.target;
+				xPos = {
+					target: t.x,
+					value: position.value?.x
+				};
+				yPos = {
+					target: t.y,
+					value: position.value?.y
+				};
+			} else {
+				xPos = {
+					target: position.target,
+					value: position.value?.x
+				};
+				yPos = {
+					target: void 0,
+					value: position.value?.y
+				};
+			}
+		}
+		this.#x = new Spring(motions, xPos, config);
+		this.#y = new Spring(motions, yPos, config);
+	}
+	get target() {
+		return {
+			x: this.#x.target,
+			y: this.#y.target
+		};
+	}
+	set target(value) {
+		if (value instanceof Spring2D) {
+			this.#x.target = value.#x;
+			this.#y.target = value.#y;
+		} else if ("spring" in value && value.spring instanceof Spring2D) {
+			const { spring, offset } = value;
+			this.#x.target = toScalarTarget(spring.#x, offset?.x);
+			this.#y.target = toScalarTarget(spring.#y, offset?.y);
+		} else {
+			const v = value;
+			this.#x.target = v.x;
+			this.#y.target = v.y;
+		}
+	}
+	get value() {
+		this.#value.x = this.#x.value;
+		this.#value.y = this.#y.value;
+		return this.#value;
+	}
+	set value(value) {
+		this.#x.value = value.x;
+		this.#y.value = value.y;
+	}
+	get velocity() {
+		this.#velocity.x = this.#x.velocity;
+		this.#velocity.y = this.#y.velocity;
+		return this.#velocity;
+	}
+	set velocity(value) {
+		this.#x.velocity = value.x;
+		this.#y.velocity = value.y;
+	}
+	get config() {
+		return this.#x.config;
+	}
+	get mass() {
+		return this.#x.mass;
+	}
+	get tension() {
+		return this.#x.tension;
+	}
+	get damping() {
+		return this.#x.damping;
+	}
+	get dampingRatio() {
+		return this.#x.dampingRatio;
+	}
+	get precision() {
+		return this.#x.precision;
+	}
+	set config(value) {
+		this.#x.config = value;
+		this.#y.config = value;
+	}
+	get timeRemaining() {
+		return Math.max(this.#x.timeRemaining, this.#y.timeRemaining);
+	}
+	get isResting() {
+		return this.#x.isResting && this.#y.isResting;
+	}
 	jumpTo(value) {
-		this.#target = value;
-		this.#motion.position = 0;
-		this.#motion.velocity = 0;
-		this.#motion.tick(0);
+		this.#x.jumpTo(value.x);
+		this.#y.jumpTo(value.y);
 	}
 	dispose() {
-		this.#motions.remove(this.#motion);
-		this.#motion.dispose();
+		this.#x.dispose();
+		this.#y.dispose();
+	}
+	onUpdate(callback) {
+		const a = this.#x.onUpdate(callback);
+		const b = this.#y.onUpdate(callback);
+		return () => {
+			a();
+			b();
+		};
+	}
+	onStart(callback) {
+		const a = this.#x.onStart(callback);
+		const b = this.#y.onStart(callback);
+		return () => {
+			a();
+			b();
+		};
+	}
+	onStop(callback) {
+		const check = () => {
+			if (this.isResting) callback();
+		};
+		const a = this.#x.onStop(check);
+		const b = this.#y.onStop(check);
+		return () => {
+			a();
+			b();
+		};
 	}
 };
 //#endregion
@@ -570,12 +931,15 @@ var SpringSystemImpl = class {
 	#motion;
 	#ticker;
 	constructor(options) {
-		this.#motion = new MotionSet();
+		this.#motion = new MotionSet(options?.debug);
 		this.#ticker = new Ticker(this.#motion, options);
 	}
 	createSpring(position, config) {
 		return new Spring(this.#motion, position, config);
 	}
+	createSpring2D(position, config) {
+		return new Spring2D(this.#motion, position, config);
+	}
 	advance(dt) {
 		this.#motion.tick(dt / 1e3);
 	}