@mirawision/domino/wait.d.ts

Lightweight DOM utilities for Chrome Extension content scripts

import { ElementTarget, WaitOptions } from './types';
/**
 * Waits for an element matching the target to appear in the DOM.
 *
 * @param target - A selector string, Element, or predicate function to match elements against
 * @param options - Configuration options
 * @param options.root - The root element to observe (defaults to document)
 * @param options.timeout - Maximum time to wait in milliseconds (defaults to 10000)
 * @param options.signal - Optional AbortSignal to cancel the wait
 * @param options.subtree - Whether to observe the entire subtree (defaults to true)
 * @returns Promise that resolves with the matching element
 *
 * @example
 * ```typescript
 * // Wait for element by selector
 * const element = await waitFor('.my-class');
 *
 * // Wait with timeout and abort signal
 * const controller = new AbortController();
 * const element = await waitFor('.my-class', {
 *   timeout: 5000,
 *   signal: controller.signal
 * });
 * ```
 *
 * @throws {Error} If the operation times out or is aborted
 */
export declare function waitFor(target: ElementTarget, options?: WaitOptions): Promise<Element>;
/**
 * Waits for an element matching the target to be removed from the DOM.
 *
 * @param target - A selector string, Element, or predicate function to match elements against
 * @param options - Configuration options
 * @param options.root - The root element to observe (defaults to document)
 * @param options.timeout - Maximum time to wait in milliseconds (defaults to 10000)
 * @param options.signal - Optional AbortSignal to cancel the wait
 * @param options.subtree - Whether to observe the entire subtree (defaults to true)
 * @returns Promise that resolves when the element is removed
 *
 * @example
 * ```typescript
 * // Wait for element to be removed
 * await waitForRemoved('.loading-spinner');
 *
 * // Wait with custom timeout
 * await waitForRemoved('.my-class', {
 *   timeout: 3000
 * });
 * ```
 *
 * @throws {Error} If the operation times out or is aborted
 */
export declare function waitForRemoved(target: ElementTarget, options?: WaitOptions): Promise<void>;
/**
 * Waits for a specific change to occur on elements matching the target.
 * The change is determined by a predicate function that evaluates mutation records.
 *
 * @param target - A selector string, Element, or predicate function to match elements against
 * @param predicate - Function that evaluates mutation records to determine if the desired change occurred
 * @param options - Configuration options
 * @param options.root - The root element to observe (defaults to document)
 * @param options.timeout - Maximum time to wait in milliseconds (defaults to 10000)
 * @param options.signal - Optional AbortSignal to cancel the wait
 * @param options.subtree - Whether to observe the entire subtree (defaults to true)
 * @returns Promise that resolves with the mutation records when the predicate returns true
 *
 * @example
 * ```typescript
 * // Wait for a specific attribute to change
 * const records = await waitForChange('.my-class',
 *   (records) => records.some(r => r.attributeName === 'data-status')
 * );
 *
 * // Wait for text content to contain specific text
 * const records = await waitForChange('.my-class',
 *   (records) => records.some(r => {
 *     const node = r.target as Element;
 *     return node.textContent?.includes('Ready');
 *   })
 * );
 * ```
 *
 * @throws {Error} If the operation times out or is aborted
 */
export declare function waitForChange(target: ElementTarget, predicate: (records: MutationRecord[]) => boolean, options?: WaitOptions): Promise<MutationRecord[]>;