saltfish/dist/utils/elementSizeValidator.d.ts

An interactive video-guided tour system for web applications

/**
 * Element Validator
 *
 * Validates that DOM elements match expected characteristics from recording.
 * Supports two validation strategies:
 *   1. Tag+Text validation: Matches element by tag name and text content (tried first)
 *   2. Size validation: Matches element by dimensions (fallback)
 *
 * Used to prevent cursor/transitions targeting obviously wrong elements.
 * If validation fails, returns null (acts as "element not found").
 */
export interface ExpectedSize {
    width: number;
    height: number;
}
export interface ExpectedElement {
    tagName: string;
    textContent: string;
}
interface SizeValidationConfig {
    /** Max allowed size difference ratio (0.5 = 50%) */
    tolerance: number;
    /** Minimum element size in pixels */
    minSize: number;
}
/**
 * Find a single valid element matching selector
 *
 * Validation strategy (in order):
 *   1. If expectedElement provided: Try tag+text matching first
 *   2. If expectedSize provided (or tag+text failed): Use size validation
 *   3. If neither provided: Return first visible element
 *
 * @param selector - CSS selector
 * @param expectedElement - Expected tag+text (optional, tried first)
 * @param expectedSize - Expected width/height (optional, fallback)
 * @param config - Validation config (optional)
 * @returns Element if valid, null if not found or all rejected
 */
export declare function findValidElement(selector: string, expectedElement?: ExpectedElement | null, expectedSize?: ExpectedSize | null, config?: SizeValidationConfig): Element | null;
/**
 * Find all valid elements matching selector
 * Used when attaching listeners to multiple elements (e.g., dom-click transitions)
 *
 * Validation strategy (in order):
 *   1. If expectedElement provided: Try tag+text matching first
 *   2. If expectedSize provided (or tag+text failed): Use size validation
 *   3. If neither provided: Return all visible elements
 *
 * @param selector - CSS selector
 * @param expectedElement - Expected tag+text (optional, tried first)
 * @param expectedSize - Expected width/height (optional, fallback)
 * @param config - Validation config (optional)
 * @returns Array of valid elements (may be empty)
 */
export declare function findAllValidElements(selector: string, expectedElement?: ExpectedElement | null, expectedSize?: ExpectedSize | null, config?: SizeValidationConfig): Element[];
/**
 * Validate a specific element against expected characteristics
 * Used when you already have an element reference
 *
 * Validation strategy (in order):
 *   1. If expectedElement provided: Check tag+text match
 *   2. If expectedSize provided (and tag+text passed or not provided): Check size match
 *   3. If neither provided: Just check basic visibility
 *
 * @param element - Element to validate
 * @param expectedElement - Expected tag+text (optional, tried first)
 * @param expectedSize - Expected width/height (optional, fallback)
 * @param config - Validation config (optional)
 * @returns true if valid, false if rejected
 */
export declare function isElementValid(element: Element, expectedElement?: ExpectedElement | null, expectedSize?: ExpectedSize | null, config?: SizeValidationConfig): boolean;
export {};
//# sourceMappingURL=elementSizeValidator.d.ts.map