coily 0.10.1 → 0.11.0

package/README.md

@@ -32,7 +32,6 @@ The `createSpring` function takes the following arguments:
 
 - `config: SpringConfig`
   The configuration for the spring. `SpringConfig` takes the following parameters:
-
   - `config.mass: number`
     How massive the spring is. A lower number will allow the spring to speed up and slow down more quickly than a
     larger number. Larger numbers are more likely to overshoot the `target`
@@ -47,7 +46,6 @@ The `createSpring` function takes the following arguments:
 
 - `options: SpringOptions`
   Additional options for the spring. `SpringOptions` takes the following parameters:
-
   - `options.restingDistance: number`
     The minimum difference between the `target` and `value` at which the spring will consider itself "at" the `target`
 
@@ -229,7 +227,7 @@ The links take one of two forms:
 const chain = createSpringChain(
   0, // initial
   [50, 50, (value) => value * 1.25],
-  { mass: 10, tension: 3000, friction: 300 } // config
+  { mass: 10, tension: 3000, friction: 300 }, // config
 )
 ```
 

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+import { a as SpringPosition, c as defineSpring, i as Spring, n as createSpringSystem, o as SpringConfig, r as TickerOptions, s as SpringOptions, t as SpringSystem } from "./system-B_kZMcpg.js";
+export { type Spring, type SpringConfig, type SpringOptions, type SpringPosition, type SpringSystem, type TickerOptions, createSpringSystem, defineSpring };

package/dist/index.js

@@ -0,0 +1,2 @@
+import { r as defineSpring, t as createSpringSystem } from "./system-Dxxv4ee7.js";
+export { createSpringSystem, defineSpring };

package/dist/nuxt.d.ts

@@ -0,0 +1,6 @@
+import { NuxtModule } from "@nuxt/schema";
+
+//#region src/vue/nuxt.d.ts
+declare const coilyModule: NuxtModule;
+//#endregion
+export { coilyModule as default };

package/dist/nuxt.js

@@ -0,0 +1,44 @@
+import { addComponent, addImports, addPluginTemplate, defineNuxtModule } from "@nuxt/kit";
+//#region src/vue/nuxt.ts
+const pluginTemplate = `import { createSpringSystem } from 'coily'
+import { provideSpringSystem } from 'coily/vue'
+
+export default defineNuxtPlugin((nuxtApp) => {
+  nuxtApp.hook('app:created', (vueApp) => {
+    const system = createSpringSystem()
+    provideSpringSystem(system, vueApp)
+
+    if(import.meta.client) {
+      system.start()
+    }
+  })
+})`;
+const coilyModule = defineNuxtModule({
+	meta: {
+		name: "coily",
+		configKey: "coily"
+	},
+	async setup() {
+		addPluginTemplate({
+			name: "coily",
+			filename: "coily.plugin.mjs",
+			mode: "all",
+			getContents: () => pluginTemplate
+		});
+		addImports([{
+			from: "coily/vue",
+			name: "useSpring"
+		}, {
+			from: "coily",
+			name: "defineSpring"
+		}]);
+		addComponent({
+			name: "SpringValue",
+			filePath: "coily/vue",
+			export: "SpringValue",
+			chunkName: "placement"
+		});
+	}
+});
+//#endregion
+export { coilyModule as default };

package/dist/system-B_kZMcpg.d.ts

@@ -0,0 +1,276 @@
+//#region src/config.d.ts
+interface BaseOptions {
+  /**
+   * Mass of the spring system.
+   * @default 1
+   */
+  mass?: number | undefined;
+  /**
+   * Precision for resting threshold.
+   * @default 2
+   */
+  precision?: number | undefined;
+}
+interface WithTension {
+  /**
+   * Spring stiffness coefficient.
+   * Must be greater than 0.
+   */
+  tension: number;
+}
+interface WithDamping {
+  /**
+   * Viscous damping coefficient.
+   * Must be greater than or equal to 0.
+   */
+  damping: number;
+}
+interface WithDampingRatio {
+  /**
+   * Ratio of damping to critical damping (0 = undamped, 1 = critically damped).
+   * Must be greater than or equal to 0.
+   */
+  dampingRatio: number;
+}
+interface WithBounce {
+  /**
+   * Bounciness of the spring. Converted to dampingRatio as `1 - bounce`.
+   * [-1, 1]
+   */
+  bounce: number;
+}
+interface WithDuration {
+  /**
+   * Target settle duration in milliseconds.
+   * Must be greater than 0.
+   */
+  duration: number;
+}
+interface WithDisplacement {
+  /**
+   * Initial displacement used for duration-based envelope calculation.
+   * @default 1
+   */
+  displacement?: number | undefined;
+}
+interface DirectOptions extends BaseOptions, WithTension, WithDamping {}
+interface TensionRatioOptions extends BaseOptions, WithTension, WithDampingRatio {}
+interface TensionBounceOptions extends BaseOptions, WithTension, WithBounce {}
+interface DampingRatioOptions extends BaseOptions, WithDamping, WithDampingRatio {}
+interface DampingBounceOptions extends BaseOptions, WithDamping, WithBounce {}
+interface TensionDampingRatioOptions extends BaseOptions, WithTension, WithDamping, WithDampingRatio {}
+interface TensionDampingBounceOptions extends BaseOptions, WithTension, WithDamping, WithBounce {}
+interface DurationOptions extends BaseOptions, WithDampingRatio, WithDuration, WithDisplacement {}
+interface BounceDurationOptions extends BaseOptions, WithBounce, WithDuration, WithDisplacement {}
+interface TensionDurationOptions extends BaseOptions, WithTension, WithDampingRatio, WithDuration, WithDisplacement {}
+interface TensionBounceDurationOptions extends BaseOptions, WithTension, WithBounce, WithDuration, WithDisplacement {}
+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 {
+  readonly mass: number;
+  readonly tension: number;
+  readonly damping: number;
+  readonly precision: number;
+  readonly naturalFrequency: number;
+  readonly criticalDamping: number;
+  readonly dampingRatio: number;
+  readonly precisionMultiplier: number;
+  readonly restingMagnitude: number;
+  constructor(input: SpringOptions);
+}
+/**
+ * Direct physical parameters. You control stiffness and friction exactly;
+ * mass defaults to 1.
+ */
+declare function defineSpring(input: DirectOptions): SpringConfig;
+/**
+ * Tension sets the stiffness; dampingRatio controls oscillation character
+ * (0 = undamped, 1 = critically damped, >1 = overdamped).
+ * Damping is derived as `2 * dampingRatio * sqrt(mass * tension)`.
+ */
+declare function defineSpring(input: TensionRatioOptions): SpringConfig;
+/**
+ * Tension sets the stiffness; bounce controls how oscillatory the spring is,
+ * from -1 (overdamped, no oscillation) to 1 (maximum bounce).
+ * Damping is derived to match the requested bounciness.
+ */
+declare function defineSpring(input: TensionBounceOptions): SpringConfig;
+/**
+ * Damping is given directly; dampingRatio is used to derive tension
+ * as `damping² / (4 * dampingRatio² * mass)`.
+ * dampingRatio must be greater than 0.
+ */
+declare function defineSpring(input: DampingRatioOptions): SpringConfig;
+/**
+ * Damping is given directly; bounce controls how oscillatory the spring is.
+ * Tension is derived to match the requested bounciness.
+ * bounce must be less than 1.
+ */
+declare function defineSpring(input: DampingBounceOptions): SpringConfig;
+/**
+ * All three physical knobs specified — mass is derived
+ * as `damping² / (4 * dampingRatio² * tension)`.
+ * dampingRatio must be greater than 0.
+ */
+declare function defineSpring(input: TensionDampingRatioOptions): SpringConfig;
+/**
+ * All three physical knobs specified — mass is derived
+ * from tension, damping, and the requested bounciness.
+ * bounce must be less than 1.
+ */
+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.
+ * 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.
+ * Bounce controls how oscillatory the motion is while settling.
+ * Tension and damping are both derived.
+ */
+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.
+ */
+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.
+ */
+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.
+ */
+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.
+ */
+declare function defineSpring(input: DampingBounceDurationOptions): SpringConfig;
+//#endregion
+//#region src/motion.d.ts
+declare class Motion {
+  #private;
+  constructor(config: SpringConfig, position: number, velocity: number);
+  get position(): number;
+  set position(value: number);
+  get velocity(): number;
+  set velocity(value: number);
+  get resting(): boolean;
+  configure(config: SpringConfig): void;
+  tick(dt: number, emit?: boolean): void;
+  onUpdate(callback: () => void): () => void;
+  onStart(callback: () => void): () => void;
+  onStop(callback: () => void): () => void;
+  dispose(): void;
+}
+//#endregion
+//#region src/motion-set.d.ts
+declare class MotionSet {
+  #private;
+  add(motion: Motion): void;
+  remove(motion: Motion): void;
+  tick(dt: number): void;
+}
+//#endregion
+//#region src/spring.d.ts
+interface DisplacedSpringPosition {
+  target?: number | undefined;
+  value?: number | undefined;
+}
+type SpringPosition = number | DisplacedSpringPosition;
+declare class Spring {
+  #private;
+  constructor(motions: MotionSet, position: SpringPosition, config: SpringConfig);
+  get target(): number;
+  set target(value: number);
+  get value(): number;
+  set value(value: number);
+  get velocity(): number;
+  set velocity(value: number);
+  get mass(): number;
+  get tension(): number;
+  get damping(): number;
+  get dampingRatio(): number;
+  get precision(): number;
+  get resting(): boolean;
+  configure(config: SpringConfig): void;
+  onUpdate(callback: () => void): () => void;
+  onStart(callback: () => void): () => void;
+  onStop(callback: () => void): () => void;
+  jumpTo(value: number): void;
+  dispose(): void;
+}
+//#endregion
+//#region src/ticker.d.ts
+interface TickerOptions {
+  /**
+   * The target frames per second for the simulation loop
+   *
+   * must be greater than 0, defaults to 60
+   */
+  fps?: number | undefined;
+  /**
+   * 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, defaults to 500
+   */
+  lagThreshold?: number | undefined;
+  /**
+   * 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, defaults to 33
+   */
+  adjustedLag?: number | undefined;
+}
+//#endregion
+//#region src/system.d.ts
+interface SpringSystem {
+  createSpring(position: SpringPosition, config: SpringConfig): Spring;
+  /** Advance all springs by `dt` milliseconds, without affecting internal timing. */
+  advance(dt: number): void;
+  /** Start the animation loop. */
+  start(): void;
+  /** Stop the animation loop. */
+  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;
+//#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 };