coily 0.14.0 → 0.16.0

package/dist/vue.js

@@ -1,4 +1,5 @@
-import { a as SpringDefinition, n as SpringSourceSymbol, r as isSpringSource, t as createSpringSystem } from "./system-BXxAHM2a.js";
+import { a as SpringSourceSymbol, n as CompositeSpring, o as isSpringSource, r as SpringDefinition, t as createSpringSystem } from "./system-WejqGkfv.js";
+import { o as invariant } from "./solver-CAXuxdKj.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();
@@ -26,25 +27,24 @@ function injectLocal(key) {
 //#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.
+* Provides a spring system you create and manage yourself. Coily never
+* starts or stops it. With `app`, the whole app gets it, as with the
+* Nuxt module. Without `app`, call it in `setup()`, and it reaches the
+* current component, including its own `useSpring` calls, and its
+* descendants. Mostly useful in tests.
 */
 function provideSpringSystem(system, app) {
 	if (app) app.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.
+* Returns the spring system this component or an ancestor provides, or
+* creates one. A created system is provided to this component and its
+* descendants, starts when the component mounts, and is disposed before
+* it unmounts.
 *
-* Idempotent: call it near the root and again in any descendant.
-* `options` only applies when the call actually creates a system.
-* Throws outside `setup()`.
+* A call below a provider returns the provided system, and `options`
+* applies only when the call creates one. Throws outside `setup()`.
 */
 function useSpringSystem(options) {
 	if (!getCurrentInstance()) throw new Error("useSpringSystem must be called inside setup()");
@@ -53,7 +53,7 @@ function useSpringSystem(options) {
 	const system = createSpringSystem(options);
 	provideLocal(SpringSystemKey, system);
 	onMounted(() => system.start());
-	onBeforeUnmount(() => system.stop());
+	onBeforeUnmount(() => system.dispose());
 	return system;
 }
 //#endregion
@@ -83,6 +83,9 @@ function createReactiveSpringRef(spring, config, instanceKey) {
 		triggerVelocity?.();
 		triggerTimeRemaining?.();
 	});
+	const triggerRemaining = () => triggerTimeRemaining?.();
+	spring.onStart(triggerRemaining);
+	spring.onStop(triggerRemaining);
 	const value = divergentRef((track, trigger) => ({
 		get() {
 			triggerValue ??= trigger;
@@ -142,27 +145,38 @@ const CompositeSpringInstanceKey = Symbol("composite-spring");
 function hasCompositeSpringInstance(value) {
 	return typeof value === "object" && value !== null && CompositeSpringInstanceKey in value;
 }
+/** The composite that `value` leads with, or `undefined` when it is not a `CompositeLeader`. */
+function compositeLeaderOf(value) {
+	if (value instanceof CompositeSpring) return value;
+	if (hasCompositeSpringInstance(value)) return value[CompositeSpringInstanceKey];
+}
+const SHAPED_SOURCE = "useSpring follows a scalar SpringSource or a composite spring, not a source of another shape. Derive a scalar source with mapSpring";
 function resolveConfigShape(config) {
 	return computed(() => toValue(config));
 }
-function createCompositeSpringRef(value, config, options) {
+/**
+* Creates the composite behind an object `useSpring`. `target` resolves
+* to a shape to animate toward or a `CompositeLeader` to follow, and it
+* can switch between them.
+*/
+function createCompositeSpringRef(target, config, options) {
 	const system = injectSpringSystem();
 	const resolvedConfig = resolveConfigShape(config);
-	const spring = system.createSpring(toValue(value), resolvedConfig.value, options);
+	const resolve = () => {
+		const next = toValue(target);
+		const leader = compositeLeaderOf(next);
+		if (leader !== void 0) return leader;
+		invariant(!isSpringSource(next), SHAPED_SOURCE);
+		return next;
+	};
+	const initial = resolve();
+	const spring = system.createSpring(initial instanceof CompositeSpring ? initial.value : initial, resolvedConfig.value, options);
 	const ref = createReactiveSpringRef(spring, resolvedConfig, CompositeSpringInstanceKey);
 	watchSyncEffect(() => {
-		spring.target = toValue(value);
+		spring.target = resolve();
 	});
 	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/spring.ts
 const SpringInstanceKey = Symbol("spring");
@@ -171,10 +185,10 @@ function hasSpringInstance(value) {
 }
 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);
+	const follow = isSpringSource(target) ? () => target : target;
+	const resolved = toValue(follow);
+	if (typeof resolved === "number" || isSpringSource(resolved) && typeof resolved[SpringSourceSymbol].value === "number") return createSpringRef(follow, config, options);
+	return createCompositeSpringRef(follow, config, options);
 }
 function createSpringRef(target, config, options) {
 	const system = injectSpringSystem();
@@ -194,16 +208,121 @@ function createLinkedSpringRef(leaderRef, config, options) {
 	return createReactiveSpringRef(system.createSpring(leader, resolvedConfig.value, options), resolvedConfig, SpringInstanceKey);
 }
 //#endregion
+//#region src/vue/ramp.ts
+/**
+* Creates a ramp and returns it as a `RampRef`. A ramp moves toward
+* `target` in a straight line at `rate` value units per second, and
+* stops there. A target of `Infinity` or `-Infinity` makes it endless.
+* A spring following the ref with the default `arrival` tracks its
+* steady motion exactly, with no frame-to-frame steps. On an endless
+* ramp, that spring lags behind like a heavy spinning object.
+*
+* A new `target` sends the ramp there from its current value. A new
+* `rate` applies from the current value on.
+*
+* Call it during `setup()` below a provided spring system (the coily/nuxt
+* module, or `useSpringSystem()` in an ancestor). It throws without one.
+* The ramp is disposed with the component's scope.
+*
+* @example
+* ```ts
+* const angle = useRamp(Infinity, 270, { from: 0 })
+* const ring = useSpring(angle, { duration: 300, dampingRatio: 1 })
+* // template: <div :style="{ rotate: `${ring}deg` }" />
+*
+* const heading = ref(0)
+* const slew = useRamp(heading, 400) // turns toward heading at 400 deg/s
+* ```
+*/
+function useRamp(target, rate, options) {
+	const system = injectSpringSystem();
+	const initial = toValue(target);
+	const from = options?.from ?? initial;
+	invariant(Number.isFinite(from), "useRamp needs a finite `from` when its initial target is infinite");
+	const ramp = system.createRamp(from, {
+		rate: toValue(rate),
+		target: initial,
+		purpose: options?.purpose
+	});
+	watchSyncEffect(() => {
+		ramp.target = toValue(target);
+	});
+	watchSyncEffect(() => {
+		ramp.rate = toValue(rate);
+	});
+	const ref = createRampRef(ramp);
+	if (getCurrentScope()) onScopeDispose(() => ramp.dispose());
+	return ref;
+}
+function createRampRef(ramp) {
+	const triggers = /* @__PURE__ */ new Set();
+	let unread = false;
+	let unsubscribe = null;
+	const triggerAll = () => {
+		for (const trigger of triggers) trigger();
+	};
+	const onUpdate = () => {
+		if (unread) {
+			unsubscribe();
+			unsubscribe = null;
+			return;
+		}
+		unread = true;
+		triggerAll();
+	};
+	const read = (trigger) => {
+		triggers.add(trigger);
+		unread = false;
+		if (unsubscribe === null) {
+			const offUpdate = ramp.onUpdate(onUpdate);
+			const offStart = ramp.onStart(triggerAll);
+			const offStop = ramp.onStop(triggerAll);
+			unsubscribe = () => {
+				offUpdate();
+				offStart();
+				offStop();
+			};
+		}
+	};
+	const value = customRef((track, trigger) => ({
+		get() {
+			track();
+			read(trigger);
+			return ramp.value;
+		},
+		set(next) {
+			ramp.value = next;
+			trigger();
+		}
+	}));
+	const readOnly = (get) => customRef((track, trigger) => ({
+		get() {
+			track();
+			read(trigger);
+			return get();
+		},
+		set() {}
+	}));
+	const ref = Object.assign(value, {
+		velocity: readOnly(() => ramp.velocity),
+		timeRemaining: readOnly(() => ramp.timeRemaining),
+		isResting: readOnly(() => ramp.isResting),
+		jumpTo: (next) => ramp.jumpTo(next)
+	});
+	Object.defineProperty(ref, "settled", { get: () => ramp.settled });
+	Object.defineProperty(ref, SpringSourceSymbol, { value: ramp[SpringSourceSymbol] });
+	return ref;
+}
+//#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.
+* Returns spring factories bound to the provided spring system. When
+* the current effect scope stops, the pool disposes every pooled spring
+* still alive.
 *
-* Call it during `setup()` — or inside an effect scope — below a
-* provided spring system. Outside a scope, pooled springs are only
-* disposed manually.
+* Call it during `setup()` or inside an effect scope, below a provided
+* spring system. It throws without one. Outside a scope, you must
+* dispose each pooled spring yourself.
 */
 function useSpringPool() {
 	const system = injectSpringSystem();
@@ -225,13 +344,14 @@ function useSpringPool() {
 //#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.
+* A renderless component that passes one spring's state to its default
+* slot: the template-only form of `useSpring`. It must render below a
+* provided spring system, and throws otherwise. A template ref to it
+* reads the same fields as the slot scope.
 *
 * @example
 * ```vue
-* <SpringValue :target="expanded ? 1 : 0" purpose="appearance" v-slot="{ value }">
+* <SpringValue :target="expanded ? 1 : 0" purpose="nonmotion" v-slot="{ value }">
 *   <div :style="{ opacity: value }" />
 * </SpringValue>
 * ```
@@ -262,4 +382,4 @@ const SpringValue = defineComponent((props, { slots, expose }) => {
 	]
 });
 //#endregion
-export { SpringValue, provideSpringSystem, useSpring, useSpringPool, useSpringSystem };
+export { SpringValue, provideSpringSystem, useRamp, useSpring, useSpringPool, useSpringSystem };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "coily",
-  "version": "0.14.0",
+  "version": "0.16.0",
   "description": "Simulate values using spring physics",
   "homepage": "https://github.com/tkofh/coily#readme",
   "bugs": {
@@ -19,6 +19,7 @@
   "sideEffects": false,
   "exports": {
     ".": "./dist/index.js",
+    "./css": "./dist/css.js",
     "./nuxt": "./dist/nuxt.js",
     "./vue": "./dist/vue.js",
     "./package.json": "./package.json"