coily 0.12.2 → 0.13.1

package/README.md

@@ -1,254 +1,171 @@
-# `coily`
+# coily
 
-Spring Physics Utilities
+Simulate values using spring physics.
 
-## Installation & Setup
+Coily animates numbers — and whole numeric shapes — with damped spring motion. Each frame is computed from the closed-form solution of the spring equation — underdamped, critically damped, or overdamped — rather than numerical integration, so motion doesn't accumulate error and springs can be retargeted mid-flight without losing momentum.
 
-`coily` is available on npm and can be installed with your favorite package manager:
+The core has zero dependencies and runs anywhere (it falls back from `requestAnimationFrame` to `setTimeout` outside the browser). Vue and Nuxt integrations ship as separate entry points; `vue` and `@nuxt/kit` are optional peer dependencies.
 
-```shell
-$ yarn add coily
-# or
-$ npm i coily
-```
-
-Then import the creator from the package in your code:
-
-```typescript
-import { createSpring } from 'coily'
+## Install
 
-const spring = createSpring(0, { mass: 1, tension: 100, friction: 25 })
+```sh
+pnpm add coily
 ```
 
-## Usage
+## Quick start
 
-### Creating a Spring
+```ts
+import { createSpringSystem, defineSpring } from 'coily'
 
-The `createSpring` function takes the following arguments:
-
-- `initial: number`
-  The initial value of the spring, and its target. All springs start in a resting state, but you can set `spring.target`
-  at any time
-
-- `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`
+const system = createSpringSystem()
+system.start()
 
-  - `config.tension: number`
-    How much force the spring experiences toward its `target`. A higher value will move the spring more quickly, and
-    allow the spring to potentially overshoot.
+const spring = system.createSpring(0, defineSpring({ tension: 500, damping: 40 }))
 
-  - `config.friction: number`
-    How much dampening the spring experiences against its tension. A higher friction will make sure the spring doesn't
-    move too quickly, and slows down dramatically as it approaches the `target`
+spring.onUpdate(() => {
+  ball.style.setProperty('--x', String(spring.value))
+})
 
-- `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`
+// Animate toward a new target at any time. Position and velocity
+// carry over, so interruptions look natural.
+spring.target = 300
+```
 
-  - `options.restingVelocity: number`
-    The minimum velocity at which the spring will consider itself "not moving"
+## Configuring springs
 
-  - `options.arrivalBehavior: 'bounce' | 'clamp' | 'none' | number | ((velocity: number) => number)`
-    How the spring's `velocity` behaves when it arrives at its `target` value.
-    `velocity` is expressed in unit/second. Defaults to `none`.
-    - `'bounce'`: multiplies the velocity by -1, bouncing the value back in the direction from which it came
-    - `'clamp'`: multiplies the velocity by 0, instantly stopping the spring at its value
-    - `'none'`: multiplies the velocity by 1, allowing the spring to overshoot as necessary
-    - `number`: multiplies the velocity by the given number
-    - `(velocity: number) => number`: sets the velocity to the result of a function whose only argument is the
-      previous velocity
+`defineSpring` accepts several input shapes; whatever you leave out is derived:
 
-#### Spring Config Tips
+```ts
+defineSpring({ tension: 500, damping: 40 }) // direct physical parameters
+defineSpring({ tension: 500, dampingRatio: 0.7 }) // damping derived
+defineSpring({ tension: 500, bounce: 0.3 }) // bounce = 1 - dampingRatio
+defineSpring({ duration: 750, dampingRatio: 1 }) // tuned to settle in ~750ms
+defineSpring({ duration: 750, bounce: 0.5 })
+```
 
-The configuration object above provides a good starting point when picking your config:
+- **`tension`** — stiffness (> 0)
+- **`damping`** — friction (≥ 0)
+- **`dampingRatio`** — 0 = undamped, < 1 = bouncy, 1 = critically damped, > 1 = overdamped
+- **`bounce`** — friendlier alias for damping ratio: −1 (overdamped) to 1 (max bounce)
+- **`duration`** — target settle time in ms. Assumes an initial displacement of 1; pass `displacement` matching your animation range for accurate timing
+- **`mass`** — defaults to 1
+- **`precision`** — decimal places of the resting threshold (default 2). A spring is _resting_ once its remaining motion cannot reach half a unit in the last place — 0.005 at the default. Values are never rounded; set precision to match your domain's resolution (see [PRECISION.md](https://github.com/tkofh/coily/blob/main/PRECISION.md))
 
-```typescript
-createSpring(0, { mass: 1, tension: 100, friction: 25 })
-```
+Without a config, springs are critically damped with a ~500ms settle time.
 
-Don't be afraid to make `mass` a decimal, and don't be afraid of large tensions and frictions either. Picking the
-configuration is more of an art than a science.
+## Spring API
 
-#### Spring Options
+- `spring.target` — set to animate toward a new value
+- `spring.value` — current value; writable to displace the spring
+- `spring.velocity` — current velocity; writable to fling
+- `spring.jumpTo(v)` — snap to a value with no animation
+- `spring.config` — assign a new `SpringConfig`, or `null` to revert to the default (or the leader's, if following)
+- `spring.isResting`, `spring.timeRemaining` — settle state and estimated ms until rest
+- `spring.settled` — a promise that resolves when the spring next comes to rest (immediately if already resting). Retargeting mid-flight extends the wait; disposing resolves it. `await spring.settled` to sequence animations
+- `spring.onUpdate(cb)` / `onStart(cb)` / `onStop(cb)` / `onDispose(cb)` — subscribe; each returns an unsubscribe function. `start` fires when the spring leaves rest, `stop` when it settles — the two always alternate, and retargeting mid-flight fires neither
+- `spring.dispose()` — release the spring (calling it twice is a no-op)
 
-The spring options object is helpful in reducing the amount of computation your springs perform. If the spring was
-allowed to wait until its `velocity` and difference (`value` - `target`) were _at_ zero, it would imperceptibly update
-every frame for a very long time.
+### Chaining
 
-The `restingDistance` and `restingVelocity` options help combat this, by telling the spring at what point it should
-consider itself on target and resting. Once the velocity is less than `restingVelocity` and the difference
-between `value` and `target` is less than `restingDistance`, the spring sets its `value` to its `target` and enters
-the `resting` state.
+A spring can follow another spring's live value instead of a fixed number:
 
-### Working With Springs
+```ts
+const leader = system.createSpring(0)
+const follower = system.createSpring({ target: leader })
+const trailing = system.createSpring({ target: { spring: leader, offset: 20 } })
+```
 
-#### Reading Information
+Followers inherit the leader's config unless given their own. Assigning a number to `target` unfollows.
 
-The spring exposes some readonly information such as its `value`, `state` and `velocity`:
+### Objects
 
-```typescript
-/**
- * The current value of the spring
- */
-spring.value
+`system.createSpringObject(value, config?)` springs over any numeric shape — a plain object or array whose leaves are all numbers, nested arbitrarily. Each leaf becomes an independent channel behind one composite API:
 
-/**
- * In which state the spring is currently. Will be one of:
- * - "resting"
- * - "moving"
- * - "frozen"
- */
-spring.state
+```ts
+const spring = system.createSpringObject({ position: { x: 0, y: 0 }, opacity: 1 })
 
-/**
- * How fast the spring is currently moving, and in which direction
- */
-spring.velocity
+spring.target = { position: { x: 100 } } // partial — other channels are left alone
+spring.value // { position: { x, y }, opacity } — a stable, read-only mirror
 ```
 
-Additionally, `target` and `config` can be updated whenever:
-
-```typescript
-/**
- * Get & Set the target of the spring
- */
-console.log(spring.target)
-spring.target = 10
+The shape is fixed at creation, and unknown channels throw with their path (`position.z`). `value`, `velocity`, and `jumpTo` take the same partial shapes. Composite events are coalesced: `update` fires at most once per frame with every channel in its final per-frame state, and `stop` always lands after that frame's final `update`. `settled` and reduced motion compose channel-wise.
 
-/**
- * Get & Set the config of the spring
- */
-console.log(spring.config)
-spring.config = { mass: 0.1, tension: 500, friction: 5 }
-```
+Shapes are validated at compile time too (the `Shape` type — interfaces like your own `Vector2` work without index signatures): non-numeric, optional, or `undefined`-typed channels are rejected where they're declared.
 
-#### Updating
+Configs apply per channel. Pass a single `SpringConfig` for every channel, or a shape mirroring the value with configs (or `null` to revert) at any level — a config at a subtree covers every channel below it:
 
-To simulate the spring and update its value, call the `simulate` method and pass in the number of milliseconds since the
-last update:
+```ts
+spring.config = { position: stiff, opacity: defineSpring({ duration: 300, dampingRatio: 1 }) }
+```
 
-```typescript
-// Tickloop is a library that exposes a simple requestAnimationFrame based update loop
-import { createTicker } from 'tickloop'
-import { createSpring } from 'coily'
+Configs are `SpringConfig` instances — build them with `defineSpring`. Unlike the scalar `useSpring` above, config positions here don't accept bare option objects: a plain object is always a per-channel shape, so any non-config leaf it reaches throws with its path.
 
-const spring = createSpring(0, { mass: 1, tension: 100, friction: 20 })
+Spring objects chain channel-wise. Assign another spring object of the exact same shape (optionally with a partial offset shape), and a partial numeric target detaches only the channels it names:
 
-const ticker = createTicker()
-ticker.add((_, delta) => {
-  spring.simulate(delta)
-})
+```ts
+follower.target = leader
+trailing.target = { spring: leader, offset: { position: { x: 20 } } }
 ```
 
-#### Freezing
+## Reduced motion
 
-To hold a spring in place (while maintaining its velocity), use the `freeze()` (and `unfreeze()`) methods.
-Calling `freeze()` will set the spring's `state` to `'frozen'`
+Coily respects `prefers-reduced-motion` by default. When it's active, springs snap to their targets instead of animating: retargets and value writes apply instantly, velocity impulses are ignored, and springs created displaced start at their target. Events stay coherent — one `update` per change, no `start`/`stop`, and `settled` resolves immediately — so code written against the animated path keeps working.
 
-```typescript
-const spring = createSpring(0, { mass: 1, tension: 100, friction: 20 })
+Control it with the `reducedMotion` system option: `'user'` (default — follow the OS setting, including live changes, which finish in-flight animations instantly), `'always'`, or `'never'`. Read `system.reducedMotion` to gate purely decorative effects (particles, flourishes) in your own code.
 
-spring.target = 100
+## Vue
 
-console.log(spring.value) // 0
+Call `useSpringSystem()` once near the root of your app. It returns the spring system provided by this component or an ancestor; if none exists, it creates one, provides it to descendants, and starts/stops it with the component lifecycle. It's idempotent, and options apply only when a system is actually created:
 
-spring.freeze()
-spring.simulate(1000)
+```ts
+import { useSpringSystem } from 'coily/vue'
 
-console.log(spring.value) // 0
+const system = useSpringSystem() // e.g. read system.reducedMotion to gate decorative effects
 ```
 
-### Creating a Spring System
+(`provideSpringSystem(system, app?)` remains for plugging in a system you created yourself — mostly useful in tests. You manage `start()`/`stop()` for it.)
 
-Manually updating every spring with its `simulate` method would be tedious to say the least. Where possible, prefer
-using a `SpringSystem` to group springs together and provide a single call site for updating each spring:
+Then animate anywhere below:
 
-```typescript
-import { createSpringSystem } from 'coily'
+```vue
+<script setup>
+import { useSpring } from 'coily/vue'
 
-// First, create the system
-const system = createSpringSystem()
-
-// Then, create some springs
-const spring1 = system.createSpring(0, { mass: 1, tension: 100, friction: 20 })
-const spring2 = system.createSpring(0, { mass: 0.25, tension: 50, friction: 10 })
+const target = ref(0)
+const x = useSpring(target, { duration: 500, bounce: 0.3 })
+</script>
 
-// Simulate all springs at once from the system
-system.simulate(16)
+<template>
+  <div class="ball" :style="{ translate: `${x}px 0` }" @click="target = 300" />
+</template>
 ```
 
-Should a spring become irrelevant for some reason, remember to call the `cleanup` method so that the system stops
-updating it:
-
-```typescript
-import { createSpringSystem } from 'coily'
+`useSpring` returns a `SpringRef`: a writable ref of the animated value with `velocity`, `isResting`, and `timeRemaining` refs plus `jumpTo()` attached. The target can be a ref, a getter, or another `SpringRef` (which chains the springs). Options are also reactive — swap configs and the spring reconfigures in place.
 
-const system = createSpringSystem()
+Numeric shapes work the same way: pass a record or array (plain, ref, or getter) and get a `SpringObjectRef`. Reads are the deep-readonly composite value, writes take partial shapes, options accept reactive per-channel config shapes, and passing another `SpringObjectRef` follows it channel-wise. Deeply reactive targets retarget on nested mutation. For several _independent_ scalar springs, map over the targets — composables are loop-safe: `targets.map((t) => useSpring(t))`.
 
-const spring = system.createSpring(0, { mass: 1, tension: 100, friction: 20 })
+There's also a renderless `<SpringValue :target="n">` component exposing `{ value, velocity, isResting, timeRemaining, jumpTo }` through its default slot.
 
-// Later
+For imperative work — a dynamic set of springs created and disposed at arbitrary times (particles, per-item effects) — `useSpringPool()` returns `createSpring`/`createSpringObject` bound to the provided system. Every spring created through the pool is disposed automatically when the component's scope is torn down, so leaked motions are structurally impossible; disposing a spring manually before that is fine.
 
-system.cleanup(spring)
-```
+## Nuxt
 
-### Spring Chains
-
-Sometimes the `target` of one spring should be the `value` of another.
-This can be tedious to set up manually and involves juggling multiple updates per frame to get a good look at the
-current state.
-
-Spring Chains help with this problem by building on the `createSpring` API. You'll still supply an `initial` target,
-a `SpringConfig`, and an optional `SpringOptions`. You'll also pass an array of chain "links" that describe additional
-values in the chain.
-
-The links take one of two forms:
-
-- A fixed, additive offset from the previous value, e.g. `50` will make Spring 2 target Spring 1's current value plus 50.
-- A function with the following signature:
-  ```typescript
-  const link = (
-    previousSpringValue: number,
-    previousSpringTarget: number,
-    currentSpringValue?: number,
-    currentSpringTarget?: number
-  ): number => /* ... */
-  ```
-  The `currentSpringTarget` and `currentSpringValue` will be `undefined` the first time the function is called, as the
-  targets are initialized for all springs.
-
-#### Creating
-
-```typescript
-const chain = createSpringChain(
-  0, // initial
-  [50, 50, (value) => value * 1.25],
-  { mass: 10, tension: 3000, friction: 300 }, // config
-)
+```ts
+export default defineNuxtConfig({
+  modules: ['coily/nuxt'],
+  coily: {
+    debug: false, // debug logs active motion counts
+    reducedMotion: 'user', // 'user' | 'always' | 'never'
+  },
+})
 ```
 
-#### Reading State
+The module provides a spring system for the whole app (started on the client), auto-imports `useSpring`, `useSpringSystem`, `useSpringPool`, and `defineSpring`, and registers the `SpringValue` component.
 
-Spring Chains have almost the same interface as Springs do.
+## Timing
 
-Instead of a single `value`, they have an array of numbers as their value. The same goes for `targets`, `states`,
-and `velocities`. Each of these arrays are updated _in place_, which means it is safe to grab a reference to the value
-and read from it later.
+The built-in ticker advances springs once per displayed frame, so motion is as smooth as the screen it runs on — 60Hz, 120Hz, or adaptive sync. The loop sleeps while every spring is at rest (an idle system schedules no frames) and wakes on the next write. Set `fps` (option/property) to cap the rate; caps are paced to whole display frames, and each tick still receives the true elapsed time. Large frame gaps — e.g. returning from a backgrounded tab — are clamped via `lagThreshold` (default 500ms) and `adjustedLag` (default 33ms), so springs don't teleport. For manual stepping, skip `system.start()` and call `system.advance(dtMs)` yourself.
 
-Additionally, Spring Chains have a singular `state` property which indicates if _any_ of its links are in a `'moving'` state or not.
+## License
 
-There is also a singular `target` property which returns the first target in the chain. Setting this will update the springs as well.
-
-```typescript
-chain.values // readonly number[]
-chain.velocities // readonly number[]
-chain.targets // readonly number[]
-chain.states // readonly number[]
-
-chain.target = 10 // get and set the first target
-chain.state // if any children are 'moving', this will be moving. if the chain is frozen, it will be 'frozen'. otherwise, it is 'resting'.
-```
+MIT

package/dist/index.d.ts

@@ -1,2 +1,2 @@
-import { _ as defineSpring, a as Spring2D, c as Spring2DWithOffset, d as SpringPosition, f as SpringTarget, g as SpringState, h as SpringOptions, i as TickerOptions, l as Vector2, m as SpringConfig, n as SpringSystemOptions, o as Spring2DPosition, p as SpringWithOffset, r as createSpringSystem, s as Spring2DTarget, t as SpringSystem, u as Spring } from "./system-coAFNYnb.js";
-export { type Spring, type Spring2D, type Spring2DPosition, type Spring2DTarget, type Spring2DWithOffset, type SpringConfig, type SpringOptions, type SpringPosition, type SpringState, type SpringSystem, type SpringSystemOptions, type SpringTarget, type SpringWithOffset, type TickerOptions, type Vector2, createSpringSystem, defineSpring };
+import { _ as SpringOptions, a as ConfigShape, c as Shape, d as SpringObjectWithOffset, f as Spring, g as SpringConfig, h as SpringWithOffset, i as TickerOptions, l as SpringObject, m as SpringTarget, n as SpringSystemOptions, o as PartialShape, p as SpringPosition, r as createSpringSystem, s as ReadonlyShape, t as SpringSystem, u as SpringObjectTarget, v as SpringState, y as defineSpring } from "./system-86fsXJN_.js";
+export { type ConfigShape, type PartialShape, type ReadonlyShape, type Shape, type Spring, type SpringConfig, type SpringObject, type SpringObjectTarget, type SpringObjectWithOffset, type SpringOptions, type SpringPosition, type SpringState, type SpringSystem, type SpringSystemOptions, type SpringTarget, type SpringWithOffset, type TickerOptions, createSpringSystem, defineSpring };

package/dist/index.js

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

package/dist/nuxt.d.ts

@@ -1,8 +1,11 @@
 import { NuxtModule } from "@nuxt/schema";
-
 //#region src/vue/nuxt.d.ts
 interface CoilyModuleOptions {
   debug?: boolean;
+  fps?: number;
+  lagThreshold?: number;
+  adjustedLag?: number;
+  reducedMotion?: 'user' | 'always' | 'never';
 }
 declare const coilyModule: NuxtModule;
 //#endregion

package/dist/nuxt.js

@@ -1,12 +1,18 @@
 import { addComponent, addImports, addPluginTemplate, defineNuxtModule } from "@nuxt/kit";
 //#region src/vue/nuxt.ts
 function getPluginTemplate(options) {
+	const systemOptions = {};
+	if (options.debug) systemOptions.debug = true;
+	if (options.fps !== void 0) systemOptions.fps = options.fps;
+	if (options.lagThreshold !== void 0) systemOptions.lagThreshold = options.lagThreshold;
+	if (options.adjustedLag !== void 0) systemOptions.adjustedLag = options.adjustedLag;
+	if (options.reducedMotion) systemOptions.reducedMotion = options.reducedMotion;
 	return `import { createSpringSystem } from 'coily'
 import { provideSpringSystem } from 'coily/vue'
 
 export default defineNuxtPlugin((nuxtApp) => {
   nuxtApp.hook('app:created', (vueApp) => {
-    const system = createSpringSystem(${options.debug ? "{ debug: true }" : ""})
+    const system = createSpringSystem(${Object.keys(systemOptions).length > 0 ? JSON.stringify(systemOptions) : ""})
     provideSpringSystem(system, vueApp)
 
     if(import.meta.client) {
@@ -35,7 +41,11 @@ const coilyModule = defineNuxtModule({
 			},
 			{
 				from: "coily/vue",
-				name: "useSpring2D"
+				name: "useSpringSystem"
+			},
+			{
+				from: "coily/vue",
+				name: "useSpringPool"
 			},
 			{
 				from: "coily/vue",
@@ -44,7 +54,12 @@ const coilyModule = defineNuxtModule({
 			},
 			{
 				from: "coily/vue",
-				name: "SpringRef2D",
+				name: "SpringObjectRef",
+				type: true
+			},
+			{
+				from: "coily/vue",
+				name: "SpringPool",
 				type: true
 			},
 			{