/**
 * Licensed to the Apache Software Foundation (ASF) under one or more
 * contributor license agreements.  See the NOTICE file distributed with
 * this work for additional information regarding copyright ownership.
 * The ASF licenses this file to You under the Apache License, Version 2.0
 * (the "License", destination); you may not use this file except in compliance with
 * the License.  You may obtain a copy of the License at
 *
 *      https://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
import { WebElement, WebDriver, Locator } from 'selenium-webdriver';
import { Locators } from '../locators/locators';
import { WaitHelper } from '../utils/WaitHelper';
import { type ErrorContext } from '../errors/ExTesterError';
/**
 * Information needed to relocate an element after it becomes stale.
 */
export interface LocatorInfo {
    /** The locator used to find this element */
    locator: Locator;
    /** The parent element or locator this element was found within */
    enclosingLocator?: Locator | WebElement;
}
/**
 * Default wrapper for webElement
 */
export declare abstract class AbstractElement extends WebElement {
    static readonly ctlKey: string;
    protected static driver: WebDriver;
    protected static locators: Locators & Record<string, Record<string, unknown>>;
    protected static versionInfo: {
        version: string;
        browser: string;
    };
    protected static waitHelper: WaitHelper;
    protected enclosingItem: WebElement;
    /**
     * Locator information for auto-recovery when element becomes stale.
     * Stored when element is created with a Locator (not a WebElement).
     */
    protected locatorInfo?: LocatorInfo;
    /**
     * Constructs a new element from a Locator or an existing WebElement
     * @param base WebDriver compatible Locator for the given element or a reference to an existing WebElement
     * @param enclosingItem Locator or a WebElement reference to an element containing the element being constructed
     * this will be used to narrow down the search for the underlying DOM element
     */
    constructor(base: Locator | WebElement, enclosingItem?: WebElement | Locator);
    isEnabled(): Promise<boolean>;
    /**
     * Click the element, recovering when a transient overlay intercepts the
     * click. VS Code renders hovers/tooltips as DOM overlays that appear while
     * the WebDriver pointer rests on the last click point and never auto-hide,
     * so a plain W3C click deadlocks on its pre-dispatch hit-test. See
     * {@link WaitHelper.clickThroughInterception} for the recovery strategy.
     */
    click(): Promise<void>;
    isSelected(): Promise<boolean>;
    /**
     * Wait for the element to become visible
     * @param timeout custom timeout for the wait
     * @returns thenable self reference
     */
    wait(timeout?: number): Promise<this>;
    /**
     * Wait for the element to become stable (position/size stops changing).
     * Useful after animations or dynamic content loading.
     * @param timeout Maximum time to wait in milliseconds
     * @returns thenable self reference
     */
    waitForStable(timeout?: number): Promise<this>;
    /**
     * Return a reference to the WebElement containing this element
     */
    getEnclosingElement(): WebElement;
    /**
     * Get the stored locator information for this element, if available.
     */
    getLocatorInfo(): LocatorInfo | undefined;
    /**
     * Check if this element can be automatically recovered when stale.
     */
    canAutoRecover(): boolean;
    /**
     * Get the WaitHelper instance for condition-based waiting.
     */
    protected getWaitHelper(): WaitHelper;
    /**
     * Create error context for this element.
     * Useful for creating detailed error messages.
     */
    protected createErrorContext(action: string, details?: string): ErrorContext;
    static init(locators: Locators, driver: WebDriver, browser: string, version: string): void;
    /**
     * Execute a function with automatic recovery from stale element references.
     * If the element becomes stale during execution, it will be relocated and
     * the function will be retried once.
     *
     * @param fn The async function to execute
     * @param maxRetries Maximum number of recovery attempts (default: 1)
     * @returns The result of the function
     */
    withRecovery<T>(fn: (self: this) => Promise<T>, maxRetries?: number): Promise<T>;
    /**
     * Re-locate this element using stored locator information.
     * This is called automatically by withRecovery() when an element becomes stale.
     *
     * Subclasses can override this for custom recovery logic, but the default
     * implementation works for most cases when the element was created with a locator.
     *
     * @returns A new instance of this element type pointing to the relocated DOM element
     * @throws ElementRecoveryError if the element cannot be recovered
     */
    protected reinitialize(): Promise<this>;
    /**
     * Safely click on the element with automatic retry on stale/interactable errors.
     */
    safeClick(): Promise<void>;
    /**
     * Safely send keys to the element with automatic retry on stale/interactable errors.
     */
    safeSendKeys(...keys: (string | Promise<string>)[]): Promise<void>;
    /**
     * Safely get text from the element with automatic retry on stale errors.
     */
    safeGetText(): Promise<string>;
    /**
     * Safely get attribute from the element with automatic retry on stale errors.
     */
    safeGetAttribute(name: string): Promise<string>;
}