/**
 * @file useOverlay.tsx
 * @input Overlay options (showOn, scrim, position, content, etc.)
 * @output containerRef, containerProps, element, renderOverlay
 * @position Core hook for overlay system — same pattern as useTooltip
 *
 * For applying overlay behavior to an existing container (Card,
 * custom elements) without a wrapper. Returns props to spread on the
 * container and the scrim to render inside it.
 *
 * Handles: marker, positioning, touch toggle (via useClickableContainer),
 * and scrim rendering.
 */
import { type ReactNode, type ReactElement, type MouseEvent } from 'react';
import type { OverlayScrimMode, OverlayPosition, OverlayAlign, OverlayShowOn } from './OverlayScrim';
export interface UseOverlayOptions {
    /** Content rendered inside the scrim overlay. */
    content?: ReactNode;
    /**
     * CSS-driven visibility trigger.
     * - `"always"` — always visible
     * - `"hover"` — hover + focus (accessible default). Touch: strip = always visible, fill = tap-to-toggle.
     * - `"focus"` — focus-within only
     * - `"hover-or-focus"` — alias for "hover"
     * @default "always"
     */
    showOn?: OverlayShowOn;
    /**
     * JS-controlled visibility override. Takes precedence over showOn + touch.
     */
    isOpen?: boolean;
    /**
     * Scrim background mode.
     * @default "dark"
     */
    scrim?: OverlayScrimMode;
    /**
     * Scrim placement.
     * @default "fill"
     */
    position?: OverlayPosition;
    /**
     * Content alignment.
     * @default "end"
     */
    align?: OverlayAlign;
}
export interface OverlayContainerProps {
    /** CSS class names for marker + positioning. */
    className: string | undefined;
    /** Inline styles for marker + positioning. */
    style: React.CSSProperties | undefined;
    /** Touch tap-to-toggle handler. Only set on touch devices with full overlays. */
    onClick: ((e: MouseEvent<HTMLElement>) => void) | undefined;
    /** Touch tap-to-toggle handler. Only set on touch devices with full overlays. */
    onMouseUp: ((e: MouseEvent<HTMLElement>) => void) | undefined;
}
export interface UseOverlayResult {
    /** Ref — attach to the container element. */
    containerRef: React.RefObject<HTMLElement | null>;
    /** Props to spread on the container element. */
    containerProps: OverlayContainerProps;
    /**
     * Pre-rendered scrim element — place inside the container.
     * Only available when `content` is provided in options.
     */
    element: ReactElement | null;
    /**
     * Render function for the overlay scrim. Use when you want to
     * control where/when the scrim mounts, or pass dynamic content.
     * Same pattern as useTooltip's renderTooltip.
     */
    renderOverlay: (children: ReactNode) => ReactElement;
}
/**
 * Hook for overlay behavior on an existing container.
 * Returns containerRef, containerProps, and scrim element/render function.
 *
 * @example
 * ```
 * const overlay = useOverlay({
 *   showOn: 'hover',
 *   content: <Button label="Quick view" variant="ghost" />,
 * });
 * <Card ref={overlay.containerRef} {...overlay.containerProps}>
 *   <Layout content={...} />
 *   {overlay.element}
 * </Card>
 * ```
 *
 * @example
 * ```
 * const overlay = useOverlay({ showOn: 'hover' });
 * <div ref={overlay.containerRef} {...overlay.containerProps}>
 *   <img src={src} />
 *   {overlay.renderOverlay(<Button label="Quick view" />)}
 * </div>
 * ```
 */
export declare function useOverlay({ content, showOn, isOpen: isOpenProp, scrim, position, align, }?: UseOverlayOptions): UseOverlayResult;
//# sourceMappingURL=useOverlay.d.ts.map