/**
 * Focus trap utility — pure Functional Core + a small imperative setup.
 * Used by eo-drawer to hold keyboard focus inside the modal until closed.
 */
/**
 * Pure: list keyboard-focusable descendants of `root` in DOM order.
 *
 * `root` should be the **light-DOM host** (the custom-element) of the modal,
 * NOT its shadowRoot — slotted content lives in the host's light DOM, not the
 * drawer's shadow DOM, so starting from `shadowRoot` would miss it.
 *
 * Traversal recurses into every open shadow root encountered so that focusables
 * inside nested shadow-scoped custom elements are discovered.
 */
export declare function getFocusableElements(root: ParentNode): HTMLElement[];
/**
 * Resolves the actually-focused element through nested open shadow roots —
 * `document.activeElement` alone reports the outermost host.
 */
export declare function getDeepActiveElement(): Element | null;
/**
 * Pure: given a Tab event and the current focusables list, decide where focus
 * should go next. Returns the element to focus, or null for "let browser handle".
 */
export declare function computeTrapTarget(e: KeyboardEvent, focusables: HTMLElement[], active: Element | null): HTMLElement | null;
/**
 * Attach a focus trap to `root`. Returns a teardown function that restores
 * focus to `restoreTo` (typically the element that triggered the modal).
 *
 * Focus is NOT auto-captured from `document.activeElement` because install is
 * deferred by the caller (via rAF, after animation kickoff) — by then focus
 * has already moved, making auto-capture unreliable.
 */
export declare function setupFocusTrap(root: ParentNode, restoreTo?: HTMLElement | null): () => void;