help-layer 1.0.0

package/src/dom-builder.js

@@ -0,0 +1,59 @@
+/**
+ * Factory functions that create the DOM elements for markers, popups, and the blocking layer.
+ * Event wiring and positioning are not done here (that is the caller's responsibility).
+ *
+ * Accessibility:
+ * - Markers are <button> elements so they are focusable and can be activated with Enter/Space.
+ * - The popup uses role="dialog" + aria-labelledby (the title element) to describe itself to assistive tech.
+ */
+
+const POPUP_TITLE_ID = 'help-layer-popup-title';
+
+export function createBlockingLayer() {
+  const layer = document.createElement('div');
+  layer.className = 'help-layer-blocking-layer';
+  return layer;
+}
+
+/**
+ * @param {string} title description title used for the assistive-tech label
+ * @param {string} [label] character shown on the marker (default '?'). Visual only; does not affect the aria-label.
+ */
+export function createMarker(title, label = '?') {
+  const marker = document.createElement('button');
+  marker.type = 'button';
+  marker.className = 'help-layer-marker';
+  marker.textContent = label;
+  marker.setAttribute('aria-label', `Help: ${title}`);
+  return marker;
+}
+
+/**
+ * Create the single popup shared across the whole library.
+ * Also returns references to titleEl/textEl (used to update the content) and the close button closeEl.
+ */
+export function createPopup() {
+  const root = document.createElement('div');
+  root.className = 'help-layer-popup';
+  root.setAttribute('role', 'dialog');
+  root.setAttribute('aria-labelledby', POPUP_TITLE_ID);
+  root.tabIndex = -1;
+
+  const titleEl = document.createElement('div');
+  titleEl.className = 'help-layer-popup__title';
+  titleEl.id = POPUP_TITLE_ID;
+
+  const textEl = document.createElement('div');
+  textEl.className = 'help-layer-popup__text';
+
+  // Explicit close affordance. Wiring the click is popup.js's job (only element creation here).
+  const closeEl = document.createElement('button');
+  closeEl.type = 'button';
+  closeEl.className = 'help-layer-popup__close';
+  closeEl.textContent = '×';
+  closeEl.setAttribute('aria-label', 'Close');
+
+  root.append(titleEl, textEl, closeEl);
+
+  return { root, titleEl, textEl, closeEl };
+}

package/src/floating.js

@@ -0,0 +1,122 @@
+/**
+ * A thin wrapper around Floating UI (@floating-ui/dom).
+ * Use of Floating UI is confined to this one file; other modules only call the
+ * purpose-specific functions (anchorMarker / anchorPopup / watchReference /
+ * makeVirtualElement). That way, if Floating UI is ever swapped out, the blast
+ * radius stays limited to here.
+ *
+ * Floating UI in a nutshell (note for readers unfamiliar with the DOM):
+ * - computePosition(reference, floating, options) computes the optimal placement
+ *   coordinates (x,y) for "this exact moment" and returns them (one-shot).
+ * - autoUpdate(reference, floating, update) watches scroll, resize, and element-size
+ *   changes (internally using ResizeObserver, etc.) and calls update on every change.
+ *   Calling the returned cleanup stops watching. This is what makes the element "stick"
+ *   to its target.
+ */
+import { autoUpdate, computePosition, flip, offset, shift } from '@floating-ui/dom';
+
+import { docRectToViewportRect } from './geometry.js';
+
+/**
+ * Create a "virtual reference element" for free-placement items not bound to an element.
+ * When getDocRect() returns document coordinates, this converts them to viewport
+ * coordinates according to the current scroll. Because autoUpdate re-evaluates on every
+ * scroll, the element sticks to the given coordinate while scrolling along with the page.
+ * @param {() => {top:number,left:number,width?:number,height?:number}} getDocRect
+ */
+export function makeVirtualElement(getDocRect) {
+  return {
+    // Tell autoUpdate that this element's ancestor is body (= scroll is watched up to window).
+    // Without this the virtual element isn't scroll-watched and won't follow page scroll.
+    contextElement: document.body,
+    getBoundingClientRect() {
+      return docRectToViewportRect(getDocRect(), { x: window.scrollX, y: window.scrollY });
+    },
+  };
+}
+
+function place(el, x, y) {
+  el.style.left = `${x}px`;
+  el.style.top = `${y}px`;
+}
+
+// Half of the default marker size (22px). The amount used to overlap the marker onto the
+// target's corner with an "inset". (If the marker-size CSS variable is changed, the resulting
+// drift is left as existing behavior = not compensated for here.)
+const MARKER_INSET = 11;
+
+/**
+ * Derive the offset for overlapping the marker onto the target's corner from the placement.
+ * mainAxis is always negative (bites inward past the target's edge). crossAxis flips sign by
+ * alignment direction: `-end` (right/bottom-aligned) is negative to go inward, `-start`
+ * (left/top-aligned) is positive to go inward.
+ * @param {string} placement
+ */
+function markerOffset(placement) {
+  const isStart = placement.endsWith('-start');
+  return { mainAxis: -MARKER_INSET, crossAxis: isStart ? MARKER_INSET : -MARKER_INSET };
+}
+
+/**
+ * Overlap the marker onto a corner of the target (element or virtual element), stick it there, and keep it following.
+ * @param {Element|object} reference
+ * @param {HTMLElement} markerEl
+ * @param {() => void} [onPlaced] called every time placement is finalized (used to trigger the overlap-avoidance pass, etc.)
+ * @param {import('@floating-ui/dom').Placement} [placement] corner to overlap (top-end/top-start/bottom-end/bottom-start). Default 'top-end'
+ * @returns {() => void} cleanup
+ */
+export function anchorMarker(reference, markerEl, onPlaced, placement = 'top-end') {
+  const update = () => {
+    computePosition(reference, markerEl, {
+      placement,
+      middleware: [offset(markerOffset(placement))],
+    }).then(({ x, y }) => {
+      place(markerEl, x, y);
+      if (onPlaced) {
+        onPlaced();
+      }
+    });
+  };
+  // animationFrame: true syncs repositioning to the rAF loop. With the default (scroll/resize
+  // events only), computePosition resolves asynchronously, so left/top is written the frame after
+  // the browser already painted the scroll — the marker lags a frame and visibly jitters.
+  return autoUpdate(reference, markerEl, update, { animationFrame: true });
+}
+
+/**
+ * Place the popup below the target, and at screen edges use flip (flip to the opposite side) /
+ * shift (nudge) to avoid clipping. Only follows while visible.
+ * @param {Element|object} reference
+ * @param {HTMLElement} popupEl
+ * @param {import('@floating-ui/dom').Placement} [placement] initial placement (Floating UI placement). Default 'bottom-start'
+ * @returns {{ update: () => void, cleanup: () => void }}
+ *   calling update repositions immediately (used for reference-side transform moves that autoUpdate doesn't pick up, etc.).
+ */
+export function anchorPopup(reference, popupEl, placement = 'bottom-start') {
+  const update = () => {
+    computePosition(reference, popupEl, {
+      placement,
+      middleware: [offset(8), flip({ padding: 8 }), shift({ padding: 8 })],
+    }).then(({ x, y }) => {
+      place(popupEl, x, y);
+    });
+  };
+  // animationFrame: true for the same smooth-tracking reason as anchorMarker. The reference here is
+  // the marker element, which itself moves per frame, so the popup must track per frame to stay glued.
+  const cleanup = autoUpdate(reference, popupEl, update, { animationFrame: true });
+  return { update, cleanup };
+}
+
+/**
+ * Watch a reference element's position/size changes and call onUpdate on every change.
+ * (Used for non-placement purposes, e.g. keeping the blocking layer's clip-path hole following the toggle position.)
+ * autoUpdate requires a floating element, so floatingEl is just passed as a dummy that
+ * onUpdate doesn't actually position.
+ * @param {Element} referenceEl
+ * @param {HTMLElement} floatingEl
+ * @param {() => void} onUpdate
+ * @returns {() => void} cleanup
+ */
+export function watchReference(referenceEl, floatingEl, onUpdate) {
+  return autoUpdate(referenceEl, floatingEl, onUpdate);
+}

package/src/geometry.js

@@ -0,0 +1,41 @@
+/**
+ * Pure geometry calculations. Takes no DOM elements, only numbers already read off.
+ *
+ * Clamping things that overflow the viewport is handled by Floating UI's shift()
+ * middleware. toDocumentPosition is used for the virtual-element math of free placement, etc.
+ */
+
+/**
+ * Given getBoundingClientRect() values (viewport-relative) and the scroll offset,
+ * compute coordinates relative to the whole document.
+ */
+export function toDocumentPosition(rect, scroll) {
+  return {
+    top: rect.top + scroll.y,
+    left: rect.left + scroll.x,
+  };
+}
+
+/**
+ * Convert a document-coordinate rect into a viewport-coordinate rect by subtracting
+ * the current scroll offset. This is what the getBoundingClientRect of a Floating UI
+ * virtual reference element (a free-placement marker) returns.
+ * @param {{top:number,left:number,width?:number,height?:number}} docRect
+ * @param {{x:number,y:number}} scroll
+ */
+export function docRectToViewportRect(docRect, scroll) {
+  const width = docRect.width || 0;
+  const height = docRect.height || 0;
+  const left = docRect.left - scroll.x;
+  const top = docRect.top - scroll.y;
+  return {
+    x: left,
+    y: top,
+    left,
+    top,
+    right: left + width,
+    bottom: top + height,
+    width,
+    height,
+  };
+}

package/src/index.js

@@ -0,0 +1,40 @@
+import { createToggleController } from './toggle.js';
+
+/**
+ * Initialize the help mode.
+ *
+ * It can be toggled ON/OFF by clicking the toggle element, and also controlled programmatically
+ * via the returned API. If `toggle` is omitted, there's no DOM toggle and it's programmatic-only.
+ *
+ * @param {object} options
+ * @param {import('./config.js').HelpConfig} options.config - configuration that specifies targets by data-help-id or position.
+ *   Elements not in config can still be targets via the data-help-title / data-help-text inline definition (config wins)
+ * @param {string|HTMLElement} [options.toggle] - toggle element that switches ON/OFF (CSS selector string or element). Optional
+ * @param {() => void} [options.onEnable] - called right after the mode is turned ON
+ * @param {() => void} [options.onDisable] - called right after the mode is turned OFF
+ * @param {(record: import('./matcher.js').HelpRecord) => void} [options.onOpen] - called when a description popup is opened
+ * @param {() => void} [options.onClose] - called when a description popup is closed
+ * @param {boolean} [options.silent] - suppress the warning log for unregistered keys
+ * @param {string} [options.attribute] - attribute name marking targets (default 'data-help-id')
+ * @param {(record: import('./matcher.js').HelpRecord) => (Node|null|undefined)} [options.render] - render the popup body with your own DOM.
+ *   Return a Node to display it; if nothing is returned, fall back to safe text display (the title is always record.title).
+ *   ⚠️ The return value is inserted as-is without sanitization. If it contains untrusted data, neutralize it on the caller side (XSS prevention)
+ * @param {string} [options.markerLabel] - character shown on the marker (default '?')
+ * @param {import('@floating-ui/dom').Placement} [options.markerPlacement] - corner to overlap the marker onto (default 'top-end')
+ * @param {import('@floating-ui/dom').Placement} [options.popupPlacement] - initial popup placement (default 'bottom-start')
+ * @param {string} [options.nonce] - nonce to allow the injected <style> under a strict CSP (style-src 'nonce-…')
+ * @returns {{
+ *   enable(): void,
+ *   disable(): void,
+ *   toggle(): void,
+ *   isActive(): boolean,
+ *   open(key: string): void,
+ *   close(): void,
+ *   update(config: import('./config.js').HelpConfig): void,
+ *   destroy(): void,
+ * }} a handle to control the mode and fully clean up at the end.
+ *   open(key) opens the description for the given key (auto-enables when OFF). close() closes the open description.
+ */
+export function initHelpLayer(options) {
+  return createToggleController(options);
+}

package/src/markers.js

@@ -0,0 +1,185 @@
+/**
+ * Marker manager.
+ * Markers can be dynamically mounted/unmounted per help record (SPA dynamic-element support).
+ * Each marker keeps following its target (an element, or the virtual element of a free placement)
+ * via Floating UI's autoUpdate. On every finalized placement it triggers the overlap-avoidance pass,
+ * debounced with rAF.
+ *
+ * Marker identifier (id):
+ * - element-bound: the target element itself (distinguishes multiple elements with the same data-help-id)
+ * - free placement: the config key string
+ */
+import { createMarker } from './dom-builder.js';
+import { anchorMarker, makeVirtualElement } from './floating.js';
+import { resolveOverlaps } from './overlap.js';
+
+// Temporary class added to the target element only while the marker is hovered/focused (matches the style.js definition).
+const TARGET_HIGHLIGHT_CLASS = 'help-layer-target-highlight';
+
+/** @param {import('./matcher.js').HelpRecord} record */
+function referenceFor(record) {
+  if (record.kind === 'free') {
+    return makeVirtualElement(() => ({
+      top: record.position.top,
+      left: record.position.left,
+      width: 0,
+      height: 0,
+    }));
+  }
+  return record.target;
+}
+
+/**
+ * @param {object} state teardown registry
+ * @param {object} options
+ * @param {(record: import('./matcher.js').HelpRecord, markerEl: HTMLElement) => void} options.onMarkerClick
+ * @param {() => void} [options.onOverlapResolved]
+ * @param {string} [options.markerLabel] character shown on the marker (default '?')
+ * @param {import('@floating-ui/dom').Placement} [options.markerPlacement] corner to overlap (default 'top-end')
+ */
+export function createMarkerManager(state, {
+  onMarkerClick,
+  onOverlapResolved,
+  markerLabel = '?',
+  markerPlacement = 'top-end',
+}) {
+  /** @type {Map<Element|string, {record:import('./matcher.js').HelpRecord, el:HTMLElement, cleanup:() => void}>} */
+  const markers = new Map();
+  let rafId = null;
+  // Don't schedule a new rAF during teardown (prevents a frame lingering after teardown).
+  let tornDown = false;
+
+  function runOverlapPass() {
+    rafId = null;
+    const entries = [...markers.values()];
+    // With one marker or fewer, overlap is impossible. Skip getBoundingClientRect (forced reflow)
+    // and the O(n^2) push-out math entirely (avoids a per-frame reflow while scrolling on screens
+    // with few targets). However, right after dropping from 2 to 1, if the remaining one still has
+    // a leftover push-out transform, clear it and let an open popup follow that move (in steady
+    // state, with an empty transform, do nothing).
+    if (entries.length <= 1) {
+      const el = entries.length === 1 ? entries[0].el : null;
+      if (el && el.style.transform) {
+        el.style.transform = '';
+        if (onOverlapResolved) {
+          onOverlapResolved();
+        }
+      }
+      return;
+    }
+
+    // Clear the accumulated transform to measure base centers, then reapply after resolving overlaps.
+    entries.forEach((e) => { e.el.style.transform = ''; });
+    const centers = entries.map((e) => {
+      const r = e.el.getBoundingClientRect();
+      return { x: r.left + r.width / 2, y: r.top + r.height / 2 };
+    });
+    const offsets = resolveOverlaps(centers);
+    entries.forEach((e, i) => {
+      const { dx, dy } = offsets[i];
+      e.el.style.transform = (dx || dy) ? `translate(${dx}px, ${dy}px)` : '';
+    });
+
+    // Marker positions moved, so give an open popup etc. the chance to follow.
+    if (onOverlapResolved) {
+      onOverlapResolved();
+    }
+  }
+
+  function scheduleOverlapPass() {
+    if (rafId !== null || tornDown) {
+      return;
+    }
+    rafId = requestAnimationFrame(runOverlapPass);
+  }
+
+  /** @param {import('./matcher.js').HelpRecord} record */
+  function mount(record) {
+    if (markers.has(record.id)) {
+      return;
+    }
+
+    const el = createMarker(record.title, markerLabel);
+    document.body.appendChild(el);
+
+    const handleClick = () => onMarkerClick(record, el);
+    el.addEventListener('click', handleClick);
+
+    const cleanupAnchor = anchorMarker(referenceFor(record), el, scheduleOverlapPass, markerPlacement);
+
+    // Target-element highlight (element-bound only; free placement has no target, so skip).
+    // Show an outline on the target only while the marker is hovered/focused, to make clear "which element this explains".
+    const target = record.kind === 'element' ? record.target : null;
+    const addHighlight = () => target && target.classList.add(TARGET_HIGHLIGHT_CLASS);
+    const removeHighlight = () => target && target.classList.remove(TARGET_HIGHLIGHT_CLASS);
+    if (target) {
+      el.addEventListener('mouseenter', addHighlight);
+      el.addEventListener('mouseleave', removeHighlight);
+      el.addEventListener('focus', addHighlight);
+      el.addEventListener('blur', removeHighlight);
+    }
+
+    let done = false;
+    const cleanup = () => {
+      if (done) {
+        return;
+      }
+      done = true;
+      cleanupAnchor();
+      el.removeEventListener('click', handleClick);
+      if (target) {
+        el.removeEventListener('mouseenter', addHighlight);
+        el.removeEventListener('mouseleave', removeHighlight);
+        el.removeEventListener('focus', addHighlight);
+        el.removeEventListener('blur', removeHighlight);
+        removeHighlight(); // don't leave the highlight on the target if unmounted while highlighted
+      }
+      el.remove();
+      markers.delete(record.id);
+      scheduleOverlapPass();
+    };
+
+    markers.set(record.id, { record, el, cleanup });
+  }
+
+  function unmount(id) {
+    const entry = markers.get(id);
+    if (entry) {
+      entry.cleanup();
+    }
+  }
+
+  function mountAll(records) {
+    records.forEach(mount);
+  }
+
+  // Register a single teardown for the whole manager with state
+  // (individual mount/unmount happen many times during a session, so they're bundled here).
+  state.track(() => {
+    tornDown = true;
+    if (rafId !== null) {
+      cancelAnimationFrame(rafId);
+      rafId = null;
+    }
+    [...markers.values()].forEach((entry) => entry.cleanup());
+  });
+
+  return {
+    mount,
+    unmount,
+    mountAll,
+    has(id) {
+      return markers.has(id);
+    },
+    // Return the first entry matching the config key (either element-bound or free placement).
+    // Used by the programmatic open(key).
+    findByKey(key) {
+      for (const entry of markers.values()) {
+        if (entry.record.key === key) {
+          return entry;
+        }
+      }
+      return null;
+    },
+  };
+}

package/src/matcher.js

@@ -0,0 +1,133 @@
+/**
+ * Map the help-item array returned by normalizeConfig() onto actual DOM elements or free
+ * placements, producing the "help records" the marker manager works with. Reads the DOM only;
+ * never writes.
+ *
+ * Behavior of this module:
+ * - Searches with queryAllDeep for Shadow DOM support.
+ * - Emits a marker for each of multiple elements sharing the same data-help-id (correct in practice).
+ *   Because of that, an element-bound record uses "the element itself" as its id (identity).
+ * - A free-placement record uses the config key as its id.
+ *
+ * Resolution order for title/text:
+ * - First look up config by the `data-help-id` value (config always wins).
+ * - If config has no match, use the element's `data-help-title` / `data-help-text` as an inline definition.
+ *   This lets you adopt the library with markup alone, without a config object.
+ */
+import { queryAllDeep } from './observer.js';
+
+/**
+ * One marker's worth of "help record". Produced by matcher; consumed by markers/popup/toggle/index — the shared contract.
+ * Other modules reference it via `import('./matcher.js').HelpRecord` (the same style as config.js's HelpConfig).
+ * @typedef {object} HelpRecord
+ * @property {Element|string} id for element-bound, the target element itself; for free placement, the config key string
+ * @property {'element'|'free'} kind
+ * @property {string|null} key config key (null for an inline-definition-only element)
+ * @property {string} title
+ * @property {string} text
+ * @property {Element} [target] the target element when kind:'element'
+ * @property {{top:number,left:number}} [position] the placement coordinate when kind:'free'
+ */
+
+// Attribute names used for inline definitions (fixed defaults so as not to grow the API).
+export const TITLE_ATTR = 'data-help-title';
+export const TEXT_ATTR = 'data-help-text';
+
+/**
+ * Build the selector to scan. In addition to elements with `data-help-id` (default), also pick up
+ * elements that only have an inline definition (`data-help-title`).
+ * A single source of truth so collectElementRecords and the MutationObserver share the same condition.
+ * @param {string} [attribute] attribute name marking targets (default 'data-help-id')
+ */
+export function targetSelector(attribute = 'data-help-id') {
+  return `[${attribute}], [${TITLE_ATTR}]`;
+}
+
+/** Turn element-bound items into a key->item Map. */
+export function elementConfigMap(items) {
+  const map = new Map();
+  for (const item of items) {
+    if (item.kind === 'element') {
+      map.set(item.key, item);
+    }
+  }
+  return map;
+}
+
+/**
+ * Turn free-placement items into records.
+ * @returns {HelpRecord[]}
+ */
+export function freeRecords(items) {
+  return items
+    .filter((item) => item.kind === 'free')
+    .map((item) => ({
+      id: item.key,
+      kind: 'free',
+      key: item.key,
+      title: item.title,
+      text: item.text,
+      position: item.position,
+    }));
+}
+
+/**
+ * Build the help record for a single element. title/text prefer config; if absent, fall back to
+ * the element's data-help-title / data-help-text (inline definition). If neither source yields
+ * both title and text, return null (not a target).
+ * (Used by both the initial scan and SPA dynamic additions.)
+ * @param {string} [attribute] attribute name marking targets (default 'data-help-id')
+ * @returns {HelpRecord|null}
+ */
+export function recordForElement(el, configMap, attribute = 'data-help-id') {
+  const key = el.getAttribute(attribute);
+  // config wins. If there's no matching key, fall back to the inline attributes.
+  const item = key != null ? configMap.get(key) : undefined;
+  const title = item ? item.title : el.getAttribute(TITLE_ATTR);
+  const text = item ? item.text : el.getAttribute(TEXT_ATTR);
+  // If both title and text aren't present, it's not a target (treated as unregistered).
+  if (!title || !text) {
+    return null;
+  }
+  return {
+    id: el,
+    kind: 'element',
+    key,
+    title,
+    text,
+    target: el,
+  };
+}
+
+/**
+ * Scan target-attribute elements under root (including Shadow DOM) and collect element-bound records.
+ * Targets not in config are warned about and ignored (non-fatal). silent:true suppresses the warning.
+ * @param {object[]} items
+ * @param {ParentNode} [root]
+ * @param {object} [options]
+ * @param {boolean} [options.silent] don't warn on unregistered keys
+ * @param {string} [options.attribute] attribute name marking targets (default 'data-help-id')
+ * @returns {HelpRecord[]}
+ */
+export function collectElementRecords(items, root = document, { silent = false, attribute = 'data-help-id' } = {}) {
+  const configMap = elementConfigMap(items);
+  const records = [];
+
+  queryAllDeep(root, targetSelector(attribute)).forEach((el) => {
+    const record = recordForElement(el, configMap, attribute);
+    if (!record) {
+      if (!silent) {
+        const key = el.getAttribute(attribute);
+        console.warn(
+          key != null
+            ? `[help-layer] element with ${attribute}="${key}" has no matching helpConfig entry or inline ${TITLE_ATTR}/${TEXT_ATTR}`
+            : `[help-layer] element needs both ${TITLE_ATTR} and ${TEXT_ATTR} (or a ${attribute} matching helpConfig)`,
+        );
+      }
+      return;
+    }
+    records.push(record);
+  });
+
+  return records;
+}