@sqaitech/shared 0.5.0

package/src/extractor/dom-util.ts

@@ -0,0 +1,152 @@
+import { NodeType } from '../constants';
+import { generateHashId } from '../utils';
+
+export function isFormElement(node: globalThis.Node) {
+  return (
+    node instanceof HTMLElement &&
+    (node.tagName.toLowerCase() === 'input' ||
+      node.tagName.toLowerCase() === 'textarea' ||
+      node.tagName.toLowerCase() === 'select' ||
+      node.tagName.toLowerCase() === 'option')
+  );
+}
+
+export function isButtonElement(
+  node: globalThis.Node,
+): node is globalThis.HTMLButtonElement {
+  return node instanceof HTMLElement && node.tagName.toLowerCase() === 'button';
+}
+
+export function isAElement(
+  node: globalThis.Node,
+): node is globalThis.HTMLButtonElement {
+  return node instanceof HTMLElement && node.tagName.toLowerCase() === 'a';
+}
+
+export function isSvgElement(
+  node: globalThis.Node,
+): node is globalThis.SVGSVGElement {
+  return node instanceof SVGElement;
+}
+
+export function isImgElement(
+  node: globalThis.Node,
+): node is globalThis.HTMLImageElement {
+  // check if the node is an image element
+  if (!includeBaseElement(node) && node instanceof Element) {
+    const computedStyle = window.getComputedStyle(node);
+    const backgroundImage = computedStyle.getPropertyValue('background-image');
+    if (backgroundImage !== 'none') {
+      return true;
+    }
+  }
+
+  if (isIconfont(node)) {
+    return true;
+  }
+
+  return (
+    (node instanceof HTMLElement && node.tagName.toLowerCase() === 'img') ||
+    (node instanceof SVGElement && node.tagName.toLowerCase() === 'svg')
+  );
+}
+
+function isIconfont(node: globalThis.Node): boolean {
+  if (node instanceof Element) {
+    const computedStyle = window.getComputedStyle(node);
+    const fontFamilyValue = computedStyle.fontFamily || '';
+    return fontFamilyValue.toLowerCase().indexOf('iconfont') >= 0;
+  }
+
+  return false;
+}
+
+export function isNotContainerElement(node: globalThis.Node) {
+  return (
+    isTextElement(node) ||
+    isIconfont(node) ||
+    isImgElement(node) ||
+    isButtonElement(node) ||
+    isAElement(node) ||
+    isFormElement(node)
+  );
+}
+
+export function isTextElement(
+  node: globalThis.Node,
+): node is globalThis.HTMLTextAreaElement {
+  if (node instanceof Element) {
+    if (node?.childNodes?.length === 1 && node?.childNodes[0] instanceof Text) {
+      return true;
+    }
+  }
+
+  return node.nodeName?.toLowerCase?.() === '#text' && !isIconfont(node);
+}
+
+export function isContainerElement(
+  node: globalThis.Node,
+): node is globalThis.HTMLElement {
+  if (!(node instanceof HTMLElement)) return false;
+
+  // include other base elements
+  if (includeBaseElement(node)) {
+    return false;
+  }
+
+  const computedStyle = window.getComputedStyle(node);
+  const backgroundColor = computedStyle.getPropertyValue('background-color');
+  if (backgroundColor) {
+    return true;
+  }
+
+  return false;
+}
+
+function includeBaseElement(node: globalThis.Node) {
+  if (!(node instanceof HTMLElement)) return false;
+
+  // include text
+  if (node.innerText) {
+    return true;
+  }
+
+  const includeList = [
+    'svg',
+    'button',
+    'input',
+    'textarea',
+    'select',
+    'option',
+    'img',
+    'a',
+  ];
+
+  for (const tagName of includeList) {
+    const element = node.querySelectorAll(tagName);
+    if (element.length > 0) {
+      return true;
+    }
+  }
+
+  return false;
+}
+
+export function generateElementByPosition(position: { x: number; y: number }) {
+  const rect = {
+    left: Math.max(position.x - 4, 0),
+    top: Math.max(position.y - 4, 0),
+    width: 8,
+    height: 8,
+  };
+  const id = generateHashId(rect);
+  const element = {
+    id,
+    attributes: { nodeType: NodeType.POSITION },
+    rect,
+    content: '',
+    center: [position.x, position.y],
+  };
+
+  return element;
+}

package/src/extractor/index.ts

@@ -0,0 +1,50 @@
+import type { NodeType } from '../constants/index';
+
+export interface ElementInfo {
+  id: string;
+  indexId: number;
+  nodeHashId: string;
+  xpaths?: string[];
+  attributes: {
+    nodeType: NodeType;
+    [key: string]: string;
+  };
+  nodeType: NodeType;
+  content: string;
+  rect: { left: number; top: number; width: number; height: number };
+  center: [number, number];
+  isVisible: boolean;
+}
+
+export interface ElementNode {
+  node: ElementInfo | null;
+  children: ElementNode[];
+}
+
+export {
+  descriptionOfTree,
+  traverseTree,
+  treeToList,
+  truncateText,
+  trimAttributes,
+} from './tree';
+
+export { extractTextWithPosition as webExtractTextWithPosition } from './web-extractor';
+
+export { extractTreeNode as webExtractNodeTree } from './web-extractor';
+
+export { extractTreeNodeAsString as webExtractNodeTreeAsString } from './web-extractor';
+
+export { setNodeHashCacheListOnWindow, getNodeFromCacheList } from './util';
+
+export {
+  getXpathsById,
+  getXpathsByPoint,
+  getNodeInfoByXpath,
+  getElementInfoByXpath,
+  getElementXpath,
+} from './locator';
+
+export { generateElementByPosition } from './dom-util';
+
+export { isNotContainerElement } from './dom-util';

package/src/extractor/locator.ts

@@ -0,0 +1,179 @@
+import type { ElementInfo } from '.';
+import type { Point } from '../types';
+import { isSvgElement } from './dom-util';
+import { getNodeFromCacheList } from './util';
+import { getRect, isElementPartiallyInViewport } from './util';
+import { collectElementInfo } from './web-extractor';
+
+const getElementXpathIndex = (element: Element): number => {
+  let index = 1;
+  let prev = element.previousElementSibling;
+
+  while (prev) {
+    if (prev.nodeName.toLowerCase() === element.nodeName.toLowerCase()) {
+      index++;
+    }
+    prev = prev.previousElementSibling;
+  }
+
+  return index;
+};
+
+const normalizeXpathText = (text: string): string => {
+  if (typeof text !== 'string') {
+    return '';
+  }
+
+  return text.replace(/\s+/g, ' ').trim();
+};
+
+const buildCurrentElementXpath = (
+  element: Element,
+  isOrderSensitive: boolean,
+  isLeafElement: boolean,
+): string => {
+  // Build parent path - inline the buildParentXpath logic
+  const parentPath = element.parentNode
+    ? getElementXpath(element.parentNode, isOrderSensitive)
+    : '';
+  const prefix = parentPath ? `${parentPath}/` : '/';
+  const tagName = element.nodeName.toLowerCase();
+  const textContent = element.textContent?.trim();
+
+  // Order-sensitive mode: always use index
+  if (isOrderSensitive) {
+    const index = getElementXpathIndex(element);
+    return `${prefix}${tagName}[${index}]`;
+  }
+
+  // Order-insensitive mode:
+  // - Leaf elements: try text first, fallback to index if no text
+  // - Non-leaf elements: always use index
+  if (isLeafElement && textContent) {
+    return `${prefix}${tagName}[normalize-space()="${normalizeXpathText(textContent)}"]`;
+  }
+
+  // Fallback to index (for non-leaf elements or leaf elements without text)
+  const index = getElementXpathIndex(element);
+  return `${prefix}${tagName}[${index}]`;
+};
+
+export const getElementXpath = (
+  element: Node,
+  isOrderSensitive = false,
+  isLeafElement = false,
+): string => {
+  // process text node
+  if (element.nodeType === Node.TEXT_NODE) {
+    const parentNode = element.parentNode;
+    if (parentNode && parentNode.nodeType === Node.ELEMENT_NODE) {
+      // For text nodes, treat parent as leaf element to enable text matching
+      const parentXPath = getElementXpath(parentNode, isOrderSensitive, true);
+      const textContent = element.textContent?.trim();
+      if (textContent) {
+        return `${parentXPath}/text()[normalize-space()="${normalizeXpathText(textContent)}"]`;
+      }
+      return `${parentXPath}/text()`;
+    }
+    return '';
+  }
+
+  // process element node
+  if (element.nodeType !== Node.ELEMENT_NODE) return '';
+
+  // process element node - at this point, element should be an Element
+  const el = element as Element;
+
+  // special element handling
+  if (el === document.documentElement) return '/html';
+  if (el === document.body) return '/html/body';
+
+  // if the element is any SVG element, find the nearest non-SVG ancestor
+  if (isSvgElement(el)) {
+    let parent = el.parentNode;
+    while (parent && parent.nodeType === Node.ELEMENT_NODE) {
+      if (!isSvgElement(parent)) {
+        return getElementXpath(parent, isOrderSensitive, isLeafElement);
+      }
+      parent = parent.parentNode;
+    }
+    // fallback if no non-SVG parent found
+    return getElementXpath(el.parentNode!, isOrderSensitive, isLeafElement);
+  }
+
+  // decide which format to use
+  return buildCurrentElementXpath(el, isOrderSensitive, isLeafElement);
+};
+
+export function getXpathsById(id: string): string[] | null {
+  const node = getNodeFromCacheList(id);
+
+  if (!node) {
+    return null;
+  }
+
+  const fullXPath = getElementXpath(node, false, true);
+  return [fullXPath];
+}
+
+export function getXpathsByPoint(
+  point: Point,
+  isOrderSensitive: boolean,
+): string[] | null {
+  const element = document.elementFromPoint(point.left, point.top);
+
+  if (!element) {
+    return null;
+  }
+
+  const fullXPath = getElementXpath(element, isOrderSensitive, true);
+  return [fullXPath];
+}
+
+export function getNodeInfoByXpath(xpath: string): Node | null {
+  const xpathResult = document.evaluate(
+    xpath,
+    document,
+    null,
+    XPathResult.ORDERED_NODE_SNAPSHOT_TYPE,
+    null,
+  );
+
+  if (xpathResult.snapshotLength !== 1) {
+    return null;
+  }
+
+  const node = xpathResult.snapshotItem(0);
+
+  return node;
+}
+
+export function getElementInfoByXpath(xpath: string): ElementInfo | null {
+  const node = getNodeInfoByXpath(xpath);
+
+  if (!node) {
+    return null;
+  }
+
+  if (node instanceof HTMLElement) {
+    // only when the element is not completely in the viewport, call scrollIntoView
+    const rect = getRect(node, 1, window);
+    const isVisible = isElementPartiallyInViewport(rect, window, document, 1);
+
+    if (!isVisible) {
+      node.scrollIntoView({ behavior: 'instant', block: 'center' });
+    }
+  }
+
+  return collectElementInfo(
+    node,
+    window,
+    document,
+    1,
+    {
+      left: 0,
+      top: 0,
+    },
+    true,
+  );
+}

package/src/extractor/tree.ts

@@ -0,0 +1,179 @@
+import type { BaseElement, ElementTreeNode } from '../types';
+
+export function truncateText(
+  text: string | number | object | undefined,
+  maxLength = 150,
+) {
+  if (typeof text === 'undefined') {
+    return '';
+  }
+
+  if (typeof text === 'object') {
+    text = JSON.stringify(text);
+  }
+
+  if (typeof text === 'number') {
+    return text.toString();
+  }
+
+  if (typeof text === 'string' && text.length > maxLength) {
+    return `${text.slice(0, maxLength)}...`;
+  }
+
+  if (typeof text === 'string') {
+    return text.trim();
+  }
+
+  return '';
+}
+
+export function trimAttributes(
+  attributes: Record<string, any>,
+  truncateTextLength?: number,
+) {
+  const tailorAttributes = Object.keys(attributes).reduce(
+    (res, currentKey: string) => {
+      const attributeVal = (attributes as any)[currentKey];
+      if (
+        currentKey === 'style' ||
+        currentKey === 'htmlTagName' ||
+        currentKey === 'nodeType'
+      ) {
+        return res;
+      }
+
+      res[currentKey] = truncateText(attributeVal, truncateTextLength);
+      return res;
+    },
+    {} as BaseElement['attributes'],
+  );
+  return tailorAttributes;
+}
+
+const nodeSizeThreshold = 4;
+export function descriptionOfTree<
+  ElementType extends BaseElement = BaseElement,
+>(
+  tree: ElementTreeNode<ElementType>,
+  truncateTextLength?: number,
+  filterNonTextContent = false,
+  visibleOnly = true,
+) {
+  const attributesString = (kv: Record<string, any>) => {
+    return Object.entries(kv)
+      .map(
+        ([key, value]) => `${key}="${truncateText(value, truncateTextLength)}"`,
+      )
+      .join(' ');
+  };
+
+  function buildContentTree(
+    node: ElementTreeNode<ElementType>,
+    indent = 0,
+    visibleOnly = true,
+  ): string {
+    let before = '';
+    let contentWithIndent = '';
+    let after = '';
+    let emptyNode = true;
+    const indentStr = '  '.repeat(indent);
+
+    let children = '';
+    for (let i = 0; i < (node.children || []).length; i++) {
+      const childContent = buildContentTree(
+        node.children[i],
+        indent + 1,
+        visibleOnly,
+      );
+      if (childContent) {
+        children += `\n${childContent}`;
+      }
+    }
+
+    if (
+      node.node &&
+      node.node.rect.width > nodeSizeThreshold &&
+      node.node.rect.height > nodeSizeThreshold &&
+      (!filterNonTextContent || (filterNonTextContent && node.node.content)) &&
+      (!visibleOnly || (visibleOnly && node.node.isVisible))
+    ) {
+      emptyNode = false;
+      let nodeTypeString: string;
+      if (node.node.attributes?.htmlTagName) {
+        nodeTypeString = node.node.attributes.htmlTagName.replace(/[<>]/g, '');
+      } else {
+        nodeTypeString = node.node.attributes.nodeType
+          .replace(/\sNode$/, '')
+          .toLowerCase();
+      }
+      const markerId = node.node.indexId;
+      const markerIdString = markerId ? `markerId="${markerId}"` : '';
+      const rectAttribute = node.node.rect
+        ? {
+            left: node.node.rect.left,
+            top: node.node.rect.top,
+            width: node.node.rect.width,
+            height: node.node.rect.height,
+          }
+        : {};
+      before = `<${nodeTypeString} id="${node.node.id}" ${markerIdString} ${attributesString(trimAttributes(node.node.attributes || {}, truncateTextLength))} ${attributesString(rectAttribute)}>`;
+      const content = truncateText(node.node.content, truncateTextLength);
+      contentWithIndent = content ? `\n${indentStr}  ${content}` : '';
+      after = `</${nodeTypeString}>`;
+    } else if (!filterNonTextContent) {
+      if (!children.trim().startsWith('<>')) {
+        before = '<>';
+        contentWithIndent = '';
+        after = '</>';
+      }
+    }
+
+    if (emptyNode && !children.trim()) {
+      return '';
+    }
+
+    const result = `${indentStr}${before}${contentWithIndent}${children}\n${indentStr}${after}`;
+    if (result.trim()) {
+      return result;
+    }
+    return '';
+  }
+
+  const result = buildContentTree(tree, 0, visibleOnly);
+  return result.replace(/^\s*\n/gm, '');
+}
+
+export function treeToList<T extends BaseElement>(
+  tree: ElementTreeNode<T>,
+): T[] {
+  const result: T[] = [];
+  function dfs(node: ElementTreeNode<T>) {
+    if (node.node) {
+      result.push(node.node);
+    }
+    for (const child of node.children) {
+      dfs(child);
+    }
+  }
+  dfs(tree);
+  return result;
+}
+
+export function traverseTree<
+  T extends BaseElement,
+  ReturnNodeType extends BaseElement,
+>(
+  tree: ElementTreeNode<T>,
+  onNode: (node: T) => ReturnNodeType,
+): ElementTreeNode<ReturnNodeType> {
+  function dfs(node: ElementTreeNode<T>) {
+    if (node.node) {
+      node.node = onNode(node.node) as any;
+    }
+    for (const child of node.children) {
+      dfs(child);
+    }
+  }
+  dfs(tree);
+  return tree as any;
+}