coily 0.14.0 → 0.16.0

package/dist/vue.d.ts

@@ -1,33 +1,31 @@
-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";
+import { n as SpringDefinitionOptions, t as SpringDefinition } from "./config-B8M2xp26.js";
+import { O as SpringSource, _ as Spring, c as CompositeSpring, d as PartialShape, g as Purpose, i as SpringSystemOptions, m as Shape, n as SpringOptions, p as ReadonlyShape, r as SpringSystem, t as CompositeSpringOptions, u as ConfigShape, x as TargetedSource } from "./system-C7PbI4L0.js";
+import { App, MaybeRef, MaybeRefOrGetter, Ref, SlotsType } from "vue";
 //#region src/vue/reactive-spring.d.ts
 /**
  * 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.
+ * `defineSpring` accepts, or a ref or getter of either. A changed
+ * reactive config reconfigures the spring in place. `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
+ * The ref `useSpring` returns: a writable ref of the animated value, with
+ * the rest of the spring attached. It triggers once per frame while the
+ * spring moves. Writing it displaces the spring, which springs back
+ * toward its target. To move the spring, change the target 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.
+ * The ref is a `TargetedSource`, so another `useSpring` can follow it,
+ * and `velocityOf`, `accelerationOf`, and `targetOf` accept it. A scalar
+ * ref also works as a `mapSpring` leaf or a composite channel target.
+ * Followers read the backing spring directly, so following never adds a
+ * Vue dependency, even inside an effect that moves the leader.
  */
-interface ReactiveSpringRef<V, W = V> extends Ref<V, W>, SpringSource<V> {
+interface ReactiveSpringRef<V, W = V> extends Ref<V, W>, TargetedSource<V> {
   /**
    * The current velocity in value units per second, as a writable ref.
-   * Writing flings the spring; it settles back to its target.
+   * Writing flings the spring, and it settles back to its target.
    */
   readonly velocity: Ref<V, W>;
   /**
@@ -38,67 +36,71 @@ interface ReactiveSpringRef<V, W = V> extends Ref<V, W>, SpringSource<V> {
   /** 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.
+   * A promise that resolves when the spring next comes to rest. It is
+   * already resolved while the spring rests. A retarget mid-flight
+   * extends the wait, and disposal resolves it.
    */
   readonly settled: Promise<void>;
-  /** Snaps the spring to `value` with no animation, target included. */
+  /**
+   * Snaps the spring to `value` with no animation, target included. The
+   * spring rests there until the target you passed to `useSpring`
+   * changes, or until a leader it follows moves.
+   */
   readonly jumpTo: (value: W) => void;
 }
 //#endregion
 //#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.
+ * Config for an object `useSpring`: a `ConfigShape`, or a ref or getter
+ * of one. A `ConfigShape` is one `SpringDefinition` for every channel,
+ * `null` for the default, or a shape with configs at any level. A
+ * changed reactive config reconfigures the 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.
+ * Each config position takes only a `SpringDefinition` from
+ * `defineSpring`. A plain object reads as a nested level of the shape,
+ * never as spring options.
  */
 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.
+ * The ref an object `useSpring` returns. Reads return the deep-readonly
+ * composite value, and writes accept partial shapes. It carries
+ * `velocity`, `timeRemaining`, and `isResting` refs plus `settled` and
+ * `jumpTo`. Writing it displaces the named channels, which spring back.
+ * To move them, change the target passed to `useSpring`.
  */
 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.
+ * The writable ref a scalar `useSpring` returns, carrying `velocity`,
+ * `timeRemaining`, and `isResting` refs plus `settled` and `jumpTo`.
+ * Writing it displaces the spring, which springs back. To move it,
+ * change the target passed to `useSpring`.
  */
 interface SpringRef extends ReactiveSpringRef<number> {}
 /**
- * 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.
+ * 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, or a pooled `Spring`), or a ref
+ * or getter of either.
  *
- * Following bypasses Vue reactivity — the spring subscribes to the
- * source directly — so effects and getters never gain a dependency on a
- * leader's animation.
+ * A changed reactive number retargets the spring, which keeps its
+ * momentum. A getter of a source re-follows when its own dependencies
+ * change, so `useSpring(() => (split.value ? left : right))` switches
+ * leaders mid-flight. A changed reactive `config` reconfigures the
+ * spring in place. While following, the spring uses its own `config`,
+ * never the leader's.
  *
- * 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.
+ * The spring subscribes to a followed source directly, so no effect or
+ * getter gains a dependency on the leader's animation.
  *
- * `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.
+ * Call it during `setup()` below a provided spring system (the coily/nuxt
+ * module, or `useSpringSystem()` in an ancestor). It throws without one.
+ * The spring is disposed with the component's scope.
+ *
+ * `options.purpose` is read once, at creation. Under reduced motion, a
+ * `'motion'` spring, the default, snaps. A `'nonmotion'` spring, such as
+ * a cross-fade or a color, keeps animating.
  *
  * @example
  * ```ts
@@ -106,63 +108,155 @@ interface SpringRef extends ReactiveSpringRef<number> {}
  * 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' })
+ * const shown = ref(false)
+ * const opacity = useSpring(() => (shown.value ? 1 : 0), undefined, { purpose: 'nonmotion' })
  * ```
  */
 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.
+ * Creates a composite spring that follows a leader channel by channel,
+ * animating toward its live values. The leader is an object `useSpring`
+ * ref or a pooled `CompositeSpring` of the same shape. A ref of a
+ * leader, such as a `computed`, works too, and the spring follows each
+ * new leader the ref holds.
  *
- * Call it during `setup()` below a provided spring system. The springs
- * are disposed with the component's scope.
+ * Call it during `setup()` below a provided spring system. It throws
+ * without one. 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>;
+declare function useSpring<T extends object>(target: MaybeRef<CompositeSpringRef<T> | CompositeSpring<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.
+ * Creates a composite spring over a numeric shape and returns a
+ * `CompositeSpringRef`. The shape is a plain object or array whose
+ * leaves are all numbers, or a ref or getter of one, and it is fixed at
+ * creation. Reads return the deep-readonly value, and writes take
+ * partial shapes.
+ *
+ * A reactive target retargets the channels, which keep their momentum.
+ * A ref retargets when you replace its value or mutate a nested channel.
+ * `config` takes a per-channel config shape and may be reactive.
  *
- * Call it during `setup()` below a provided spring system. The springs
- * are disposed with the component's scope.
+ * Call it during `setup()` below a provided spring system. It throws
+ * without one. 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.
+ * `options.purpose` sets reduced-motion behavior per channel: one
+ * `Purpose` for all channels, or a shape that mirrors the value. It is
+ * read once, at creation.
  */
 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.
+ * Creates a composite spring driven by a getter that returns a numeric
+ * shape to animate toward, or a leader to follow (an object `useSpring`
+ * ref or a pooled `CompositeSpring`). When the getter's dependencies
+ * change, the spring retargets or follows the new leader, so
+ * `useSpring(() => (split.value ? left : right))` switches leaders
+ * mid-flight. Every shape and leader must match the spring's shape,
+ * which is fixed at creation.
+ *
+ * Call it during `setup()` below a provided spring system. It throws
+ * without one. The springs are disposed with the component's scope.
+ */
+declare function useSpring<T extends object>(target: () => (T & Shape<T>) | CompositeSpringRef<T> | CompositeSpring<T>, config?: UseCompositeSpringConfig<T>, options?: CompositeSpringOptions<T>): CompositeSpringRef<T>;
+//#endregion
+//#region src/vue/ramp.d.ts
+/** Options for `useRamp`, read once at creation. */
+interface UseRampOptions {
+  /**
+   * The value the ramp starts from. Must be finite, so it is required
+   * when the initial target is infinite.
+   * @default the initial target, so the ramp starts at rest
+   */
+  from?: number | undefined;
+  /**
+   * What the ramp drives. Under reduced motion, a `'motion'` ramp jumps
+   * to a bounded target and holds still on an endless one. A
+   * `'nonmotion'` ramp keeps moving. See `Purpose`.
+   * @default 'motion'
+   */
+  purpose?: Purpose | undefined;
+}
+/**
+ * The writable ref `useRamp` returns, carrying `velocity`,
+ * `timeRemaining`, and `isResting` refs plus `settled` and `jumpTo`.
+ * Writing it places the ramp at the written value, and the ramp
+ * continues toward its target from there.
+ *
+ * Reading any of the refs puts the ramp in the frame loop, and it leaves
+ * when reads stop. In a rendering template it updates every frame. Read
+ * only in an event handler, it stays in the loop for about two frames
+ * after each read. Unread, it still moves, and the next read returns its
+ * current value.
+ *
+ * The ref is a `TargetedSource`, so `useSpring` can follow it, and
+ * `velocityOf` and `targetOf` accept it. Followers subscribe to the
+ * ramp directly, so following never depends on reads of the ref.
+ */
+interface RampRef extends Ref<number>, TargetedSource<number> {
+  /**
+   * The current velocity in value units per second, as a reactive ref.
+   * It is `rate` with the sign of the direction to the target while the
+   * ramp moves, and 0 at rest. Writes are ignored.
+   */
+  readonly velocity: Ref<number>;
+  /**
+   * Milliseconds until the ramp reaches its target, as a reactive ref. It
+   * is 0 at rest and `Infinity` toward an infinite target. Writes are
+   * ignored.
+   */
+  readonly timeRemaining: Ref<number>;
+  /** Whether the ramp is at rest, as a reactive ref. Writes are ignored. */
+  readonly isResting: Ref<boolean>;
+  /**
+   * A promise that resolves when the ramp next comes to rest. It is
+   * already resolved while the ramp rests. While the promise is pending,
+   * a bounded ramp stays in the frame loop until it arrives.
+   */
+  readonly settled: Promise<void>;
+  /**
+   * Places the ramp at `value` and rests it there, target included, until
+   * the `target` passed to `useRamp` next changes.
+   */
+  readonly jumpTo: (value: number) => void;
+}
+/**
+ * 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.
  *
- * (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 coily/nuxt
+ * module, or `useSpringSystem()` in an ancestor). It throws without one.
+ * The ramp is disposed with the component's scope.
  *
- * Call it during `setup()` below a provided spring system. The springs
- * are 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
+ * ```
  */
-declare function useSpring<T extends object>(target: () => T & Shape<T>, config?: UseCompositeSpringConfig<T>, options?: CompositeSpringOptions<T>): CompositeSpringRef<T>;
+declare function useRamp(target: MaybeRefOrGetter<number>, rate: MaybeRefOrGetter<number>, options?: UseRampOptions): RampRef;
 //#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.
+ * Imperative spring factories bound to the provided system, for springs
+ * you create and dispose at any time, such as particles or per-item
+ * effects. When the creating scope stops, the pool disposes every pooled
+ * spring still alive. You can dispose one yourself before then.
  */
 interface SpringPool {
   /**
    * 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.
+   * spring uses the default config. `options.purpose` sets reduced-motion
+   * behavior: a `'nonmotion'` spring keeps animating, and a `'motion'`
+   * spring, the default, snaps.
    */
   createSpring(value: number, config?: SpringDefinition, options?: SpringOptions): Spring;
   /**
@@ -171,39 +265,38 @@ interface SpringPool {
    */
   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.
+   * Creates a pooled composite spring over a shape whose leaves are all
+   * numbers. `config` applies per channel: one `SpringDefinition` for all
+   * channels, or a shape with configs at any level. `options.purpose` sets
+   * reduced-motion behavior per channel in 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.
+ * 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.
  */
 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. */
+  /** The value to animate toward. A new value retargets the spring and keeps its momentum. */
   target: number;
   /**
    * Spring config: a `SpringDefinition` or any option shape `defineSpring`
-   * accepts. Changing it reconfigures the spring in place; omit it for
-   * the default.
+   * accepts. A new config reconfigures the spring in place. Without it,
+   * the spring uses the default config.
    */
   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.
+   * What the spring animates. Under reduced motion, a `'motion'` spring
+   * snaps, and a `'nonmotion'` spring, such as a cross-fade or a color,
+   * keeps animating. Read once in `setup()`, so later changes are ignored.
    * @default 'motion'
    */
   purpose?: Purpose;
@@ -220,7 +313,10 @@ interface SpringValueSlotScope {
   isResting: boolean;
   /** Estimated milliseconds until the spring rests. */
   timeRemaining: number;
-  /** Snaps the spring to `value` with no animation, target included. */
+  /**
+   * Snaps the spring to `value` with no animation, target included. The
+   * spring rests there until the `target` prop changes.
+   */
   jumpTo: (value: number) => void;
 }
 /** Slot types: `default` receives the live `SpringValueSlotScope`. */
@@ -228,13 +324,14 @@ 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.
+ * 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>
  * ```
@@ -245,23 +342,22 @@ declare const SpringValue: import("vue").DefineSetupFnComponent<SpringValueProps
 //#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.
+ * 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.
  */
 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.
+ * 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()`.
  */
 declare function useSpringSystem(options?: SpringSystemOptions): SpringSystem;
 //#endregion
-export { type CompositeSpringRef, type SpringPool, type SpringRef, SpringValue, type SpringValueProps, type SpringValueSlots, provideSpringSystem, useSpring, useSpringPool, useSpringSystem };
+export { type CompositeSpringRef, type RampRef, type SpringPool, type SpringRef, SpringValue, type SpringValueProps, type SpringValueSlotScope, type SpringValueSlots, type UseCompositeSpringConfig, type UseRampOptions, type UseSpringConfig, provideSpringSystem, useRamp, useSpring, useSpringPool, useSpringSystem };