accessibility-checker-engine/v4/simulator/SRCursor.d.ts

An automated accessibility checking engine for use by other tools

import { AccessibleNameResult } from "../util/AccNameUtil";
/**
 * Function type for matching nodes during cursor navigation
 * @param role - The ARIA role of the current node
 * @param bStartTag - Whether this is a start tag (true) or end tag (false)
 * @param node - The DOM node being evaluated
 * @returns True if the node matches the criteria, false otherwise
 */
export type SRCursorMatchFunc = (role: string, bStartTag: boolean, node: Node) => boolean;
export type SRCursorSkipFunc = (cursor: SRCursor) => {
    skipCurrent: boolean;
    skipChildren: boolean;
} | null;
/**
 * SRCursor (Screen Reader Cursor) class
 *
 * This class provides a cursor-like interface for navigating the DOM in a way that
 * simulates how screen readers process and navigate content. It tracks:
 * - The current node position
 * - Whether it's at a start or end tag
 * - The ARIA role of the current node
 * - The accessible name of the current node
 */
export declare class SRCursor {
    /** The ARIA role of the current node */
    private role;
    /** The computed accessible name of the current node */
    private name;
    /** The underlying DOM walker that handles node traversal */
    private walker;
    /**
     * Creates a new SRCursor positioned at the specified element
     * @param element - The DOM node to position the cursor at
     * @param bEnd - Whether to position at the end tag (true) or start tag (false)
     */
    constructor(element: Node, bEnd?: boolean);
    /**
     * Creates a copy of this cursor at the same position
     * @returns A new SRCursor instance with the same position and properties
     */
    clone(): SRCursor;
    /**
     * Updates the role and accessible name properties based on the current node
     * This is called whenever the cursor position changes
     * @private
     */
    private refreshName;
    /**
     * Moves the cursor to the next node that matches the provided criteria
     * @param matchingFunc - Function that determines if a node matches the search criteria
     * @returns true if a matching node was found, false otherwise
     */
    next(matchingFunc: SRCursorMatchFunc, skipFunc?: SRCursorSkipFunc): boolean;
    /**
     * Moves the cursor to the previous node that matches the provided criteria
     * @param matchingFunc - Function that determines if a node matches the search criteria
     * @returns true if a matching node was found, false otherwise
     */
    previous(matchingFunc: SRCursorMatchFunc, skipFunc?: SRCursorSkipFunc): boolean;
    /**
     * Moves the cursor to the parent node of the current node
     * @param endTag - Whether to position at the end tag (true) or start tag (false)
     * @returns true if successfully moved to parent, false if no parent exists
     */
    parent(endTag?: boolean): boolean;
    /**
     * Moves the cursor up the DOM tree until finding a node with a matching role or element name
     * @param roles - Array of ARIA roles to match
     * @param elems - Optional array of element names to match
     * @returns true if a matching node was found, false otherwise
     */
    getCurrentOrParentByRole(roles: string[], elems?: string[]): boolean;
    /**
     * Creates a new cursor and moves it up the DOM tree until finding a node with a matching role or element name
     * @param roles - Array of ARIA roles to match
     * @param elems - Optional array of element names to match
     * @returns A new cursor at the matching node, or null if no match found
     */
    getCurrentOrParentByRoleClone(roles: string[], elems?: string[]): SRCursor;
    getCurrentOrParentTabbableClone(): SRCursor;
    /**
     * Gets the ARIA role of the current node
     * @returns The ARIA role as a string, or undefined if not available
     */
    getRole(): string | undefined;
    /**
     * Gets the accessible name info for the current node
     * @returns The AccessibleNameResult object, or undefined if not available
     */
    getNameInfo(): AccessibleNameResult | undefined;
    /**
     * Get the accessible name of the current node
     */
    getName(): string | undefined;
    /**
     * Sets whether the cursor is at an end tag or start tag
     * @param val - True for end tag, false for start tag
     */
    setEndTag(val: boolean): void;
    /**
     * Gets the DOM node at the current cursor position
     * @returns The current DOM node
     */
    getNode(): Node;
    /**
     * Gets the current node as an HTMLElement if it is an element node
     * @returns The current node as HTMLElement, or undefined if not an element
     */
    getElement(): HTMLElement;
    getParentElement(): SRCursor;
    /**
     * Checks if the cursor is positioned at an end tag
     * @returns true if at an end tag, false if at a start tag
     */
    isEndTag(): boolean;
    /**
     * Checks if the cursor is positioned at an end tag
     * @returns true if at an end tag, false if at a start tag
     */
    isStartTag(): boolean;
    /**
     * Compares the document position of two cursors
     * @param one - First cursor to compare
     * @param two - Second cursor to compare
     * @returns 0 if equal, -1 if one is before two, 1 if one is after two
     */
    static compare(one: SRCursor | null, two: SRCursor | null): 0 | 1 | -1;
    /**
     * Checks if this cursor's node contains another cursor's node
     * @param other - The other cursor to check
     * @returns true if this cursor contains (is a parent/ancestor of) the other cursor's node
     */
    contains(other: SRCursor): boolean;
    /**
     * Checks if this cursor points to the same node as another cursor
     * @param other - The other cursor to compare with
     * @returns true if both cursors point to the same node
     */
    isSameNode(other: SRCursor): boolean;
    /**
     * Checks if the current node has a non-empty accessible name
     * @returns true if the node has a non-empty accessible name
     */
    hasNonEmptyName(): boolean;
}