Animation & Effects

/**
 * Reactive scroll position with arrival state detection
 * @param element - Target element or ref
 * @param options - Configuration options
 * @returns Scroll state and utilities
 */
function useScroll(
  element: MaybeComputedElementRef,
  options?: UseScrollOptions
): UseScrollReturn;

interface UseScrollReturn {
  x: Ref<number>;
  y: Ref<number>;
  isScrolling: Ref<boolean>;
  arrivedState: ScrollState;
  directions: ScrollDirections;
  measure(): void;
}

interface ScrollState {
  left: boolean;
  right: boolean;
  top: boolean;
  bottom: boolean;
}

interface ScrollDirections {
  left: boolean;
  right: boolean;
  top: boolean;
  bottom: boolean;
}

interface UseScrollOptions {
  throttle?: number;
  idle?: number;
  onScroll?: (e: Event) => void;
  onStop?: (e: Event) => void;
  eventListenerOptions?: boolean | AddEventListenerOptions;
  behavior?: MaybeRefOrGetter<ScrollBehavior>;
  window?: Window;
}

import { ref } from "vue";
import { useScroll } from "@vueuse/core";

const el = ref<HTMLElement>();
const { x, y, isScrolling, arrivedState, directions } = useScroll(el);

// Check if scrolled to edges
console.log(arrivedState.top); // true when at top
console.log(arrivedState.bottom); // true when at bottom

// Check scroll direction
console.log(directions.top); // true when scrolling up
console.log(directions.left); // true when scrolling left

/**
 * Reactive window scroll position
 * @param options - Configuration options
 * @returns Window scroll state
 */
function useWindowScroll(options?: UseScrollOptions): UseScrollReturn;

/**
 * Lock scrolling of an element
 * @param element - Target element or ref (defaults to body)
 * @param initialState - Initial lock state
 * @returns Scroll lock utilities
 */
function useScrollLock(
  element?: MaybeElementRef,
  initialState?: boolean
): WritableComputedRef<boolean>;

/**
 * Infinite scroll functionality
 * @param element - Scrollable element or ref
 * @param onLoadMore - Load more callback
 * @param options - Configuration options
 * @returns Infinite scroll state
 */
function useInfiniteScroll(
  element: MaybeElementRef,
  onLoadMore: (state: UseInfiniteScrollReturn) => Awaitable<void>,
  options?: UseInfiniteScrollOptions
): UseInfiniteScrollReturn;

interface UseInfiniteScrollReturn {
  isLoading: Ref<boolean>;
  isFinished: WritableComputedRef<boolean>;
  pause: () => void;
  resume: () => void;
  reset: () => void;
}

interface UseInfiniteScrollOptions {
  distance?: number;
  direction?: 'top' | 'bottom' | 'left' | 'right';
  preserveScrollPosition?: boolean;
  throttle?: number;
  idle?: number;
  canLoadMore?: (el: Element) => boolean;
}

/**
 * Reactive Web Animations API wrapper
 * @param target - Target element or ref
 * @param keyframes - Animation keyframes
 * @param options - Animation options
 * @returns Animation utilities
 */
function useAnimate(
  target: MaybeElementRef,
  keyframes: MaybeRefOrGetter<Keyframe[]>,
  options?: MaybeRefOrGetter<number | KeyframeAnimationOptions>
): UseAnimateReturn;

interface UseAnimateReturn {
  isSupported: Ref<boolean>;
  animate: Ref<Animation | undefined>;
  play: () => void;
  pause: () => void;
  reverse: () => void;
  finish: () => void;
  cancel: () => void;
  pending: Ref<boolean>;
  playState: Ref<AnimationPlayState>;
  replaceState: Ref<AnimationReplaceState>;
  startTime: Ref<CSSNumberish | null>;
  currentTime: Ref<CSSNumberish | null>;
  timeline: Ref<AnimationTimeline | null>;
  playbackRate: Ref<number>;
}

import { ref } from "vue";
import { useAnimate } from "@vueuse/core";

const el = ref<HTMLElement>();

// Simple fade animation
const { play, pause, reverse } = useAnimate(
  el,
  [
    { opacity: 0 },
    { opacity: 1 }
  ],
  {
    duration: 1000,
    easing: 'ease-in-out'
  }
);

// Complex keyframe animation
const { play } = useAnimate(
  el,
  [
    { transform: 'translateX(0px)', opacity: 1 },
    { transform: 'translateX(100px)', opacity: 0.5 },
    { transform: 'translateX(200px)', opacity: 1 }
  ],
  {
    duration: 2000,
    iterations: Infinity,
    direction: 'alternate'
  }
);

/**
 * Create smooth transitions between values
 * @param source - Source value to transition
 * @param options - Transition options
 * @returns Transitioning value
 */
function useTransition(
  source: Ref<number>,
  options?: UseTransitionOptions
): Ref<number>;

function useTransition<T extends MaybeRefOrGetter<number>[]>(
  source: [...T],
  options?: UseTransitionOptions
): ComputedRef<{ [K in keyof T]: number }>;

interface UseTransitionOptions {
  delay?: MaybeRefOrGetter<number>;
  disabled?: MaybeRefOrGetter<boolean>;
  duration?: MaybeRefOrGetter<number>;
  onFinished?: () => void;
  onStarted?: () => void;
  transition?: TransitionPresets | CubicBezierPoints | EasingFunction;
}

type TransitionPresets = 'linear' | 'easeInSine' | 'easeOutSine' | 'easeInOutSine' | 'easeInCubic' | 'easeOutCubic' | 'easeInOutCubic' | 'easeInQuint' | 'easeOutQuint' | 'easeInOutQuint' | 'easeInCirc' | 'easeOutCirc' | 'easeInOutCirc' | 'easeInBack' | 'easeOutBack' | 'easeInOutBack';

/**
 * Reactive CSS custom properties
 * @param prop - CSS property name (with or without --)
 * @param target - Target element or ref
 * @param options - Configuration options
 * @returns Reactive CSS variable ref
 */
function useCssVar(
  prop: MaybeRefOrGetter<string>,
  target?: MaybeElementRef,
  options?: UseCssVarOptions
): WritableComputedRef<string>;

interface UseCssVarOptions extends ConfigurableWindow {
  initialValue?: string;
  observe?: boolean;
}

/**
 * Create and manage style tags dynamically
 * @param css - CSS content (reactive)
 * @param options - Configuration options
 * @returns Style tag utilities
 */
function useStyleTag(
  css: MaybeRefOrGetter<string>,
  options?: UseStyleTagOptions
): UseStyleTagReturn;

interface UseStyleTagReturn {
  id: string;
  css: Ref<string>;
  load: () => void;
  unload: () => void;
  isLoaded: Readonly<Ref<boolean>>;
}

interface UseStyleTagOptions extends ConfigurableDocument {
  immediate?: boolean;
  manual?: boolean;
  id?: string;
  media?: string;
}

/**
 * Load and manage script tags dynamically  
 * @param src - Script source URL (reactive)
 * @param onLoaded - Callback when script loads
 * @param options - Configuration options
 * @returns Script tag utilities
 */
function useScriptTag(
  src: MaybeRefOrGetter<string>,
  onLoaded?: (el: HTMLScriptElement) => void,
  options?: UseScriptTagOptions
): UseScriptTagReturn;

interface UseScriptTagReturn {
  scriptTag: Ref<HTMLScriptElement | null>;
  load: (waitForScriptLoad?: boolean) => Promise<HTMLScriptElement | boolean>;
  unload: () => void;
}

interface UseScriptTagOptions extends ConfigurableDocument {
  immediate?: boolean;
  async?: boolean;
  type?: string;
  manual?: boolean;
  crossOrigin?: 'anonymous' | 'use-credentials';
  referrerPolicy?: ReferrerPolicy;
  noModule?: boolean;
  defer?: boolean;
  document?: Document;
  attrs?: Record<string, string>;
}

/**
 * Reactive Fullscreen API
 * @param target - Target element or ref
 * @param options - Configuration options
 * @returns Fullscreen utilities
 */
function useFullscreen(
  target?: MaybeElementRef,
  options?: UseFullscreenOptions
): UseFullscreenReturn;

interface UseFullscreenReturn {
  isSupported: ComputedRef<boolean>;
  isFullscreen: Ref<boolean>;
  enter: () => Promise<void>;
  exit: () => Promise<void>;
  toggle: () => Promise<void>;
}

interface UseFullscreenOptions extends ConfigurableDocument {
  autoExit?: boolean;
}

/**
 * Reactive requestAnimationFrame utility
 * @param fn - Function to call on each frame
 * @param options - Configuration options
 * @returns Animation frame utilities
 */
function useRafFn(
  fn: (args: UseRafFnCallbackArguments) => void,
  options?: UseRafFnOptions
): Pausable;

interface UseRafFnCallbackArguments {
  delta: number;
  timestamp: DOMHighResTimeStamp;
}

interface UseRafFnOptions {
  immediate?: boolean;
  fpsLimit?: number;
}

/**
 * Reactive FPS counter
 * @param options - Configuration options
 * @returns FPS state
 */
function useFps(options?: UseFpsOptions): Ref<number>;

interface UseFpsOptions {
  every?: number;
}

/**
 * Create parallax effects based on mouse movement
 * @param target - Target element or ref
 * @param options - Configuration options
 * @returns Parallax transform values
 */
function useParallax(
  target: MaybeElementRef,
  options?: UseParallaxOptions
): UseParallaxReturn;

interface UseParallaxReturn {
  tilt: ComputedRef<number>;
  roll: ComputedRef<number>;
  source: 'mouse' | 'deviceOrientation';
}

interface UseParallaxOptions {
  deviceOrientationTiltAdjust?: (i: number) => number;
  deviceOrientationRollAdjust?: (i: number) => number;
  mouseTiltAdjust?: (i: number) => number;
  mouseRollAdjust?: (i: number) => number;
}