import { HTMLAttributes, ReactNode } from 'react';
import { SmoothScrollConfig, ScrollProgress, PerformanceMetrics } from './smooth/SmoothScrollEngine.types';
/**
 * Scrollbar visibility behavior
 * - 'auto': Standard browser behavior (show when content overflows)
 * - 'always': Always show scrollbar
 * - 'scroll': Show scrollbar only while actively scrolling (overlay, no track)
 * - 'hover': Show scrollbar only on hover
 * - 'none': Hide scrollbar completely while keeping scroll functionality
 */
export type ScrollAreaType = 'auto' | 'always' | 'scroll' | 'hover' | 'none';
/**
 * Scrollbar size
 * - 'default': 8px scrollbar (w-2/h-2)
 * - 'thin': 4px scrollbar (w-1/h-1)
 */
export type ScrollAreaSize = 'default' | 'thin';
/**
 * Theme structure for the ScrollArea component
 */
export interface ScrollAreaTheme {
    baseStyle: string;
    scrollbarStyle: string;
    thumbStyle: string;
}
/**
 * Theme overrides for customizing ScrollArea styles
 */
export interface ScrollAreaThemeOverrides {
    baseStyle?: string;
    scrollbarStyle?: string;
    thumbStyle?: string;
}
/**
 * Extended ScrollArea ref with smooth scroll API
 */
export interface ScrollAreaRef extends HTMLDivElement {
    /** Programmatically scroll to position with smooth animation */
    smoothScrollTo?: (position: number, options?: import("./smooth/SmoothScrollEngine.types").ScrollToOptions) => void;
    /** Get current scroll velocity */
    getScrollVelocity?: () => number;
    /** Pause smooth scrolling */
    pauseSmoothScroll?: () => void;
    /** Resume smooth scrolling */
    resumeSmoothScroll?: () => void;
    /** Refresh snap points */
    refreshSnapPoints?: () => void;
}
/**
 * ScrollArea component props
 *
 * @example
 * ```tsx
 * <ScrollArea className="h-72">
 *   <div className="p-4">
 *     {items.map(item => <div key={item.id}>{item.name}</div>)}
 *   </div>
 * </ScrollArea>
 *
 * <ScrollArea type="hover" orientation="horizontal" className="w-96">
 *   <div className="flex gap-4">{children}</div>
 * </ScrollArea>
 *
 * // With smooth scrolling
 * <ScrollArea smooth smoothConfig={{ lerp: 0.1, elasticEdges: true }}>
 *   {content}
 * </ScrollArea>
 * ```
 */
export interface ScrollAreaProps extends HTMLAttributes<HTMLDivElement> {
    /** Content to render inside the scroll area */
    children: ReactNode;
    /** Scrollbar visibility behavior @default 'hover' */
    type?: ScrollAreaType;
    /** Scrollbar size @default 'default' */
    size?: ScrollAreaSize;
    /** Scroll direction @default 'vertical' */
    orientation?: 'vertical' | 'horizontal' | 'both';
    /**
     * Enable scroll snapping. Sets scroll-snap-type on the viewport (axis derived from orientation).
     * Use 'mandatory' for strict snapping or 'proximity' for snap-when-close behavior.
     * @default undefined (no snapping)
     */
    snap?: 'mandatory' | 'proximity';
    /**
     * Snap alignment applied to direct children via [&>*]:snap-*.
     * Only takes effect when `snap` is set.
     * @default 'start'
     */
    snapAlign?: 'start' | 'center' | 'end';
    /**
     * Enable smooth momentum-based scrolling
     * @default false
     */
    smooth?: boolean;
    /**
     * Configuration for smooth scrolling
     * Only applies when smooth={true}
     */
    smoothConfig?: Partial<SmoothScrollConfig>;
    /**
     * Callback fired on scroll progress updates
     * Only applies when smooth={true}
     */
    onScrollProgress?: (progress: ScrollProgress) => void;
    /**
     * Callback fired on performance metrics updates
     * Only applies when smooth={true}
     */
    onPerformanceUpdate?: (metrics: PerformanceMetrics) => void;
    /** Custom class name for the scroll area */
    className?: string;
    /** Theme overrides */
    theme?: ScrollAreaThemeOverrides;
}
