import { KeyframeOptions, AnimationPlaybackControls, DOMKeyframesDefinition } from 'motion';

/**
 * Common easing keywords mapped to their cubic-bezier equivalents (ported from AOS),
 * in addition to the standard supported functions from motion
 */
declare const EASINGS: Record<string, KeyframeOptions["ease"]>;
type EasingKeyword = keyof typeof EASINGS;

type DeviceDisable = boolean | "mobile" | "phone" | "tablet" | (() => boolean);
interface MosOptions {
    /** Additional px distance before an element is considered in view */
    offset: number;
    /** Animation duration default */
    duration: number;
    /** Delay before starting the animation */
    delay: number;
    /** Units for duration and delay ("ms" or "s") - defaults to "ms" */
    timeUnits: "ms" | "s";
    /** Travel distance for directional animations in px */
    distance: number;
    /** CSS easing string */
    easing: EasingKeyword | string;
    /** If true, an element animates only once */
    once: boolean;
    /** If true, elements animate when scrolling up as well as down (requires once: false) */
    mirror: boolean;
    /** Disable condition */
    disable: DeviceDisable;
    /** If true, automatic DOM MutationObserver is not started */
    disableMutationObserver: boolean;
    /** DOM event that triggers MOS to start. Defaults to "DOMContentLoaded" */
    startEvent: string;
    /** Throttle delay for scroll events in ms */
    throttleDelay: number;
    /** Debounce delay for resize/orientation events in ms */
    debounceDelay: number;
}
type AnchorPlacement = "top-top" | "top-center" | "top-bottom" | "center-top" | "center-center" | "center-bottom" | "bottom-top" | "bottom-center" | "bottom-bottom";
interface ElementOptions extends MosOptions {
    /** Preset animation name */
    keyframes: string;
    /** Selector of anchor element whose position controls trigger */
    anchor?: string;
    /** 9-grid intersection that decides when the animation triggers */
    anchorPlacement?: AnchorPlacement;
}
type PartialMosOptions = Partial<MosOptions>;

/**
 * Factory function type for creating custom animations
 * Takes an element and options, returns Motion's animation controls
 */
type AnimationFactory = (el: HTMLElement, opts: ElementOptions) => AnimationPlaybackControls;
/**
 * Registers a custom animation that can be used by name in data-mos attributes
 * The factory function receives the element and options, and must return Motion's AnimationPlaybackControls
 *
 * @param name - Unique name for the animation (used in data-mos="name")
 * @param factory - Function that creates and returns animation controls
 *
 * @example
 * ```typescript
 * registerAnimation('customSlide', (element, options) => {
 *   return animate(element, { x: [100, 0] }, { duration: options.duration });
 * });
 * ```
 *
 * @throws Error if name is empty or invalid
 */
declare function registerAnimation(name: string, factory: AnimationFactory): void;

/**
 * Type for custom easing definitions that can be registered
 */
type EasingDefinition = KeyframeOptions["ease"];
/**
 * Register a custom easing function with a given name.
 *
 * Accepts Motion's easing definitions:
 * - Named strings: "easeIn", "easeOut", "linear", etc.
 * - Cubic bezier arrays: [0.25, 0.46, 0.45, 0.94]
 * - Step functions and other Motion easing types
 * - Cubic bezier strings: "cubic-bezier(0.25, 0.46, 0.45, 0.94)"
 *
 * @param name - The name to register the easing under
 * @param definition - The easing definition (Motion-compatible or cubic-bezier string)
 *
 * @example
 * ```typescript
 * // Register a cubic bezier array
 * registerEasing("bouncy", [0.68, -0.55, 0.265, 1.55]);
 *
 * // Register a cubic-bezier string (will be parsed for motion)
 * registerEasing("custom", "cubic-bezier(0.25, 0.46, 0.45, 0.94)");
 * ```
 */
declare function registerEasing(name: string, definition: EasingDefinition | string): void;

/**
 * Register custom animation keyframes by name.
 * Must be called **before** `MOS.init()` so the name can be picked up when elements are observed.
 * Supplying the same name twice will overwrite the previous definition.
 */
declare function registerKeyframes(name: string, definition: DOMKeyframesDefinition): void;

/**
 * Recalculates element positions after layout changes
 * Called on window resize and orientation change
 */
declare function handleLayoutChange(): void;
/**
 * Sets up the start event listener based on configuration
 * Handles both standard events (DOMContentLoaded, load) and custom events
 */
declare function setupStartEventListener(): void;
/**
 * Initializes the Motion-on-Scroll library with the given options
 * Can be called multiple times - options will be merged
 * @param options - Configuration options for the library
 * @returns Array of elements found in the DOM (for compatibility)
 */
declare function init(options?: PartialMosOptions): HTMLElement[];
/**
 * Refreshes the library by updating element positions and re-initializing scroll system
 * Does NOT re-find elements - only updates existing tracked elements
 * @param shouldActivate - Whether this refresh should activate the library (if not already active)
 */
declare function refresh(shouldActivate?: boolean): void;
/**
 * Performs a hard refresh - re-finds all MOS elements and completely re-initializes
 * This is a full re-initialization that discovers new elements in the DOM
 */
declare function refreshHard(): void;
declare const MOS: {
    init: typeof init;
    refresh: typeof refresh;
    refreshHard: typeof refreshHard;
    registerKeyframes: typeof registerKeyframes;
    registerEasing: typeof registerEasing;
    registerAnimation: typeof registerAnimation;
};

export { MOS, MOS as default, handleLayoutChange, init, refresh, refreshHard, registerAnimation, registerEasing, registerKeyframes, setupStartEventListener };