coily 0.11.0 → 0.12.0

package/dist/{system-B_kZMcpg.d.ts → system-Do5rE0j7.d.ts}

@@ -1,4 +1,8 @@
 //#region src/config.d.ts
+interface SpringState {
+  readonly position: number;
+  readonly velocity: number;
+}
 interface BaseOptions {
   /**
    * Mass of the spring system.
@@ -67,10 +71,8 @@ interface TensionBounceDurationOptions extends BaseOptions, WithTension, WithBou
 interface DampingDurationOptions extends BaseOptions, WithDamping, WithDampingRatio, WithDuration, WithDisplacement {}
 interface DampingBounceDurationOptions extends BaseOptions, WithDamping, WithBounce, WithDuration, WithDisplacement {}
 type SpringOptions = DirectOptions | TensionRatioOptions | TensionBounceOptions | DampingRatioOptions | DampingBounceOptions | TensionDampingRatioOptions | TensionDampingBounceOptions | DurationOptions | BounceDurationOptions | TensionDurationOptions | TensionBounceDurationOptions | DampingDurationOptions | DampingBounceDurationOptions;
-/**
- * Immutable spring configuration.
- */
 declare class SpringConfig {
+  #private;
   readonly mass: number;
   readonly tension: number;
   readonly damping: number;
@@ -81,6 +83,29 @@ declare class SpringConfig {
   readonly precisionMultiplier: number;
   readonly restingMagnitude: number;
   constructor(input: SpringOptions);
+  static get globalVersion(): number;
+  static version(config: SpringConfig): number;
+  static assign(target: SpringConfig, source: SpringConfig): void;
+  /**
+   * Analytically estimates the time remaining for a spring to come to rest,
+   * given the current displacement and velocity.
+   *
+   * Uses the exponential decay envelope common to all three damping regimes.
+   * The decay rate depends on the regime:
+   * - Underdamped (ζ < 1): σ = ζωₙ
+   * - Critically damped (ζ = 1): σ = ωₙ
+   * - Overdamped (ζ > 1): σ = (ζ - √(ζ²-1))ωₙ  (the slower eigenvalue)
+   *
+   * The effective initial amplitude accounts for both displacement and velocity,
+   * since kinetic energy can convert to additional displacement:
+   *   A₀ = |x₀| + |v₀| / ωₙ
+   *
+   * Settling time: t = ln(A₀ / threshold) / σ, with a 2× safety factor
+   * to account for polynomial terms in the critically damped solution.
+   *
+   * Returns the estimated time in milliseconds.
+   */
+  computeTimeRemaining(state: SpringState): number;
 }
 /**
  * Direct physical parameters. You control stiffness and friction exactly;
@@ -126,12 +151,16 @@ declare function defineSpring(input: TensionDampingBounceOptions): SpringConfig;
 /**
  * Duration-based configuration. The spring is tuned so that its envelope
  * decays to the resting threshold within the given duration.
+ * Duration assumes a displacement of 1 by default — provide `displacement`
+ * to match your actual animation range for accurate timing.
  * Tension and damping are both derived from dampingRatio and duration.
  */
 declare function defineSpring(input: DurationOptions): SpringConfig;
 /**
  * Duration-based configuration. The spring is tuned so that its envelope
  * decays to the resting threshold within the given duration.
+ * Duration assumes a displacement of 1 by default — provide `displacement`
+ * to match your actual animation range for accurate timing.
  * Bounce controls how oscillatory the motion is while settling.
  * Tension and damping are both derived.
  */
@@ -139,23 +168,31 @@ declare function defineSpring(input: BounceDurationOptions): SpringConfig;
 /**
  * Duration-based with a tension constraint. Mass is derived from tension
  * and the computed natural frequency; damping follows from mass and dampingRatio.
+ * Duration assumes a displacement of 1 by default — provide `displacement`
+ * to match your actual animation range for accurate timing.
  */
 declare function defineSpring(input: TensionDurationOptions): SpringConfig;
 /**
  * Duration-based with a tension constraint. Bounce controls how oscillatory
  * the motion is while settling. Mass is derived from tension and the
  * computed natural frequency.
+ * Duration assumes a displacement of 1 by default — provide `displacement`
+ * to match your actual animation range for accurate timing.
  */
 declare function defineSpring(input: TensionBounceDurationOptions): SpringConfig;
 /**
  * Duration-based with a damping constraint. Mass is derived from damping,
  * dampingRatio, and the computed natural frequency; tension follows from mass.
+ * Duration assumes a displacement of 1 by default — provide `displacement`
+ * to match your actual animation range for accurate timing.
  */
 declare function defineSpring(input: DampingDurationOptions): SpringConfig;
 /**
  * Duration-based with a damping constraint. Bounce controls how oscillatory
  * the motion is while settling. Mass is derived from damping and the
  * computed natural frequency.
+ * Duration assumes a displacement of 1 by default — provide `displacement`
+ * to match your actual animation range for accurate timing.
  */
 declare function defineSpring(input: DampingBounceDurationOptions): SpringConfig;
 //#endregion
@@ -167,7 +204,8 @@ declare class Motion {
   set position(value: number);
   get velocity(): number;
   set velocity(value: number);
-  get resting(): boolean;
+  get timeRemaining(): number;
+  get isResting(): boolean;
   configure(config: SpringConfig): void;
   tick(dt: number, emit?: boolean): void;
   onUpdate(callback: () => void): () => void;
@@ -179,38 +217,94 @@ declare class Motion {
 //#region src/motion-set.d.ts
 declare class MotionSet {
   #private;
+  constructor(debug?: boolean);
   add(motion: Motion): void;
   remove(motion: Motion): void;
   tick(dt: number): void;
 }
 //#endregion
 //#region src/spring.d.ts
-interface DisplacedSpringPosition {
+interface SpringWithOffset {
+  spring: Spring;
+  offset?: number | undefined;
+}
+type SpringTarget = number | Spring | SpringWithOffset;
+interface StandaloneSpringPosition {
   target?: number | undefined;
   value?: number | undefined;
 }
-type SpringPosition = number | DisplacedSpringPosition;
+interface FollowingSpringPosition {
+  target: Spring | SpringWithOffset;
+  value?: number | undefined;
+}
+type SpringPosition = number | StandaloneSpringPosition | FollowingSpringPosition;
 declare class Spring {
   #private;
-  constructor(motions: MotionSet, position: SpringPosition, config: SpringConfig);
+  constructor(motions: MotionSet, position: SpringPosition, config?: SpringConfig);
   get target(): number;
-  set target(value: number);
+  set target(value: SpringTarget);
   get value(): number;
   set value(value: number);
   get velocity(): number;
   set velocity(value: number);
+  get config(): SpringConfig;
   get mass(): number;
   get tension(): number;
   get damping(): number;
   get dampingRatio(): number;
   get precision(): number;
-  get resting(): boolean;
   configure(config: SpringConfig): void;
+  clearConfigOverride(): void;
+  get timeRemaining(): number;
+  get isResting(): boolean;
+  jumpTo(value: number): void;
+  dispose(): void;
   onUpdate(callback: () => void): () => void;
   onStart(callback: () => void): () => void;
   onStop(callback: () => void): () => void;
-  jumpTo(value: number): void;
+}
+//#endregion
+//#region src/vector2.d.ts
+interface Vector2 {
+  x: number;
+  y: number;
+}
+//#endregion
+//#region src/spring2d.d.ts
+interface Spring2DWithOffset {
+  spring: Spring2D;
+  offset?: Vector2 | undefined;
+}
+type Spring2DTarget = Vector2 | Spring2D | Spring2DWithOffset;
+interface DisplacedSpring2DPosition {
+  target?: Spring2DTarget | undefined;
+  value?: Vector2 | undefined;
+}
+type Spring2DPosition = Vector2 | DisplacedSpring2DPosition;
+declare class Spring2D {
+  #private;
+  constructor(motions: MotionSet, position: Spring2DPosition, config?: SpringConfig);
+  get target(): Vector2;
+  set target(value: Spring2DTarget);
+  get value(): Readonly<Vector2>;
+  set value(value: Vector2);
+  get velocity(): Readonly<Vector2>;
+  set velocity(value: Vector2);
+  get config(): SpringConfig;
+  get mass(): number;
+  get tension(): number;
+  get damping(): number;
+  get dampingRatio(): number;
+  get precision(): number;
+  configure(config: SpringConfig): void;
+  clearConfigOverride(): void;
+  get timeRemaining(): number;
+  get isResting(): boolean;
+  jumpTo(value: Vector2): void;
   dispose(): void;
+  onUpdate(callback: () => void): () => void;
+  onStart(callback: () => void): () => void;
+  onStop(callback: () => void): () => void;
 }
 //#endregion
 //#region src/ticker.d.ts
@@ -239,8 +333,12 @@ interface TickerOptions {
 }
 //#endregion
 //#region src/system.d.ts
+interface SpringSystemOptions extends TickerOptions {
+  debug?: boolean | undefined;
+}
 interface SpringSystem {
-  createSpring(position: SpringPosition, config: SpringConfig): Spring;
+  createSpring(position: SpringPosition, config?: SpringConfig): Spring;
+  createSpring2D(position: Spring2DPosition, config?: SpringConfig): Spring2D;
   /** Advance all springs by `dt` milliseconds, without affecting internal timing. */
   advance(dt: number): void;
   /** Start the animation loop. */
@@ -249,28 +347,10 @@ interface SpringSystem {
   stop(): void;
   /** Whether the animation loop is currently running. */
   readonly running: boolean;
-  /**
-   * The target frames per second for the simulation loop.
-   *
-   * must be greater than 0
-   */
   fps: number;
-  /**
-   * The maximum elapsed time (in ms) before a frame is considered a lag spike
-   * (e.g. from a backgrounded tab). When exceeded, `adjustedLag` is used instead
-   * of the real elapsed time. Set to 0 to disable lag detection.
-   *
-   * must be greater than or equal to 0
-   */
   lagThreshold: number;
-  /**
-   * The substitute elapsed time (in ms) used when a lag spike is detected.
-   * Clamped to be at most `lagThreshold`.
-   *
-   * must be greater than or equal to 0
-   */
   adjustedLag: number;
 }
-declare function createSpringSystem(options?: TickerOptions): SpringSystem;
+declare function createSpringSystem(options?: SpringSystemOptions): SpringSystem;
 //#endregion
-export { SpringPosition as a, defineSpring as c, Spring as i, createSpringSystem as n, SpringConfig as o, TickerOptions as r, SpringOptions as s, SpringSystem as t };
+export { defineSpring as _, Spring2D as a, Spring2DWithOffset as c, SpringPosition as d, SpringTarget as f, SpringState as g, SpringOptions as h, TickerOptions as i, Vector2 as l, SpringConfig as m, SpringSystemOptions as n, Spring2DPosition as o, SpringWithOffset as p, createSpringSystem as r, Spring2DTarget as s, SpringSystem as t, Spring as u };

package/dist/vue.d.ts

@@ -1,31 +1,42 @@
-import { o as SpringConfig, s as SpringOptions, t as SpringSystem } from "./system-B_kZMcpg.js";
+import { h as SpringOptions, l as Vector2, m as SpringConfig, n as SpringSystemOptions, t as SpringSystem } from "./system-Do5rE0j7.js";
 import * as vue from "vue";
 import { App, MaybeRefOrGetter, Ref, SlotsType } from "vue";
 
 //#region src/vue/spring.d.ts
-interface UseSpringReturn {
-  readonly value: Ref<number>;
+type UseSpringOptions = MaybeRefOrGetter<SpringOptions | SpringConfig | undefined>;
+interface SpringRef extends Ref<number> {
   readonly velocity: Ref<number>;
-  readonly resting: Readonly<Ref<boolean>>;
+  readonly timeRemaining: Ref<number>;
+  readonly isResting: Ref<boolean>;
   readonly jumpTo: (value: number) => void;
 }
-declare function useSpring(target: MaybeRefOrGetter<number>, options?: MaybeRefOrGetter<SpringOptions | SpringConfig>): UseSpringReturn;
+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 };
+interface SpringRef2D extends Ref<Readonly<Vector2>> {
+  readonly velocity: Ref<Readonly<Vector2>>;
+  readonly timeRemaining: Ref<number>;
+  readonly isResting: Ref<boolean>;
+  readonly jumpTo: (value: Vector2) => void;
+}
+declare function useSpring2D(target: MaybeRefOrGetter<Vector2>, options?: UseSpringOptions): SpringRef2D;
+declare function useSpring2D(target: SpringRef2D, options?: UseSpringOptions): SpringRef2D;
 //#endregion
 //#region src/vue/component.d.ts
 interface SpringValueProps {
   target: number;
-  mass?: number;
-  tension?: number;
-  damping?: number;
-  precision?: number;
+  config?: SpringOptions | SpringConfig;
 }
 type SpringValueEmits = Record<string, never>;
+interface SpringValueSlotScope {
+  value: number;
+  velocity: number;
+  isResting: boolean;
+  timeRemaining: number;
+  jumpTo: (value: number) => void;
+}
 type SpringValueSlots = SlotsType<{
-  default: {
-    value: number;
-    velocity: number;
-    resting: boolean;
-  };
+  default: SpringValueSlotScope;
 }>;
 declare const SpringValue: vue.DefineSetupFnComponent<SpringValueProps, SpringValueEmits, SpringValueSlots, SpringValueProps & {
   [x: `on${Capitalize<string>}`]: ((...args: unknown[]) => any) | undefined;
@@ -33,6 +44,6 @@ declare const SpringValue: vue.DefineSetupFnComponent<SpringValueProps, SpringVa
 //#endregion
 //#region src/vue/system.d.ts
 declare function provideSpringSystem(system: SpringSystem, app?: App): void;
-declare function useSpringSystem(): void;
+declare function useSpringSystem(options?: SpringSystemOptions): void;
 //#endregion
-export { SpringValue, type SpringValueProps, type SpringValueSlots, provideSpringSystem, useSpring, useSpringSystem };
+export { type SpringRef, type SpringRef2D, SpringValue, type SpringValueProps, type SpringValueSlots, provideSpringSystem, useSpring, useSpring2D, useSpringSystem };