@guidelytech/guide-runtime 0.8.0 → 0.10.0

package/dist/index.js

@@ -5,9 +5,16 @@ import {
   sanitizeHtml,
   sanitizeToFragment,
   setSanitizedHtml
-} from "./chunk-4FKYF6OB.js";
+} from "./chunk-KJRXCITD.js";
 import {
+  SHADOW_SEPARATOR,
   TargetTimeoutError,
+  closestComposed,
+  componentAnchor,
+  composedParent,
+  composedTarget,
+  containsComposed,
+  deepElementFromPoint,
   describeElement,
   generateSelectors,
   isGuidelyElement,
@@ -16,10 +23,12 @@ import {
   normalizeText,
   querySelectorStrategy,
   resolveTarget,
+  shadowHostChain,
   textSnapshotOf,
   urlMatches,
+  visualRect,
   waitForTarget
-} from "./chunk-GUSKGNNR.js";
+} from "./chunk-GUH2PQJ7.js";
 import {
   DEFAULT_THEME,
   HOST_ID,
@@ -30,11 +39,12 @@ import {
   ensureHost,
   prefersReducedMotion,
   resolveTheme
-} from "./chunk-7DOGZKWD.js";
+} from "./chunk-PG7CMBHD.js";
 
 // src/position.ts
 import { arrow, autoPlacement, autoUpdate, computePosition, flip, offset, shift } from "@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 = [offset(gap + (options.arrowEl ? 4 : 0))];
@@ -87,7 +97,7 @@ function trackRect(el2, cb) {
   let stopped = false;
   const run = () => {
     if (stopped) return;
-    cb(el2.getBoundingClientRect());
+    cb(visualRect(el2));
   };
   const schedule = () => {
     if (stopped) return;
@@ -100,6 +110,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 {
@@ -115,6 +128,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);
@@ -501,6 +515,17 @@ function isAnchoredStep(step) {
 import { evaluateRules } from "@guidelytech/shared/runtime";
 function noop() {
 }
+var escapeHtml = (s) => s.replace(/[&<>"']/g, (c) => `&#${c.charCodeAt(0)};`);
+function navigableUrl(pattern) {
+  if (!pattern || /[*?#\s]/.test(pattern) || pattern.includes("/:")) return null;
+  if (pattern.startsWith("/") && !pattern.startsWith("//")) return pattern;
+  try {
+    const u = new URL(pattern);
+    if (typeof location !== "undefined" && u.origin === location.origin) return u.pathname;
+  } catch {
+  }
+  return null;
+}
 function runGuide(guide, options = {}) {
   const doc = options.doc ?? (options.container?.ownerDocument || document);
   const steps = guide.config.steps;
@@ -645,15 +670,15 @@ function runGuide(guide, options = {}) {
       onError(err);
     }
   };
-  const setupAdvance = (step) => {
+  const setupAdvance = (step, target) => {
     const modes = step.advanceOn === "any" ? ["element_click", "element_visible", "event", "delay"] : [step.advanceOn];
     for (const mode of modes) {
-      if (mode === "element_click" && step.advanceValue) {
+      if (mode === "element_click" && (step.advanceValue || target)) {
         const selector = step.advanceValue;
         const handler = (e) => {
-          const t = e.target;
+          const t = composedTarget(e);
           try {
-            if (t && typeof t.closest === "function" && t.closest(selector)) advance();
+            if (selector ? t && closestComposed(t, selector) : t && target && containsComposed(target, t)) advance();
           } catch {
           }
         };
@@ -689,10 +714,11 @@ function runGuide(guide, options = {}) {
   const render = (step, target, asModal = false) => {
     if (ended) return;
     status = "running";
+    const shown = !target && step.advanceOn === "element_click" && !step.advanceValue && !step.buttons.length ? { ...step, buttons: [{ id: "g-next", label: index + 1 >= total ? "Done" : "Next", action: index + 1 >= total ? "complete" : "next", variant: "primary" }] } : step;
     try {
       view = renderStep({
         scope: getScope(),
-        step,
+        step: shown,
         index,
         total,
         canGoBack: history.length > 0 || index > 0,
@@ -714,7 +740,43 @@ function runGuide(guide, options = {}) {
     }
     emit("step_viewed", step, index, asModal ? { fallback: "show_as_modal" } : void 0);
     announce(step.title ? `${step.title}. Step ${index + 1} of ${total}` : `Step ${index + 1} of ${total}`);
-    setupAdvance(step);
+    setupAdvance(step, target);
+  };
+  const showUrlPrompt = (step) => {
+    if (ended || status !== "waiting_url" || view) return;
+    const href = navigableUrl(step.url);
+    const where = (step.url ?? "").replace(/^https?:\/\/[^/]+/i, "") || "another page";
+    const prompt = {
+      ...step,
+      type: "modal",
+      title: "Continue on another page",
+      body: `<p>The next step${step.title ? `, <strong>${escapeHtml(step.title)}</strong>,` : ""} is on <code>${escapeHtml(where)}</code>.</p>`,
+      imageUrl: "",
+      buttons: [
+        ...href ? [{ id: "g-go", label: "Take me there", action: "url", value: href, variant: "primary" }] : [],
+        { id: "g-exit", label: "Exit", action: "dismiss", variant: href ? "secondary" : "primary" }
+      ]
+    };
+    try {
+      view = renderStep({
+        scope: getScope(),
+        step: prompt,
+        index,
+        total,
+        canGoBack: false,
+        target: null,
+        asModal: true,
+        onButton: (b) => {
+          if (b.action !== "url" || !b.value) return end("dismissed");
+          if (options.onNavigate) options.onNavigate(b.value);
+          else location.assign(b.value);
+        },
+        onClose: () => end("dismissed"),
+        announce
+      });
+    } catch (err) {
+      onError(err);
+    }
   };
   const applyFallback = (step, direction) => {
     const fallback = step.target?.fallback ?? "skip";
@@ -740,9 +802,18 @@ function runGuide(guide, options = {}) {
       if (nextIndex < 0) return;
       return showStep(nextIndex, direction);
     }
+    try {
+      options.onPosition?.(step.id);
+    } catch (err) {
+      onError(err);
+    }
     if (step.url && !urlMatches(step.url, currentUrl())) {
       status = "waiting_url";
       pendingIndex = i;
+      if (options.promptForUrl) {
+        const t = setTimeout(() => showUrlPrompt(step), options.urlPromptDelayMs ?? 1200);
+        stepCleanups.push(() => clearTimeout(t));
+      }
       return;
     }
     pendingIndex = -1;
@@ -1276,7 +1347,14 @@ function renderResourceCenter(options) {
     loadArticle: options.loadArticle,
     onStartGuide: options.onStartGuide,
     onOpenChecklist: options.onOpenChecklist,
-    onArticleView: options.onArticleView
+    onArticleView: options.onArticleView,
+    guides: () => guides,
+    onShowMe: (key) => {
+      setOpen(false);
+      options.onStartGuide?.(key);
+    },
+    // Articles read in a larger panel.
+    onArticleChange: (reading) => panel.classList.toggle("g-panel-reading", reading)
   });
   panel.append(head, help.el);
   root.append(launcher, panel);
@@ -1365,7 +1443,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` });
@@ -1373,9 +1451,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;
@@ -1390,7 +1468,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();
@@ -1403,8 +1481,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();
   };
@@ -1462,7 +1539,7 @@ function previewStep(step, theme, options = {}) {
     name: "Preview",
     kind: "flow",
     version: 0,
-    config: { steps: [previewStepConfig], targeting: { id: "root", op: "and", rules: [] }, trigger: { type: "manual", delayMs: 0 }, frequency: { mode: "every_time", cooldownHours: 0, priority: 0, mutuallyExclusiveWith: [], reshowAfterDismiss: true }, appearance: options.appearance ?? { theme: "auto", animation: "fade" }, urlPatterns: [], platforms: ["web"] }
+    config: { steps: [previewStepConfig], visibility: "everyone", targeting: { id: "root", op: "and", rules: [] }, trigger: { type: "manual", delayMs: 0 }, frequency: { mode: "every_time", cooldownHours: 0, priority: 0, mutuallyExclusiveWith: [], reshowAfterDismiss: true }, appearance: options.appearance ?? { theme: "auto", animation: "fade" }, urlPatterns: [], platforms: ["web"] }
   };
   const controller = runGuide(guide, { theme, doc: options.doc, onEnd: () => options.onEnd?.(), onNavigate: () => {
   }, onAction: () => {
@@ -1475,17 +1552,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` });
@@ -1505,12 +1580,19 @@ function highlightSelectors(selectors, options = {}) {
 export {
   DEFAULT_THEME,
   HOST_ID,
+  SHADOW_SEPARATOR,
   STYLES,
   TargetTimeoutError,
   anchor,
   applyTheme,
   buildCard,
+  closestComposed,
+  componentAnchor,
+  composedParent,
+  composedTarget,
+  containsComposed,
   createScope,
+  deepElementFromPoint,
   describeElement,
   destroyHost,
   enhancePdfViewers,
@@ -1544,10 +1626,12 @@ export {
   sanitizeHtml,
   sanitizeToFragment,
   setSanitizedHtml,
+  shadowHostChain,
   startAuthoring,
   textSnapshotOf,
   trackRect,
   urlMatches,
+  visualRect,
   waitForTarget
 };
 //# sourceMappingURL=index.js.map