@olib-ai/owl-browser-sdk 2.0.5 → 2.0.7

package/dist/playwright/locator.d.ts

@@ -0,0 +1,237 @@
+/**
+ * Playwright-compatible Locator class for Owl Browser.
+ *
+ * Locators are lazy element references that resolve at action time.
+ * They store a selector and delegate all operations to the parent Page,
+ * enabling the same retry and auto-waiting semantics as Playwright.
+ *
+ * Supports Playwright selector engine formats: text=, css=, xpath=,
+ * role=, data-testid=, placeholder=, alt=, title=, label=.
+ */
+import type { Page } from './page.js';
+import type { ClickOptions, DblClickOptions, FillOptions, TypeOptions, PressOptions, HoverOptions, FocusOptions, ScreenshotOptions, CheckOptions, SelectOptionValue, SelectOptionOptions, LocatorWaitForOptions, LocatorFilterOptions, BoundingBox, SetInputFilesOptions } from './types.js';
+/**
+ * Convert a Playwright selector to a CSS/XPath selector that Owl understands.
+ *
+ * Playwright supports prefixed selectors like text=, css=, xpath=, role=, etc.
+ * This function converts those to standard CSS selectors or passes them as
+ * natural language descriptions to Owl's semantic matching.
+ *
+ * @param selector - Playwright-format selector
+ * @returns Transformed selector for Owl Browser
+ */
+export declare function convertSelector(selector: string): string;
+/**
+ * Locator represents a lazy reference to one or more DOM elements.
+ *
+ * All operations on a Locator are automatically retried until the element
+ * is available or the timeout expires. Locators can be chained to narrow
+ * the selection scope.
+ *
+ * @example
+ * ```typescript
+ * const button = page.locator('button.submit');
+ * await button.click();
+ *
+ * const text = await page.locator('.result').textContent();
+ * await page.locator('text=Sign In').click();
+ * await page.locator('[data-testid="submit"]').fill('hello');
+ * ```
+ */
+export declare class Locator {
+    /** @internal */
+    readonly _page: Page;
+    /** @internal */
+    readonly _selector: string;
+    constructor(page: Page, selector: string);
+    /** Click the element. */
+    click(options?: ClickOptions): Promise<void>;
+    /** Double-click the element. */
+    dblclick(options?: DblClickOptions): Promise<void>;
+    /** Fill the element with text (clears existing content first). */
+    fill(value: string, options?: FillOptions): Promise<void>;
+    /** Type text into the element (does NOT clear existing content). */
+    type(text: string, options?: TypeOptions): Promise<void>;
+    /** Focus the element and press a key. */
+    press(key: string, options?: PressOptions): Promise<void>;
+    /** Hover over the element. */
+    hover(options?: HoverOptions): Promise<void>;
+    /** Focus the element. */
+    focus(options?: FocusOptions): Promise<void>;
+    /** Check a checkbox (no-op if already checked). */
+    check(options?: CheckOptions): Promise<void>;
+    /** Uncheck a checkbox (no-op if already unchecked). */
+    uncheck(options?: CheckOptions): Promise<void>;
+    /** Select an option from a dropdown. */
+    selectOption(values: SelectOptionValue, options?: SelectOptionOptions): Promise<string[]>;
+    /**
+     * Upload files to a file input element.
+     *
+     * @param files - File path(s) to upload
+     * @param options - Upload options
+     */
+    setInputFiles(files: string | string[], options?: SetInputFilesOptions): Promise<void>;
+    /** Select all text within the element. */
+    selectText(): Promise<void>;
+    /**
+     * Dispatch a DOM event on the element.
+     *
+     * @param type - Event type (e.g., 'click', 'input', 'change')
+     * @param eventInit - Event initialization properties
+     */
+    dispatchEvent(type: string, eventInit?: Record<string, unknown>): Promise<void>;
+    /**
+     * Scroll the element into view if not already visible.
+     */
+    scrollIntoViewIfNeeded(): Promise<void>;
+    /**
+     * Highlight the element with a colored border for debugging.
+     */
+    highlight(): Promise<void>;
+    /** Get the text content of the element. */
+    textContent(): Promise<string | null>;
+    /** Get the inner HTML of the element. */
+    innerHTML(): Promise<string>;
+    /** Get the inner text of the element (visible text only). */
+    innerText(): Promise<string>;
+    /** Get the value of an attribute. */
+    getAttribute(name: string): Promise<string | null>;
+    /** Get the input value. */
+    inputValue(): Promise<string>;
+    /**
+     * Get the bounding box of the element.
+     *
+     * @returns Bounding box {x, y, width, height} or null if not visible
+     */
+    boundingBox(): Promise<BoundingBox | null>;
+    /**
+     * Get the count of elements matching this locator.
+     *
+     * Uses browser_count_elements for native element counting.
+     *
+     * @returns Number of matching elements
+     */
+    count(): Promise<number>;
+    /**
+     * Resolve all matching elements to an array of locators.
+     *
+     * @returns Array of Locators, one per matching element
+     */
+    all(): Promise<Locator[]>;
+    /** Whether the element is visible. */
+    isVisible(): Promise<boolean>;
+    /** Whether the element is enabled. */
+    isEnabled(): Promise<boolean>;
+    /** Whether the element (checkbox/radio) is checked. */
+    isChecked(): Promise<boolean>;
+    /** Whether the element is hidden. */
+    isHidden(): Promise<boolean>;
+    /** Whether the element is disabled. */
+    isDisabled(): Promise<boolean>;
+    /** Whether the element is editable. */
+    isEditable(): Promise<boolean>;
+    /** Wait for the element to satisfy a condition. */
+    waitFor(options?: LocatorWaitForOptions): Promise<void>;
+    /** Take a screenshot of the element (element mode). */
+    screenshot(options?: ScreenshotOptions): Promise<Buffer>;
+    /** Evaluate a function in the context of the matched element. */
+    evaluate<R>(pageFunction: string | ((el: unknown, arg?: unknown) => R), arg?: unknown): Promise<R>;
+    /**
+     * Filter this locator to only include elements matching additional criteria.
+     *
+     * @param options - Filter criteria (hasText, hasNotText)
+     * @returns A new filtered Locator
+     */
+    filter(options?: LocatorFilterOptions): Locator;
+    /**
+     * Create a locator matching elements that match either this or the given locator.
+     *
+     * @param locator - Another locator to OR with
+     * @returns A new combined Locator
+     */
+    or(locator: Locator): Locator;
+    /**
+     * Create a locator matching elements that match both this AND the given locator.
+     *
+     * @param locator - Another locator to AND with
+     * @returns A new combined Locator
+     */
+    and(locator: Locator): Locator;
+    /**
+     * Create a child locator by combining selectors.
+     *
+     * The resulting selector targets elements matching `selector`
+     * that are descendants of this locator's element.
+     */
+    locator(selector: string): Locator;
+    /**
+     * Return a locator for the first matching element.
+     *
+     * Uses :first-of-type when the selector is a simple tag, otherwise
+     * appends :nth-of-type(1) as a best-effort CSS approximation.
+     * For evaluate-dependent lookups, uses nth(0) semantics.
+     */
+    get first(): Locator;
+    /**
+     * Return a locator for the last matching element.
+     */
+    get last(): Locator;
+    /**
+     * Return a locator for the nth matching element (0-indexed).
+     *
+     * @param index - Zero-based index
+     */
+    nth(index: number): Locator;
+    /**
+     * Get a locator for elements matching text content.
+     *
+     * @param text - Text to search for
+     * @returns A new Locator targeting elements with matching text
+     */
+    getByText(text: string | RegExp): Locator;
+    /** Return the selector string this locator targets. */
+    toString(): string;
+}
+/**
+ * NthLocator wraps a base selector and an index.
+ *
+ * Uses the native `index` parameter supported by Owl Browser tools
+ * to target the Nth matching element without JavaScript evaluate hacks.
+ * When `index >= 0`, targets that specific match. When `index === -1`,
+ * targets the last match.
+ */
+export declare class NthLocator extends Locator {
+    private readonly _baseSelector;
+    private readonly _index;
+    constructor(page: Page, baseSelector: string, index: number);
+    /**
+     * Execute a tool with the base selector and index parameter.
+     * @internal
+     */
+    private _nthExecute;
+    click(options?: ClickOptions): Promise<void>;
+    dblclick(options?: DblClickOptions): Promise<void>;
+    fill(value: string, options?: FillOptions): Promise<void>;
+    type(text: string, options?: TypeOptions): Promise<void>;
+    press(key: string, options?: PressOptions): Promise<void>;
+    hover(options?: HoverOptions): Promise<void>;
+    focus(options?: FocusOptions): Promise<void>;
+    check(options?: CheckOptions): Promise<void>;
+    uncheck(options?: CheckOptions): Promise<void>;
+    textContent(): Promise<string | null>;
+    innerHTML(): Promise<string>;
+    innerText(): Promise<string>;
+    inputValue(): Promise<string>;
+    isVisible(): Promise<boolean>;
+    isChecked(): Promise<boolean>;
+    isEnabled(): Promise<boolean>;
+    isEditable(): Promise<boolean>;
+    getAttribute(name: string): Promise<string | null>;
+    dispatchEvent(type: string, eventInit?: Record<string, unknown>): Promise<void>;
+    boundingBox(): Promise<BoundingBox | null>;
+    scrollIntoViewIfNeeded(): Promise<void>;
+    selectText(): Promise<void>;
+    count(): Promise<number>;
+    toString(): string;
+}
+//# sourceMappingURL=locator.d.ts.map

package/dist/playwright/locator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"locator.d.ts","sourceRoot":"","sources":["../../src/playwright/locator.ts"],"names":[],"mappings":"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"}