ivya/dist/aria/index.d.ts

Fork of Playwright's locator resolution

//#region src/aria/folk/isomorphic/ariaSnapshot.d.ts
/**
 * Copyright (c) Microsoft Corporation.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 * http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
type AriaRole = 'alert' | 'alertdialog' | 'application' | 'article' | 'banner' | 'blockquote' | 'button' | 'caption' | 'cell' | 'checkbox' | 'code' | 'columnheader' | 'combobox' | 'complementary' | 'contentinfo' | 'definition' | 'deletion' | 'dialog' | 'directory' | 'document' | 'emphasis' | 'feed' | 'figure' | 'form' | 'generic' | 'grid' | 'gridcell' | 'group' | 'heading' | 'img' | 'insertion' | 'link' | 'list' | 'listbox' | 'listitem' | 'log' | 'main' | 'mark' | 'marquee' | 'math' | 'meter' | 'menu' | 'menubar' | 'menuitem' | 'menuitemcheckbox' | 'menuitemradio' | 'navigation' | 'none' | 'note' | 'option' | 'paragraph' | 'presentation' | 'progressbar' | 'radio' | 'radiogroup' | 'region' | 'row' | 'rowgroup' | 'rowheader' | 'scrollbar' | 'search' | 'searchbox' | 'separator' | 'slider' | 'spinbutton' | 'status' | 'strong' | 'subscript' | 'superscript' | 'switch' | 'tab' | 'table' | 'tablist' | 'tabpanel' | 'term' | 'textbox' | 'time' | 'timer' | 'toolbar' | 'tooltip' | 'tree' | 'treegrid' | 'treeitem';
type AriaProps = {
  checked?: boolean | 'mixed';
  disabled?: boolean;
  expanded?: boolean;
  active?: boolean;
  level?: number;
  pressed?: boolean | 'mixed';
  selected?: boolean;
};
type AriaBox = {
  visible: boolean;
  inline: boolean;
  cursor?: string;
};
type AriaNode = AriaProps & {
  role: AriaRole | 'fragment' | 'iframe';
  name: string;
  ref?: string;
  children: (AriaNode | string)[];
  box: AriaBox;
  receivesPointerEvents: boolean;
  props: Record<string, string>;
};
type AriaRegex = {
  pattern: string;
};
type AriaTextValue = {
  raw: string;
  normalized: string;
};
type AriaTemplateTextNode = {
  kind: 'text';
  text: AriaTextValue;
};
type AriaTemplateRoleNode = AriaProps & {
  kind: 'role';
  role: AriaRole | 'fragment';
  name?: AriaRegex | string;
  children?: AriaTemplateNode[];
  props?: Record<string, AriaTextValue>;
  containerMode?: ContainerMode;
};
type ContainerMode = 'contain' | 'equal' | 'deep-equal';
type AriaTemplateNode = AriaTemplateRoleNode | AriaTemplateTextNode;
//#endregion
//#region src/aria/folk/injected/ariaSnapshot.d.ts
declare function generateAriaTree(rootElement: Element): AriaNode;
declare function renderAriaTree(root: AriaNode): string;
//#endregion
//#region src/aria/template.d.ts
declare function renderAriaTemplate(template: AriaTemplateNode): string;
//#endregion
//#region src/aria/match.d.ts
/**
 * The match algorithm resolves a DOM tree through the template's lens:
 *
 *   resolved — DOM tree rendered through the template's lens. Where the
 *              template uses regexes or omits names, the resolved output
 *              adopts those patterns. Where the template doesn't match,
 *              the resolved output uses literal DOM values.
 *
 * This is NOT a raw rendering of either input:
 *   actual   = renderAriaTree(root)       — DOM as-is
 *   expected = the original YAML string   — template as-is
 * Both are independent of the match algorithm and available to the
 * caller without matchAriaTree.
 *
 * Invariant:
 *   pass = true <=> resolved = expected
 *                   TODO:
 *                   This holds all cases except `aria-expanded` tri-state behaviors,
 *                   which we inherited from playwright. We leave this case for now.
 *
 * Diff display (pass: false):
 *   Use resolved vs expected. The user sees their original assertion
 *   on the right side. The left side (resolved) normalizes matched
 *   regions so the diff highlights only genuine mismatches, not
 *   pattern-vs-literal noise.
 *
 * Snapshot update (pass: false):
 *   Write resolved. It preserves user patterns (regexes, omitted names)
 *   from matched regions while incorporating actual DOM structure for
 *   mismatched/unpaired regions.
 *
 * Round-trip invariant:
 *   element → captureAriaTree → renderAriaTree → parseAriaTemplate
 *   → matchAriaTree(captured, parsed) → pass: true.
 *   A rendered snapshot must always match its own source tree.
 *   (Tested via runPipeline in aria.test.ts.)
 */
interface MatchAriaResult {
  /** Whether the actual tree satisfies the template. */
  pass: boolean;
  /** DOM tree resolved through the template's lens. Written on --update. */
  resolved: string;
}
declare function matchAriaTree(root: AriaNode, template: AriaTemplateNode): MatchAriaResult;
//#endregion
//#region src/aria/index.d.ts
declare function parseAriaTemplate(text: string): AriaTemplateNode;
//#endregion
export { type AriaNode, type AriaTemplateNode, generateAriaTree, matchAriaTree, parseAriaTemplate, renderAriaTemplate, renderAriaTree };