/**
 * @fileoverview Track mouse/pointer position relative to an element or the window.
 * @author Saasflare™
 * @module packages/ui/hooks/use-mouse-position
 * @package ui
 *
 * @example
 * // Global mouse position
 * const { x, y } = useMousePosition();
 *
 * // Relative to an element
 * const ref = useRef<HTMLDivElement>(null);
 * const { x, y } = useMousePosition({ ref });
 */
import { type RefObject } from 'react';
/** Mouse position coordinates */
export interface MousePosition {
    /** X coordinate in pixels (relative to element or viewport) */
    x: number;
    /** Y coordinate in pixels (relative to element or viewport) */
    y: number;
}
/** Options for useMousePosition */
export interface UseMousePositionOptions {
    /** Element ref to track position relative to. Defaults to window (viewport coords). */
    ref?: RefObject<HTMLElement | null>;
    /** Whether tracking is active. Default: `true` */
    enabled?: boolean;
    /** Use requestAnimationFrame for updates. Default: `true` */
    useRAF?: boolean;
}
/**
 * Tracks the mouse position, optionally relative to a referenced element.
 * When a ref is provided, coordinates are relative to the element's top-left corner.
 * Without a ref, coordinates are relative to the viewport.
 *
 * @param {UseMousePositionOptions} [options] - Configuration options
 * @returns {MousePosition} Current x, y coordinates
 *
 * @example
 * const cardRef = useRef<HTMLDivElement>(null);
 * const { x, y } = useMousePosition({ ref: cardRef });
 * // x, y are relative to card's top-left
 */
export declare function useMousePosition(options?: UseMousePositionOptions): MousePosition;