coily 0.14.0 → 0.16.0

package/dist/config-B8M2xp26.d.ts

@@ -0,0 +1,295 @@
+//#region src/config.d.ts
+/**
+ * A spring's instantaneous motion, measured relative to its target.
+ * `SpringDefinition.computeTimeRemaining` takes one. Build it from a live
+ * spring as `{ position: spring.value - spring.target, velocity: spring.velocity }`.
+ */
+interface SpringState {
+  /** Displacement from the target in value units. 0 means at the target. */
+  readonly position: number;
+  /** Rate of change of the displacement, in value units per second. */
+  readonly velocity: number;
+}
+interface BaseOptions {
+  /**
+   * Decimal places of the resting threshold. A spring rests once its
+   * remaining motion fits within `0.5 * 10^-precision` (0.005 at the
+   * default). Values are never rounded.
+   *
+   * Duration configs are tuned against this threshold, so they rest at
+   * their `duration` at any precision. See
+   * https://github.com/tkofh/coily/blob/main/PRECISION.md.
+   *
+   * @default 2
+   */
+  readonly precision?: number | undefined;
+  /**
+   * Velocity multiplier applied each time the value crosses the target.
+   *
+   * - `'passthrough'` (1) leaves the motion alone. The value swings
+   *   through the target and settles as its damping allows.
+   * - `'stop'` (0) ends the motion at the first crossing, with no
+   *   overshoot however bouncy the config.
+   * - A number between -1 and 1 sets the multiplier directly. Negative
+   *   values rebound. `-0.75` reverses at three quarters speed on every
+   *   return. Values between 0 and 1 pass through slower.
+   *
+   * A motion that never crosses ignores `arrival`. With `dampingRatio` 1
+   * or above (`bounce` 0 or below), a spring retargeted from rest closes
+   * in from one side. It crosses only when it starts with enough velocity
+   * toward the target, or when the target moves past it.
+   *
+   * Crossings are solved exactly, never sampled per frame, so `'stop'`
+   * lands exactly on the target at any frame timing. See
+   * https://github.com/tkofh/coily/blob/main/PRECISION.md.
+   *
+   * @default 'passthrough'
+   */
+  readonly arrival?: 'passthrough' | 'stop' | number | undefined;
+}
+interface WithMass {
+  /**
+   * Mass of the moving value. Heavier springs accelerate more slowly and
+   * carry more momentum through the target. Must be greater than 0.
+   * @default 1
+   */
+  readonly mass?: number | undefined;
+}
+interface WithoutMass {
+  /** Derived from the other parameters in this input shape. Cannot be provided. */
+  readonly mass?: undefined;
+}
+interface WithTension {
+  /**
+   * Spring stiffness. Higher tension pulls toward the target harder,
+   * making the whole motion faster. Must be greater than 0.
+   */
+  readonly tension: number;
+}
+interface WithDamping {
+  /**
+   * Friction strength. Higher damping removes velocity faster and
+   * reduces bounce. At 0 the spring oscillates forever. Must be greater
+   * than or equal to 0.
+   */
+  readonly damping: number;
+}
+interface WithDampingRatio {
+  /**
+   * Damping as a fraction of critical damping, the friction at which
+   * bounce disappears. It sets the motion's character independent of its
+   * speed. Below 1 the spring bounces, and at 0 it never settles. At 1 it
+   * settles fastest without overshooting. Above 1 it settles slower, still
+   * without overshooting. Must be greater than or equal to 0.
+   */
+  readonly dampingRatio: number;
+}
+interface WithBounce {
+  /**
+   * Bounciness, converted to a damping ratio as `1 - bounce`. 0 settles
+   * fastest without overshooting. Positive values bounce. Negative values
+   * settle slower without bouncing. At 1 the ratio clamps just short of
+   * undamped, so the spring still settles. Must be between -1 and 1, and
+   * below 1 in a config that sets `damping` without `duration`.
+   */
+  readonly bounce: number;
+}
+interface WithDuration {
+  /**
+   * Settle time in ms. Starting `displacement` away from the target, the
+   * spring rests within a frame of it at any `precision`. A bouncy config
+   * can rest earlier, by up to about one oscillation (several short ones
+   * when `bounce` is near 1). Must be greater than 0.
+   */
+  readonly duration: number;
+}
+interface WithDisplacement {
+  /**
+   * The starting distance from the target that the `duration` tuning
+   * assumes. Set it to your animation's range (300 when animating 0 to
+   * 300). Timing drifts as the real distance departs from it. The sign is
+   * ignored. The magnitude must exceed the resting threshold,
+   * `0.5 * 10^-precision`.
+   * @default 1
+   */
+  readonly displacement?: number | undefined;
+}
+interface DirectOptions extends BaseOptions, WithMass, WithTension, WithDamping {}
+interface TensionRatioOptions extends BaseOptions, WithMass, WithTension, WithDampingRatio {}
+interface TensionBounceOptions extends BaseOptions, WithMass, WithTension, WithBounce {}
+interface DampingRatioOptions extends BaseOptions, WithMass, WithDamping, WithDampingRatio {}
+interface DampingBounceOptions extends BaseOptions, WithMass, WithDamping, WithBounce {}
+interface TensionDampingRatioOptions extends BaseOptions, WithoutMass, WithTension, WithDamping, WithDampingRatio {}
+interface TensionDampingBounceOptions extends BaseOptions, WithoutMass, WithTension, WithDamping, WithBounce {}
+interface DurationOptions extends BaseOptions, WithMass, WithDampingRatio, WithDuration, WithDisplacement {}
+interface BounceDurationOptions extends BaseOptions, WithMass, WithBounce, WithDuration, WithDisplacement {}
+interface TensionDurationOptions extends BaseOptions, WithoutMass, WithTension, WithDampingRatio, WithDuration, WithDisplacement {}
+interface TensionBounceDurationOptions extends BaseOptions, WithoutMass, WithTension, WithBounce, WithDuration, WithDisplacement {}
+interface DampingDurationOptions extends BaseOptions, WithoutMass, WithDamping, WithDampingRatio, WithDuration, WithDisplacement {}
+interface DampingBounceDurationOptions extends BaseOptions, WithoutMass, WithDamping, WithBounce, WithDuration, WithDisplacement {}
+/** Every option key accepted by at least one `defineSpring` input shape. */
+type SpringOptionKeys = 'mass' | 'tension' | 'damping' | 'dampingRatio' | 'bounce' | 'duration' | 'displacement' | 'precision' | 'arrival';
+/**
+ * Marks every option key foreign to `T` as absent or undefined, so mixing
+ * keys from different input shapes fails to type-check.
+ */
+type Exact<T> = T & { [K in Exclude<SpringOptionKeys, keyof T>]?: undefined; };
+/**
+ * Every input `defineSpring` accepts: one of the documented parameter
+ * combinations, with no keys mixed in from another.
+ */
+type SpringDefinitionOptions = Exact<DirectOptions> | Exact<TensionRatioOptions> | Exact<TensionBounceOptions> | Exact<DampingRatioOptions> | Exact<DampingBounceOptions> | Exact<TensionDampingRatioOptions> | Exact<TensionDampingBounceOptions> | Exact<DurationOptions> | Exact<BounceDurationOptions> | Exact<TensionDurationOptions> | Exact<TensionBounceDurationOptions> | Exact<DampingDurationOptions> | Exact<DampingBounceDurationOptions>;
+/**
+ * Resolved spring parameters, frozen and safe to share between springs.
+ * Whatever `defineSpring` input shape produced it, a config has concrete
+ * `mass`, `tension`, `damping`, `precision`, and `arrival`, plus the
+ * quantities derived from them. To change a spring's behavior, assign a
+ * new config to `spring.config`.
+ */
+declare class SpringDefinition {
+  /** The config for springs created without one: critically damped, settling in about 500ms. */
+  static readonly default: SpringDefinition;
+  /** Mass of the moving value, as provided or derived. */
+  readonly mass: number;
+  /** Spring stiffness, as provided or derived. */
+  readonly tension: number;
+  /** Friction strength, as provided or derived. */
+  readonly damping: number;
+  /** Decimal places of the resting threshold. See `restingMagnitude`. */
+  readonly precision: number;
+  /**
+   * Velocity multiplier applied each time the value crosses the target.
+   * `'passthrough'` resolves to 1, which leaves the motion untouched.
+   * `'stop'` resolves to 0, which ends it at the target. Negative values
+   * rebound.
+   */
+  readonly arrival: number;
+  /** Oscillation rate with no damping: `sqrt(tension / mass)`, in radians per second. */
+  readonly naturalFrequency: number;
+  /** The damping at which bounce disappears: `2 * mass * naturalFrequency`. */
+  readonly criticalDamping: number;
+  /**
+   * `damping / criticalDamping`. Below 1 the spring bounces. At 1 it
+   * settles fastest without overshooting. Above 1 it settles slower.
+   */
+  readonly dampingRatio: number;
+  /** Resting threshold in value units, `0.5 * 10^-precision`. */
+  readonly restingMagnitude: number;
+  constructor(input: SpringDefinitionOptions);
+  /**
+   * Computes the time in ms until a spring with this config rests from
+   * `state`, solved exactly from the motion's decay bound. The spring
+   * rests at the first tick at or after it.
+   *
+   * An underdamped spring can also rest earlier, on a frame that samples
+   * a dip in its pulsing rest amplitude, so read the result as "no later
+   * than". The motion an early rest cuts off never leaves the resting
+   * threshold. See https://github.com/tkofh/coily/blob/main/PRECISION.md.
+   *
+   * Returns 0 when `state` is already inside the resting threshold.
+   * Returns Infinity when the motion never settles: a `dampingRatio` of 0
+   * whose `arrival` neither stops nor slows it. With `arrival` 0, the
+   * result is capped at the first target crossing, where the spring rests
+   * exactly. Other multipliers fold their per-crossing velocity loss into
+   * the time.
+   */
+  computeTimeRemaining(state: SpringState): number;
+}
+/** Creates a config with stiffness (`tension`) and friction (`damping`) set directly. */
+declare function defineSpring(input: Exact<DirectOptions>): SpringDefinition;
+/**
+ * Creates a config from stiffness and motion character. Damping is
+ * derived as `2 * dampingRatio * sqrt(mass * tension)`.
+ */
+declare function defineSpring(input: Exact<TensionRatioOptions>): SpringDefinition;
+/**
+ * Creates a config from stiffness and bounciness. Damping is derived to
+ * match the requested bounce, from -1 (no bounce, slow settle) to 1
+ * (maximum bounce).
+ */
+declare function defineSpring(input: Exact<TensionBounceOptions>): SpringDefinition;
+/**
+ * Creates a config from friction and motion character. Tension is
+ * derived as `damping^2 / (4 * dampingRatio^2 * mass)`. `dampingRatio`
+ * must be greater than 0.
+ */
+declare function defineSpring(input: Exact<DampingRatioOptions>): SpringDefinition;
+/**
+ * Creates a config from friction and bounciness, deriving tension.
+ * `bounce` must be less than 1, since the derived tension grows without
+ * limit as it nears 1.
+ */
+declare function defineSpring(input: Exact<DampingBounceOptions>): SpringDefinition;
+/**
+ * Creates a config from all three physical parameters. Mass is derived
+ * as `damping^2 / (4 * dampingRatio^2 * tension)` and cannot be
+ * provided. `dampingRatio` must be greater than 0.
+ */
+declare function defineSpring(input: Exact<TensionDampingRatioOptions>): SpringDefinition;
+/**
+ * Creates a config from tension, damping, and bounce. Mass is derived and
+ * cannot be provided. `bounce` must be less than 1, since the derived
+ * mass grows without limit as it nears 1.
+ */
+declare function defineSpring(input: Exact<TensionDampingBounceOptions>): SpringDefinition;
+/**
+ * Tunes the spring to rest at `duration` ms, deriving tension and
+ * damping. `dampingRatio` sets the motion's character and must be
+ * greater than 0.
+ *
+ * The timing assumes the motion starts `displacement` (default 1) away
+ * from the target. Pass your animation's range for accurate timing.
+ *
+ * @example
+ * ```ts
+ * // Tuned for a 300px move. Rests within 750ms.
+ * defineSpring({ duration: 750, dampingRatio: 1, displacement: 300 })
+ * ```
+ */
+declare function defineSpring(input: Exact<DurationOptions>): SpringDefinition;
+/**
+ * Tunes the spring to rest at `duration` ms, deriving tension and
+ * damping. `bounce` sets how oscillatory the settling motion is.
+ *
+ * The timing assumes the motion starts `displacement` (default 1) away
+ * from the target. Pass your animation's range for accurate timing.
+ */
+declare function defineSpring(input: Exact<BounceDurationOptions>): SpringDefinition;
+/**
+ * Tunes a spring of the given stiffness to rest at `duration` ms. Mass is
+ * derived to meet the timing, then damping from mass and `dampingRatio`.
+ * Mass cannot be provided, and `dampingRatio` must be greater than 0.
+ *
+ * The timing assumes the motion starts `displacement` (default 1) away
+ * from the target. Pass your animation's range for accurate timing.
+ */
+declare function defineSpring(input: Exact<TensionDurationOptions>): SpringDefinition;
+/**
+ * Tunes a spring of the given stiffness to rest at `duration` ms, with
+ * `bounce` setting how oscillatory the settling motion is. Mass is
+ * derived to meet the timing and cannot be provided.
+ *
+ * The timing assumes the motion starts `displacement` (default 1) away
+ * from the target. Pass your animation's range for accurate timing.
+ */
+declare function defineSpring(input: Exact<TensionBounceDurationOptions>): SpringDefinition;
+/**
+ * Tunes a spring of the given friction to rest at `duration` ms. Mass is
+ * derived to meet the timing, then tension from mass. Mass cannot be
+ * provided, and `dampingRatio` must be greater than 0.
+ *
+ * The timing assumes the motion starts `displacement` (default 1) away
+ * from the target. Pass your animation's range for accurate timing.
+ */
+declare function defineSpring(input: Exact<DampingDurationOptions>): SpringDefinition;
+/**
+ * Tunes a spring of the given friction to rest at `duration` ms, with
+ * `bounce` setting how oscillatory the settling motion is. Mass is
+ * derived to meet the timing and cannot be provided.
+ *
+ * The timing assumes the motion starts `displacement` (default 1) away
+ * from the target. Pass your animation's range for accurate timing.
+ */
+declare function defineSpring(input: Exact<DampingBounceDurationOptions>): SpringDefinition;
+//#endregion
+export { defineSpring as i, SpringDefinitionOptions as n, SpringState as r, SpringDefinition as t };

package/dist/css.d.ts

@@ -0,0 +1,203 @@
+import { r as SpringState, t as SpringDefinition } from "./config-B8M2xp26.js";
+//#region src/css.d.ts
+interface LinearEasingOptions {
+  /**
+   * The size of the move the easing is timed for, in value units. A larger
+   * move takes longer to come within the fixed rest threshold, so it gets a
+   * longer duration, different `linear()` stop percentages, and possibly a
+   * different stop count. The keyframe helpers (`springToWaapi`,
+   * `springToCss`, `springToTransition`) default it to the largest move
+   * among their specs.
+   * @default 1
+   */
+  readonly displacement?: number;
+  /**
+   * The largest output error allowed in the piecewise-linear
+   * approximation, in progress units (0 at the start, 1 at the target). A
+   * smaller value keeps more stops.
+   * @default 0.0025
+   */
+  readonly maxError?: number;
+  /**
+   * The longest duration to generate, in ms. It cuts off configs with so
+   * little damping (friction) that they take very long to settle. A
+   * `'loop'` easing ignores the cap and lasts one half period.
+   * @default 10000
+   */
+  readonly maxDuration?: number;
+}
+interface EasingBase {
+  /** A CSS `linear()` easing string. */
+  readonly easing: string;
+  /** Duration to pair the easing with, in ms. */
+  readonly duration: number;
+  /** Number of stops in the easing (diagnostic). */
+  readonly stops: number;
+  /** The largest error of `easing` against the dense samples (diagnostic). */
+  readonly maxError: number;
+}
+/** The easing of a spring that comes to rest: play it once over `duration`. */
+interface SettlingEasing extends EasingBase {
+  readonly mode: 'settle';
+}
+/**
+ * The easing of a spring that never rests: an undamped oscillation (no
+ * friction), expressed as an infinite loop. Animate the property between
+ * its two swing extremes, `from` and `2 * target - from`, with the target
+ * at the 50% midpoint. Use `animation-iteration-count: infinite` and
+ * `animation-direction: alternate`. `duration` is one half period, in ms.
+ */
+interface LoopingEasing extends EasingBase {
+  readonly mode: 'loop';
+  readonly direction: 'alternate';
+  readonly iterations: 'infinite';
+}
+type LinearEasing = SettlingEasing | LoopingEasing;
+/**
+ * Turns a spring config into a CSS `linear()` easing and the duration in
+ * ms to pair it with. A settling config returns a `'settle'` easing. A
+ * pure undamped config (`dampingRatio: 0` with passthrough `arrival`)
+ * never settles and returns a `'loop'` easing for an infinite alternating
+ * animation. Any other config that never settles, such as
+ * `dampingRatio: 0` with `arrival: -1`, returns a `'settle'` easing cut
+ * off at `maxDuration`.
+ */
+declare function springToLinear(config: SpringDefinition, options?: LinearEasingOptions): LinearEasing;
+/**
+ * Like `springToLinear`, but for a spring caught mid-flight. `state`
+ * carries the displacement from the target (`position`) and the current
+ * `velocity`, so the easing continues the motion instead of restarting it.
+ * Use it to regenerate an animation when its target changes. The curve
+ * depends on the velocity, so compute it per interruption instead of
+ * caching it per config.
+ *
+ * The result is always a `'settle'` easing, timed from `position`, so
+ * `options.displacement` is ignored. A config that never settles is cut
+ * off at `maxDuration`. Throws when `position` is 0 (within 1e-9), even if
+ * `velocity` is not.
+ */
+declare function springFromState(config: SpringDefinition, state: SpringState, options?: LinearEasingOptions): LinearEasing;
+/**
+ * Advances a spring `state` by `elapsedMs` ms and returns the new
+ * displacement and velocity. `elapsedMs <= 0` returns a copy of `state`.
+ *
+ * The Web Animations API doesn't expose velocity, so to interrupt a running
+ * `element.animate`, advance the state it started from by its `currentTime`
+ * and hand the result to `springFromState`.
+ */
+declare function springStateAt(config: SpringDefinition, state: SpringState, elapsedMs: number): SpringState;
+/** What to animate: a CSS property from one numeric value to another. */
+interface PropertySpec {
+  /** The CSS property, for example `'opacity'`, `'transform'`, or `'translate'`. */
+  readonly property: string;
+  /** The start value. */
+  readonly from: number;
+  /** The target value. */
+  readonly to: number;
+  /**
+   * Unit appended to numbers, for example `'px'`, `'%'`, or `'deg'`.
+   * @default ''
+   */
+  readonly unit?: string;
+  /**
+   * Formats an interpolated number into a property value, overriding
+   * `unit`. Use it for values that wrap the number, such as
+   * ``(v) => `translateX(${v}px)` ``.
+   */
+  readonly format?: (value: number) => string;
+  /**
+   * The property's current velocity, in its units per second. Set it to
+   * regenerate an interrupted animation with its momentum instead of from
+   * rest. A spec with a nonzero velocity must be the only spec in the call,
+   * or the call throws.
+   */
+  readonly velocity?: number;
+}
+interface CssOptions extends LinearEasingOptions {
+  /**
+   * Name for the generated `@keyframes` rule.
+   * @default 'coily'
+   */
+  readonly name?: string;
+}
+/**
+ * Builds arguments for `element.animate(keyframes, options)`: two keyframes
+ * carrying the endpoint values, and options carrying the spring's `linear()`
+ * easing and duration. Pass an array of specs to drive several properties
+ * from one spring. A settling spring fills forwards. An undamped one repeats
+ * infinitely in alternating directions.
+ *
+ * @example
+ * ```ts
+ * const { keyframes, options } = springToWaapi(config, {
+ *   property: 'translate',
+ *   from: 0,
+ *   to: 300,
+ *   unit: 'px',
+ * })
+ * element.animate(keyframes, options)
+ * ```
+ */
+declare function springToWaapi(config: SpringDefinition, spec: PropertySpec | PropertySpec[], options?: LinearEasingOptions): {
+  keyframes: Keyframe[];
+  options: KeyframeAnimationOptions;
+};
+/**
+ * Builds CSS text for the animation: a `@keyframes` rule named by `name`
+ * (default `'coily'`) and an `animation` shorthand value that references
+ * it, driving one property or several from one spring. A settling spring
+ * fills forwards. An undamped one repeats infinitely in alternating
+ * directions.
+ *
+ * @example
+ * ```ts
+ * const { keyframes, animation } = springToCss(config, {
+ *   property: 'translate',
+ *   from: 0,
+ *   to: 300,
+ *   unit: 'px',
+ * })
+ * const style = document.createElement('style')
+ * style.textContent = keyframes
+ * document.head.append(style)
+ * element.style.animation = animation
+ * ```
+ */
+declare function springToCss(config: SpringDefinition, spec: PropertySpec | PropertySpec[], options?: CssOptions): {
+  keyframes: string;
+  animation: string;
+};
+/**
+ * Builds a CSS `transition` value that animates a property change with the
+ * spring. Set it on the element, then change the property, for example on
+ * `:hover`, with a toggled class, or with a state attribute. Pass several
+ * specs to build one `transition` for several properties.
+ *
+ * The values come from your CSS rules. Each spec's `from` and `to` only
+ * size the move, which tunes the duration. An undamped (looping) config
+ * throws, because a transition cannot loop.
+ *
+ * A transition starts from rest unless its spec carries a `velocity`, in
+ * the property's units per second, such as a drag's speed at release. The
+ * velocity reshapes the curve and the duration, so build the transition at
+ * the handoff. A spec with a velocity must be the only spec in the call.
+ *
+ * ```ts
+ * // Release a dragged card back to 0 at the drag's speed.
+ * card.style.transition = springToTransition(config, {
+ *   property: 'translate',
+ *   from: dragX,
+ *   to: 0,
+ *   velocity: releaseVelocity,
+ * })
+ * card.style.translate = '0px'
+ * ```
+ *
+ * The browser carries no momentum between transitions, so a change that
+ * interrupts one mid-flight stalls at the turn. To keep the momentum, read
+ * the velocity with `springStateAt` and rebuild the transition with it.
+ * For motion that reverses often, drive a live `Spring` instead.
+ */
+declare function springToTransition(config: SpringDefinition, spec: PropertySpec | PropertySpec[], options?: LinearEasingOptions): string;
+//#endregion
+export { CssOptions, LinearEasing, LinearEasingOptions, LoopingEasing, PropertySpec, SettlingEasing, springFromState, springStateAt, springToCss, springToLinear, springToTransition, springToWaapi };