coily 0.12.2 → 0.14.0

package/dist/vue.js

@@ -1,46 +1,79 @@
-import { n as SpringConfig, t as createSpringSystem } from "./system-Bzrx4uso.js";
-import { computed, customRef, defineComponent, getCurrentScope, inject, onBeforeUnmount, onMounted, onScopeDispose, provide, toRefs, toValue, watchSyncEffect } from "vue";
+import { a as SpringDefinition, n as SpringSourceSymbol, r as isSpringSource, t as createSpringSystem } from "./system-BXxAHM2a.js";
+import { computed, customRef, defineComponent, getCurrentInstance, getCurrentScope, inject, onBeforeUnmount, onMounted, onScopeDispose, provide, toRefs, toValue, watchSyncEffect } from "vue";
+//#region src/vue/local.ts
+const localProvides = /* @__PURE__ */ new WeakMap();
+function provideLocal(key, value) {
+	const instance = getCurrentInstance();
+	if (instance) {
+		let values = localProvides.get(instance);
+		if (!values) {
+			values = /* @__PURE__ */ new Map();
+			localProvides.set(instance, values);
+		}
+		values.set(key, value);
+	}
+	provide(key, value);
+}
+function injectLocal(key) {
+	const instance = getCurrentInstance();
+	if (instance) {
+		const values = localProvides.get(instance);
+		if (values?.has(key)) return values.get(key);
+	}
+	return inject(key, void 0);
+}
+//#endregion
 //#region src/vue/system.ts
 const SpringSystemKey = Symbol.for("coily/spring-system");
+/**
+* Supplies a spring system you created and manage yourself — coily never
+* starts or stops it. With `app`, the system is installed app-wide
+* (what the Nuxt module does); without, it is provided to the current
+* component and its descendants, including this component's own
+* `useSpring` calls. Mostly useful in tests.
+*/
 function provideSpringSystem(system, app) {
 	if (app) app.provide(SpringSystemKey, system);
-	else provide(SpringSystemKey, system);
+	else provideLocal(SpringSystemKey, system);
 }
+/**
+* Returns the spring system provided by this component or an ancestor,
+* creating one when none exists. A created system is provided to this
+* component and its descendants and started/stopped with the component's
+* mount lifecycle.
+*
+* Idempotent: call it near the root and again in any descendant.
+* `options` only applies when the call actually creates a system.
+* Throws outside `setup()`.
+*/
 function useSpringSystem(options) {
+	if (!getCurrentInstance()) throw new Error("useSpringSystem must be called inside setup()");
+	const existing = injectLocal(SpringSystemKey);
+	if (existing) return existing;
 	const system = createSpringSystem(options);
-	provideSpringSystem(system);
-	onMounted(() => {
-		system.start();
-	});
-	onBeforeUnmount(() => {
-		system.stop();
-	});
+	provideLocal(SpringSystemKey, system);
+	onMounted(() => system.start());
+	onBeforeUnmount(() => system.stop());
+	return system;
 }
 //#endregion
-//#region src/vue/spring.ts
-/** @internal Symbol to access the underlying Spring from a SpringRef */
-const SpringInstanceKey = Symbol("spring");
-function hasSpringInstance(value) {
-	return typeof value === "object" && value !== null && SpringInstanceKey in value;
-}
-function useSpring(target, options) {
-	if (Array.isArray(target)) return Array.from(target, (t) => createSpringRef(t, options));
-	if (hasSpringInstance(target)) return createLinkedSpringRef(target, options);
-	return createSpringRef(target, options);
+//#region src/vue/reactive-spring.ts
+const divergentRef = customRef;
+function injectSpringSystem() {
+	const system = injectLocal(SpringSystemKey);
+	if (!system) throw new Error("No SpringSystem found — install the coily/nuxt module or call useSpringSystem() in an ancestor component");
+	return system;
 }
-function createSpringRef(target, options) {
-	const system = inject(SpringSystemKey);
-	if (!system) throw new Error("No SpringSystem found");
-	const config = computed(() => {
-		const opts = toValue(options);
-		if (opts instanceof SpringConfig) return opts;
-		return opts ? new SpringConfig(opts) : void 0;
+function resolveSpringConfig(config) {
+	return computed(() => {
+		const resolved = toValue(config);
+		if (resolved instanceof SpringDefinition) return resolved;
+		return resolved ? new SpringDefinition(resolved) : void 0;
 	});
-	const spring = system.createSpring(toValue(target), config.value ?? void 0);
+}
+function createReactiveSpringRef(spring, config, instanceKey) {
 	watchSyncEffect(() => {
-		const c = config.value;
-		if (c) spring.config = c;
-		else spring.config = null;
+		spring.config = config.value ?? null;
 	});
 	let triggerValue;
 	let triggerVelocity;
@@ -50,25 +83,25 @@ function createSpringRef(target, options) {
 		triggerVelocity?.();
 		triggerTimeRemaining?.();
 	});
-	const value = customRef((track, trigger) => ({
+	const value = divergentRef((track, trigger) => ({
 		get() {
 			triggerValue ??= trigger;
 			track();
 			return spring.value;
 		},
-		set(value) {
-			spring.value = value;
+		set(next) {
+			spring.value = next;
 			trigger();
 		}
 	}));
-	const velocity = customRef((track, trigger) => ({
+	const velocity = divergentRef((track, trigger) => ({
 		get() {
 			triggerVelocity ??= trigger;
 			track();
 			return spring.velocity;
 		},
-		set(value) {
-			spring.velocity = value;
+		set(next) {
+			spring.velocity = next;
 			trigger();
 		}
 	}));
@@ -91,262 +124,121 @@ function createSpringRef(target, options) {
 			set() {}
 		};
 	});
-	watchSyncEffect(() => {
-		spring.target = toValue(target);
-	});
 	if (getCurrentScope()) onScopeDispose(() => spring.dispose());
 	const ref = Object.assign(value, {
 		velocity,
 		timeRemaining,
 		isResting,
-		jumpTo: (value) => spring.jumpTo(value)
+		jumpTo: (next) => spring.jumpTo(next)
 	});
-	Object.defineProperty(ref, SpringInstanceKey, { value: spring });
+	Object.defineProperty(ref, "settled", { get: () => spring.settled });
+	Object.defineProperty(ref, instanceKey, { value: spring });
+	Object.defineProperty(ref, SpringSourceSymbol, { value: spring[SpringSourceSymbol] });
 	return ref;
 }
-function createLinkedSpringRef(leaderRef, options) {
-	const system = inject(SpringSystemKey);
-	if (!system) throw new Error("No SpringSystem found");
-	const leaderSpring = leaderRef[SpringInstanceKey];
-	const config = computed(() => {
-		const opts = toValue(options);
-		if (!opts) return void 0;
-		if (opts instanceof SpringConfig) return opts;
-		return new SpringConfig(opts);
-	});
-	const spring = system.createSpring({ target: leaderSpring }, config.value);
+//#endregion
+//#region src/vue/composite-spring.ts
+const CompositeSpringInstanceKey = Symbol("composite-spring");
+function hasCompositeSpringInstance(value) {
+	return typeof value === "object" && value !== null && CompositeSpringInstanceKey in value;
+}
+function resolveConfigShape(config) {
+	return computed(() => toValue(config));
+}
+function createCompositeSpringRef(value, config, options) {
+	const system = injectSpringSystem();
+	const resolvedConfig = resolveConfigShape(config);
+	const spring = system.createSpring(toValue(value), resolvedConfig.value, options);
+	const ref = createReactiveSpringRef(spring, resolvedConfig, CompositeSpringInstanceKey);
 	watchSyncEffect(() => {
-		const c = config.value;
-		if (c) spring.config = c;
-		else spring.config = null;
-	});
-	let triggerValue;
-	let triggerVelocity;
-	let triggerTimeRemaining;
-	spring.onUpdate(() => {
-		triggerValue?.();
-		triggerVelocity?.();
-		triggerTimeRemaining?.();
-	});
-	const value = customRef((track, trigger) => ({
-		get() {
-			triggerValue ??= trigger;
-			track();
-			return spring.value;
-		},
-		set(value) {
-			spring.value = value;
-			trigger();
-		}
-	}));
-	const velocity = customRef((track, trigger) => ({
-		get() {
-			triggerVelocity ??= trigger;
-			track();
-			return spring.velocity;
-		},
-		set(value) {
-			spring.velocity = value;
-			trigger();
-		}
-	}));
-	const timeRemaining = customRef((track, trigger) => ({
-		get() {
-			triggerTimeRemaining ??= trigger;
-			track();
-			return spring.timeRemaining;
-		},
-		set() {}
-	}));
-	const isResting = customRef((track, trigger) => {
-		spring.onStart(trigger);
-		spring.onStop(trigger);
-		return {
-			get() {
-				track();
-				return spring.isResting;
-			},
-			set() {}
-		};
-	});
-	if (getCurrentScope()) onScopeDispose(() => spring.dispose());
-	const ref = Object.assign(value, {
-		velocity,
-		timeRemaining,
-		isResting,
-		jumpTo: (value) => spring.jumpTo(value)
+		spring.target = toValue(value);
 	});
-	Object.defineProperty(ref, SpringInstanceKey, { value: spring });
 	return ref;
 }
+function createLinkedCompositeSpringRef(leaderRef, config, options) {
+	const system = injectSpringSystem();
+	const leader = leaderRef[CompositeSpringInstanceKey];
+	const resolvedConfig = resolveConfigShape(config);
+	const spring = system.createSpring(leader.value, resolvedConfig.value, options);
+	spring.target = leader;
+	return createReactiveSpringRef(spring, resolvedConfig, CompositeSpringInstanceKey);
+}
 //#endregion
-//#region src/vue/spring2d.ts
-/** @internal Symbol to access the underlying Spring2D from a SpringRef2D */
-const Spring2DInstanceKey = Symbol("spring2d");
-function hasSpring2DInstance(value) {
-	return typeof value === "object" && value !== null && Spring2DInstanceKey in value;
+//#region src/vue/spring.ts
+const SpringInstanceKey = Symbol("spring");
+function hasSpringInstance(value) {
+	return typeof value === "object" && value !== null && SpringInstanceKey in value;
 }
-function useSpring2D(target, options) {
-	if (Array.isArray(target)) return Array.from(target, (t) => createSpringRef2D(t, options));
-	if (hasSpring2DInstance(target)) return createLinkedSpringRef2D(target, options);
-	return createSpringRef2D(target, options);
+function useSpring(target, config, options) {
+	if (hasSpringInstance(target)) return createLinkedSpringRef(target, config, options);
+	if (hasCompositeSpringInstance(target)) return createLinkedCompositeSpringRef(target, config, options);
+	const resolved = toValue(target);
+	if (typeof resolved === "number" || isSpringSource(resolved)) return createSpringRef(target, config, options);
+	return createCompositeSpringRef(target, config, options);
 }
-function createSpringRef2D(target, options) {
-	const system = inject(SpringSystemKey);
-	if (!system) throw new Error("No SpringSystem found");
-	const config = computed(() => {
-		const opts = toValue(options);
-		if (opts instanceof SpringConfig) return opts;
-		return opts ? new SpringConfig(opts) : void 0;
-	});
-	const spring = system.createSpring2D(toValue(target), config.value ?? void 0);
-	watchSyncEffect(() => {
-		const c = config.value;
-		if (c) spring.config = c;
-		else spring.config = null;
-	});
-	let triggerValue;
-	let triggerVelocity;
-	let triggerTimeRemaining;
-	spring.onUpdate(() => {
-		triggerValue?.();
-		triggerVelocity?.();
-		triggerTimeRemaining?.();
-	});
-	const value = customRef((track, trigger) => ({
-		get() {
-			triggerValue ??= trigger;
-			track();
-			return spring.value;
-		},
-		set(value) {
-			spring.value = value;
-			trigger();
-		}
-	}));
-	const velocity = customRef((track, trigger) => ({
-		get() {
-			triggerVelocity ??= trigger;
-			track();
-			return spring.velocity;
-		},
-		set(value) {
-			spring.velocity = value;
-			trigger();
-		}
-	}));
-	const timeRemaining = customRef((track, trigger) => ({
-		get() {
-			triggerTimeRemaining ??= trigger;
-			track();
-			return spring.timeRemaining;
-		},
-		set() {}
-	}));
-	const isResting = customRef((track, trigger) => {
-		spring.onStart(trigger);
-		spring.onStop(trigger);
-		return {
-			get() {
-				track();
-				return spring.isResting;
-			},
-			set() {}
-		};
-	});
+function createSpringRef(target, config, options) {
+	const system = injectSpringSystem();
+	const resolvedConfig = resolveSpringConfig(config);
+	const initial = toValue(target);
+	const spring = system.createSpring(typeof initial === "number" ? initial : initial[SpringSourceSymbol].value, resolvedConfig.value, options);
+	const ref = createReactiveSpringRef(spring, resolvedConfig, SpringInstanceKey);
 	watchSyncEffect(() => {
 		spring.target = toValue(target);
 	});
-	if (getCurrentScope()) onScopeDispose(() => spring.dispose());
-	const ref = Object.assign(value, {
-		velocity,
-		timeRemaining,
-		isResting,
-		jumpTo: (value) => spring.jumpTo(value)
-	});
-	Object.defineProperty(ref, Spring2DInstanceKey, { value: spring });
 	return ref;
 }
-function createLinkedSpringRef2D(leaderRef, options) {
-	const system = inject(SpringSystemKey);
-	if (!system) throw new Error("No SpringSystem found");
-	const leaderSpring = leaderRef[Spring2DInstanceKey];
-	const config = computed(() => {
-		const opts = toValue(options);
-		if (!opts) return void 0;
-		if (opts instanceof SpringConfig) return opts;
-		return new SpringConfig(opts);
-	});
-	const spring = system.createSpring2D({ target: leaderSpring }, config.value);
-	watchSyncEffect(() => {
-		const c = config.value;
-		if (c) spring.config = c;
-		else spring.config = null;
-	});
-	let triggerValue;
-	let triggerVelocity;
-	let triggerTimeRemaining;
-	spring.onUpdate(() => {
-		triggerValue?.();
-		triggerVelocity?.();
-		triggerTimeRemaining?.();
-	});
-	const value = customRef((track, trigger) => ({
-		get() {
-			triggerValue ??= trigger;
-			track();
-			return spring.value;
-		},
-		set(value) {
-			spring.value = value;
-			trigger();
-		}
-	}));
-	const velocity = customRef((track, trigger) => ({
-		get() {
-			triggerVelocity ??= trigger;
-			track();
-			return spring.velocity;
-		},
-		set(value) {
-			spring.velocity = value;
-			trigger();
-		}
-	}));
-	const timeRemaining = customRef((track, trigger) => ({
-		get() {
-			triggerTimeRemaining ??= trigger;
-			track();
-			return spring.timeRemaining;
-		},
-		set() {}
-	}));
-	const isResting = customRef((track, trigger) => {
-		spring.onStart(trigger);
-		spring.onStop(trigger);
-		return {
-			get() {
-				track();
-				return spring.isResting;
-			},
-			set() {}
-		};
-	});
-	if (getCurrentScope()) onScopeDispose(() => spring.dispose());
-	const ref = Object.assign(value, {
-		velocity,
-		timeRemaining,
-		isResting,
-		jumpTo: (value) => spring.jumpTo(value)
-	});
-	Object.defineProperty(ref, Spring2DInstanceKey, { value: spring });
-	return ref;
+function createLinkedSpringRef(leaderRef, config, options) {
+	const system = injectSpringSystem();
+	const leader = leaderRef[SpringInstanceKey];
+	const resolvedConfig = resolveSpringConfig(config);
+	return createReactiveSpringRef(system.createSpring(leader, resolvedConfig.value, options), resolvedConfig, SpringInstanceKey);
+}
+//#endregion
+//#region src/vue/pool.ts
+/**
+* Returns spring factories bound to the provided spring system, with
+* lifetimes tied to the current effect scope: every pooled spring still
+* alive at scope teardown is disposed, so leaked motions are
+* structurally impossible.
+*
+* Call it during `setup()` — or inside an effect scope — below a
+* provided spring system. Outside a scope, pooled springs are only
+* disposed manually.
+*/
+function useSpringPool() {
+	const system = injectSpringSystem();
+	const live = /* @__PURE__ */ new Set();
+	const adopt = (spring) => {
+		live.add(spring);
+		spring.onDispose(() => {
+			live.delete(spring);
+		});
+		return spring;
+	};
+	onScopeDispose(() => {
+		for (const spring of live) spring.dispose();
+	}, true);
+	const create = system.createSpring.bind(system);
+	const createSpring = ((value, config, options) => adopt(create(value, config, options)));
+	return { createSpring };
 }
 //#endregion
 //#region src/vue/component.ts
+/**
+* Renderless component exposing one springed number through its default
+* slot — the template-only sibling of `useSpring`. Must sit below a
+* provided spring system.
+*
+* @example
+* ```vue
+* <SpringValue :target="expanded ? 1 : 0" purpose="appearance" v-slot="{ value }">
+*   <div :style="{ opacity: value }" />
+* </SpringValue>
+* ```
+*/
 const SpringValue = defineComponent((props, { slots, expose }) => {
 	const { target, config } = toRefs(props);
-	const spring = useSpring(target, config);
+	const spring = useSpring(target, config, { purpose: props.purpose });
 	expose({
 		value: spring,
 		velocity: spring.velocity,
@@ -363,7 +255,11 @@ const SpringValue = defineComponent((props, { slots, expose }) => {
 	}) ?? null;
 }, {
 	name: "SpringValue",
-	props: ["target", "config"]
+	props: [
+		"target",
+		"config",
+		"purpose"
+	]
 });
 //#endregion
-export { SpringValue, provideSpringSystem, useSpring, useSpring2D, useSpringSystem };
+export { SpringValue, provideSpringSystem, useSpring, useSpringPool, useSpringSystem };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "coily",
-  "version": "0.12.2",
+  "version": "0.14.0",
   "description": "Simulate values using spring physics",
   "homepage": "https://github.com/tkofh/coily#readme",
   "bugs": {
@@ -27,22 +27,24 @@
     "access": "public"
   },
   "devDependencies": {
-    "@nuxt/kit": "^4.4.2",
-    "@nuxt/schema": "^4.4.2",
-    "@vitejs/plugin-vue": "^6.0.5",
-    "@vitest/browser-playwright": "^4.1.0",
-    "@vitest/coverage-v8": "^4.1.0",
-    "@vue/test-utils": "^2.4.6",
-    "fast-check": "^4.6.0",
-    "happy-dom": "^20.8.4",
-    "tsdown": "^0.21.3",
-    "vitest": "^4.1.0",
+    "@nuxt/kit": "^4.4.8",
+    "@nuxt/schema": "^4.4.8",
+    "@vitejs/plugin-vue": "^6.0.7",
+    "@vitest/browser-playwright": "^4.1.10",
+    "@vitest/coverage-v8": "^4.1.10",
+    "@vue/test-utils": "^2.4.11",
+    "fast-check": "^4.9.0",
+    "happy-dom": "^20.10.6",
+    "playwright": "1.61.1",
+    "tsdown": "^0.22.4",
+    "typescript": "^6.0.0",
+    "vitest": "^4.1.10",
     "vitest-browser-vue": "^2.1.0",
-    "vue": "^3.5.30"
+    "vue": "^3.5.39"
   },
   "peerDependencies": {
     "@nuxt/kit": "^4.0.0",
-    "vue": "^3.4.0"
+    "vue": "^3.5.0"
   },
   "peerDependenciesMeta": {
     "vue": {
@@ -52,11 +54,9 @@
       "optional": true
     }
   },
-  "engines": {
-    "node": ">=24.10.0"
-  },
   "scripts": {
     "build": "tsdown",
+    "check": "tsc -p .",
     "test": "vitest run",
     "test:coverage": "vitest run --coverage",
     "bench": "vitest bench --run",