@guidelytech/guide-runtime 0.9.0 → 0.10.0

package/dist/index.cjs

@@ -24,12 +24,19 @@ var src_exports = {};
 __export(src_exports, {
   DEFAULT_THEME: () => DEFAULT_THEME,
   HOST_ID: () => HOST_ID2,
+  SHADOW_SEPARATOR: () => SHADOW_SEPARATOR,
   STYLES: () => STYLES,
   TargetTimeoutError: () => TargetTimeoutError,
   anchor: () => anchor,
   applyTheme: () => applyTheme,
   buildCard: () => buildCard,
+  closestComposed: () => closestComposed,
+  componentAnchor: () => componentAnchor,
+  composedParent: () => composedParent,
+  composedTarget: () => composedTarget,
+  containsComposed: () => containsComposed,
   createScope: () => createScope,
+  deepElementFromPoint: () => deepElementFromPoint,
   describeElement: () => describeElement,
   destroyHost: () => destroyHost,
   enhancePdfViewers: () => enhancePdfViewers,
@@ -63,10 +70,12 @@ __export(src_exports, {
   sanitizeHtml: () => sanitizeHtml,
   sanitizeToFragment: () => sanitizeToFragment,
   setSanitizedHtml: () => setSanitizedHtml,
+  shadowHostChain: () => shadowHostChain,
   startAuthoring: () => startAuthoring,
   textSnapshotOf: () => textSnapshotOf,
   trackRect: () => trackRect,
   urlMatches: () => urlMatches,
+  visualRect: () => visualRect,
   waitForTarget: () => waitForTarget
 });
 module.exports = __toCommonJS(src_exports);
@@ -129,6 +138,82 @@ function safeQueryAll(root, selector) {
     return [];
   }
 }
+var SHADOW_SEPARATOR = " >>> ";
+var SHADOW_SPLIT = /\s*>>>\s*/;
+function isShadowRoot(node) {
+  return !!node && node.nodeType === 11 && !!node.host;
+}
+function shadowRootOf(el2) {
+  const root = el2.getRootNode?.();
+  return isShadowRoot(root) ? root : null;
+}
+function composedParent(el2) {
+  return el2.parentElement ?? shadowRootOf(el2)?.host ?? null;
+}
+function containsComposed(ancestor, node) {
+  let cur = node ? node.nodeType === 1 ? node : node.parentElement : null;
+  for (; cur; cur = composedParent(cur)) if (cur === ancestor) return true;
+  return false;
+}
+function composedTarget(e) {
+  const path = typeof e.composedPath === "function" ? e.composedPath() : [];
+  const first = path[0] ?? e.target;
+  if (!first) return null;
+  return first.nodeType === 1 ? first : first.parentElement;
+}
+var shadowRootCache = null;
+function shadowRootsIn(root) {
+  const cached = shadowRootCache?.get(root);
+  if (cached) return cached;
+  const out = [];
+  const visit = (scope) => {
+    const own = scope.nodeType === 1 ? scope.shadowRoot : null;
+    const hosts = own ? [scope] : [];
+    for (const el2 of safeQueryAll(scope, "*")) if (el2.shadowRoot) hosts.push(el2);
+    for (const host of hosts) {
+      if (host.id === HOST_ID || !host.shadowRoot || out.includes(host.shadowRoot)) continue;
+      out.push(host.shadowRoot);
+      visit(host.shadowRoot);
+    }
+  };
+  visit(root);
+  shadowRootCache?.set(root, out);
+  return out;
+}
+function queryAllDeep(root, selector) {
+  const out = safeQueryAll(root, selector);
+  for (const sr of shadowRootsIn(root)) out.push(...safeQueryAll(sr, selector));
+  return out;
+}
+function queryCss(root, selector, deep) {
+  if (!selector.includes(">>>")) return deep ? queryAllDeep(root, selector) : safeQueryAll(root, selector);
+  const steps = selector.split(SHADOW_SPLIT).filter(Boolean);
+  let scopes = [root];
+  let matches = [];
+  steps.forEach((step, i) => {
+    matches = Array.from(new Set(scopes.flatMap((scope) => queryAllDeep(scope, step))));
+    if (i < steps.length - 1) scopes = matches.map((el2) => el2.shadowRoot).filter((sr) => !!sr);
+  });
+  return matches;
+}
+function closestComposed(el2, selector) {
+  if (selector.includes(">>>")) {
+    const hits = new Set(queryCss(docOf(el2), selector, true));
+    for (let cur = el2; cur; cur = composedParent(cur)) if (hits.has(cur)) return cur;
+    return null;
+  }
+  for (let cur = el2; cur; cur = composedParent(cur)) if (cur.matches(selector)) return cur;
+  return null;
+}
+function deepElementFromPoint(doc, x, y) {
+  let el2 = doc.elementFromPoint(x, y);
+  while (el2?.shadowRoot && el2.id !== HOST_ID && typeof el2.shadowRoot.elementFromPoint === "function") {
+    const inner = el2.shadowRoot.elementFromPoint(x, y);
+    if (!inner || inner === el2) break;
+    el2 = inner;
+  }
+  return el2;
+}
 function escapeCss(value) {
   const g = globalThis;
   if (g.CSS && typeof g.CSS.escape === "function") return g.CSS.escape(value);
@@ -150,32 +235,32 @@ function queryXPath(root, expr) {
     return [];
   }
 }
-function queryText(root, text) {
+function queryText(root, text, deep) {
   const needle = normalizeText(text).toLowerCase();
   if (!needle) return [];
-  const candidates = safeQueryAll(root, TEXT_CANDIDATES);
+  const candidates = queryCss(root, TEXT_CANDIDATES, deep);
   const exact = candidates.filter((c) => normalizeText(c.textContent).toLowerCase() === needle);
   if (exact.length) return exact;
   return candidates.filter((c) => normalizeText(c.textContent).toLowerCase().includes(needle));
 }
-function querySelectorStrategy(strategy, root) {
+function querySelectorStrategy(strategy, root, deep = true) {
   const value = strategy.value.trim();
   if (!value) return [];
   switch (strategy.kind) {
     case "id": {
       const id = value.startsWith("#") ? value.slice(1) : value;
-      return safeQueryAll(root, `#${escapeCss(id)}`);
+      return queryCss(root, `#${escapeCss(id)}`, deep);
     }
     case "guidely-id": {
       const id = value.startsWith("#") ? value.slice(1) : value;
-      return safeQueryAll(root, attrSelector("data-guidely-id", id));
+      return queryCss(root, attrSelector("data-guidely-id", id), deep);
     }
     case "data-attr":
     case "aria":
     case "css":
-      return safeQueryAll(root, value.startsWith("[") || /^[a-z*#.[]/i.test(value) ? value : `[${value}]`);
+      return queryCss(root, value.startsWith("[") || /^[a-z*#.[]/i.test(value) ? value : `[${value}]`, deep);
     case "text":
-      return queryText(root, value);
+      return queryText(root, value, deep);
     case "xpath":
       return queryXPath(root, value);
     default:
@@ -184,11 +269,19 @@ function querySelectorStrategy(strategy, root) {
 }
 function resolveTarget(target, root = document) {
   const selectors = Array.isArray(target) ? target : target.selectors;
-  for (const strategy of selectors) {
-    const matches = querySelectorStrategy(strategy, root).filter((el2) => !isGuidelyElement(el2) && isVisible(el2));
-    if (matches.length === 1) return matches[0];
+  const visibleMatches = (strategy, deep) => querySelectorStrategy(strategy, root, deep).filter((el2) => !isGuidelyElement(el2) && isVisible(el2));
+  const outer = shadowRootCache;
+  shadowRootCache ?? (shadowRootCache = /* @__PURE__ */ new Map());
+  try {
+    for (const strategy of selectors) {
+      let matches = visibleMatches(strategy, false);
+      if (!matches.length && strategy.kind !== "xpath") matches = visibleMatches(strategy, true);
+      if (matches.length === 1) return matches[0];
+    }
+    return null;
+  } finally {
+    shadowRootCache = outer;
   }
-  return null;
 }
 var TargetTimeoutError = class extends Error {
   constructor(message = "Target element not found before timeout") {
@@ -252,14 +345,15 @@ function isStableId(id) {
 function isStableClass(cls) {
   return !!cls && !GENERATED_CLASS.test(cls) && cls.length <= 40;
 }
-function uniqueIn(doc, selector, el2) {
-  const all = safeQueryAll(doc, selector);
+function uniqueWithin(root, selector, el2) {
+  const all = safeQueryAll(root, selector);
   return all.length === 1 && all[0] === el2;
 }
 function attrSelector(name, value) {
   return `[${name}='${value.replace(/\\/g, "\\\\").replace(/'/g, "\\'")}']`;
 }
-function cssPath(el2, doc) {
+function cssPath(el2, root) {
+  const doc = el2.ownerDocument;
   const segments = [];
   let cur = el2;
   while (cur && cur.nodeType === 1 && cur !== doc.body && cur !== doc.documentElement) {
@@ -279,20 +373,48 @@ function cssPath(el2, doc) {
     }
     segments.unshift(seg);
     const candidate = segments.join(" > ");
-    if (uniqueIn(doc, candidate, el2)) return candidate;
+    if (uniqueWithin(root, candidate, el2)) return candidate;
     cur = parent;
   }
   const full = segments.join(" > ");
-  return uniqueIn(doc, full, el2) ? full : null;
+  return uniqueWithin(root, full, el2) ? full : null;
+}
+function shadowHostChain(el2) {
+  const steps = [];
+  for (let root = shadowRootOf(el2); root; root = shadowRootOf(root.host)) {
+    const host = root.host;
+    const step = cssPath(host, shadowRootOf(host) ?? host.ownerDocument);
+    if (!step) return null;
+    steps.unshift(step);
+  }
+  return steps.join(SHADOW_SEPARATOR);
+}
+function selectorFor(el2, selector) {
+  const root = shadowRootOf(el2);
+  if (!root) return uniqueWithin(el2.ownerDocument, selector, el2) ? selector : null;
+  if (!uniqueWithin(root, selector, el2)) return null;
+  const doc = el2.ownerDocument;
+  const only = (sel) => {
+    const all = queryCss(doc, sel, true);
+    return all.length === 1 && all[0] === el2;
+  };
+  if (only(selector)) return selector;
+  const chain = shadowHostChain(el2);
+  const scoped = chain ? chain + SHADOW_SEPARATOR + selector : null;
+  return scoped && only(scoped) ? scoped : null;
+}
+function shadowText(el2) {
+  if (!el2.shadowRoot) return "";
+  const parts = Array.from(el2.shadowRoot.children).filter((c) => !/^(STYLE|SCRIPT|TEMPLATE)$/.test(c.tagName));
+  return normalizeText(parts.map((c) => c.innerText ?? c.textContent).join(" "));
 }
 function textSnapshotOf(el2) {
   const he = el2;
-  const own = normalizeText(he.innerText ?? el2.textContent);
+  const own = normalizeText(he.innerText ?? el2.textContent) || shadowText(el2);
   const alt = normalizeText(el2.getAttribute("aria-label") || el2.getAttribute("title") || el2.getAttribute("placeholder") || el2.getAttribute("alt") || el2.value);
   return (own || alt).slice(0, 200);
 }
 function generateSelectors(el2) {
-  const doc = el2.ownerDocument;
   const out = [];
   const seen = /* @__PURE__ */ new Set();
   const push = (s) => {
@@ -303,9 +425,15 @@ function generateSelectors(el2) {
     }
   };
   const tag = el2.tagName.toLowerCase();
+  const pushFor = (kind, selector, value, label) => {
+    const resolved = selectorFor(el2, selector);
+    if (resolved === selector) push({ kind, value, label });
+    else if (resolved) push({ kind: "css", value: resolved, label });
+    return !!resolved;
+  };
   const guidelyId = el2.getAttribute("data-guidely-id");
-  if (guidelyId && uniqueIn(doc, attrSelector("data-guidely-id", guidelyId), el2)) push({ kind: "guidely-id", value: guidelyId, label: `Guidely id ${guidelyId}` });
-  if (isStableId(el2.id) && uniqueIn(doc, `#${escapeCss(el2.id)}`, el2)) push({ kind: "id", value: `#${el2.id}`, label: `id ${el2.id}` });
+  if (guidelyId) pushFor("guidely-id", attrSelector("data-guidely-id", guidelyId), guidelyId, `Guidely id ${guidelyId}`);
+  if (isStableId(el2.id)) pushFor("id", `#${escapeCss(el2.id)}`, `#${el2.id}`, `id ${el2.id}`);
   const dataAttrs = Array.from(el2.attributes).filter((a) => a.name.startsWith("data-") && !IGNORED_DATA_ATTRS.test(a.name) && a.value && a.value.length <= 120 && !/\d{5,}/.test(a.value));
   dataAttrs.sort((a, b) => {
     const ia = PREFERRED_DATA_ATTRS.indexOf(a.name);
@@ -314,42 +442,75 @@ function generateSelectors(el2) {
   });
   for (const a of dataAttrs) {
     const sel = attrSelector(a.name, a.value);
-    if (uniqueIn(doc, sel, el2)) push({ kind: "data-attr", value: sel, label: `${a.name}=${a.value}` });
-    else if (uniqueIn(doc, tag + sel, el2)) push({ kind: "data-attr", value: tag + sel, label: `${a.name}=${a.value}` });
+    if (!pushFor("data-attr", sel, sel, `${a.name}=${a.value}`)) pushFor("data-attr", tag + sel, tag + sel, `${a.name}=${a.value}`);
   }
   const aria = el2.getAttribute("aria-label");
   if (aria && aria.length <= 120) {
     const sel = attrSelector("aria-label", aria);
-    if (uniqueIn(doc, sel, el2)) push({ kind: "aria", value: sel, label: aria });
-    else if (uniqueIn(doc, tag + sel, el2)) push({ kind: "aria", value: tag + sel, label: aria });
+    if (!pushFor("aria", sel, sel, aria)) pushFor("aria", tag + sel, tag + sel, aria);
   }
   const name = el2.getAttribute("name");
-  if (name && uniqueIn(doc, tag + attrSelector("name", name), el2)) push({ kind: "css", value: tag + attrSelector("name", name), label: `${tag} name=${name}` });
+  if (name) pushFor("css", tag + attrSelector("name", name), tag + attrSelector("name", name), `${tag} name=${name}`);
   const role = el2.getAttribute("role");
   if (role) {
     const title = el2.getAttribute("title") || el2.getAttribute("aria-labelledby");
     const sel = title ? `[role='${role}']${attrSelector(el2.getAttribute("title") ? "title" : "aria-labelledby", title)}` : `[role='${role}']`;
-    if (uniqueIn(doc, sel, el2)) push({ kind: "css", value: sel, label: `role ${role}` });
+    pushFor("css", sel, sel, `role ${role}`);
   }
   if (tag === "a") {
     const href = el2.getAttribute("href");
-    if (href && href.length <= 200 && uniqueIn(doc, `a${attrSelector("href", href)}`, el2)) push({ kind: "css", value: `a${attrSelector("href", href)}`, label: `link ${href}` });
+    if (href && href.length <= 200) pushFor("css", `a${attrSelector("href", href)}`, `a${attrSelector("href", href)}`, `link ${href}`);
   }
-  const path = cssPath(el2, doc);
-  if (path) push({ kind: "css", value: path, label: "css path" });
+  const path = cssPath(el2, shadowRootOf(el2) ?? el2.ownerDocument);
+  if (path) pushFor("css", path, path, "css path");
   if (/^(button|a|h[1-6]|label|summary)$/.test(tag) || role === "button" || role === "link" || role === "tab" || role === "menuitem") {
     const text = normalizeText(el2.innerText ?? el2.textContent);
     if (text && text.length <= 80) push({ kind: "text", value: text, label: `text "${text}"` });
   }
   return out.slice(0, 10);
 }
+function visualRect(el2) {
+  const own = el2.getBoundingClientRect();
+  if (!el2.shadowRoot) return own;
+  const boxes = [own, ...Array.from(el2.shadowRoot.children).map((c) => c.getBoundingClientRect())].filter((r) => r.width > 0 && r.height > 0);
+  if (boxes.length < 2) return boxes[0] ?? own;
+  const left = Math.min(...boxes.map((r) => r.left));
+  const top = Math.min(...boxes.map((r) => r.top));
+  const right = Math.max(...boxes.map((r) => r.right));
+  const bottom = Math.max(...boxes.map((r) => r.bottom));
+  return new DOMRect(left, top, right - left, bottom - top);
+}
+var ANCHOR_MAX_AREA_RATIO = 4;
+var CONTROL_SELECTOR = "button, a[href], input, select, textarea, [role='button'], [role='link'], [role='checkbox'], [role='radio'], [role='switch'], [role='tab'], [role='menuitem'], [role='combobox'], [role='option']";
+function componentAnchor(el2) {
+  if (!hasLayout(el2.ownerDocument)) return el2;
+  let cur = el2;
+  for (let root = shadowRootOf(cur); root; root = shadowRootOf(cur)) {
+    const host = root.host;
+    if (host.id === HOST_ID) break;
+    let control = null;
+    try {
+      control = cur.closest(CONTROL_SELECTOR);
+    } catch {
+    }
+    const r = visualRect(control ?? cur);
+    const area = r.width * r.height;
+    const h2 = visualRect(host);
+    const hostArea = h2.width * h2.height;
+    const inside = r.left >= h2.left - 1 && r.top >= h2.top - 1 && r.right <= h2.right + 1 && r.bottom <= h2.bottom + 1;
+    if (!area || !inside || hostArea > area * ANCHOR_MAX_AREA_RATIO) break;
+    cur = host;
+  }
+  return cur;
+}
 function describeElement(el2) {
-  const r = el2.getBoundingClientRect();
+  const target = componentAnchor(el2);
+  const r = visualRect(target);
   return {
-    selectors: generateSelectors(el2),
-    textSnapshot: textSnapshotOf(el2),
+    selectors: generateSelectors(target),
+    textSnapshot: textSnapshotOf(target) || textSnapshotOf(el2),
     rect: { x: r.x, y: r.y, width: r.width, height: r.height },
-    tag: el2.tagName.toLowerCase()
+    tag: target.tagName.toLowerCase()
   };
 }
 
@@ -904,7 +1065,8 @@ function openReader(doc, block, link, pages, start) {
 
 // src/position.ts
 var import_dom = require("@floating-ui/dom");
-function anchor(reference, floating, options = {}) {
+function anchor(target, floating, options = {}) {
+  const reference = target.shadowRoot ? { getBoundingClientRect: () => visualRect(target), contextElement: target } : target;
   const placement = options.placement ?? "auto";
   const gap = options.offset ?? 10;
   const middleware = [(0, import_dom.offset)(gap + (options.arrowEl ? 4 : 0))];
@@ -957,7 +1119,7 @@ function trackRect(el2, cb) {
   let stopped = false;
   const run = () => {
     if (stopped) return;
-    cb(el2.getBoundingClientRect());
+    cb(visualRect(el2));
   };
   const schedule = () => {
     if (stopped) return;
@@ -970,6 +1132,9 @@ function trackRect(el2, cb) {
   const win = el2.ownerDocument.defaultView;
   win?.addEventListener("scroll", schedule, true);
   win?.addEventListener("resize", schedule);
+  const shadowRoots = [];
+  for (let root = el2.getRootNode(); root.nodeType === 11 && root.host; root = root.host.getRootNode()) shadowRoots.push(root);
+  for (const root of shadowRoots) root.addEventListener("scroll", schedule, true);
   let ro = null;
   if (typeof ResizeObserver !== "undefined") {
     try {
@@ -985,6 +1150,7 @@ function trackRect(el2, cb) {
     stopped = true;
     win?.removeEventListener("scroll", schedule, true);
     win?.removeEventListener("resize", schedule);
+    for (const root of shadowRoots) root.removeEventListener("scroll", schedule, true);
     ro?.disconnect();
     clearInterval(interval);
     if (typeof cancelAnimationFrame === "function") cancelAnimationFrame(raf);
@@ -1532,9 +1698,9 @@ function runGuide(guide, options = {}) {
       if (mode === "element_click" && (step.advanceValue || target)) {
         const selector = step.advanceValue;
         const handler = (e) => {
-          const t = e.target;
+          const t = composedTarget(e);
           try {
-            if (selector ? t && typeof t.closest === "function" && t.closest(selector) : t && target?.contains(t)) advance();
+            if (selector ? t && closestComposed(t, selector) : t && target && containsComposed(target, t)) advance();
           } catch {
           }
         };
@@ -2565,7 +2731,7 @@ function startAuthoring(options) {
       outline.hidden = true;
       return;
     }
-    const r = el2.getBoundingClientRect();
+    const r = visualRect(el2);
     outline.hidden = false;
     outline.classList.toggle("g-picked", picked);
     Object.assign(outline.style, { left: `${r.left}px`, top: `${r.top}px`, width: `${r.width}px`, height: `${r.height}px` });
@@ -2573,9 +2739,9 @@ function startAuthoring(options) {
     label.style.top = r.top < 30 ? "100%" : "-24px";
   };
   const elementAt = (x, y) => {
-    const el2 = doc.elementFromPoint(x, y);
+    const el2 = deepElementFromPoint(doc, x, y);
     if (!el2 || isGuidelyElement(el2) || el2 === doc.documentElement || el2 === doc.body) return null;
-    return el2;
+    return componentAnchor(el2);
   };
   const onMove = (e) => {
     if (!picking || stopped) return;
@@ -2590,7 +2756,7 @@ function startAuthoring(options) {
   };
   const onClick = (e) => {
     if (!picking || stopped) return;
-    if (e.target && isGuidelyElement(e.target)) return;
+    if (isGuidelyElement(composedTarget(e))) return;
     const el2 = elementAt(e.clientX, e.clientY) ?? hovered;
     if (!el2) return;
     e.preventDefault();
@@ -2603,8 +2769,7 @@ function startAuthoring(options) {
   };
   const swallow = (e) => {
     if (!picking || stopped) return;
-    const t = e.target;
-    if (t && isGuidelyElement(t)) return;
+    if (isGuidelyElement(composedTarget(e))) return;
     e.preventDefault();
     e.stopPropagation();
   };
@@ -2675,17 +2840,15 @@ function highlightSelectors(selectors, options = {}) {
   const scope = createScope(null, { theme: "light", animation: "none" }, doc);
   const boxes = [];
   const counts = [];
-  let resolved = null;
+  const resolved = resolveTarget(selectors, doc);
   const matched = /* @__PURE__ */ new Set();
   selectors.forEach((s) => {
     const els = querySelectorStrategy(s, doc).filter((el2) => !isGuidelyElement(el2));
-    const visible = els.filter(isVisible);
     counts.push(els.length);
-    if (!resolved && visible.length === 1) resolved = visible[0];
     els.forEach((el2) => matched.add(el2));
   });
   matched.forEach((el2) => {
-    const r = el2.getBoundingClientRect();
+    const r = visualRect(el2);
     const box = doc.createElement("div");
     box.className = "g-highlight";
     Object.assign(box.style, { left: `${r.left}px`, top: `${r.top}px`, width: `${r.width}px`, height: `${r.height}px` });
@@ -2706,12 +2869,19 @@ function highlightSelectors(selectors, options = {}) {
 0 && (module.exports = {
   DEFAULT_THEME,
   HOST_ID,
+  SHADOW_SEPARATOR,
   STYLES,
   TargetTimeoutError,
   anchor,
   applyTheme,
   buildCard,
+  closestComposed,
+  componentAnchor,
+  composedParent,
+  composedTarget,
+  containsComposed,
   createScope,
+  deepElementFromPoint,
   describeElement,
   destroyHost,
   enhancePdfViewers,
@@ -2745,10 +2915,12 @@ function highlightSelectors(selectors, options = {}) {
   sanitizeHtml,
   sanitizeToFragment,
   setSanitizedHtml,
+  shadowHostChain,
   startAuthoring,
   textSnapshotOf,
   trackRect,
   urlMatches,
+  visualRect,
   waitForTarget
 });
 //# sourceMappingURL=index.cjs.map