help-layer 1.0.0

package/src/observer.js

@@ -0,0 +1,146 @@
+/**
+ * DOM observation and Shadow DOM-piercing traversal.
+ *
+ * A normal querySelectorAll does not cross shadow boundaries, so queryAllDeep walks open
+ * shadowRoots recursively. A closed shadowRoot is unreachable from JS, so it is unsupported
+ * (a known limitation).
+ *
+ * For SPA support, while ON a MutationObserver watches for additions/removals of data-help-id
+ * elements and mounts/unmounts markers dynamically.
+ */
+
+const ELEMENT_NODE = 1;
+
+/**
+ * Internal worker that traverses everything under root (including inside open shadowRoots) once,
+ * collecting both selector-matching elements and shadowRoots at the same time. It uses a single
+ * `querySelectorAll('*')` pass and does both the `matches` test and shadowRoot detection within it.
+ * The goal is to cut what used to be two separate full scans ("collect matches" and "find shadow
+ * hosts") down to one (lightening the hot path that reacts to host DOM changes while ON).
+ * @param {ParentNode} root
+ * @param {string} selector
+ * @param {(el: Element) => void} [onMatch]
+ * @param {(shadow: ShadowRoot) => void} [onShadowRoot]
+ */
+function walkDeep(root, selector, onMatch, onShadowRoot) {
+  if (typeof root.querySelectorAll !== 'function') {
+    return;
+  }
+  // querySelectorAll('*') does not cross shadow boundaries, so run it flatly once per root and,
+  // when a shadowRoot is found, recurse into it right there (depth-first).
+  root.querySelectorAll('*').forEach((el) => {
+    if (onMatch && el.matches(selector)) {
+      onMatch(el);
+    }
+    if (el.shadowRoot) {
+      if (onShadowRoot) {
+        onShadowRoot(el.shadowRoot);
+      }
+      walkDeep(el.shadowRoot, selector, onMatch, onShadowRoot);
+    }
+  });
+}
+
+/**
+ * Collect every element under root (including inside open shadowRoots) matching selector.
+ * @param {ParentNode} root
+ * @param {string} selector
+ * @returns {Element[]}
+ */
+export function queryAllDeep(root, selector) {
+  const results = [];
+  walkDeep(root, selector, (el) => results.push(el));
+  return results;
+}
+
+/**
+ * Collect every open shadowRoot under root (excluding root itself).
+ * @param {ParentNode} root
+ * @returns {ShadowRoot[]}
+ */
+export function collectShadowRoots(root) {
+  const roots = [];
+  walkDeep(root, '*', null, (shadow) => roots.push(shadow));
+  return roots;
+}
+
+/**
+ * Traverse a node and its descendants (including shadow) once, returning both selector-matching
+ * elements and the descendants' open shadowRoots together. Used in MutationObserver added-node
+ * handling to fold "collect matches" and "add shadow observation" into one traversal per subtree.
+ * @param {Node} node
+ * @param {string} selector
+ * @returns {{ matches: Element[], shadowRoots: ShadowRoot[] }}
+ */
+function scanSubtree(node, selector) {
+  /** @type {Element[]} */
+  const matches = [];
+  /** @type {ShadowRoot[]} */
+  const shadowRoots = [];
+  if (node.nodeType !== ELEMENT_NODE) {
+    return { matches, shadowRoots };
+  }
+  // node itself is not included in querySelectorAll('*'), so test it separately (equivalent to the former matchingWithin).
+  const el = /** @type {Element} */ (node);
+  if (typeof el.matches === 'function' && el.matches(selector)) {
+    matches.push(el);
+  }
+  // The added node itself may be a shadow host. walkDeep only inspects the shadowRoots of
+  // descendants (querySelectorAll('*') never includes the root), so handle the node's own
+  // shadowRoot here before descending into the light-DOM subtree.
+  if (el.shadowRoot) {
+    shadowRoots.push(el.shadowRoot);
+    walkDeep(el.shadowRoot, selector, (m) => matches.push(m), (shadow) => shadowRoots.push(shadow));
+  }
+  walkDeep(el, selector, (m) => matches.push(m), (shadow) => shadowRoots.push(shadow));
+  return { matches, shadowRoots };
+}
+
+/**
+ * While ON, watch root and all shadowRoots under it, notifying on entry/exit of selector-matching elements.
+ * If an added element has a new shadowRoot, that shadowRoot is also added to the observation.
+ *
+ * @param {object} params
+ * @param {ParentNode} [params.root=document]
+ * @param {string} params.selector
+ * @param {(el: Element) => void} params.onAdded
+ * @param {(el: Element) => void} params.onRemoved
+ * @returns {{ disconnect(): void }}
+ */
+export function createMutationWatcher({ root = document, selector, onAdded, onRemoved }) {
+  const observed = new Set();
+
+  const handle = (records) => {
+    for (const record of records) {
+      // For added nodes, get both "matching elements" and "shadowRoots to start observing" in one traversal per subtree.
+      record.addedNodes.forEach((node) => {
+        const { matches, shadowRoots } = scanSubtree(node, selector);
+        matches.forEach((el) => onAdded(el));
+        shadowRoots.forEach(observe);
+      });
+      record.removedNodes.forEach((node) => {
+        scanSubtree(node, selector).matches.forEach((el) => onRemoved(el));
+      });
+    }
+  };
+
+  const observer = new MutationObserver(handle);
+
+  function observe(target) {
+    if (observed.has(target)) {
+      return;
+    }
+    observed.add(target);
+    observer.observe(target, { childList: true, subtree: true });
+  }
+
+  observe(root);
+  collectShadowRoots(root).forEach(observe);
+
+  return {
+    disconnect() {
+      observer.disconnect();
+      observed.clear();
+    },
+  };
+}

package/src/overlap.js

@@ -0,0 +1,71 @@
+/**
+ * Overlap avoidance between markers (pure function).
+ *
+ * Takes an array of each marker's "base position" (the center coordinate Floating UI
+ * decided on) and returns an array of extra offsets that push overlapping ones apart.
+ * Touches no DOM.
+ *
+ * The algorithm is a simple iterative push-out (a lightweight force-based separation):
+ * if two circles are closer than the minimum distance, push them apart in opposite
+ * directions. Repeat a few times. Markers are small circles, so a circle-to-circle
+ * distance test is enough.
+ */
+
+/**
+ * @param {Array<{x:number,y:number}>} centers base coordinate of each marker center
+ * @param {object} [options]
+ * @param {number} [options.minDistance] center-to-center distance closer than this counts as overlap
+ * @param {number} [options.iterations] number of iterations
+ * @returns {Array<{dx:number,dy:number}>} offset to add to each marker
+ */
+export function resolveOverlaps(centers, options = {}) {
+  const minDistance = options.minDistance ?? 26;
+  const iterations = options.iterations ?? 6;
+
+  // Working positions (base + accumulated offset).
+  const positions = centers.map((c) => ({ x: c.x, y: c.y }));
+
+  for (let iter = 0; iter < iterations; iter++) {
+    let moved = false;
+
+    for (let i = 0; i < positions.length; i++) {
+      for (let j = i + 1; j < positions.length; j++) {
+        const a = positions[i];
+        const b = positions[j];
+        let dx = b.x - a.x;
+        let dy = b.y - a.y;
+        let dist = Math.hypot(dx, dy);
+
+        if (dist >= minDistance) {
+          continue;
+        }
+
+        // If the coordinates are exactly identical, separate in a deterministic direction (horizontal).
+        if (dist === 0) {
+          dx = 1;
+          dy = 0;
+          dist = 1;
+        }
+
+        const overlap = (minDistance - dist) / 2;
+        const ux = dx / dist;
+        const uy = dy / dist;
+
+        a.x -= ux * overlap;
+        a.y -= uy * overlap;
+        b.x += ux * overlap;
+        b.y += uy * overlap;
+        moved = true;
+      }
+    }
+
+    if (!moved) {
+      break;
+    }
+  }
+
+  return positions.map((p, i) => ({
+    dx: p.x - centers[i].x,
+    dy: p.y - centers[i].y,
+  }));
+}

package/src/popup.js

@@ -0,0 +1,120 @@
+/**
+ * The single popup shared across the whole library.
+ * Placed on its target (the clicked marker) with Floating UI; at screen edges, flip/shift avoid
+ * clipping. While visible it follows via autoUpdate.
+ *
+ * Accessibility:
+ * - On open, move focus to the popup (role=dialog).
+ * - On close, return focus to the trigger element (the marker).
+ */
+import { createPopup } from './dom-builder.js';
+import { anchorPopup } from './floating.js';
+
+/**
+ * @param {object} state teardown registry
+ * @param {object} [options]
+ * @param {() => void} [options.onClose] called when the popup closes (transitions from shown to hidden)
+ * @param {(record: import('./matcher.js').HelpRecord) => (Node|null|undefined)} [options.render]
+ *   Escape hatch to render the body area with your own DOM node. Return a Node to display it;
+ *   if nothing is returned, fall back to safe text rendering (textContent). The title is always record.title.
+ *   Note: the return value is appendChild'd as-is without sanitization, so untrusted data must be neutralized by the caller.
+ * @param {import('@floating-ui/dom').Placement} [options.popupPlacement] initial placement (default 'bottom-start')
+ */
+export function createPopupController(state, { onClose, render, popupPlacement = 'bottom-start' } = {}) {
+  const { root, titleEl, textEl, closeEl } = createPopup();
+  document.body.appendChild(root);
+
+  // The close (×) button. root is removed on teardown, so explicitly detaching the listener isn't needed.
+  closeEl.addEventListener('click', () => close());
+
+  let openId = null;
+  let triggerEl = null;
+  let anchor = null;
+
+  function stopAnchor() {
+    if (anchor) {
+      anchor.cleanup();
+      anchor = null;
+    }
+  }
+
+  /**
+   * @param {import('./matcher.js').HelpRecord} record
+   * @param {HTMLElement} referenceEl placement reference (the clicked marker element)
+   */
+  function open(record, referenceEl) {
+    titleEl.textContent = record.title;
+    // If render exists, replace the body with a custom Node; otherwise fall back to safe text rendering.
+    const custom = render ? render(record) : null;
+    textEl.textContent = '';
+    if (custom) {
+      textEl.appendChild(custom);
+    } else {
+      textEl.textContent = record.text;
+    }
+    root.style.display = 'block';
+    openId = record.id;
+    triggerEl = referenceEl;
+
+    stopAnchor();
+    anchor = anchorPopup(referenceEl, root, popupPlacement);
+
+    // preventScroll: the popup is positioned asynchronously (computePosition().then), so at this
+    // point it's still at its stale position; a default focus would scroll toward that, causing a
+    // visible jump. flip/shift keep it in the viewport, so suppressing the scroll is safe.
+    root.focus({ preventScroll: true });
+  }
+
+  // Reposition immediately, only when open.
+  // (Called e.g. right after a marker shifts due to the overlap-avoidance transform.)
+  function reposition() {
+    if (anchor) {
+      anchor.update();
+    }
+  }
+
+  function hide() {
+    // Call onClose only if it was open (catches both the close-path and teardown-path close routes at one point).
+    const wasOpen = openId !== null;
+    stopAnchor();
+    openId = null;
+    triggerEl = null;
+    root.style.display = 'none';
+    if (wasOpen && onClose) {
+      onClose();
+    }
+  }
+
+  /**
+   * Close and return focus.
+   * @param {HTMLElement} [focusTarget] explicit focus-return target.
+   *   If omitted, returns to the trigger element (the marker). In contexts where the trigger
+   *   disappears (SPA removal), pass another surviving element such as the toggle.
+   */
+  function close(focusTarget) {
+    const returnTo = focusTarget ?? triggerEl;
+    hide();
+    // Return focus if the target is still in the DOM.
+    if (returnTo && returnTo.isConnected && typeof returnTo.focus === 'function') {
+      returnTo.focus({ preventScroll: true });
+    }
+  }
+
+  state.track(() => {
+    hide();
+    root.remove();
+  });
+
+  return {
+    root,
+    isOpen(id) {
+      return openId === id;
+    },
+    getOpenId() {
+      return openId;
+    },
+    open,
+    close,
+    reposition,
+  };
+}

package/src/state.js

@@ -0,0 +1,21 @@
+/**
+ * Registry of teardown callbacks.
+ * DOM, listeners, and style changes added while the mode is ON are unwound in
+ * reverse order of creation (LIFO), so that dependent cleanups (e.g. detach an
+ * internal listener, then remove its element) run in a natural order.
+ */
+export function createState() {
+  const cleanupFns = [];
+
+  return {
+    track(fn) {
+      cleanupFns.push(fn);
+    },
+    teardownAll() {
+      while (cleanupFns.length > 0) {
+        const cleanup = cleanupFns.pop();
+        cleanup();
+      }
+    },
+  };
+}

package/src/style.js

@@ -0,0 +1,183 @@
+/**
+ * The z-index constants help-layer uses, and the CSS it injects.
+ * Things that must sit above the blocking layer use Z_TOP (markers); the popup uses Z_POPUP so it
+ * always paints in front of the markers (they share a stacking context as <body> children, so a tie
+ * would otherwise be decided by DOM order and a remounted marker could cover an open popup).
+ * The toggle is made visible through the clip-path "hole", so its z-index is left untouched.
+ */
+export const Z_BLOCKING_LAYER = 2147483000;
+export const Z_TOP = 2147483001;
+export const Z_POPUP = 2147483002;
+
+const STYLE_ATTR = 'data-help-layer-style';
+
+// The theme is fully exposed via CSS custom properties. Users can change the look just by
+// overriding the following variables in host-side CSS (e.g. :root or any scope):
+//   --help-layer-marker-size       marker diameter (default 22px)
+//   --help-layer-marker-bg         marker background color (default #2563eb)
+//   --help-layer-marker-color      marker text color (default #fff)
+//   --help-layer-popup-bg          popup background color (default #fff)
+//   --help-layer-popup-color       popup text color (default #1f2933)
+//   --help-layer-popup-max-width   popup max width (default 280px)
+//   --help-layer-popup-max-height  body max height (default 50vh, scrolls when exceeded)
+//   --help-layer-accent            focus ring color (default #1d4ed8)
+//   --help-layer-overlay-bg        blocking-layer (scrim) background (default transparent; e.g. rgba(0,0,0,0.15))
+//   --help-layer-overlay-cursor    cursor over the blocked area (default default; e.g. not-allowed / help)
+const CSS = `
+.help-layer-blocking-layer {
+  position: fixed;
+  inset: 0;
+  /* Default transparent (unchanged). Set --help-layer-overlay-bg to tint it into a scrim that signals
+     "the host app is inactive". The clip-path hole isn't painted, so the toggle stays untinted. */
+  background: var(--help-layer-overlay-bg, transparent);
+  /* Cursor over the blocked area only (the toggle shows through the hole and keeps its own cursor).
+     e.g. not-allowed / help makes "this won't respond" obvious without needing a tint. */
+  cursor: var(--help-layer-overlay-cursor, default);
+  z-index: ${Z_BLOCKING_LAYER};
+}
+
+.help-layer-marker {
+  /* reset of the button element */
+  appearance: none;
+  -webkit-appearance: none;
+  margin: 0;
+  padding: 0;
+  border: none;
+  position: absolute;
+  top: 0;
+  left: 0;
+  width: var(--help-layer-marker-size, 22px);
+  height: var(--help-layer-marker-size, 22px);
+  border-radius: 50%;
+  background: var(--help-layer-marker-bg, #2563eb);
+  color: var(--help-layer-marker-color, #fff);
+  font-family: sans-serif;
+  font-size: 13px;
+  font-weight: bold;
+  line-height: var(--help-layer-marker-size, 22px);
+  text-align: center;
+  cursor: pointer;
+  user-select: none;
+  box-shadow: 0 1px 4px rgba(0, 0, 0, 0.35);
+  z-index: ${Z_TOP};
+}
+
+.help-layer-marker:focus-visible {
+  outline: 3px solid var(--help-layer-accent, #1d4ed8);
+  outline-offset: 2px;
+}
+
+.help-layer-popup {
+  position: absolute;
+  top: 0;
+  left: 0;
+  display: none;
+  max-width: var(--help-layer-popup-max-width, 280px);
+  background: var(--help-layer-popup-bg, #fff);
+  color: var(--help-layer-popup-color, #1f2933);
+  border-radius: 6px;
+  padding: 12px 14px;
+  box-shadow: 0 4px 16px rgba(0, 0, 0, 0.25);
+  font-family: sans-serif;
+  font-size: 13px;
+  line-height: 1.5;
+  z-index: ${Z_POPUP};
+}
+
+.help-layer-popup:focus {
+  outline: none;
+}
+
+.help-layer-popup:focus-visible {
+  outline: 3px solid var(--help-layer-accent, #1d4ed8);
+  outline-offset: 2px;
+}
+
+.help-layer-popup__title {
+  font-weight: bold;
+  margin-bottom: 4px;
+  /* Reserve space so it doesn't overlap the × button at the top-right. */
+  padding-right: 16px;
+}
+
+.help-layer-popup__text {
+  /* Render the body's \n as line breaks (still textContent, so no XSS risk). */
+  white-space: pre-line;
+  /* Keep long text from spilling off-screen; only the body scrolls within the popup. */
+  max-height: var(--help-layer-popup-max-height, 50vh);
+  overflow-y: auto;
+}
+
+.help-layer-popup__close {
+  /* reset of the button element */
+  appearance: none;
+  -webkit-appearance: none;
+  position: absolute;
+  top: 6px;
+  right: 6px;
+  width: 22px;
+  height: 22px;
+  padding: 0;
+  border: none;
+  border-radius: 4px;
+  background: transparent;
+  color: inherit;
+  font-size: 16px;
+  line-height: 1;
+  cursor: pointer;
+}
+
+.help-layer-popup__close:hover {
+  background: rgba(0, 0, 0, 0.08);
+}
+
+.help-layer-popup__close:focus-visible {
+  outline: 2px solid var(--help-layer-accent, #1d4ed8);
+  outline-offset: 1px;
+}
+
+/*
+ * Show an outline on the target element only while the marker is hovered/focused (clarifies "which element this explains").
+ * Make only the outline !important so it can beat host-side outline resets.
+ */
+.help-layer-target-highlight {
+  outline: 2px solid var(--help-layer-accent, #1d4ed8) !important;
+  outline-offset: 2px !important;
+}
+
+/*
+ * Dark-mode defaults. If the user specifies CSS variables, those always win via var(), so here we
+ * only swap the dark fallback values (the properties themselves aren't re-declared).
+ */
+@media (prefers-color-scheme: dark) {
+  .help-layer-popup {
+    background: var(--help-layer-popup-bg, #1f2933);
+    color: var(--help-layer-popup-color, #e5e7eb);
+    box-shadow: 0 4px 16px rgba(0, 0, 0, 0.55);
+  }
+}
+`;
+
+/**
+ * Inject a <style> tag into head and return that element.
+ * @param {string} [nonce] nonce to allow this <style> under a strict CSP (style-src 'nonce-…').
+ *   The nonce attribute is added only when provided. If omitted, nothing is added (as before).
+ */
+export function injectStyles(nonce) {
+  const styleEl = document.createElement('style');
+  styleEl.setAttribute(STYLE_ATTR, '');
+  // Under a CSP running style-src 'nonce-…', only a <style> with a matching nonce is applied.
+  if (nonce) {
+    styleEl.setAttribute('nonce', nonce);
+  }
+  styleEl.textContent = CSS;
+  document.head.appendChild(styleEl);
+  return styleEl;
+}
+
+/**
+ * Remove the <style> tag injected by injectStyles().
+ */
+export function removeStyles(styleEl) {
+  styleEl.remove();
+}