coily 0.13.1 → 0.14.0

package/dist/vue.d.ts

@@ -1,57 +1,267 @@
-import { _ as SpringOptions, a as ConfigShape, c as Shape, f as Spring, g as SpringConfig, l as SpringObject, n as SpringSystemOptions, o as PartialShape, p as SpringPosition, s as ReadonlyShape, t as SpringSystem } from "./system-86fsXJN_.js";
+import { C as SpringDefinitionOptions, S as SpringDefinition, c as ConfigShape, d as ReadonlyShape, f as Shape, i as SpringSystemOptions, l as PartialShape, m as Spring, n as SpringOptions, o as CompositeSpring, p as Purpose, r as SpringSystem, t as CompositeSpringOptions, y as SpringSource } from "./system-Ci-R4RaI.js";
 import { App, MaybeRefOrGetter, Ref, SlotsType } from "vue";
 //#region src/vue/reactive-spring.d.ts
-type UseSpringOptions = MaybeRefOrGetter<SpringOptions | SpringConfig | undefined>;
-interface ReactiveSpringRef<V, W = V> extends Ref<V, W> {
+/**
+ * Config for a scalar `useSpring`: a `SpringDefinition`, any option shape
+ * `defineSpring` accepts, or a ref/getter of either. Reactive config
+ * reconfigures the spring in place when it changes; `undefined` means the
+ * default config.
+ */
+type UseSpringConfig = MaybeRefOrGetter<SpringDefinitionOptions | SpringDefinition | undefined>;
+/**
+ * The reactive surface `useSpring` returns: a writable ref of the
+ * animated value with the rest of the spring attached. Reads track
+ * reactively and update once per tick while the spring moves.
+ *
+ * Writing the main ref displaces the spring — it springs back toward its
+ * target. To move the spring, drive the target you passed to
+ * `useSpring`.
+ *
+ * The ref is also a `SpringSource`: it goes anywhere a source does —
+ * another `useSpring`, a `mapSpring` leaf, a composite channel target.
+ * Followers read the backing spring through `SpringSourceSymbol`, never
+ * through the ref's tracked getter, so following registers no Vue
+ * dependencies — an effect that touches a follower's leader stays
+ * independent of the leader's animation.
+ */
+interface ReactiveSpringRef<V, W = V> extends Ref<V, W>, SpringSource<V> {
+  /**
+   * The current velocity in value units per second, as a writable ref.
+   * Writing flings the spring; it settles back to its target.
+   */
   readonly velocity: Ref<V, W>;
+  /**
+   * Estimated milliseconds until the spring rests, as a reactive ref: 0
+   * while resting. Writes are ignored.
+   */
   readonly timeRemaining: Ref<number>;
+  /** Whether the spring is resting, as a reactive ref. Writes are ignored. */
   readonly isResting: Ref<boolean>;
+  /**
+   * A promise that resolves when the spring next comes to rest — already
+   * resolved while resting. Retargeting mid-flight extends the wait;
+   * disposal resolves it.
+   */
   readonly settled: Promise<void>;
+  /** Snaps the spring to `value` with no animation, target included. */
   readonly jumpTo: (value: W) => void;
 }
 //#endregion
-//#region src/vue/spring-object.d.ts
-type UseSpringObjectOptions<T extends object> = MaybeRefOrGetter<ConfigShape<T> | undefined>;
-interface SpringObjectRef<T extends object> extends ReactiveSpringRef<ReadonlyShape<T>, PartialShape<T>> {}
+//#region src/vue/composite-spring.d.ts
+/**
+ * Config for an object `useSpring`: a `ConfigShape` — one `SpringDefinition`
+ * for every channel, `null`, or a shape with configs at any level — or a
+ * ref/getter of one. Reactive config reconfigures channels in place.
+ *
+ * Unlike scalar config, positions here take `SpringDefinition` instances
+ * only (build them with `defineSpring`): a plain object is always read as
+ * a per-channel shape.
+ */
+type UseCompositeSpringConfig<T extends object> = MaybeRefOrGetter<ConfigShape<T> | undefined>;
+/**
+ * The reactive handle for a composite spring: a ref reading the
+ * deep-readonly composite value and accepting partial shapes on writes,
+ * with `velocity`, `timeRemaining`, and `isResting` refs plus `settled`
+ * and `jumpTo` attached. Writing the main ref displaces the named
+ * channels; drive the `useSpring` target to move them.
+ */
+interface CompositeSpringRef<T extends object> extends ReactiveSpringRef<ReadonlyShape<T>, PartialShape<T>> {}
 //#endregion
 //#region src/vue/spring.d.ts
+/**
+ * The reactive handle for a scalar spring: a writable ref of the
+ * animated number, with `velocity`, `timeRemaining`, and `isResting`
+ * refs plus `settled` and `jumpTo` attached. Writing the main ref
+ * displaces the spring; drive the `useSpring` target to move it.
+ */
 interface SpringRef extends ReactiveSpringRef<number> {}
-declare function useSpring(target: MaybeRefOrGetter<number>, options?: UseSpringOptions): SpringRef;
-declare function useSpring(target: SpringRef, options?: UseSpringOptions): SpringRef;
-declare function useSpring<T extends object>(target: SpringObjectRef<T>, options?: UseSpringObjectOptions<T>): SpringObjectRef<T>;
-declare function useSpring<T extends object>(target: T & Shape<T>, options?: UseSpringObjectOptions<T>): SpringObjectRef<T>;
-declare function useSpring<T extends object>(target: Ref<T & Shape<T>>, options?: UseSpringObjectOptions<T>): SpringObjectRef<T>;
-declare function useSpring<T extends object>(target: () => T & Shape<T>, options?: UseSpringObjectOptions<T>): SpringObjectRef<T>;
+/**
+ * Creates a scalar spring and returns it as a `SpringRef`. The target
+ * is a number to animate toward, or a `SpringSource` to follow — another
+ * `useSpring` ref, a `mapSpring` result, a pooled `Spring` — or a
+ * ref/getter of either. Reactive numbers retarget the spring whenever
+ * they change, momentum intact; a getter of a source re-follows when its
+ * own dependencies change, so `useSpring(() => (split.value ? left :
+ * right))` switches leaders live. Reactive `config` reconfigures the
+ * spring in place; while following, it configures the follower's own
+ * motion — the leader's config plays no part.
+ *
+ * Following bypasses Vue reactivity — the spring subscribes to the
+ * source directly — so effects and getters never gain a dependency on a
+ * leader's animation.
+ *
+ * Call it during `setup()` below a provided spring system (the
+ * coily/nuxt module, or `useSpringSystem()` in an ancestor). The spring
+ * is disposed with the component's scope, and composables are loop-safe:
+ * map over targets for several independent springs.
+ *
+ * `options.purpose` marks what the spring animates — `'appearance'`
+ * (a cross-fade, a color) keeps animating under reduced motion, `'motion'`
+ * (the default) snaps. It is read once, so unlike `config` it is not
+ * reactive.
+ *
+ * @example
+ * ```ts
+ * const target = ref(0)
+ * const x = useSpring(target, { duration: 500, bounce: 0.3 })
+ * // template: <div :style="{ translate: `${x}px 0` }" @click="target = 300" />
+ *
+ * const opacity = useSpring(shown ? 1 : 0, undefined, { purpose: 'appearance' })
+ * ```
+ */
+declare function useSpring(target: MaybeRefOrGetter<number | SpringSource>, config?: UseSpringConfig, options?: SpringOptions): SpringRef;
+/**
+ * Creates a composite spring that follows another `useSpring` object ref
+ * channel by channel, animating toward the leader's live values.
+ *
+ * Call it during `setup()` below a provided spring system. The springs
+ * are disposed with the component's scope.
+ */
+declare function useSpring<T extends object>(target: CompositeSpringRef<T>, config?: UseCompositeSpringConfig<T>, options?: CompositeSpringOptions<T>): CompositeSpringRef<T>;
+/**
+ * Creates a composite spring over a numeric shape — a plain object or
+ * array whose leaves are all numbers, or a ref/getter of one — and
+ * returns a `CompositeSpringRef`: reads are the deep-readonly composite
+ * value, writes take partial shapes. The shape is fixed at creation.
+ * Reactive targets retarget the channels, momentum intact — a ref on
+ * replacement or nested mutation, a getter whenever its reactive
+ * dependencies change. Reactive `config` accepts a per-channel config
+ * shape.
+ *
+ * Call it during `setup()` below a provided spring system. The springs
+ * are disposed with the component's scope.
+ *
+ * `options.purpose` marks reduced-motion behavior per channel: a single
+ * `Purpose` for all, or a shape mirroring the value. It is read once, so
+ * unlike `config` it is not reactive.
+ */
+declare function useSpring<T extends object>(target: MaybeRefOrGetter<T & Shape<T>>, config?: UseCompositeSpringConfig<T>, options?: CompositeSpringOptions<T>): CompositeSpringRef<T>;
+/**
+ * Creates a composite spring driven by a getter of a numeric shape: the
+ * springs retarget whenever the getter's reactive dependencies change.
+ * The shape itself is fixed at creation.
+ *
+ * (This is the getter case of the shape overload above, split out
+ * because the shape doesn't infer through `MaybeRefOrGetter`'s
+ * function member.)
+ *
+ * Call it during `setup()` below a provided spring system. The springs
+ * are disposed with the component's scope.
+ */
+declare function useSpring<T extends object>(target: () => T & Shape<T>, config?: UseCompositeSpringConfig<T>, options?: CompositeSpringOptions<T>): CompositeSpringRef<T>;
 //#endregion
 //#region src/vue/pool.d.ts
+/**
+ * Imperative spring factories bound to the provided system, for dynamic
+ * sets of springs — particles, per-item effects — created and disposed
+ * at arbitrary times. Any pooled spring still alive when the creating
+ * scope tears down is disposed automatically; disposing one manually
+ * before that is fine.
+ */
 interface SpringPool {
-  createSpring(position: SpringPosition, config?: SpringConfig): Spring;
-  createSpringObject<T extends object>(value: T & Shape<T>, config?: ConfigShape<T>): SpringObject<T>;
+  /**
+   * Creates a pooled spring at rest at `value`. Without `config`, the
+   * default applies. `options.purpose` sets reduced-motion behavior —
+   * `'appearance'` keeps animating, `'motion'` (default) snaps.
+   */
+  createSpring(value: number, config?: SpringDefinition, options?: SpringOptions): Spring;
+  /**
+   * Creates a pooled spring already following `source`, starting at its
+   * current value. `options.purpose` sets reduced-motion behavior.
+   */
+  createSpring(source: SpringSource, config?: SpringDefinition, options?: SpringOptions): Spring;
+  /**
+   * Creates a pooled composite spring over a numeric shape whose leaves
+   * are all numbers. `config` applies per channel: one `SpringDefinition`
+   * for all, or a shape with configs at any level. `options.purpose` sets
+   * reduced-motion behavior per channel the same way.
+   */
+  createSpring<T extends object>(value: T & Shape<T>, config?: ConfigShape<T>, options?: CompositeSpringOptions<T>): CompositeSpring<T>;
 }
+/**
+ * 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.
+ */
 declare function useSpringPool(): SpringPool;
 //#endregion
 //#region src/vue/component.d.ts
 interface SpringValueProps {
+  /** The value to animate toward. Changing it retargets the spring, momentum intact. */
   target: number;
-  config?: SpringOptions | SpringConfig;
+  /**
+   * Spring config: a `SpringDefinition` or any option shape `defineSpring`
+   * accepts. Changing it reconfigures the spring in place; omit it for
+   * the default.
+   */
+  config?: SpringDefinitionOptions | SpringDefinition;
+  /**
+   * What the spring animates — `'motion'` (default) or `'appearance'`.
+   * `'appearance'` (a cross-fade, a color) keeps animating under reduced
+   * motion. Read once at mount; later changes are ignored.
+   * @default 'motion'
+   */
+  purpose?: Purpose;
 }
+/** `SpringValue` emits no events. */
 type SpringValueEmits = Record<string, never>;
+/** What `SpringValue` passes to its default slot. */
 interface SpringValueSlotScope {
+  /** The current animated value. */
   value: number;
+  /** The current velocity, in value units per second. */
   velocity: number;
+  /** Whether the spring is resting. */
   isResting: boolean;
+  /** Estimated milliseconds until the spring rests. */
   timeRemaining: number;
+  /** Snaps the spring to `value` with no animation, target included. */
   jumpTo: (value: number) => void;
 }
+/** Slot types: `default` receives the live `SpringValueSlotScope`. */
 type SpringValueSlots = SlotsType<{
   default: SpringValueSlotScope;
 }>;
+/**
+ * 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>
+ * ```
+ */
 declare const SpringValue: import("vue").DefineSetupFnComponent<SpringValueProps, SpringValueEmits, SpringValueSlots, SpringValueProps & {
   [x: `on${Capitalize<string>}`]: ((...args: unknown[]) => any) | undefined;
 }, import("vue").PublicProps>;
 //#endregion
 //#region src/vue/system.d.ts
+/**
+ * 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.
+ */
 declare function provideSpringSystem(system: SpringSystem, app?: App): void;
+/**
+ * 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()`.
+ */
 declare function useSpringSystem(options?: SpringSystemOptions): SpringSystem;
 //#endregion
-export { type SpringObjectRef, type SpringPool, type SpringRef, SpringValue, type SpringValueProps, type SpringValueSlots, type UseSpringObjectOptions, provideSpringSystem, useSpring, useSpringPool, useSpringSystem };
+export { type CompositeSpringRef, type SpringPool, type SpringRef, SpringValue, type SpringValueProps, type SpringValueSlots, provideSpringSystem, useSpring, useSpringPool, useSpringSystem };

package/dist/vue.js

@@ -1,4 +1,4 @@
-import { n as SpringConfig, t as createSpringSystem } from "./system-Csho09XW.js";
+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();
@@ -25,10 +25,27 @@ function injectLocal(key) {
 //#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 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);
@@ -47,11 +64,11 @@ function injectSpringSystem() {
 	if (!system) throw new Error("No SpringSystem found — install the coily/nuxt module or call useSpringSystem() in an ancestor component");
 	return system;
 }
-function resolveSpringConfig(options) {
+function resolveSpringConfig(config) {
 	return computed(() => {
-		const opts = toValue(options);
-		if (opts instanceof SpringConfig) return opts;
-		return opts ? new SpringConfig(opts) : void 0;
+		const resolved = toValue(config);
+		if (resolved instanceof SpringDefinition) return resolved;
+		return resolved ? new SpringDefinition(resolved) : void 0;
 	});
 }
 function createReactiveSpringRef(spring, config, instanceKey) {
@@ -116,66 +133,78 @@ function createReactiveSpringRef(spring, config, instanceKey) {
 	});
 	Object.defineProperty(ref, "settled", { get: () => spring.settled });
 	Object.defineProperty(ref, instanceKey, { value: spring });
+	Object.defineProperty(ref, SpringSourceSymbol, { value: spring[SpringSourceSymbol] });
 	return ref;
 }
 //#endregion
-//#region src/vue/spring-object.ts
-/** @internal */
-const SpringObjectInstanceKey = Symbol("spring-object");
-function hasSpringObjectInstance(value) {
-	return typeof value === "object" && value !== null && SpringObjectInstanceKey in value;
+//#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(options) {
-	return computed(() => toValue(options));
+function resolveConfigShape(config) {
+	return computed(() => toValue(config));
 }
-function createSpringObjectRef(value, options) {
+function createCompositeSpringRef(value, config, options) {
 	const system = injectSpringSystem();
-	const config = resolveConfigShape(options);
-	const spring = system.createSpringObject(toValue(value), config.value);
-	const ref = createReactiveSpringRef(spring, config, SpringObjectInstanceKey);
+	const resolvedConfig = resolveConfigShape(config);
+	const spring = system.createSpring(toValue(value), resolvedConfig.value, options);
+	const ref = createReactiveSpringRef(spring, resolvedConfig, CompositeSpringInstanceKey);
 	watchSyncEffect(() => {
 		spring.target = toValue(value);
 	});
 	return ref;
 }
-function createLinkedSpringObjectRef(leaderRef, options) {
+function createLinkedCompositeSpringRef(leaderRef, config, options) {
 	const system = injectSpringSystem();
-	const leader = leaderRef[SpringObjectInstanceKey];
-	const config = resolveConfigShape(options);
-	const spring = system.createSpringObject(leader.value, config.value);
+	const leader = leaderRef[CompositeSpringInstanceKey];
+	const resolvedConfig = resolveConfigShape(config);
+	const spring = system.createSpring(leader.value, resolvedConfig.value, options);
 	spring.target = leader;
-	return createReactiveSpringRef(spring, config, SpringObjectInstanceKey);
+	return createReactiveSpringRef(spring, resolvedConfig, CompositeSpringInstanceKey);
 }
 //#endregion
 //#region src/vue/spring.ts
-/** @internal */
 const SpringInstanceKey = Symbol("spring");
 function hasSpringInstance(value) {
 	return typeof value === "object" && value !== null && SpringInstanceKey in value;
 }
-function useSpring(target, options) {
-	if (hasSpringInstance(target)) return createLinkedSpringRef(target, options);
-	if (hasSpringObjectInstance(target)) return createLinkedSpringObjectRef(target, options);
-	if (typeof toValue(target) === "number") return createSpringRef(target, options);
-	return createSpringObjectRef(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 createSpringRef(target, options) {
+function createSpringRef(target, config, options) {
 	const system = injectSpringSystem();
-	const config = resolveSpringConfig(options);
-	const spring = system.createSpring(toValue(target), config.value);
-	const ref = createReactiveSpringRef(spring, config, SpringInstanceKey);
+	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);
 	});
 	return ref;
 }
-function createLinkedSpringRef(leaderRef, options) {
+function createLinkedSpringRef(leaderRef, config, options) {
 	const system = injectSpringSystem();
-	const config = resolveSpringConfig(options);
-	return createReactiveSpringRef(system.createSpring({ target: leaderRef[SpringInstanceKey] }, config.value), config, SpringInstanceKey);
+	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();
@@ -189,18 +218,27 @@ function useSpringPool() {
 	onScopeDispose(() => {
 		for (const spring of live) spring.dispose();
 	}, true);
-	return {
-		createSpring: (position, config) => adopt(system.createSpring(position, config)),
-		createSpringObject(value, config) {
-			return adopt(system.createSpringObject(value, config));
-		}
-	};
+	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,
@@ -217,7 +255,11 @@ const SpringValue = defineComponent((props, { slots, expose }) => {
 	}) ?? null;
 }, {
 	name: "SpringValue",
-	props: ["target", "config"]
+	props: [
+		"target",
+		"config",
+		"purpose"
+	]
 });
 //#endregion
 export { SpringValue, provideSpringSystem, useSpring, useSpringPool, useSpringSystem };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "coily",
-  "version": "0.13.1",
+  "version": "0.14.0",
   "description": "Simulate values using spring physics",
   "homepage": "https://github.com/tkofh/coily#readme",
   "bugs": {