@guidelytech/guide-runtime 0.9.0 → 0.11.0

package/dist/index.js

@@ -5,21 +5,31 @@ import {
   sanitizeHtml,
   sanitizeToFragment,
   setSanitizedHtml
-} from "./chunk-KJRXCITD.js";
+} from "./chunk-H3CROHPR.js";
 import {
+  SHADOW_SEPARATOR,
   TargetTimeoutError,
+  closestComposed,
+  componentAnchor,
+  composedParent,
+  composedTarget,
+  containsComposed,
+  deepElementFromPoint,
   describeElement,
   generateSelectors,
   isGuidelyElement,
+  isStableClass,
   isStableId,
   isVisible,
   normalizeText,
   querySelectorStrategy,
   resolveTarget,
+  shadowHostChain,
   textSnapshotOf,
   urlMatches,
+  visualRect,
   waitForTarget
-} from "./chunk-VNJPNGZ4.js";
+} from "./chunk-VQJ7MZ2K.js";
 import {
   DEFAULT_THEME,
   HOST_ID,
@@ -30,11 +40,12 @@ import {
   ensureHost,
   prefersReducedMotion,
   resolveTheme
-} from "./chunk-PG7CMBHD.js";
+} from "./chunk-VJSQM23R.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 +98,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 +111,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 +129,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);
@@ -155,7 +170,7 @@ function buildCard(doc, opts, extraClass) {
   if (step.imageUrl) {
     const img = h(doc, "img", "g-image");
     img.src = step.imageUrl;
-    img.alt = "";
+    img.alt = step.imageAlt ?? "";
     card.appendChild(img);
   }
   const inner = h(doc, "div", "g-inner");
@@ -183,18 +198,29 @@ function buildCard(doc, opts, extraClass) {
   const buttons = buildButtons(doc, step, opts.canGoBack ?? opts.index > 0, opts.onButton);
   if (buttons.length || step.showProgress && opts.total > 1) {
     const footer = h(doc, "div", "g-footer");
-    if (step.showProgress && opts.total > 1) footer.appendChild(h(doc, "span", "g-progress", `${opts.index + 1} of ${opts.total}`));
+    if (step.showProgress && opts.total > 1) {
+      const progress = h(doc, "span", "g-progress", `${opts.index + 1} of ${opts.total}`);
+      progress.setAttribute("aria-label", `Step ${opts.index + 1} of ${opts.total}`);
+      footer.appendChild(progress);
+    }
     buttons.forEach((b) => footer.appendChild(b));
     inner.appendChild(footer);
   }
   card.appendChild(inner);
   if (step.title) card.setAttribute("aria-labelledby", titleId);
+  else card.setAttribute("aria-label", opts.total > 1 ? `Step ${opts.index + 1} of ${opts.total}` : "Guide");
   if (step.body) card.setAttribute("aria-describedby", bodyId);
   return { card, inner, titleId, bodyId };
 }
 function focusables(root) {
   return Array.from(root.querySelectorAll(FOCUSABLE));
 }
+function isTextEntry(el2) {
+  const t = el2;
+  if (!t || !t.tagName) return false;
+  const tag = t.tagName.toLowerCase();
+  return tag === "input" || tag === "textarea" || tag === "select" || t.isContentEditable === true;
+}
 function installKeyboard(card, step, trap, onClose) {
   const onKey = (e) => {
     if (e.key === "Escape" && step.showClose) {
@@ -202,6 +228,16 @@ function installKeyboard(card, step, trap, onClose) {
       onClose();
       return;
     }
+    if ((e.key === "ArrowRight" || e.key === "ArrowLeft") && !e.altKey && !e.ctrlKey && !e.metaKey && !isTextEntry(e.target)) {
+      const actions = e.key === "ArrowRight" ? ["next", "complete"] : ["back"];
+      const btn = actions.map((a) => card.querySelector(`button[data-action="${a}"]`)).find(Boolean);
+      if (btn) {
+        e.preventDefault();
+        e.stopPropagation();
+        btn.click();
+      }
+      return;
+    }
     if (trap && e.key === "Tab") {
       const items = focusables(card);
       if (!items.length) {
@@ -226,7 +262,8 @@ function installKeyboard(card, step, trap, onClose) {
 }
 function focusInto(card) {
   const doc = card.ownerDocument;
-  const previous = doc.activeElement;
+  const active = doc.activeElement;
+  const previous = active && active.id !== "guidely-root" ? active : null;
   const primary = card.querySelector(".g-btn-primary") || focusables(card)[0] || card;
   try {
     primary.focus({ preventScroll: true });
@@ -374,23 +411,32 @@ function renderHotspot(doc, opts) {
   let card = null;
   let stopAnchor = null;
   let stopKeys = null;
-  const close = () => {
+  const close = (returnFocus = false) => {
+    const hadFocus = !!card && card.getRootNode().activeElement !== null && card.contains(card.getRootNode().activeElement);
     stopAnchor?.();
     stopKeys?.();
     card?.remove();
     card = null;
     dot.setAttribute("aria-expanded", "false");
+    if (returnFocus || hadFocus) {
+      try {
+        dot.focus({ preventScroll: true });
+      } catch {
+      }
+    }
   };
   const open = () => {
     if (card) return;
     const built = buildCard(doc, { ...opts, onClose: () => opts.onClose() }, "g-hotspot-card");
     card = built.card;
     card.setAttribute("role", "dialog");
+    card.id = nextId("hotspot");
+    dot.setAttribute("aria-controls", card.id);
     const arrowEl = h(doc, "div", "g-arrow");
     card.appendChild(arrowEl);
     wrapper.appendChild(card);
     stopAnchor = anchor(target, card, { placement: opts.step.placement, offset: opts.step.offset, arrowEl });
-    stopKeys = installKeyboard(card, opts.step, false, close);
+    stopKeys = installKeyboard(card, opts.step, false, () => close(true));
     dot.setAttribute("aria-expanded", "true");
     opts.onOpen?.();
     if (cfg.openOn === "click") focusInto(card);
@@ -412,7 +458,8 @@ function renderBanner(doc, opts) {
   const cleanups = [];
   const pos = step.position === "top" || step.placement === "top" || step.position.startsWith("top") ? "top" : "bottom";
   const banner = h(doc, "div", `g-banner g-pos-${pos}`);
-  banner.setAttribute("role", "status");
+  banner.setAttribute("role", "region");
+  banner.setAttribute("aria-label", step.title || "Announcement");
   banner.setAttribute("data-step-id", step.id);
   const body = h(doc, "div", "g-body");
   if (step.title) body.appendChild(h(doc, "strong", "", `${step.title} `));
@@ -445,6 +492,27 @@ function renderSlideout(doc, opts) {
   cleanups.push(focusInto(card));
   return { el: wrapper, card, destroy: () => cleanupAll(cleanups, wrapper) };
 }
+function runCodeBlock(code, container, opts) {
+  const act = (action) => () => opts.onButton({ id: `code-${action}`, label: action, action, variant: "primary" });
+  const api = Object.freeze({ next: act("next"), back: act("back"), complete: act("complete"), skip: act("skip"), dismiss: () => opts.onClose(), stepId: opts.step.id });
+  try {
+    const fn = new Function("guidely", "container", `"use strict";
+${code}`);
+    const result = fn(api, container);
+    return typeof result === "function" ? () => {
+      try {
+        result();
+      } catch (err) {
+        opts.onError?.(err);
+      }
+    } : () => {
+    };
+  } catch (err) {
+    opts.onError?.(err);
+    return () => {
+    };
+  }
+}
 function renderCustom(doc, opts) {
   const cleanups = [];
   const wrapper = h(doc, "div", "g-step");
@@ -453,6 +521,9 @@ function renderCustom(doc, opts) {
   el2.tabIndex = -1;
   el2.setAttribute("data-step-id", opts.step.id);
   setSanitizedHtml(el2, opts.step.customHtml || opts.step.body || "");
+  el2.setAttribute("role", opts.step.showOverlay ? "dialog" : "group");
+  el2.setAttribute("aria-label", opts.step.title || "Guide");
+  if (opts.step.showOverlay) el2.setAttribute("aria-modal", "true");
   const onClick = (e) => {
     const t = e.target?.closest?.("[data-g-action]");
     const action = t?.getAttribute("data-g-action");
@@ -466,6 +537,7 @@ function renderCustom(doc, opts) {
   opts.scope.appendChild(wrapper);
   cleanups.push(installKeyboard(el2, opts.step, false, opts.onClose));
   cleanups.push(focusInto(el2));
+  if (opts.runCode && opts.step.code) cleanups.push(runCodeBlock(opts.step.code, el2, opts));
   return { el: wrapper, card: el2, destroy: () => cleanupAll(cleanups, wrapper) };
 }
 function renderStep(opts) {
@@ -563,6 +635,17 @@ function runGuide(guide, options = {}) {
     view = null;
     stepDone = false;
   };
+  let returnFocusTo = null;
+  const restoreFocus = () => {
+    const el2 = returnFocusTo;
+    returnFocusTo = null;
+    try {
+      const now = doc.activeElement;
+      const lost = !now || now === doc.body || now.id === "guidely-root";
+      if (el2 && lost && el2.isConnected && typeof el2.focus === "function") el2.focus({ preventScroll: true });
+    } catch {
+    }
+  };
   const end = (reason) => {
     if (ended) return;
     ended = true;
@@ -574,6 +657,7 @@ function runGuide(guide, options = {}) {
     else if (reason === "skipped") emit("guide_skipped", step, index);
     scope?.destroy();
     scope = null;
+    restoreFocus();
     try {
       options.onEnd?.(reason);
     } catch (err) {
@@ -662,9 +746,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 {
           }
         };
@@ -712,7 +796,9 @@ function runGuide(guide, options = {}) {
         asModal,
         onButton: handleButton,
         onClose: () => end("dismissed"),
-        announce
+        announce,
+        runCode: options.runCode,
+        onError
       });
     } catch (err) {
       onError(err);
@@ -824,6 +910,8 @@ function runGuide(guide, options = {}) {
     guide,
     start() {
       if (status !== "idle") return;
+      const focused = doc.activeElement;
+      if (focused && focused !== doc.body && focused.id !== "guidely-root") returnFocusTo = focused;
       emit("guide_viewed");
       if (total === 0) return end("completed");
       let startIndex = options.startAtStep ? steps.findIndex((s) => s.id === options.startAtStep) : 0;
@@ -1296,6 +1384,7 @@ function renderSurvey(options) {
 }
 
 // src/resource-center.ts
+import { orderedModules, unreadAnnouncements, visibleAnnouncements } from "@guidelytech/shared/runtime";
 function renderResourceCenter(options) {
   const { scope, config } = options;
   const doc = scope.ownerDocument;
@@ -1315,6 +1404,19 @@ function renderResourceCenter(options) {
   launcher.appendChild(el(doc, "span", "", config.launcher.label || config.title));
   launcher.setAttribute("aria-label", config.launcher.label || config.title);
   if (options.hideLauncher) launcher.hidden = true;
+  const badge = el(doc, "span", "g-launcher-badge");
+  badge.hidden = true;
+  launcher.appendChild(badge);
+  const modules = () => orderedModules(config.modules).filter((m) => m.enabled && (!("targeting" in m) || !m.targeting || !options.evaluate || options.evaluate(m.targeting))).map((m) => m.id);
+  const announcements = () => modules().includes("announcements") ? visibleAnnouncements(config.announcements, options.audienceIds?.() ?? []) : [];
+  const updateBadge = () => {
+    const unread = unreadAnnouncements(announcements(), options.announcementsSeenAt?.());
+    badge.hidden = unread === 0;
+    badge.textContent = unread > 9 ? "9+" : String(unread);
+    const label = config.launcher.label || config.title;
+    launcher.setAttribute("aria-label", unread ? `${label} (${unread} new update${unread === 1 ? "" : "s"})` : label);
+  };
+  updateBadge();
   const panel = el(doc, "div", `g-panel ${pos}`);
   panel.setAttribute("role", "dialog");
   panel.setAttribute("aria-label", config.title);
@@ -1325,9 +1427,20 @@ function renderResourceCenter(options) {
   close.type = "button";
   close.setAttribute("aria-label", "Close");
   head.appendChild(close);
+  let seenAtOpen = options.announcementsSeenAt?.() ?? null;
   const help = createHelpView({
     doc,
-    data: () => ({ collections: config.collections, articles: config.articles, recommended: byId(config.recommendedGuideIds), checklists: byId(config.checklistGuideIds), faqs: config.faqs, links: config.links }),
+    data: () => ({
+      collections: config.collections,
+      articles: config.articles,
+      recommended: byId(config.recommendedGuideIds),
+      checklists: byId(config.checklistGuideIds),
+      faqs: config.faqs,
+      links: config.links,
+      announcements: announcements(),
+      announcementsSeenAt: seenAtOpen,
+      modules: modules()
+    }),
     search: options.search,
     audienceIds: options.audienceIds,
     loadArticle: options.loadArticle,
@@ -1351,8 +1464,13 @@ function renderResourceCenter(options) {
     panel.hidden = !v;
     launcher.setAttribute("aria-expanded", String(v));
     if (v) {
+      seenAtOpen = options.announcementsSeenAt?.() ?? null;
       help.render();
       help.focusSearch();
+      if (announcements().length) {
+        options.onAnnouncementsSeen?.();
+        updateBadge();
+      }
       options.onOpen?.();
     } else {
       help.reset();
@@ -1429,7 +1547,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` });
@@ -1437,9 +1555,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;
@@ -1454,7 +1572,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();
@@ -1467,8 +1585,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();
   };
@@ -1539,17 +1656,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` });
@@ -1569,12 +1684,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,
@@ -1585,6 +1707,7 @@ export {
   isChecklistComplete,
   isGuidelyElement,
   isQuestionVisible,
+  isStableClass,
   isStableId,
   isVisible,
   normalizeText,
@@ -1608,10 +1731,12 @@ export {
   sanitizeHtml,
   sanitizeToFragment,
   setSanitizedHtml,
+  shadowHostChain,
   startAuthoring,
   textSnapshotOf,
   trackRect,
   urlMatches,
+  visualRect,
   waitForTarget
 };
 //# sourceMappingURL=index.js.map