Skip to content

Privacy-first password manager with built-in email aliasing. Fully encrypted and self-hostable.

7.6 KB
Raw Blame
/**
 * Helpers for working with pages that render (part of) their content inside open shadow roots.
 */

import { devLog } from '@/utils/devLogger/DevLogger';

/**
 * Upper bound on the number of shadow roots a single deep query descends into, to limit scans to
 * sane max values. Component-heavy pages are known to run well into the hundreds, therefore we
 * set this to a high value.
 */
const MAX_SHADOW_ROOTS = 2000;

/**
 * Get the shadow root a node lives in, or null when it is in the normal DOM.
 * @param node - The node to resolve the root for.
 * @returns The containing ShadowRoot, or null when the node is not inside a shadow root.
 */
export function getContainingShadowRoot(node: Node | null): ShadowRoot | null {
  const root = node?.getRootNode() as ShadowRoot | undefined;
  return root?.host ? root : null;
}

/**
 * Get the root node (Document or ShadowRoot) a node belongs to.
 * @param node - The node to resolve the root for.
 * @returns The node's Document or ShadowRoot.
 */
export function getQueryRoot(node: Node): Document | ShadowRoot {
  return node.getRootNode() as Document | ShadowRoot;
}

/**
 * Like `Element.parentElement`, but hops from the top of a shadow root to its host element
 * instead of returning null.
 * @param element - The element to get the parent of.
 * @returns The parent element in the composed tree, or null at the top of the root node.
 */
export function getComposedParentElement(element: Element | null): Element | null {
  if (!element) {
    return null;
  }

  if (element.parentElement) {
    return element.parentElement;
  }

  return getContainingShadowRoot(element)?.host ?? null;
}

/**
 * Collect the shadow hosts an element sits inside, innermost first.
 * @param element - The element to resolve the hosts for.
 * @param maxDepth - Maximum number of hosts to walk up to.
 * @returns The shadow hosts wrapping the element, innermost first; empty when it is not in a shadow tree.
 */
export function getShadowHostChain(element: Element | null, maxDepth: number = 3): Element[] {
  const hosts: Element[] = [];
  let current: Element | null = element;

  while (current && hosts.length < maxDepth) {
    const host = getContainingShadowRoot(current)?.host ?? null;
    if (!host) {
      break;
    }

    hosts.push(host);
    current = host;
  }

  return hosts;
}

/**
 * Similar to `Element.closest()`, but continues the search at the shadow host when the element's own shadow root contains no match.
 * @param element - The element to start searching from.
 * @param selector - The CSS selector to match against.
 * @returns The nearest matching ancestor in the composed tree, or null when there is none.
 */
export function closestAcrossShadow(element: Element | null, selector: string): HTMLElement | null {
  let current: Element | null = element;

  while (current) {
    const match = current.closest(selector) as HTMLElement | null;
    if (match) {
      return match;
    }
    current = getContainingShadowRoot(current)?.host ?? null;
  }

  return null;
}

/**
 * Similar to `Node.contains()`, but treats a shadow host as containing its shadow root.
 * @param ancestor - The candidate ancestor element.
 * @param node - The node to test.
 * @returns True when node is ancestor itself or sits below it in the composed tree.
 */
export function composedContains(ancestor: Element | null, node: Node | null): boolean {
  if (!ancestor || !node) {
    return false;
  }

  let current: Node | null = node;
  while (current) {
    if (current === ancestor) {
      return true;
    }

    // At the top of a shadow tree parentNode is the ShadowRoot itself — continue at its host.
    const parent = current.parentNode as (Node & { host?: Element }) | null;
    current = parent ? (parent.host ?? parent) : null;
  }

  return false;
}

/**
 * Resolve the element a focus/pointer event really originated from, looking through shadow
 * boundaries. Events crossing an open shadow root are retargeted to the host, so `event.target`
 * alone would report the custom element instead of the input the user actually focused.
 * @param event - The event to resolve the target for.
 * @returns The deepest element in the event's composed path, falling back to `event.target`.
 */
export function getDeepEventTarget(event: Event): Element | null {
  const path = typeof event.composedPath === 'function' ? event.composedPath() : [];
  const deepest = path[0] as Element | undefined;

  // Node.ELEMENT_NODE — duck-typed so it also holds for nodes from another realm.
  if (deepest && deepest.nodeType === 1) {
    return deepest;
  }

  return event.target as Element | null;
}

/**
 * Resolve the focused element, descending through open shadow roots. `document.activeElement`
 * only reports the outermost host for content inside a shadow tree.
 * @param documentOrRoot - The document (or shadow root) to start from.
 * @returns The deepest focused element, or null when nothing is focused.
 */
export function getDeepActiveElement(documentOrRoot: Document | ShadowRoot): Element | null {
  let active = documentOrRoot.activeElement;

  while (active?.shadowRoot?.activeElement) {
    active = active.shadowRoot.activeElement;
  }

  return active;
}

/**
 * Collect every open shadow root reachable from the given root.
 * @param root - The root to scan.
 * @returns The reachable shadow roots, outermost first.
 */
export function collectShadowRoots(root: Document | ShadowRoot | Element): ShadowRoot[] {
  const shadowRoots: ShadowRoot[] = [];
  const seen = new Set<ShadowRoot>();
  const queue: (Document | ShadowRoot | Element)[] = [root];

  while (queue.length > 0 && shadowRoots.length < MAX_SHADOW_ROOTS) {
    const current = queue.shift()!;

    for (const element of Array.from(current.querySelectorAll<HTMLElement>('*'))) {
      const shadowRoot = element.shadowRoot;
      if (shadowRoot && !seen.has(shadowRoot)) {
        seen.add(shadowRoot);
        shadowRoots.push(shadowRoot);
        queue.push(shadowRoot);

        if (shadowRoots.length >= MAX_SHADOW_ROOTS) {
          devLog(`[ShadowDom] Shadow root scan truncated at ${MAX_SHADOW_ROOTS} roots; deeper components are not visible to detection.`);
          break;
        }
      }
    }
  }

  return shadowRoots;
}

/**
 * Similar to `querySelectorAll`, but also descends into open shadow roots.
 * @param root - The root to query from.
 * @param selector - The CSS selector to match.
 * @returns The matching elements from the normal DOM and every reachable shadow root.
 */
export function queryAllDeep<T extends Element>(root: Document | ShadowRoot | Element, selector: string): T[] {
  const results: T[] = Array.from(root.querySelectorAll<T>(selector));

  for (const shadowRoot of collectShadowRoots(root)) {
    results.push(...Array.from(shadowRoot.querySelectorAll<T>(selector)));
  }

  return results;
}

/**
 * Like `document.getElementById`, but also searches open shadow roots. IDs inside a shadow tree
 * are scoped to that tree, so the same id may legitimately exist more than once; the normal DOM
 * match wins, then shadow trees in document order.
 * @param documentOrRoot - The document to search.
 * @param elementId - The id to look for.
 * @returns The first matching element, or null when there is none.
 */
export function getDeepElementById(documentOrRoot: Document | ShadowRoot, elementId: string): HTMLElement | null {
  const lightMatch = documentOrRoot.getElementById(elementId) as HTMLElement | null;
  if (lightMatch) {
    return lightMatch;
  }

  for (const shadowRoot of collectShadowRoots(documentOrRoot)) {
    const match = shadowRoot.getElementById(elementId);
    if (match) {
      return match as HTMLElement;
    }
  }

  return null;
}