import { type ReducedMotionOverride } from '../a11y/config';
import { type DecayOptions } from '../physics/decay';
import { type Simulation, type SimulationState } from '../physics/simulation';
import { type SpringOptions } from '../physics/spring';
import { type ToOptions } from '../physics/tween';
import type { Scheduler } from '../scheduler/scheduler';
import { type LifecycleCallbacks, type LifecycleEvent } from './lifecycle';
import { type ThenFn } from './thenable';
export interface AnimationHandle {
    /** Resolves when the animation settles OR is interrupted. Never rejects. */
    readonly finished: Promise<void>;
    /**
     * Handles are awaitable: `await animate(...)` / `await handle` resolves when the
     * animation settles or is interrupted (delegates to `finished`; never rejects).
     */
    then: ThenFn;
    /** Freezes the value in place - only if this animation is still the active one. */
    stop(): void;
    /**
     * Attach or (with `null`) replace a lifecycle callback after creation; last writer wins per event.
     * Present on the handles that carry a lifecycle (spring/to/decay/simulate, playable, animate); use
     * `?.` on a handle whose source may not (a composed/keyframe aggregate). Callbacks passed in the
     * call always fire regardless.
     */
    eventCallback?(event: LifecycleEvent, fn: ((handle: AnimationHandle) => void) | null): AnimationHandle;
}
export interface AnimatableOptions {
    /** Injection point for tests; defaults to the shared rAF scheduler. */
    scheduler?: Scheduler;
}
export interface SetOptions {
    /** Seed a velocity (units/s) along with the value - external handoffs (WAAPI reclaim, gestures). */
    velocity?: number;
}
export interface SimulateOptions {
    /** Initial velocity (units/s); defaults to the value's current velocity. */
    velocity?: number;
    /** Per-animation override of the reduced-motion behavior. */
    reducedMotion?: ReducedMotionOverride;
}
export interface Animatable {
    get(): number;
    /** units/s */
    velocity(): number;
    isAnimating(): boolean;
    /** Teleport: cancels any animation; velocity resets to 0 unless seeded. */
    set(value: number, options?: SetOptions): void;
    /**
     * Passive write of position+velocity: emits `change`, but does NOT freeze an
     * active animation, fire `rest`, or zero velocity. The playback layer drives
     * a value through this; the value stays a state holder.
     */
    drive(state: SimulationState): void;
    /** Freeze in place: position AND velocity stay readable. */
    stop(): void;
    /** Retargets from the current position and velocity - interruptible at any time. */
    spring(target: number, options?: SpringOptions & LifecycleCallbacks<AnimationHandle>): AnimationHandle;
    /** Glide on inertia from the current (or imposed) velocity; optional clamp boundaries. */
    decay(options?: DecayOptions & LifecycleCallbacks<AnimationHandle>): AnimationHandle;
    /** Duration/easing escape hatch - still interruptible, with a readable derived velocity. */
    to(target: number, options?: ToOptions & LifecycleCallbacks<AnimationHandle>): AnimationHandle;
    /**
     * Drive the value with a custom Simulation - the general physics mode that
     * spring/decay/to specialize. Runs from the current position and velocity on
     * the same fixed-timestep clock, fully interruptible. Bring your own
     * acceleration (gravity, a force field, a bounce) and rest condition.
     */
    simulate(simulation: Simulation, options?: SimulateOptions & LifecycleCallbacks<AnimationHandle>): AnimationHandle;
    on(event: 'change', listener: (value: number) => void): () => void;
    on(event: 'rest', listener: () => void): () => void;
    dispose(): void;
}
export declare function animatable(initial: number, options?: AnimatableOptions): Animatable;
//# sourceMappingURL=animatable.d.ts.map