/app/chrome-extension/shared/selector/dom-path.ts

/**
 * DOM Path - DOM 路径计算和定位
 *
 * DOM 路径是元素在 DOM 树中的索引路径，用于：
 * - 元素位置追踪
 * - 选择器失效后的快速恢复
 * - 元素比较和验证
 */

// =============================================================================
// Types
// =============================================================================

/**
 * DOM 路径：从根到目标元素的子元素索引数组
 *
 * @example
 * ```
 * [0, 2, 1] 表示:
 * root
 *  └─ children[0]
 *      └─ children[2]
 *          └─ children[1]  <- 目标元素
 * ```
 */
export type DomPath = number[];

// =============================================================================
// Core Functions
// =============================================================================

/**
 * 计算元素在 DOM 树中的路径
 *
 * 从目标元素向上遍历到根节点（Document 或 ShadowRoot），
 * 记录每一层在父元素 children 中的索引。
 *
 * @example
 * ```ts
 * const path = computeDomPath(button);
 * // => [0, 2, 1] - 从 body/shadowRoot 开始的路径
 * ```
 */
export function computeDomPath(element: Element): DomPath {
  const path: DomPath = [];
  let current: Element | null = element;

  while (current) {
    const parent: Element | null = current.parentElement;

    if (parent) {
      // 正常父元素
      const siblings = Array.from(parent.children);
      const index = siblings.indexOf(current);
      if (index >= 0) {
        path.unshift(index);
      }
      current = parent;
      continue;
    }

    // 检查是否是 ShadowRoot 或 Document 的直接子元素
    const parentNode = current.parentNode;
    if (parentNode instanceof ShadowRoot || parentNode instanceof Document) {
      const children = Array.from(parentNode.children);
      const index = children.indexOf(current);
      if (index >= 0) {
        path.unshift(index);
      }
    }

    // 到达根节点，停止遍历
    break;
  }

  return path;
}

/**
 * 根据 DOM 路径定位元素
 *
 * @param root - 查询根节点（Document 或 ShadowRoot）
 * @param path - DOM 路径
 * @returns 找到的元素，如果路径无效则返回 null
 *
 * @example
 * ```ts
 * const element = locateByDomPath(document, [0, 2, 1]);
 * // => 返回 body > children[0] > children[2] > children[1]
 * ```
 */
export function locateByDomPath(root: Document | ShadowRoot, path: DomPath): Element | null {
  if (path.length === 0) {
    return null;
  }

  let current: Element | null = root.children[path[0]] ?? null;

  for (let i = 1; i < path.length && current; i++) {
    const index = path[i];
    current = current.children[index] ?? null;
  }

  return current;
}

/**
 * 比较两个 DOM 路径
 *
 * @returns 包含是否相同和公共前缀长度的结果
 *
 * @example
 * ```ts
 * const result = compareDomPaths([0, 2, 1], [0, 2, 3]);
 * // => { same: false, commonPrefixLength: 2 }
 * ```
 */
export function compareDomPaths(
  a: DomPath,
  b: DomPath,
): { same: boolean; commonPrefixLength: number } {
  const minLen = Math.min(a.length, b.length);
  let commonPrefixLength = 0;

  for (let i = 0; i < minLen; i++) {
    if (a[i] === b[i]) {
      commonPrefixLength++;
    } else {
      break;
    }
  }

  const same = a.length === b.length && commonPrefixLength === a.length;

  return { same, commonPrefixLength };
}

/**
 * 检查路径 A 是否是路径 B 的祖先
 *
 * @example
 * ```ts
 * isAncestorPath([0, 2], [0, 2, 1]); // true
 * isAncestorPath([0, 2, 1], [0, 2]); // false
 * ```
 */
export function isAncestorPath(ancestor: DomPath, descendant: DomPath): boolean {
  if (ancestor.length >= descendant.length) {
    return false;
  }

  for (let i = 0; i < ancestor.length; i++) {
    if (ancestor[i] !== descendant[i]) {
      return false;
    }
  }

  return true;
}

/**
 * 获取从祖先路径到后代路径的相对路径
 *
 * @example
 * ```ts
 * getRelativePath([0, 2], [0, 2, 1, 3]); // [1, 3]
 * ```
 */
export function getRelativePath(ancestor: DomPath, descendant: DomPath): DomPath | null {
  if (!isAncestorPath(ancestor, descendant)) {
    return null;
  }

  return descendant.slice(ancestor.length);
}