import { type AutoFocusEvent } from './dismissal.js';
/**
 * Resolution of initialFocus/finalFocus selectors for overlay families
 * (Dialog, Drawer, Popover). Uses CSS selector strings (not
 * element handles) so members survive as attributes on `<skdx-*-content>` —
 * a DOM node cannot cross HTML attribute boundaries.
 *
 * A miss falls back to the overlay's automatic target (the whole point).
 * Wrong selectors warn on console even in production (a selector pointing at
 * nothing is a defect regardless).
 * @internal
 */
export type FocusTargetFamily = 'Dialog' | 'Drawer' | 'Popover';
/**
 * Resolves one focus-target selector against `root`, or returns `null` and
 * warns when it names nothing.
 *
 * @param root Content for `initialFocus` (the target is part of the panel by
 * definition, and a loose selector must not reach into the page behind it), the
 * document for `finalFocus` (whose target is outside Content by definition).
 * @internal
 */
export declare function resolveFocusSelector(root: ParentNode, selector: string | undefined, prop: 'initialFocus' | 'finalFocus', family: FocusTargetFamily): HTMLElement | null;
/**
 * Element initial focus should land on inside content: the selector's match or
 * the default (a Cancel part when present, then first tabbable, then panel).
 * @internal
 */
export declare function initialFocusTarget(content: HTMLElement, selector: string | undefined, family: FocusTargetFamily): HTMLElement;
/**
 * Places initial focus for a native `<dialog>` after `showModal()`: the selector's match, then the family's own
 * default target, else — unless the platform already focused inside the panel — the first tabbable, then the panel itself.
 * @internal
 */
export declare function applyInitialFocus(content: HTMLElement, selector: string | undefined, family: FocusTargetFamily): void;
/**
 * Sends focus where finalFocus names, resolved at document level (panel is
 * closing and the opening element may be gone). Returns whether focus was placed.
 * @internal
 */
export declare function applyFinalFocus(selector: string | undefined, family: FocusTargetFamily): boolean;
/**
 * The open-time focus move under its veto: `open-auto-focus` fires *before*
 * anything moves, so a consumer preventing it keeps focus where the user left
 * it. A native `<dialog>` is the exception — `showModal()` has already moved
 * focus into the panel by the time any handler can run, so a veto has to put it
 * back rather than merely decline to move it. A veto that places focus itself is the
 * documented way to take initial focus over, so that undo only runs when the handler
 * left focus where the platform put it.
 *
 * @param content the overlay panel
 * @param selector the `initialFocus` selector, or `undefined` for the default chain
 * @param family which overlay family, for the console warning a missed selector prints
 * @param handler the consumer's `open-auto-focus` handler
 * @param previouslyFocused what had focus before the platform moved it, for the undo
 * @returns whether focus was placed inside the panel
 * @internal
 */
export declare function applyOpenAutoFocus(content: HTMLElement, selector: string | undefined, family: FocusTargetFamily, handler?: (event: AutoFocusEvent) => void, previouslyFocused?: HTMLElement | null): boolean;
/**
 * The close-time focus return, run on every close route (Escape, outside press,
 * the close button, a controlled `open` flipping) so focus never strands on a
 * panel that is going away. `close-auto-focus` fires *before* the move, and a
 * veto leaves focus alone; otherwise `finalFocus` wins, and the element that
 * opened the overlay is the fallback — skipped when it has left the document,
 * since focusing a detached node silently drops focus onto `<body>`, and skipped
 * when it *is* `<body>` or `<html>`, which means nothing was focused when the
 * overlay opened rather than that the page root should take focus.
 *
 * @param selector the `finalFocus` selector, or `undefined` to go straight to the opener
 * @param family which overlay family, for the console warning a missed selector prints
 * @param opener the element focused before the overlay opened
 * @param handler the consumer's `close-auto-focus` handler
 * @returns whether focus was placed
 * @internal
 */
export declare function returnFocus(selector: string | undefined, family: FocusTargetFamily, opener: HTMLElement | null | undefined, handler?: (event: AutoFocusEvent) => void): boolean;