Merge pull request #1 from quatico-solutions/quatico-installable

Shadow DOM traversal + git-installable build

Author: eins78

package.json

@@ -52,6 +52,7 @@
     "compile": "tsup",
     "lint": "eslint src test --cache",
     "lint:fix": "yarn lint --fix",
+    "prepare": "yarn build",
     "prepublish": "yarn build",
     "test": "jest",
     "test:coverage": "yarn test --coverage",

src/createAccessibilityTree.ts

@@ -39,6 +39,66 @@ interface AccessibilityContext {
   visitedNodes: Set<Node>;
 }
 
+/**
+ * Returns the child nodes to traverse for building the flattened
+ * accessibility tree, handling shadow DOM and slot projection:
+ *
+ * 1. If the node has an open shadow root → return shadow root's children
+ * 2. If the node is a <slot> → return assigned nodes (or default content)
+ * 3. Otherwise → return the node's direct children
+ */
+function getAccessibleChildNodes(node: Node): Node[] {
+  // Shadow host: traverse into the shadow tree
+  if (isElement(node) && node.shadowRoot) {
+    return Array.from(node.shadowRoot.childNodes);
+  }
+
+  // Slot element: traverse assigned (projected) content, or default content
+  if (isElement(node) && node.localName === "slot") {
+    const slot = node as HTMLSlotElement;
+    const assigned = slot.assignedNodes({ flatten: true });
+
+    if (assigned.length > 0) {
+      return assigned;
+    }
+
+    // No assigned content — fall through to default slot content (childNodes)
+  }
+
+  return Array.from(node.childNodes);
+}
+
+/**
+ * Shadow-aware querySelectorAll: searches the node and all descendant
+ * shadow roots for elements matching the selector.
+ */
+function deepQuerySelectorAll(
+  node: Node,
+  selector: string
+): Element[] {
+  if (!isElement(node)) {
+    return [];
+  }
+
+  const results: Element[] = Array.from(node.querySelectorAll(selector));
+
+  // Also search inside shadow roots
+  const searchShadowRoots = (root: Element) => {
+    if (root.shadowRoot) {
+      results.push(
+        ...Array.from(root.shadowRoot.querySelectorAll(selector))
+      );
+      root.shadowRoot.querySelectorAll("*").forEach(searchShadowRoots);
+    }
+  };
+
+  // Search the node itself and all its descendants
+  searchShadowRoots(node);
+  node.querySelectorAll("*").forEach(searchShadowRoots);
+
+  return results;
+}
+
 function addAlternateReadingOrderNodes(
   node: Element,
   alternateReadingOrderMap: Map<Node, Set<Node>>,
@@ -72,11 +132,9 @@ function mapAlternateReadingOrder(node: Node) {
     return alternateReadingOrderMap;
   }
 
-  node
-    .querySelectorAll("[aria-flowto]")
-    .forEach((parentNode) =>
-      addAlternateReadingOrderNodes(parentNode, alternateReadingOrderMap, node)
-    );
+  deepQuerySelectorAll(node, "[aria-flowto]").forEach((parentNode) =>
+    addAlternateReadingOrderNodes(parentNode, alternateReadingOrderMap, node)
+  );
 
   return alternateReadingOrderMap;
 }
@@ -107,9 +165,9 @@ function getAllOwnedNodes(node: Node) {
     return ownedNodes;
   }
 
-  node
-    .querySelectorAll("[aria-owns]")
-    .forEach((owningNode) => addOwnedNodes(owningNode, ownedNodes, node));
+  deepQuerySelectorAll(node, "[aria-owns]").forEach((owningNode) =>
+    addOwnedNodes(owningNode, ownedNodes, node)
+  );
 
   return ownedNodes;
 }
@@ -160,7 +218,23 @@ function growTree(
     tree.parentDialog = parentDialog;
   }
 
-  node.childNodes.forEach((childNode) => {
+  /**
+   * Determine which child nodes to traverse based on the flattened tree:
+   *
+   * - If the node has an open shadow root, traverse the shadow tree instead
+   *   of the light DOM children (shadow DOM replaces light DOM in the
+   *   accessibility tree).
+   * - If a child is a <slot>, traverse its assigned nodes (the projected
+   *   light DOM content). If no nodes are assigned, fall back to the slot's
+   *   default content (its own childNodes).
+   * - Otherwise, traverse the node's direct childNodes (standard light DOM).
+   *
+   * REF: https://www.w3.org/TR/wai-aria-1.2/#accessibility_tree
+   * REF: https://developer.mozilla.org/en-US/docs/Web/API/HTMLSlotElement/assignedNodes
+   */
+  const childNodes = getAccessibleChildNodes(node);
+
+  childNodes.forEach((childNode) => {
     if (isHiddenFromAccessibilityTree(childNode)) {
       return;
     }

src/getNodeByIdRef.ts

@@ -1,5 +1,9 @@
 import { isElement } from "./isElement";
 
+/**
+ * Shadow-aware ID lookup: searches the container and all descendant
+ * shadow roots for an element with the given ID.
+ */
 export function getNodeByIdRef({
   container,
   idRef,
@@ -11,5 +15,48 @@ export function getNodeByIdRef({
     return null;
   }
 
-  return container.querySelector(`#${CSS.escape(idRef)}`);
+  const selector = `#${CSS.escape(idRef)}`;
+
+  // Try light DOM first
+  const result = container.querySelector(selector);
+
+  if (result) {
+    return result;
+  }
+
+  // Search inside shadow roots
+  return findInShadowRoots(container, selector);
+}
+
+function findInShadowRoots(
+  root: Element,
+  selector: string
+): Element | null {
+  if (root.shadowRoot) {
+    const found = root.shadowRoot.querySelector(selector);
+
+    if (found) {
+      return found;
+    }
+
+    for (const child of root.shadowRoot.querySelectorAll("*")) {
+      const result = findInShadowRoots(child, selector);
+
+      if (result) {
+        return result;
+      }
+    }
+  }
+
+  for (const child of root.querySelectorAll("*")) {
+    if (child.shadowRoot) {
+      const result = findInShadowRoots(child, selector);
+
+      if (result) {
+        return result;
+      }
+    }
+  }
+
+  return null;
 }

src/observeDOM.ts

@@ -1,6 +1,39 @@
 import { isElement } from "./isElement";
 import type { Root } from "./Virtual";
 
+const OBSERVE_OPTIONS: MutationObserverInit = {
+  attributes: true,
+  characterData: true,
+  childList: true,
+  subtree: true,
+};
+
+/**
+ * Recursively find all open shadow roots within a node tree.
+ */
+function collectShadowRoots(node: Node): ShadowRoot[] {
+  const roots: ShadowRoot[] = [];
+
+  if (isElement(node) && node.shadowRoot) {
+    roots.push(node.shadowRoot);
+    node.shadowRoot.querySelectorAll("*").forEach((child) => {
+      if (child.shadowRoot) {
+        roots.push(...collectShadowRoots(child));
+      }
+    });
+  }
+
+  if (isElement(node)) {
+    node.querySelectorAll("*").forEach((child) => {
+      if (child.shadowRoot) {
+        roots.push(...collectShadowRoots(child));
+      }
+    });
+  }
+
+  return roots;
+}
+
 export function observeDOM(
   root: Root | undefined,
   node: Node,
@@ -10,21 +43,28 @@ export function observeDOM(
     return () => {};
   }
 
-  const MutationObserver =
+  const MutationObserverCtor =
     typeof root !== "undefined" ? root?.MutationObserver : null;
 
-  if (MutationObserver) {
-    const mutationObserver = new MutationObserver(onChange);
+  if (MutationObserverCtor) {
+    const observers: MutationObserver[] = [];
 
-    mutationObserver.observe(node, {
-      attributes: true,
-      characterData: true,
-      childList: true,
-      subtree: true,
-    });
+    // Observe the main container
+    const mainObserver = new MutationObserverCtor(onChange);
+    mainObserver.observe(node, OBSERVE_OPTIONS);
+    observers.push(mainObserver);
+
+    // Observe all shadow roots within the container
+    const shadowRoots = collectShadowRoots(node);
+
+    for (const shadowRoot of shadowRoots) {
+      const shadowObserver = new MutationObserverCtor(onChange);
+      shadowObserver.observe(shadowRoot, OBSERVE_OPTIONS);
+      observers.push(shadowObserver);
+    }
 
     return () => {
-      mutationObserver.disconnect();
+      observers.forEach((observer) => observer.disconnect());
     };
   }