/**
 * Attaches a natural hide/show behavior to a sticky element placed at the top.
 *
 * This function creates a smooth, natural-feeling top element (like a header) that:
 * - Hides when scrolling down by naturally scrolling with the content
 * - Shows when scrolling up by positioning itself just above the viewport to scroll into view naturally
 * - Becomes sticky at the top when fully visible during upward scroll
 * - Releases from sticky position when scrolling down to allow natural hiding
 *
 * Key characteristics of the top implementation:
 * - Uses 'top' property for positioning in both modes
 * - When reserveSpace=true: sticky ↔ relative positioning (reserves document space)
 * - When reserveSpace=false: fixed ↔ absolute positioning (floating, no document space)
 * - When releasing from top position on scroll down, positions element at current scroll position
 * - When moving above viewport on scroll up, positions element just above viewport
 * - Transitions using scroll step prediction to avoid visual gaps (predicted elementRect.top >= 0)
 *
 * The script dispatches a `natural-sticky` event with the following states in `event.detail.state`:
 * - 'sticky': The element is stuck to the top of the viewport.
 * - 'home': The element is at its original position at the top of the document.
 * - 'relative': The element is scrolling with the page content.
 *
 * @param element - The HTML element to make naturally sticky
 * @param options - Configuration options
 * @param options.snapEagerness - How eagerly the element snaps into sticky position (default: 1)
 *   - 0: Pure natural movement, occasional visual gaps
 *   - 1: Balanced behavior (recommended)
 *   - 2-3: Reduced gaps, element "snaps" more eagerly to position
 *   - Higher: Strong snap effect, immediate attraction to edge
 * @param options.scrollThreshold - Minimum scroll speed (pixels/event) to trigger natural scroll-in effect (default: 0)
 *   - 0: Always activate scroll-in effect (current behavior)
 *   - 2: Low threshold for gentle filtering
 *   - 10: Medium threshold for deliberate scrolling
 *   - 25: High threshold for fast scrolling only
 * @param options.reserveSpace - Whether the element should reserve space in document flow (default: true)
 *   - true: Uses sticky ↔ relative positioning (normal headers/footers)
 *   - false: Uses fixed ↔ absolute positioning (floating buttons, multiple headers)
 */
export declare function naturalStickyTop(element: HTMLElement, options?: {
    snapEagerness?: number;
    scrollThreshold?: number;
    reserveSpace?: boolean;
}): {
    destroy: () => void;
};
export default naturalStickyTop;