"""Type stubs for the xa11y native extension module."""

from __future__ import annotations

from collections.abc import Iterator
from types import TracebackType

# ── Exceptions ───────────────────────────────────────────────────────────────

class XA11yError(Exception): ...
class PermissionDeniedError(XA11yError): ...
class AppNotFoundError(XA11yError): ...
class SelectorNotMatchedError(XA11yError): ...
class ActionNotSupportedError(XA11yError): ...
class TimeoutError(XA11yError): ...
class InvalidSelectorError(XA11yError): ...
class PlatformError(XA11yError): ...

# ── Data Classes ─────────────────────────────────────────────────────────────

class Rect:
    @property
    def x(self) -> int: ...
    @property
    def y(self) -> int: ...
    @property
    def width(self) -> int: ...
    @property
    def height(self) -> int: ...
    def __repr__(self) -> str: ...
    def __eq__(self, other: object) -> bool: ...

class NormalizedRect:
    @property
    def left(self) -> float: ...
    @property
    def top(self) -> float: ...
    @property
    def right(self) -> float: ...
    @property
    def bottom(self) -> float: ...
    def __repr__(self) -> str: ...

class AppInfo:
    @property
    def name(self) -> str: ...
    @property
    def pid(self) -> int: ...
    @property
    def bundle_id(self) -> str | None: ...
    def __repr__(self) -> str: ...

# ── Node ─────────────────────────────────────────────────────────────────────

class Node:
    @property
    def role(self) -> str: ...
    @property
    def name(self) -> str | None: ...
    @property
    def value(self) -> str | None: ...
    @property
    def description(self) -> str | None: ...
    @property
    def depth(self) -> int: ...
    @property
    def numeric_value(self) -> float | None: ...
    @property
    def min_value(self) -> float | None: ...
    @property
    def max_value(self) -> float | None: ...
    @property
    def stable_id(self) -> str | None: ...
    @property
    def actions(self) -> list[str]: ...
    @property
    def bounds(self) -> Rect | None: ...
    @property
    def bounds_normalized(self) -> NormalizedRect | None: ...
    @property
    def enabled(self) -> bool: ...
    @property
    def visible(self) -> bool: ...
    @property
    def focused(self) -> bool: ...
    @property
    def checked(self) -> str | None: ...
    @property
    def selected(self) -> bool: ...
    @property
    def expanded(self) -> bool | None: ...
    @property
    def editable(self) -> bool: ...
    @property
    def focusable(self) -> bool: ...
    @property
    def modal(self) -> bool: ...
    @property
    def required(self) -> bool: ...
    @property
    def busy(self) -> bool: ...
    def __repr__(self) -> str: ...
    def __str__(self) -> str: ...
    def __len__(self) -> int: ...

# ── Target type for action methods ───────────────────────────────────────────

_Target = Node | str

# ── Tree ─────────────────────────────────────────────────────────────────────

class Tree:
    @property
    def app_name(self) -> str: ...
    @property
    def pid(self) -> int | None: ...
    @property
    def screen_size(self) -> tuple[int, int]: ...
    @property
    def root(self) -> Node: ...
    def children(self, node: Node) -> list[Node]: ...
    def parent(self, node: Node) -> Node | None: ...
    def query(self, selector: str) -> list[Node]: ...
    def find_by_role(self, role: str) -> list[Node]: ...
    def find_by_name(self, pattern: str) -> list[Node]: ...
    def perform(
        self,
        target: _Target,
        action: str,
        *,
        value: str | None = None,
        numeric_value: float | None = None,
        direction: str | None = None,
        amount: float | None = None,
        start: int | None = None,
        end: int | None = None,
    ) -> None: ...
    def press(self, target: _Target) -> None: ...
    def focus(self, target: _Target) -> None: ...
    def blur(self, target: _Target) -> None: ...
    def toggle(self, target: _Target) -> None: ...
    def expand(self, target: _Target) -> None: ...
    def collapse(self, target: _Target) -> None: ...
    def select(self, target: _Target) -> None: ...
    def increment(self, target: _Target) -> None: ...
    def decrement(self, target: _Target) -> None: ...
    def show_menu(self, target: _Target) -> None: ...
    def scroll_into_view(self, target: _Target) -> None: ...
    def set_value(self, target: _Target, value: str) -> None: ...
    def set_numeric_value(self, target: _Target, value: float) -> None: ...
    def type_text(self, target: _Target, text: str) -> None: ...
    def scroll(self, target: _Target, direction: str, amount: float = 1.0) -> None: ...
    def select_text(self, target: _Target, start: int, end: int) -> None: ...
    def locator(
        self,
        selector: str,
        *,
        max_depth: int | None = None,
        max_elements: int | None = None,
        visible_only: bool = False,
        roles: list[str] | None = None,
        include_raw: bool = False,
    ) -> Locator: ...
    def dump(self) -> str: ...
    def __len__(self) -> int: ...
    def __iter__(self) -> Iterator[Node]: ...
    def __repr__(self) -> str: ...
    def __str__(self) -> str: ...

# ── Provider ─────────────────────────────────────────────────────────────────

class Provider:
    def __init__(self) -> None: ...
    def app(
        self,
        name: str | None = None,
        *,
        pid: int | None = None,
        max_depth: int | None = None,
        max_elements: int | None = None,
        visible_only: bool = False,
        roles: list[str] | None = None,
        include_raw: bool = False,
    ) -> Tree: ...
    def all_apps(
        self,
        *,
        max_depth: int | None = None,
        max_elements: int | None = None,
        visible_only: bool = False,
        roles: list[str] | None = None,
        include_raw: bool = False,
    ) -> Tree: ...
    def list_apps(self) -> list[AppInfo]: ...
    def check_permissions(self) -> str: ...
    def locator(
        self,
        name: str | None = None,
        *,
        pid: int | None = None,
        selector: str,
        max_depth: int | None = None,
        max_elements: int | None = None,
        visible_only: bool = False,
        roles: list[str] | None = None,
        include_raw: bool = False,
    ) -> Locator: ...
    def __enter__(self) -> Provider: ...
    def __exit__(
        self,
        exc_type: type[BaseException] | None = None,
        exc_val: BaseException | None = None,
        exc_tb: TracebackType | None = None,
    ) -> bool: ...
    def __repr__(self) -> str: ...

# ── Locator ──────────────────────────────────────────────────────────────────

class Locator:
    @property
    def selector(self) -> str: ...
    def nth(self, n: int) -> Locator: ...
    def first(self) -> Locator: ...
    def child(self, selector: str) -> Locator: ...
    def descendant(self, selector: str) -> Locator: ...
    def role(self) -> str: ...
    def name(self) -> str | None: ...
    def value(self) -> str | None: ...
    def description(self) -> str | None: ...
    def is_visible(self) -> bool: ...
    def is_enabled(self) -> bool: ...
    def is_focused(self) -> bool: ...
    def exists(self) -> bool: ...
    def count(self) -> int: ...
    def get(self) -> Node: ...
    def press(self) -> None: ...
    def focus(self) -> None: ...
    def blur(self) -> None: ...
    def toggle(self) -> None: ...
    def expand(self) -> None: ...
    def collapse(self) -> None: ...
    def select_item(self) -> None: ...
    def show_menu(self) -> None: ...
    def scroll_into_view(self) -> None: ...
    def increment(self) -> None: ...
    def decrement(self) -> None: ...
    def set_value(self, value: str) -> None: ...
    def set_numeric_value(self, value: float) -> None: ...
    def type_text(self, text: str) -> None: ...
    def select_text(self, start: int, end: int) -> None: ...
    def scroll(self, direction: str, amount: float = 1.0) -> None: ...
    def wait_visible(self, timeout: float = 5.0) -> None: ...
    def wait_attached(self, timeout: float = 5.0) -> None: ...
    def wait_detached(self, timeout: float = 5.0) -> None: ...
    def wait_enabled(self, timeout: float = 5.0) -> None: ...
    def wait_hidden(self, timeout: float = 5.0) -> None: ...
    def __repr__(self) -> str: ...

# ── Module-level functions ───────────────────────────────────────────────────

def connect() -> Provider: ...
def app(
    name: str | None = None,
    *,
    pid: int | None = None,
    max_depth: int | None = None,
    max_elements: int | None = None,
    visible_only: bool = False,
    roles: list[str] | None = None,
    include_raw: bool = False,
) -> Tree: ...
def list_apps() -> list[AppInfo]: ...
def check_permissions() -> str: ...

# ── Test helpers ─────────────────────────────────────────────────────────────

def _make_test_tree() -> Tree: ...
def _make_test_provider() -> Provider: ...
