Utilities

interface Commons {
  aria: Aria;
  color: ColorUtils;
  dom: DomUtils;
  forms: FormsUtils;
  math: MathUtils;
  matches: MatchesFunction;
  standards: StandardsUtils;
  table: TableUtils;
  text: TextUtils;
}

/**
 * Get allowed ARIA attributes for an element
 * @param element - Element to analyze
 * @returns Array of allowed attribute names
 */
function allowedAttr(element: Element | VirtualNode): string[];

/**
 * Get text from aria-label attribute
 * @param element - Element to analyze
 * @returns aria-label text or null
 */
function arialabelText(element: Element | VirtualNode): string | null;

/**
 * Get text from aria-labelledby references
 * @param element - Element to analyze
 * @returns Concatenated labelledby text
 */
function arialabelledbyText(element: Element | VirtualNode): string;

/**
 * Get accessible references for aria-labelledby or aria-describedby
 * @param element - Element to analyze
 * @param attr - Attribute name ('aria-labelledby' or 'aria-describedby')
 * @returns Array of referenced elements
 */
function getAccessibleRefs(element: Element | VirtualNode, attr: string): Element[];

/**
 * Get roles not allowed on an element
 * @param element - Element to analyze
 * @returns Array of unallowed role names
 */
function getElementUnallowedRoles(element: Element | VirtualNode): string[];

/**
 * Get explicit ARIA role from role attribute
 * @param element - Element to analyze
 * @returns Explicit role or null
 */
function getExplicitRole(element: Element | VirtualNode): string | null;

/**
 * Get implicit ARIA role for an element
 * @param element - Element to analyze
 * @returns Implicit role or null
 */
function getImplicitRole(element: Element | VirtualNode): string | null;

/**
 * Get owned virtual nodes via aria-owns
 * @param element - Element to analyze
 * @returns Array of owned virtual nodes
 */
function getOwnedVirtual(element: VirtualNode): VirtualNode[];

/**
 * Get the computed ARIA role for an element
 * @param element - Element to analyze
 * @returns Role string or null
 */
function getRole(element: Element | VirtualNode): string | null;

/**
 * Get the ARIA role type for an element
 * @param role - Role string, element, or virtual node
 * @returns Role type or null
 */
function getRoleType(role: string | Element | VirtualNode | null): string | null;

/**
 * Get roles by type category
 * @param roleType - Type of roles to retrieve
 * @returns Array of role names
 */
function getRolesByType(roleType: string): string[];

/**
 * Get roles that get their name from contents
 * @returns Array of role names
 */
function getRolesWithNameFromContents(): string[];

/**
 * Get implicit ARIA nodes
 * @param role - Role to analyze
 * @returns Array of node types
 */
function implicitNodes(role: string): string[];

/**
 * Check if element is accessible reference
 * @param element - Element to test
 * @returns True if accessible reference
 */
function isAccessibleRef(element: Element | VirtualNode): boolean;

/**
 * Check if ARIA role is allowed on element
 * @param element - Element to test
 * @param role - Role to check
 * @returns True if role allowed
 */
function isAriaRoleAllowedOnElement(element: Element | VirtualNode, role: string): boolean;

/**
 * Check if element is combobox popup
 * @param element - Element to test
 * @returns True if combobox popup
 */
function isComboboxPopup(element: Element | VirtualNode): boolean;

/**
 * Check if role is unsupported
 * @param role - Role to check
 * @returns True if unsupported
 */
function isUnsupportedRole(role: string): boolean;

/**
 * Check if role is valid
 * @param role - Role to check
 * @returns True if valid
 */
function isValidRole(role: string): boolean;

/**
 * Get the accessible name for an element using virtual node
 * @param element - Virtual node to analyze
 * @param options - Options for name calculation
 * @returns Accessible name string
 */
function labelVirtual(element: VirtualNode, options?: AccessibleNameOptions): string;

/**
 * Get the accessible name for an element
 * @param element - Element to analyze
 * @param options - Options for name calculation
 * @returns Accessible name string
 */
function label(element: Element | VirtualNode, options?: AccessibleNameOptions): string;

/**
 * Get ARIA lookup table data
 * @param key - Lookup key
 * @returns Lookup table entry or null
 */
function lookupTable(key: string): any | null;

/**
 * Check if element gets name from contents
 * @param element - Element to check
 * @returns True if named from contents
 */
function namedFromContents(element: Element | VirtualNode): boolean;

/**
 * Get required ARIA attributes for element
 * @param element - Element to analyze
 * @returns Array of required attribute names
 */
function requiredAttr(element: Element | VirtualNode): string[];

/**
 * Get required context roles for element
 * @param element - Element to analyze
 * @returns Array of required context roles
 */
function requiredContext(element: Element | VirtualNode): string[];

/**
 * Get required owned roles for element
 * @param element - Element to analyze
 * @returns Array of required owned roles
 */
function requiredOwned(element: Element | VirtualNode): string[];

/**
 * Validate an ARIA attribute value
 * @param element - Element with the attribute
 * @param attr - Attribute name
 * @param value - Attribute value
 * @returns True if valid
 */
function validateAttrValue(element: Element | VirtualNode, attr: string, value: string): boolean;

/**
 * Validate an ARIA attribute
 * @param element - Element with the attribute
 * @param attr - Attribute name
 * @returns True if valid
 */
function validateAttr(element: Element | VirtualNode, attr: string): boolean;

// Setup required for commons usage
axe.setup();

const button = document.querySelector('button');
const role = axe.commons.aria.getRole(button);
console.log('Button role:', role);

const label = axe.commons.aria.label(button);
console.log('Button label:', label);

const roleType = axe.commons.aria.getRoleType('button');
console.log('Role type:', roleType); // 'widget'

const allowedAttrs = axe.commons.aria.allowedAttr(button);
console.log('Allowed attributes:', allowedAttrs);

axe.teardown();

/**
 * Color class for color manipulation and analysis
 */
class Color {
  constructor(red: number, green: number, blue: number, alpha?: number);
  
  /**
   * Get contrast ratio with another color
   * @param color2 - Second color for comparison
   * @returns Contrast ratio (1-21)
   */
  getContrast(color2: Color): number;
  
  /**
   * Get relative luminance
   * @returns Luminance value (0-1)
   */
  getRelativeLuminance(): number;
  
  /**
   * Convert to hex string
   * @returns Hex color string
   */
  toHexString(): string;
  
  /**
   * Parse color from string
   * @param colorString - CSS color string
   * @returns Color instance or null
   */
  static parseString(colorString: string): Color | null;
}

/**
 * Get center point of rectangle
 * @param rect - Rectangle object
 * @returns Center point {x, y}
 */
function centerPointOfRect(rect: DOMRect): { x: number; y: number };

/**
 * Check if element has background image
 * @param element - Element to check
 * @returns True if has background image
 */
function elementHasImage(element: Element | VirtualNode): boolean;

/**
 * Check if element is visually distinct
 * @param element - Element to check
 * @returns True if visually distinct
 */
function elementIsDistinct(element: Element | VirtualNode): boolean;

/**
 * Get filtered rectangle stack for color analysis
 * @param element - Element to analyze
 * @returns Array of rectangle objects
 */
function filteredRectStack(element: Element | VirtualNode): DOMRect[];

/**
 * Flatten colors for contrast calculation
 * @param fgColor - Foreground color
 * @param bgColor - Background color
 * @param opacity - Opacity value
 * @returns Flattened color
 */
function flattenColors(fgColor: Color, bgColor: Color, opacity: number): Color;

/**
 * Get background color of element
 * @param element - Element to analyze
 * @param options - Analysis options
 * @returns Background color
 */
function getBackgroundColor(element: Element | VirtualNode, options?: any): Color | null;

/**
 * Get background stack for element
 * @param element - Element to analyze
 * @returns Array of background elements
 */
function getBackgroundStack(element: Element | VirtualNode): Element[];

/**
 * Get contrast ratio between foreground and background
 * @param element - Element to analyze
 * @param options - Analysis options
 * @returns Contrast ratio or null
 */
function getContrast(element: Element | VirtualNode, options?: any): number | null;

/**
 * Get foreground color of element
 * @param element - Element to analyze
 * @param options - Analysis options
 * @returns Foreground color
 */
function getForegroundColor(element: Element | VirtualNode, options?: any): Color | null;

/**
 * Check if contrast ratio is valid
 * @param contrastRatio - Contrast ratio to check
 * @param fontSize - Font size in pixels
 * @param isBold - Whether text is bold
 * @param level - WCAG level ('AA' or 'AAA')
 * @returns True if valid contrast
 */
function hasValidContrastRatio(contrastRatio: number, fontSize: number, isBold: boolean, level: 'AA' | 'AAA'): boolean;

/**
 * Get incomplete contrast data
 * @param element - Element to analyze
 * @returns Incomplete data object
 */
function incompleteData(element: Element | VirtualNode): any;

axe.setup();

const textElement = document.querySelector('p');
const contrast = axe.commons.color.getContrast(textElement);
console.log('Contrast ratio:', contrast);

const hasValidContrast = axe.commons.color.hasValidContrastRatio(contrast, 16, false, 'AA');
console.log('Valid AA contrast:', hasValidContrast);

// Create and manipulate colors
const red = new axe.commons.color.Color(255, 0, 0, 1);
const blue = new axe.commons.color.Color(0, 0, 255, 1);
const contrastRatio = red.getContrast(blue);
console.log('Red vs Blue contrast:', contrastRatio);

axe.teardown();

/**
 * Create grid for layout analysis
 * @param container - Container element
 * @param options - Grid options
 * @returns Grid data structure
 */
function createGrid(container: Element, options?: any): any;

/**
 * Find elements in context
 * @param context - Context specification
 * @param selector - CSS selector
 * @returns Array of matching elements
 */
function findElmsInContext(context: any, selector: string): Element[];

/**
 * Find nearby elements
 * @param element - Reference element
 * @returns Array of nearby elements
 */
function findNearbyElms(element: Element | VirtualNode): Element[];

/**
 * Find ancestor matching condition (virtual node version)
 * @param element - Starting virtual node
 * @param condition - Test function
 * @returns Matching ancestor or null
 */
function findUpVirtual(element: VirtualNode, condition: (el: VirtualNode) => boolean): VirtualNode | null;

/**
 * Find ancestor matching condition
 * @param element - Starting element
 * @param condition - Test function
 * @returns Matching ancestor or null
 */
function findUp(element: Element, condition: (el: Element) => boolean): Element | null;

/**
 * Check if focus is disabled on element
 * @param element - Element to check
 * @returns True if focus disabled
 */
function focusDisabled(element: Element | VirtualNode): boolean;

/**
 * Get composed parent in shadow DOM
 * @param element - Element to analyze
 * @returns Composed parent element
 */
function getComposedParent(element: Element): Element | null;

/**
 * Get element by reference attribute
 * @param element - Referencing element
 * @param attr - Reference attribute name
 * @returns Referenced element or null
 */
function getElementByReference(element: Element | VirtualNode, attr: string): Element | null;

/**
 * Get element coordinates
 * @param element - Element to analyze
 * @returns Coordinate object
 */
function getElementCoordinates(element: Element | VirtualNode): { x: number; y: number };

/**
 * Get element stack at point
 * @param element - Element to analyze
 * @returns Array of elements at point
 */
function getElementStack(element: Element | VirtualNode): Element[];

/**
 * Get modal dialog element
 * @param options - Search options
 * @returns Modal dialog element or null
 */
function getModalDialog(options?: any): Element | null;

/**
 * Get overflow hidden ancestors
 * @param element - Element to analyze
 * @returns Array of ancestors with overflow hidden
 */
function getOverflowHiddenAncestors(element: Element | VirtualNode): Element[];

/**
 * Get rectangle stack for element
 * @param element - Element to analyze
 * @returns Array of rectangles
 */
function getRectStack(element: Element | VirtualNode): DOMRect[];

/**
 * Get root node for element
 * @param element - Element to analyze
 * @returns Root node
 */
function getRootNode(element: Element | VirtualNode): Node;

/**
 * Get scroll offset
 * @param element - Element to analyze
 * @returns Scroll offset {x, y}
 */
function getScrollOffset(element: Element | VirtualNode): { x: number; y: number };

/**
 * Get tabbable elements within a container
 * @param node - Container element
 * @returns Array of tabbable elements
 */
function getTabbableElements(node: Element | VirtualNode): Element[];

/**
 * Get target rectangles for element
 * @param element - Element to analyze
 * @returns Array of target rectangles
 */
function getTargetRects(element: Element | VirtualNode): DOMRect[];

/**
 * Get target size for element
 * @param element - Element to analyze
 * @returns Target size {width, height}
 */
function getTargetSize(element: Element | VirtualNode): { width: number; height: number };

/**
 * Get text element stack
 * @param element - Element to analyze
 * @returns Array of text elements
 */
function getTextElementStack(element: Element | VirtualNode): Element[];

/**
 * Get viewport size
 * @param win - Window object (defaults to current window)
 * @returns Object with width and height
 */
function getViewportSize(win?: Window): { width: number; height: number };

/**
 * Get visible child text rectangles
 * @param element - Parent element
 * @returns Array of text rectangles
 */
function getVisibleChildTextRects(element: Element | VirtualNode): DOMRect[];

/**
 * Check if element has content (virtual node version)
 * @param element - Virtual node to check
 * @returns True if has content
 */
function hasContentVirtual(element: VirtualNode): boolean;

/**
 * Check if element has content
 * @param element - Element to check
 * @returns True if has content
 */
function hasContent(element: Element | VirtualNode): boolean;

/**
 * Check if element has language text
 * @param element - Element to check
 * @returns True if has language text
 */
function hasLangText(element: Element | VirtualNode): boolean;

/**
 * Get elements referenced by IDREF/IDREFS
 * @param element - Element with references
 * @param attr - Reference attribute
 * @returns Array of referenced elements
 */
function idrefs(element: Element | VirtualNode, attr: string): Element[];

/**
 * Check if element is inserted into focus order
 * @param element - Element to check
 * @returns True if in focus order
 */
function insertedIntoFocusOrder(element: Element | VirtualNode): boolean;

/**
 * Check if element is current page link
 * @param element - Link element to check
 * @returns True if current page link
 */
function isCurrentPageLink(element: Element | VirtualNode): boolean;

/**
 * Check if an element is focusable
 * @param node - Element or virtual node to test
 * @returns True if focusable
 */
function isFocusable(node: Element | VirtualNode): boolean;

/**
 * Check if element is hidden for everyone
 * @param element - Element to check
 * @returns True if hidden for everyone
 */
function isHiddenForEveryone(element: Element | VirtualNode): boolean;

/**
 * Check if element is hidden with CSS
 * @param element - Element to check
 * @returns True if CSS hidden
 */
function isHiddenWithCss(element: Element | VirtualNode): boolean;

/**
 * Check if document is HTML5
 * @param doc - Document to check
 * @returns True if HTML5
 */
function isHtml5(doc: Document): boolean;

/**
 * Check if element is in tab order
 * @param element - Element to check
 * @returns True if in tab order
 */
function isInTabOrder(element: Element | VirtualNode): boolean;

/**
 * Check if element is in text block
 * @param element - Element to check
 * @returns True if in text block
 */
function isInTextBlock(element: Element | VirtualNode): boolean;

/**
 * Check if element is inert
 * @param element - Element to check
 * @returns True if inert
 */
function isInert(element: Element | VirtualNode): boolean;

/**
 * Check if modal is open
 * @param options - Check options
 * @returns True if modal open
 */
function isModalOpen(options?: any): boolean;

/**
 * Check if element is multiline
 * @param element - Element to check
 * @returns True if multiline
 */
function isMultiline(element: Element | VirtualNode): boolean;

/**
 * Check if an element is natively focusable
 * @param node - Element or virtual node to test
 * @returns True if natively focusable
 */
function isNativelyFocusable(node: Element | VirtualNode): boolean;

/**
 * Check if value is DOM node
 * @param candidate - Value to check
 * @returns True if DOM node
 */
function isNode(candidate: any): candidate is Node;

/**
 * Check if element is offscreen
 * @param element - Element to check
 * @returns True if offscreen
 */
function isOffscreen(element: Element | VirtualNode): boolean;

/**
 * Check if element is opaque
 * @param element - Element to check
 * @returns True if opaque
 */
function isOpaque(element: Element | VirtualNode): boolean;

/**
 * Check if element is skip link
 * @param element - Element to check
 * @returns True if skip link
 */
function isSkipLink(element: Element | VirtualNode): boolean;

/**
 * Check if element is visible on screen
 * @param element - Element to check
 * @returns True if visible on screen
 */
function isVisibleOnScreen(element: Element | VirtualNode): boolean;

/**
 * Check if element is visible to screen reader
 * @param element - Element to check
 * @returns True if visible to screen reader
 */
function isVisibleToScreenreader(element: Element | VirtualNode): boolean;

/**
 * Check if an element is visible
 * @param element - Element to test
 * @param screenReader - Whether to check for screen reader visibility
 * @returns True if visible
 */
function isVisible(element: Element | VirtualNode, screenReader?: boolean): boolean;

/**
 * Check if element is visual content
 * @param element - Element to check
 * @returns True if visual content
 */
function isVisualContent(element: Element | VirtualNode): boolean;

/**
 * Reduce elements to those below floating elements
 * @param elements - Array of elements
 * @returns Filtered array of elements
 */
function reduceToElementsBelowFloating(elements: Element[]): Element[];

/**
 * Get shadow elements from point
 * @param x - X coordinate
 * @param y - Y coordinate
 * @returns Array of shadow elements
 */
function shadowElementsFromPoint(x: number, y: number): Element[];

/**
 * Get URL properties from attribute
 * @param element - Element with URL attribute
 * @param attr - Attribute name
 * @returns URL properties object
 */
function urlPropsFromAttribute(element: Element | VirtualNode, attr: string): any;

/**
 * Check if element visually contains another
 * @param container - Container element
 * @param contained - Contained element
 * @returns True if visually contains
 */
function visuallyContains(container: Element | VirtualNode, contained: Element | VirtualNode): boolean;

/**
 * Check if elements visually overlap
 * @param element1 - First element
 * @param element2 - Second element
 * @returns True if elements overlap
 */
function visuallyOverlaps(element1: Element | VirtualNode, element2: Element | VirtualNode): boolean;

/**
 * Sort elements visually
 * @param elements - Array of elements to sort
 * @returns Visually sorted array
 */
function visuallySort(elements: Element[]): Element[];

axe.setup();

const input = document.querySelector('input');
console.log('Is focusable:', axe.commons.dom.isFocusable(input));
console.log('Is visible:', axe.commons.dom.isVisible(input));

const tabbableElements = axe.commons.dom.getTabbableElements(document.body);
console.log('Tabbable elements:', tabbableElements.length);

const viewport = axe.commons.dom.getViewportSize();
console.log('Viewport:', viewport);

axe.teardown();

/**
 * Get accessible text for element
 * @param element - Element to analyze
 * @param options - Text options
 * @returns Accessible text string
 */
function accessibleText(element: Element | VirtualNode, options?: AccessibleTextOptions): string;

/**
 * Get sanitized accessible text
 * @param element - Element to analyze
 * @param options - Text options
 * @returns Sanitized text string
 */
function sanitize(text: string): string;

/**
 * Get visible text content
 * @param element - Element to analyze
 * @param options - Text options
 * @returns Visible text string
 */
function visibleTextNodes(element: Element | VirtualNode): Node[];

/**
 * Aggregate check results
 * @param results - Array of check results
 * @returns Aggregated result
 */
function aggregateChecks(results: CheckResult[]): CheckResult;

/**
 * Aggregate node results
 * @param nodeResults - Array of node results
 * @returns Aggregated node result
 */
function aggregateNodeResults(nodeResults: NodeResult[]): NodeResult;

/**
 * Clone object or array
 * @param obj - Object to clone
 * @returns Cloned object
 */
function clone<T>(obj: T): T;

/**
 * DqElement class for element representation
 * @param element - DOM element
 * @param options - Element options
 */
class DqElement {
  constructor(element: Element, options?: { absolutePaths?: boolean });
  element: Element;
  source: string;
  selector: string[];
  xpath: string[];
  ancestry: string[];
  nodeIndexes: number[];
  toJSON(): SerialDqElement;
}

/**
 * Escape CSS selector
 * @param value - Value to escape
 * @returns Escaped selector
 */
function escapeSelector(value: string): string;

/**
 * Get flattened tree of virtual nodes
 * @param node - Root node
 * @param options - Tree options
 * @returns Array of virtual nodes
 */
function getFlattenedTree(node: Element | Document, options?: any): VirtualNode[];

/**
 * Get frame contexts for element
 * @param context - Element context
 * @param options - Run options
 * @returns Array of frame contexts
 */
function getFrameContexts(context?: ElementContext, options?: RunOptions): FrameContext[];

/**
 * Get CSS selector for element
 * @param element - Element to analyze
 * @param options - Selector options
 * @returns CSS selector string
 */
function getSelector(element: Element | VirtualNode, options?: any): string;

/**
 * Get standards data
 * @returns Standards object
 */
function getStandards(): Required<Standards>;

/**
 * Get XPath for element
 * @param element - Element to analyze
 * @returns XPath string
 */
function getXpath(element: Element | VirtualNode): string;

/**
 * Check if value is context specification
 * @param context - Value to check
 * @returns True if context spec
 */
function isContextSpec(context: unknown): context is ContextSpec;

/**
 * Check if value is context object
 * @param context - Value to check
 * @returns True if context object
 */
function isContextObject(context: unknown): context is ContextObject;

/**
 * Check if value is context property
 * @param context - Value to check
 * @returns True if context property
 */
function isContextProp(context: unknown): context is ContextProp;

/**
 * Check if selector is labelled shadow DOM selector
 * @param selector - Selector to check
 * @returns True if labelled shadow DOM selector
 */
function isLabelledShadowDomSelector(selector: unknown): selector is LabelledShadowDomSelector;

/**
 * Check if selector is labelled frames selector
 * @param selector - Selector to check
 * @returns True if labelled frames selector
 */
function isLabelledFramesSelector(selector: unknown): selector is LabelledFramesSelector;

/**
 * Query shadow DOM with selector
 * @param selector - CSS selector or shadow selector
 * @returns First matching element or null
 */
function shadowSelect(selector: CrossTreeSelector): Element | null;

/**
 * Query shadow DOM with selector (all matches)
 * @param selector - CSS selector or shadow selector
 * @returns Array of matching elements
 */
function shadowSelectAll(selector: CrossTreeSelector): Element[];

/**
 * Generate UUID
 * @param options - UUID options
 * @param buf - Buffer for UUID
 * @param offset - Buffer offset
 * @returns UUID string or buffer
 */
function uuid(
  options?: { random?: Uint8Array | Array<number> },
  buf?: Uint8Array | Array<number>,
  offset?: number
): string | Uint8Array | Array<number>;

// Shadow DOM querying
const shadowElement = axe.utils.shadowSelect('#my-shadow-element');
const allShadowElements = axe.utils.shadowSelectAll('.shadow-class');

// Element analysis
const element = document.querySelector('button');
const selector = axe.utils.getSelector(element);
console.log('CSS selector:', selector);

const xpath = axe.utils.getXpath(element);
console.log('XPath:', xpath);

// Context checking
const context = { include: ['main'], exclude: ['.ads'] };
console.log('Is context spec:', axe.utils.isContextSpec(context));

// UUID generation
const id = axe.utils.uuid();
console.log('Generated UUID:', id);

// Get standards data
const standards = axe.utils.getStandards();
console.log('ARIA roles:', Object.keys(standards.ariaRoles));

interface AccessibleTextOptions {
  inControlContext?: boolean;
  inLabelledByContext?: boolean;
}

interface AccessibleNameOptions {
  startNode?: VirtualNode;
  inControlContext?: boolean;
  inLabelledByContext?: boolean;
}

interface VirtualNode {
  actualNode?: Node;
  shadowId?: string;
  children?: VirtualNode[];
  parent?: VirtualNode;
  attr(attr: string): string | null;
  hasAttr(attr: string): boolean;
  props: { [key: string]: unknown };
  boundingClientRect: DOMRect;
}

interface SerialDqElement {
  source: string;
  nodeIndexes: number[];
  selector: UnlabelledFrameSelector;
  xpath: string[];
  ancestry: UnlabelledFrameSelector;
}

interface FrameContext {
  frameSelector: CrossTreeSelector;
  frameContext: FrameContextObject;
}

interface FrameContextObject {
  include: UnlabelledFrameSelector[];
  exclude: UnlabelledFrameSelector[];
}

type CrossTreeSelector = BaseSelector | ShadowDomSelector;
type ShadowDomSelector = MultiArray<BaseSelector>;
type BaseSelector = string;
type MultiArray<T> = [T, T, ...T[]];
type UnlabelledFrameSelector = CrossTreeSelector[];