import { Page } from '@playwright/test';
import { ClickOptions, DropdownSelectOptions, DragAndDropOptions, ListedElementMatch, ActionTimeoutOptions } from '../enum/Options';
import { Element, WebElement } from '@civitas-cerebrum/element-repository';
/**
 * Classification of a failed click attempt:
 *
 * - `'interception'` — another element covers the target; input was NOT
 *   dispatched, so the `dispatchEvent('click')` fallback is safe.
 * - `'input-may-have-fired'` — timed out after the call log reached the
 *   input-dispatch phase. Clicking again risks a double fire.
 * - `'not-dispatched'` — timed out still waiting for actionability; input
 *   provably never reached the page, so continuing the click is safe.
 * - `'fatal'` — not a timeout (page closed, strict-mode violation): rethrow.
 */
export type ClickFailureClass = 'interception' | 'input-may-have-fired' | 'not-dispatched' | 'fatal';
/**
 * True when `error` is a Playwright timeout. Class-based, deliberately NOT a
 * message-substring test — driver wording reworded silently between releases
 * (see `Navigation.waitForNetworkIdle` for the same pattern). The `name`
 * fallback covers errors that crossed a serialization boundary.
 */
export declare function isTimeoutError(error: unknown): boolean;
/**
 * Classifies a failed click attempt by error class, then by the phase
 * Playwright's call log reached.
 *
 * Interception is checked first, and wins even when the input-dispatch marker
 * is also present: Playwright logs `performing click action`, *then* runs the
 * hit-target check, and only dispatches input when nothing intercepts.
 */
export declare function classifyClickFailure(error: unknown): ClickFailureClass;
/**
 * The `Interactions` class provides a robust set of methods for interacting
 * with DOM elements. All operations route through element-repository's
 * `Element` interface, keeping this class framework-agnostic.
 *
 * Every method takes an `Element` from the repository. Wrap raw Playwright
 * Locators via `new WebElement(locator)` at the call site if you need to bridge.
 */
export declare class Interactions {
    private page;
    private interceptionRetry;
    private ELEMENT_TIMEOUT;
    private utils;
    constructor(page: Page, timeout?: number, interceptionRetry?: boolean);
    private softProbe;
    /**
     * Performs a standard click on the given element.
     * Automatically waits for the element to be attached, visible, stable, and actionable.
     */
    click(element: WebElement, options?: ClickOptions): Promise<boolean | void>;
    /**
     * Dispatches a native 'click' event directly on the element, bypassing
     * actionability checks. Used for both `force` and `withoutScrolling`.
     */
    private dispatchClick;
    /**
     * Attempts a standard click. If interception is reported and
     * `interceptionRetry` is enabled (default), retries by dispatching a
     * native click event on the element instead — and surfaces the fallback
     * via a `log.warn` line plus a report-visible Playwright test annotation
     * (`interception-fallback`). When `interceptionRetry` is `false`, the
     * original interception error is rethrown so genuine overlay bugs
     * (stuck modals, cookie walls) fail the click.
     *
     * The first attempt is capped so interception is detected fast, and its
     * failure is routed by {@link ClickFailureClass} rather than by "was it an
     * interception, else click again". A timed-out click is NEVER re-dispatched:
     * `input-may-have-fired` is accepted as delivered (a physical re-click would
     * invert a toggle or wedge against an overlay the first click just opened),
     * `not-dispatched` continues within the REMAINING budget, `fatal` rethrows.
     *
     * @param subject - Optional element identity (`PageName.elementName`)
     *   threaded down from the Steps/ElementAction layer, which is where the
     *   names are known. Included in the log line and the annotation.
     */
    private clickWithInterceptionRetry;
    /**
     * Terminal handling for a failed click attempt — dispatch fallback,
     * accept-as-delivered, or rethrow. Never issues another real click, so it
     * is safe to call from any attempt in the chain.
     */
    private resolveClickFailure;
    /**
     * Pushes a report-visible annotation when running inside a Playwright
     * test. No-ops outside a test-runner context (library consumers driving
     * a raw Page), where the `log.warn` line is the only signal.
     */
    private annotate;
    /**
     * Clicks only if the element is present and visible. Returns true if clicked,
     * false if the element was absent — does not throw.
     */
    clickIfPresent(element: WebElement, options?: ActionTimeoutOptions): Promise<boolean>;
    fill(element: WebElement, text: string): Promise<void>;
    uploadFile(element: WebElement, filePath: string | string[], options?: ActionTimeoutOptions): Promise<void>;
    dropFiles(element: WebElement, filenames: string[], options?: {
        mimeType?: string;
    } & ActionTimeoutOptions): Promise<void>;
    /**
     * Unified method to interact with `<select>` dropdown elements based on the specified `DropdownSelectType`.
     * If no options are provided, safely defaults to randomly selecting an enabled, non-empty option.
     */
    selectDropdown(element: WebElement, options?: DropdownSelectOptions): Promise<string>;
    hover(element: WebElement): Promise<void>;
    scrollIntoView(element: WebElement): Promise<void>;
    /**
     * Drags an element to a target element or by a coordinate offset.
     * Absolute-offset drags use the page's mouse API (no Element equivalent
     * exists today); all other paths route through `Element.dragTo`.
     */
    dragAndDrop(element: WebElement, options: DragAndDropOptions): Promise<void>;
    /**
     * Filters an element list and returns the first match for the given text.
     * Uses Element.filter composition.
     */
    getByText(base: Element, desiredText: string, strict?: boolean): Promise<Element | null>;
    typeSequentially(element: WebElement, text: string, delay?: number): Promise<void>;
    /** Right-click (context menu) on the given element. Web-only. */
    rightClick(element: WebElement, options?: ActionTimeoutOptions): Promise<void>;
    doubleClick(element: WebElement): Promise<void>;
    check(element: WebElement): Promise<void>;
    uncheck(element: WebElement): Promise<void>;
    setSliderValue(element: WebElement, value: number, options?: ActionTimeoutOptions): Promise<void>;
    pressKey(key: string): Promise<void>;
    /**
     * Presses a key chord by joining the parts with `+` — `['Control', 'A']`
     * becomes `Control+A`. The multi-key companion to {@link pressKey}; use for
     * shortcuts (`['Meta', 'K']`) where listing modifiers reads clearer than a
     * pre-joined string. Throws on an empty array.
     */
    pressKeys(keys: string[]): Promise<void>;
    /**
     * Dispatches a synthetic DOM event on the element, optionally with an
     * `eventInit` payload (e.g. `{ key: 'Enter' }`). Goes through the locator so
     * it auto-waits for the element; unlike a real click/keypress it does NOT
     * require actionability — use it to drive handlers directly (custom events,
     * `input`/`change` on widgets that swallow synthetic typing).
     */
    dispatchEvent(element: WebElement, type: string, eventInit?: Record<string, unknown>): Promise<void>;
    clearInput(element: WebElement): Promise<void>;
    selectMultiple(element: WebElement, values: string[], options?: ActionTimeoutOptions): Promise<string[]>;
    /**
     * Resolves a specific element from a list by matching visible text or an attribute,
     * with optional child-element drill-down.
     *
     * Returns an `Element` — pass it into any `interact`/`verify`/`extract` method,
     * or cast to `WebElement` to reach the raw Playwright `Locator` for Playwright-specific
     * composition (e.g. `.and()`, `.or()`).
     */
    getListedElement(base: WebElement, options: ListedElementMatch, repo?: {
        getSelector(elementName: string, pageName: string): string;
    }): Promise<WebElement>;
}