coily 0.11.0 → 0.12.0

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-Do5rE0j7.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-DPaqec-Z.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-DPaqec-Z.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,10 @@ function invariant(condition, message) {
 /**
 * Immutable spring configuration.
 */
+let globalConfigVersion = 0;
 var SpringConfig = class {
+	/** @internal Incremented by `SpringConfig.assign` to signal mutations. */
+	#version = 0;
 	mass;
 	tension;
 	damping;
@@ -52,10 +64,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 +92,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 +119,56 @@ var SpringConfig = class {
 		this.criticalDamping = 2 * this.mass * this.naturalFrequency;
 		this.dampingRatio = this.damping / this.criticalDamping;
 	}
+	static get globalVersion() {
+		return globalConfigVersion;
+	}
+	static version(config) {
+		return config.#version;
+	}
+	static assign(target, source) {
+		globalConfigVersion++;
+		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 +236,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 +342,16 @@ var Motion = class {
 	#currentSolver = null;
 	#needsUpdate = false;
 	#needsReset = false;
+	#configVersion = 0;
+	#globalConfigVersion = 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 +359,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 +368,31 @@ 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.#globalConfigVersion = SpringConfig.globalVersion;
 		this.#needsUpdate = true;
 	}
 	tick(dt, emit = true) {
 		invariant(this.#currentSolver, "Cannot tick a disposed motion");
+		const gv = SpringConfig.globalVersion;
+		if (gv !== this.#globalConfigVersion) {
+			this.#globalConfigVersion = gv;
+			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 +401,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 +444,69 @@ var Motion = class {
 };
 //#endregion
 //#region src/spring.ts
-var Spring = class {
+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 Spring {
 	#target;
 	#config;
 	#motion;
 	#motions;
+	#leader = null;
+	#offset = 0;
+	#hasConfigOverride;
+	#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 = Spring.#rawValue(normalized.spring) + normalized.offset;
+				value = position.value ?? numericTarget;
+			} else {
+				numericTarget = position.target ?? position.value ?? 0;
+				value = position.value ?? numericTarget;
+			}
+		}
+		const hasOverride = config !== void 0;
+		this.#hasConfigOverride = hasOverride || !normalized;
+		if (normalized && !hasOverride) this.#config = normalized.spring.#config;
+		else this.#config = config;
+		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(Spring.#rawValue(this.#leader) + 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 +527,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,22 +545,32 @@ var Spring = class {
 	get precision() {
 		return this.#config.precision;
 	}
-	get resting() {
-		return this.#motion.resting;
-	}
 	configure(config) {
-		this.#config = config;
-		this.#motion.configure(config);
+		if (this.#leader && !this.#hasConfigOverride) {
+			this.#hasConfigOverride = true;
+			this.#config = new SpringConfig({
+				tension: config.tension,
+				damping: config.damping,
+				mass: config.mass,
+				precision: config.precision
+			});
+			this.#motion.configure(this.#config);
+		} else SpringConfig.assign(this.#config, config);
 		this.#motions.add(this.#motion);
 	}
-	onUpdate(callback) {
-		return this.#motion.onUpdate(callback);
+	clearConfigOverride() {
+		if (this.#leader && this.#hasConfigOverride) {
+			this.#hasConfigOverride = false;
+			this.#config = this.#leader.#config;
+			this.#motion.configure(this.#config);
+			this.#motions.add(this.#motion);
+		}
 	}
-	onStart(callback) {
-		return this.#motion.onStart(callback);
+	get timeRemaining() {
+		return this.#motion.timeRemaining;
 	}
-	onStop(callback) {
-		return this.#motion.onStop(callback);
+	get isResting() {
+		return this.#motion.isResting;
 	}
 	jumpTo(value) {
 		this.#target = value;
@@ -448,9 +579,254 @@ var Spring = class {
 		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);
+	}
+	onStart(callback) {
+		return this.#motion.onStart(callback);
+	}
+	onStop(callback) {
+		return this.#motion.onStop(callback);
+	}
+	static #rawValue(spring) {
+		return spring.#target + spring.#motion.position;
+	}
+	#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.#hasConfigOverride) {
+			this.#config = leader.#config;
+			this.#motion.configure(this.#config);
+		}
+		this.#unsubLeader = leader.onUpdate(() => {
+			this.#setTarget(Spring.#rawValue(this.#leader) + this.#offset);
+		});
+		this.#setTarget(Spring.#rawValue(leader) + offset);
+	}
+	#unfollow() {
+		if (!this.#leader) return;
+		this.#unsubLeader();
+		this.#unsubLeader = null;
+		this.#leader = null;
+		this.#offset = 0;
+		if (!this.#hasConfigOverride) {
+			this.#hasConfigOverride = 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;
+	}
+	configure(config) {
+		this.#x.configure(config);
+		this.#y.configure(config);
+	}
+	clearConfigOverride() {
+		this.#x.clearConfigOverride();
+		this.#y.clearConfigOverride();
+	}
+	get timeRemaining() {
+		return Math.max(this.#x.timeRemaining, this.#y.timeRemaining);
+	}
+	get isResting() {
+		return this.#x.isResting && this.#y.isResting;
+	}
+	jumpTo(value) {
+		this.#x.jumpTo(value.x);
+		this.#y.jumpTo(value.y);
+	}
+	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
 //#region src/ticker.ts
@@ -570,12 +946,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);
 	}