/**
 * Pure JS tweening primitives backed by `requestAnimationFrame`.
 *
 * `animateValue()` and `tween()` interpolate numeric values, arrays of
 * numbers, or plain-object records of numbers between `from` and `to`
 * over a configurable duration with an `EasingFunction` curve. They are
 * deliberately DOM-free and work in any runtime that provides `setTimeout`
 * (a `requestAnimationFrame` polyfill is used automatically when missing).
 *
 * @module bquery/motion
 */
import type { EasingFunction } from './types';
/**
 * A value type supported by `animateValue` / `tween`.
 */
export type TweenValue = number | number[] | Record<string, number>;
/**
 * Options accepted by `animateValue` and `tween`.
 */
export interface TweenOptions<T extends TweenValue> {
    /** Starting value. */
    from: T;
    /** Target value. Must be structurally compatible with `from`. */
    to: T;
    /** Total duration in milliseconds (default: 300). */
    duration?: number;
    /** Easing function (default: `linear`). */
    easing?: EasingFunction;
    /** Delay before starting in milliseconds (default: 0). */
    delay?: number;
    /** Update callback receiving the interpolated value. */
    onUpdate?: (value: T, progress: number) => void;
    /** Completion callback (called once when the tween finishes naturally). */
    onComplete?: (value: T) => void;
    /** Optional `AbortSignal` to cancel the tween early. */
    signal?: AbortSignal;
    /** Whether to respect `prefers-reduced-motion` (default: true). */
    respectReducedMotion?: boolean;
}
/**
 * Imperative controls returned by {@link tween}.
 */
export interface TweenControls<T extends TweenValue> {
    /** Pause the tween. */
    pause(): void;
    /** Resume a paused tween. */
    resume(): void;
    /** Reverse direction. The current value continues smoothly. */
    reverse(): void;
    /** Seek to a specific progress in `[0, 1]`. Triggers an `onUpdate`. */
    seek(progress: number): void;
    /** Stop and cancel the tween (does not call `onComplete`). */
    stop(): void;
    /** Current interpolated value. */
    current(): T;
    /** Progress in `[0, 1]`. */
    progress(): number;
    /** Promise resolving when the tween finishes or is stopped. */
    finished: Promise<T>;
}
/**
 * Tween any numeric structure between `from` and `to`. Returns a promise
 * that resolves with the final value when the animation completes
 * naturally, or skips the animation and resolves to `to` (after any
 * configured delay) when reduced motion is preferred.
 *
 * For full imperative controls (pause/resume/reverse/seek), use
 * {@link tween} instead.
 *
 * @example
 * ```ts
 * await animateValue({
 *   from: 0,
 *   to: 100,
 *   duration: 500,
 *   onUpdate: (v) => (counter.textContent = String(Math.round(v))),
 * });
 * ```
 */
export declare function animateValue<T extends TweenValue>(options: TweenOptions<T>): Promise<T>;
/**
 * Create a tween with full imperative controls. The animation starts
 * automatically; call `.pause()` to halt or `.stop()` to cancel.
 *
 * @example
 * ```ts
 * const t = tween({
 *   from: { x: 0, y: 0 },
 *   to: { x: 100, y: 50 },
 *   duration: 800,
 *   easing: easeOutCubic,
 *   onUpdate: ({ x, y }) => el.style.transform = `translate(${x}px, ${y}px)`,
 * });
 * t.pause();
 * t.resume();
 * await t.finished;
 * ```
 */
export declare function tween<T extends TweenValue>(options: TweenOptions<T>): TweenControls<T>;
//# sourceMappingURL=tween.d.ts.map