import type { RefObject } from 'react';
import type { Axis } from '@react-hive/honey-utils';
import type { Nullable } from './types';
import type { UseHoneyDragHandlers } from './use-honey-drag';
export type HoneySyntheticScrollMode = 'default' | 'embedded';
export interface UseHoneySyntheticScrollOptions<Element extends HTMLElement> extends Pick<UseHoneyDragHandlers<Element>, 'onStartDrag' | 'onEndDrag'> {
    /**
     * Axis along which synthetic scrolling is enabled.
     *
     * - `'x'` — horizontal only
     * - `'y'` — vertical only
     * - `'both'` — horizontal and vertical
     *
     * @default 'both'
     */
    axis?: Axis;
    /**
     * Percentage of the container size used as an overscroll buffer
     * on each enabled axis.
     *
     * This allows limited dragging beyond the natural content bounds
     * before movement is clamped.
     *
     * A value of `0` disables overscroll entirely.
     *
     * @default 0
     */
    overscrollPct?: number;
    /**
     * Controls how the hook applies scroll-related interaction styles
     * (`touch-action` and `overscroll-behavior`) to the container.
     *
     * Synthetic scrolling often requires restricting native browser scrolling
     * behavior to ensure consistent drag and wheel handling.
     *
     * However, in some embedded layouts (such as carousels placed inside a
     * vertically scrollable page), applying these styles can unintentionally
     * block natural page scrolling.
     *
     * ### Modes
     * - `default` - Applies restrictive interaction styles:
     *   - `overscroll-behavior: contain`
     *   - Axis-aware `touch-action` (`pan-y`, `pan-x`, or `none`)
     *
     *   Recommended for standalone synthetic scroll containers.
     *
     * - `embedded` - Does not apply any interaction-blocking styles.
     *
     *   Recommended when the container is integrated into another scrollable
     *   context (e.g. horizontal carousel inside a page), where native scroll
     *   chaining must remain intact.
     *
     * @default default
     */
    mode?: HoneySyntheticScrollMode;
    /**
     * Whether to clear any applied translation transforms when the window resizes.
     *
     * Useful to keep the layout state consistent after dimension changes.
     *
     * @default true
     */
    resetOnResize?: boolean;
    /**
     * Enables synthetic scrolling driven by pointer-based scroll input,
     * such as mouse wheels and trackpads.
     *
     * When enabled, scroll input is intercepted and converted into bounded
     * translation using the same logic as drag gestures.
     *
     * When disabled, native scrolling behavior is preserved and no scroll
     * input is handled by this hook.
     *
     * @default true
     */
    enablePointerScroll?: boolean;
    /**
     * Master toggle for the synthetic scroll behavior.
     *
     * When `true`, the hook:
     * - Enables drag-based translation via {@link useHoneyDrag}.
     * - Optionally resets transforms on resize via {@link useHoneyResize}.
     * - Applies overscroll and touch-action styles.
     * - Intercepts wheel / trackpad scroll input if {@link enablePointerScroll} is enabled.
     *
     * When `false`, the hook becomes completely inert:
     * - No drag or wheel listeners are attached.
     * - No transforms are applied.
     * - Native scrolling behavior is preserved.
     *
     * Useful for conditionally disabling synthetic scrolling
     * (e.g. mobile layouts, reduced motion, or feature flags).
     *
     * @default true
     */
    enabled?: boolean;
}
/**
 * Enables synthetic scrolling for a container using pointer-based drag gestures.
 *
 * Instead of relying on native scrollbars, this hook translates the container
 * using CSS transforms in response to drag input.
 *
 * ### Key characteristics
 * - Dragging is only applied when content overflows the container on a given axis.
 * - Movement is clamped within calculated bounds, with optional overscroll allowance.
 * - Scroll position is stored purely in `transform: translate(...)`.
 * - Active transforms can be automatically cleared on window resize.
 *
 * ### Internals
 * - Uses {@link useHoneyDrag} to track mouse / touch movement.
 * - Uses {@link useHoneyResize} to optionally reset scroll state on resize.
 *
 * @template Element - The HTML element type of the scrollable container.
 *
 * @param options - Configuration controlling axes, boundaries, and lifecycle behavior.
 *
 * @returns A ref that must be attached to the scrollable container element.
 */
export declare const useHoneySyntheticScroll: <Element extends HTMLElement>({ axis, overscrollPct, onStartDrag, onEndDrag, mode, resetOnResize, enablePointerScroll, enabled, }?: UseHoneySyntheticScrollOptions<Element>) => RefObject<Nullable<Element>>;