/**
 * Focus trap utilities for BeatUI.
 *
 * Provides a focus trap implementation that constrains keyboard focus within
 * a container element. Supports Tab/Shift+Tab cycling, Escape key handling,
 * click-outside detection, initial focus targeting, and focus restoration
 * on deactivation. Integrates with the `@tempots/dom` reactive rendering system.
 *
 * @module
 */
import { Renderable } from '@tempots/dom';
/**
 * Configuration options for the focus trap behavior.
 */
export interface FocusTrapOptions {
    /**
     * Whether the focus trap is active.
     * @default true
     */
    active?: boolean;
    /**
     * Whether pressing Escape deactivates the focus trap.
     * @default true
     */
    escapeDeactivates?: boolean;
    /** Callback invoked when the Escape key is pressed (if `escapeDeactivates` is true). */
    onEscape?: () => void;
    /**
     * Element to receive initial focus when the trap activates.
     * Can be an `HTMLElement` or a function returning one.
     * If not provided, the first focusable element in the container is focused.
     */
    initialFocus?: HTMLElement | (() => HTMLElement | null);
    /**
     * Element to return focus to when the trap is deactivated.
     * Can be an `HTMLElement` or a function returning one.
     * If not provided, focus returns to the element that was focused before activation.
     */
    returnFocus?: HTMLElement | (() => HTMLElement | null);
    /**
     * Whether clicking outside the container triggers deactivation.
     * @default false
     */
    clickOutsideDeactivates?: boolean;
    /** Callback invoked when a click occurs outside the container (if `clickOutsideDeactivates` is true). */
    onClickOutside?: () => void;
}
/**
 * Creates a focus trap `Renderable` that constrains keyboard focus within
 * the parent container element. When added to a container, it intercepts
 * Tab/Shift+Tab navigation to cycle through focusable children, optionally
 * handles Escape key, and restores focus on disposal.
 *
 * @param options - Configuration for the focus trap behavior
 * @returns A `Renderable` that should be included as a child of the container element
 *
 * @example
 * ```ts
 * html.div(
 *   FocusTrap({
 *     escapeDeactivates: true,
 *     onEscape: () => closeDialog(),
 *   }),
 *   html.button('Close'),
 *   html.input({ type: 'text' }),
 * )
 * ```
 */
export declare function FocusTrap(options?: FocusTrapOptions): Renderable;
/**
 * Creates a focus trap controller with `activate` and `deactivate` methods.
 * Each call to `activate()` or `deactivate()` returns a new `Renderable`
 * configured with the provided options.
 *
 * @param options - Configuration for the focus trap behavior
 * @returns An object with `activate` and `deactivate` methods that return `Renderable` instances
 *
 * @example
 * ```ts
 * const trap = useFocusTrap({ onEscape: () => console.log('escaped') })
 * // trap.activate() returns a Renderable with active=true
 * // trap.deactivate() returns a Renderable with active=false
 * ```
 */
export declare function useFocusTrap(options?: FocusTrapOptions): {
    activate: () => Renderable;
    deactivate: () => Renderable;
};