coily 0.12.2 → 0.14.0

package/dist/vue.d.ts

@@ -1,52 +1,267 @@
-import { h as SpringOptions, l as Vector2, m as SpringConfig, n as SpringSystemOptions, t as SpringSystem } from "./system-coAFNYnb.js";
-import * as vue from "vue";
+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/spring.d.ts
-type UseSpringOptions = MaybeRefOrGetter<SpringOptions | SpringConfig | undefined>;
-interface SpringRef extends Ref<number> {
-  readonly velocity: Ref<number>;
+//#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.
+ */
+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>;
-  readonly jumpTo: (value: number) => void;
+  /**
+   * 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;
 }
-declare function useSpring(target: MaybeRefOrGetter<number>, options?: UseSpringOptions): SpringRef;
-declare function useSpring(target: SpringRef, options?: UseSpringOptions): SpringRef;
-declare function useSpring<const T extends readonly MaybeRefOrGetter<number>[]>(targets: T, options?: UseSpringOptions): { [K in keyof T]: SpringRef };
 //#endregion
-//#region src/vue/spring2d.d.ts
-interface SpringRef2D extends Ref<Readonly<Vector2>> {
-  readonly velocity: Ref<Readonly<Vector2>>;
-  readonly timeRemaining: Ref<number>;
-  readonly isResting: Ref<boolean>;
-  readonly jumpTo: (value: Vector2) => void;
+//#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> {}
+/**
+ * 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 {
+  /**
+   * 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>;
 }
-declare function useSpring2D(target: MaybeRefOrGetter<Vector2>, options?: UseSpringOptions): SpringRef2D;
-declare function useSpring2D(target: SpringRef2D, options?: UseSpringOptions): SpringRef2D;
-declare function useSpring2D<const T extends readonly MaybeRefOrGetter<Vector2>[]>(targets: T, options?: UseSpringOptions): { [K in keyof T]: SpringRef2D };
+/**
+ * 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;
 }>;
-declare const SpringValue: vue.DefineSetupFnComponent<SpringValueProps, SpringValueEmits, SpringValueSlots, SpringValueProps & {
+/**
+ * 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;
-}, vue.PublicProps>;
+}, 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;
-declare function useSpringSystem(options?: SpringSystemOptions): 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 SpringRef, type SpringRef2D, SpringValue, type SpringValueProps, type SpringValueSlots, provideSpringSystem, useSpring, useSpring2D, useSpringSystem };
+export { type CompositeSpringRef, type SpringPool, type SpringRef, SpringValue, type SpringValueProps, type SpringValueSlots, provideSpringSystem, useSpring, useSpringPool, useSpringSystem };