help-layer 1.0.0

package/dist/types/geometry.d.ts

@@ -0,0 +1,39 @@
+/**
+ * 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: any, scroll: any): {
+    top: any;
+    left: any;
+};
+/**
+ * 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: {
+    top: number;
+    left: number;
+    width?: number;
+    height?: number;
+}, scroll: {
+    x: number;
+    y: number;
+}): {
+    x: number;
+    y: number;
+    left: number;
+    top: number;
+    right: number;
+    bottom: number;
+    width: number;
+    height: number;
+};

package/dist/types/index.d.ts

@@ -0,0 +1,59 @@
+/**
+ * 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: {
+    config: import("./config.js").HelpConfig;
+    toggle?: string | HTMLElement;
+    onEnable?: () => void;
+    onDisable?: () => void;
+    onOpen?: (record: import("./matcher.js").HelpRecord) => void;
+    onClose?: () => void;
+    silent?: boolean;
+    attribute?: string;
+    render?: (record: import("./matcher.js").HelpRecord) => (Node | null | undefined);
+    markerLabel?: string;
+    markerPlacement?: import("@floating-ui/dom").Placement;
+    popupPlacement?: import("@floating-ui/dom").Placement;
+    nonce?: string;
+}): {
+    enable(): void;
+    disable(): void;
+    toggle(): void;
+    isActive(): boolean;
+    open(key: string): void;
+    close(): void;
+    update(config: import("./config.js").HelpConfig): void;
+    destroy(): void;
+};

package/dist/types/markers.d.ts

@@ -0,0 +1,24 @@
+/**
+ * @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: object, { onMarkerClick, onOverlapResolved, markerLabel, markerPlacement, }: {
+    onMarkerClick: (record: import("./matcher.js").HelpRecord, markerEl: HTMLElement) => void;
+    onOverlapResolved?: () => void;
+    markerLabel?: string;
+    markerPlacement?: import("@floating-ui/dom").Placement;
+}): {
+    mount: (record: import("./matcher.js").HelpRecord) => void;
+    unmount: (id: any) => void;
+    mountAll: (records: any) => void;
+    has(id: any): boolean;
+    findByKey(key: any): {
+        record: import("./matcher.js").HelpRecord;
+        el: HTMLElement;
+        cleanup: () => void;
+    };
+};

package/dist/types/matcher.d.ts

@@ -0,0 +1,79 @@
+/**
+ * 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?: string): string;
+/** Turn element-bound items into a key->item Map. */
+export function elementConfigMap(items: any): Map<any, any>;
+/**
+ * Turn free-placement items into records.
+ * @returns {HelpRecord[]}
+ */
+export function freeRecords(items: any): HelpRecord[];
+/**
+ * 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: any, configMap: any, attribute?: string): HelpRecord | null;
+/**
+ * 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: object[], root?: ParentNode, { silent, attribute }?: {
+    silent?: boolean;
+    attribute?: string;
+}): HelpRecord[];
+/**
+ * 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'
+ */
+export const TITLE_ATTR: "data-help-title";
+export const TEXT_ATTR: "data-help-text";
+/**
+ * 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).
+ */
+export type HelpRecord = {
+    /**
+     * for element-bound, the target element itself; for free placement, the config key string
+     */
+    id: Element | string;
+    kind: "element" | "free";
+    /**
+     * config key (null for an inline-definition-only element)
+     */
+    key: string | null;
+    title: string;
+    text: string;
+    /**
+     * the target element when kind:'element'
+     */
+    target?: Element;
+    /**
+     * the placement coordinate when kind:'free'
+     */
+    position?: {
+        top: number;
+        left: number;
+    };
+};

package/dist/types/observer.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Collect every element under root (including inside open shadowRoots) matching selector.
+ * @param {ParentNode} root
+ * @param {string} selector
+ * @returns {Element[]}
+ */
+export function queryAllDeep(root: ParentNode, selector: string): Element[];
+/**
+ * Collect every open shadowRoot under root (excluding root itself).
+ * @param {ParentNode} root
+ * @returns {ShadowRoot[]}
+ */
+export function collectShadowRoots(root: ParentNode): ShadowRoot[];
+/**
+ * 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, selector, onAdded, onRemoved }: {
+    root?: ParentNode;
+    selector: string;
+    onAdded: (el: Element) => void;
+    onRemoved: (el: Element) => void;
+}): {
+    disconnect(): void;
+};

package/dist/types/overlap.d.ts

@@ -0,0 +1,29 @@
+/**
+ * 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: Array<{
+    x: number;
+    y: number;
+}>, options?: {
+    minDistance?: number;
+    iterations?: number;
+}): Array<{
+    dx: number;
+    dy: number;
+}>;

package/dist/types/popup.d.ts

@@ -0,0 +1,22 @@
+/**
+ * @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: object, { onClose, render, popupPlacement }?: {
+    onClose?: () => void;
+    render?: (record: import("./matcher.js").HelpRecord) => (Node | null | undefined);
+    popupPlacement?: import("@floating-ui/dom").Placement;
+}): {
+    root: HTMLDivElement;
+    isOpen(id: any): boolean;
+    getOpenId(): any;
+    open: (record: import("./matcher.js").HelpRecord, referenceEl: HTMLElement) => void;
+    close: (focusTarget?: HTMLElement) => void;
+    reposition: () => void;
+};

package/dist/types/state.d.ts

@@ -0,0 +1,10 @@
+/**
+ * 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(): {
+    track(fn: any): void;
+    teardownAll(): void;
+};

package/dist/types/style.d.ts

@@ -0,0 +1,20 @@
+/**
+ * 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?: string): HTMLStyleElement;
+/**
+ * Remove the <style> tag injected by injectStyles().
+ */
+export function removeStyles(styleEl: any): void;
+/**
+ * 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;

package/dist/types/toggle.d.ts

@@ -0,0 +1,41 @@
+/**
+ * @param {object} params
+ * @param {object} params.config helpConfig
+ * @param {string|HTMLElement} [params.toggle] DOM element that switches ON/OFF (if omitted, programmatic control only)
+ * @param {() => void} [params.onEnable] called right after the mode is turned ON
+ * @param {() => void} [params.onDisable] called right after the mode is turned OFF
+ * @param {(record: import('./matcher.js').HelpRecord) => void} [params.onOpen] called when a popup is opened
+ * @param {() => void} [params.onClose] called when a popup is closed
+ * @param {boolean} [params.silent] suppress the warning log for unregistered keys
+ * @param {string} [params.attribute] attribute name marking targets (default 'data-help-id')
+ * @param {(record: import('./matcher.js').HelpRecord) => (Node|null|undefined)} [params.render] render the popup body with your own Node
+ *   (the return value is inserted as-is without sanitization, so untrusted data must be neutralized by the caller)
+ * @param {string} [params.markerLabel] character shown on the marker (default '?')
+ * @param {import('@floating-ui/dom').Placement} [params.markerPlacement] corner to overlap the marker onto (default 'top-end')
+ * @param {import('@floating-ui/dom').Placement} [params.popupPlacement] initial popup placement (default 'bottom-start')
+ * @param {string} [params.nonce] nonce to allow the injected <style> under a strict CSP (style-src 'nonce-…')
+ */
+export function createToggleController({ config, toggle, onEnable, onDisable, onOpen, onClose, silent, attribute, render, markerLabel, markerPlacement, popupPlacement, nonce, }: {
+    config: object;
+    toggle?: string | HTMLElement;
+    onEnable?: () => void;
+    onDisable?: () => void;
+    onOpen?: (record: import("./matcher.js").HelpRecord) => void;
+    onClose?: () => void;
+    silent?: boolean;
+    attribute?: string;
+    render?: (record: import("./matcher.js").HelpRecord) => (Node | null | undefined);
+    markerLabel?: string;
+    markerPlacement?: import("@floating-ui/dom").Placement;
+    popupPlacement?: import("@floating-ui/dom").Placement;
+    nonce?: string;
+}): {
+    enable: () => void;
+    disable: () => void;
+    toggle: () => void;
+    isActive(): boolean;
+    open: (key: any) => void;
+    close: () => void;
+    update: (newConfig: any) => void;
+    destroy(): void;
+};

package/package.json

@@ -0,0 +1,81 @@
+{
+  "name": "help-layer",
+  "version": "1.0.0",
+  "type": "module",
+  "sideEffects": false,
+  "engines": {
+    "node": ">=18"
+  },
+  "main": "src/index.js",
+  "unpkg": "dist/help-layer.iife.js",
+  "types": "dist/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/types/index.d.ts",
+      "import": "./src/index.js"
+    },
+    "./dist/*": "./dist/*"
+  },
+  "files": [
+    "src",
+    "dist"
+  ],
+  "directories": {
+    "doc": "doc"
+  },
+  "scripts": {
+    "test": "node --experimental-vm-modules node_modules/jest/bin/jest.js",
+    "test:coverage": "node --experimental-vm-modules node_modules/jest/bin/jest.js --coverage",
+    "test:e2e": "playwright test",
+    "test:e2e:ui": "playwright test --ui",
+    "lint": "eslint src tests",
+    "lint:fix": "eslint src tests --fix",
+    "typecheck": "tsc -p jsconfig.json",
+    "check": "npm run lint && npm run typecheck && npm test",
+    "build:bundle": "node scripts/build.js",
+    "build:types": "tsc -p jsconfig.json --declaration --emitDeclarationOnly --noEmit false --rootDir src --outDir dist/types",
+    "build": "npm run build:bundle && npm run build:types",
+    "prepublishOnly": "npm run build",
+    "demo": "node scripts/serve.js"
+  },
+  "devDependencies": {
+    "@playwright/test": "^1.61.0",
+    "esbuild": "^0.28.1",
+    "eslint": "^9.39.2",
+    "eslint-plugin-import": "^2.32.0",
+    "eslint-plugin-n": "^17.24.0",
+    "eslint-plugin-promise": "^7.2.1",
+    "jest": "^29.7.0",
+    "jest-environment-jsdom": "^29.7.0",
+    "react": "^19.2.7",
+    "react-dom": "^19.2.7",
+    "typescript": "^6.0.3",
+    "vue": "^3.5.38"
+  },
+  "keywords": [
+    "help-layer",
+    "tooltip",
+    "onboarding",
+    "walkthrough",
+    "guide",
+    "annotation",
+    "accessibility",
+    "a11y",
+    "shadow-dom",
+    "framework-agnostic"
+  ],
+  "author": "Y1-Effy <ssoruto@yahoo.co.jp>",
+  "license": "ISC",
+  "description": "Framework-agnostic, drop-in help mode for existing web apps — toggleable help markers with description popups, Shadow DOM piercing, and full cleanup.",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Y1-Effy/HelpLayer.git"
+  },
+  "homepage": "https://github.com/Y1-Effy/HelpLayer#readme",
+  "bugs": {
+    "url": "https://github.com/Y1-Effy/HelpLayer/issues"
+  },
+  "dependencies": {
+    "@floating-ui/dom": "^1.7.6"
+  }
+}

package/src/blocking-layer.js

@@ -0,0 +1,131 @@
+/**
+ * Transparent interaction-blocking layer.
+ *
+ * Without touching the original app's event listeners at all, it keeps interactions from getting through. How it works:
+ *
+ * 1. Let the toggle show through via a clip-path "hole":
+ *    Set a clip-path polygon on the full-screen layer made of the outer rectangle + the toggle
+ *    rectangle (the hole). Inside the hole the layer isn't painted and hit-testing passes through,
+ *    so the toggle can be clicked natively without touching z-index at all. Unlike approaches that
+ *    shuffle z-index, this doesn't break depending on ancestor stacking contexts.
+ *    The hole is updated via autoUpdate to follow the toggle's scroll/resize.
+ *
+ * 2. Focus containment:
+ *    On ON, blur activeElement, and via focusin (capture) detect focus moving to anything other
+ *    than the library UI and pull it back to the toggle. Host listeners are not detached.
+ *
+ * 3. Key-input suppression:
+ *    Capture keydown/keyup in document's capture phase; for anything outside the library UI,
+ *    stopPropagation+preventDefault. Escape has dedicated handling (close popup / exit mode).
+ *    Inside the library UI (marker/popup/toggle), normal interactions like Tab are allowed.
+ */
+import { createBlockingLayer } from './dom-builder.js';
+import { watchReference } from './floating.js';
+
+function buildClipPath(rect) {
+  const x1 = rect.left;
+  const y1 = rect.top;
+  const x2 = rect.right;
+  const y2 = rect.bottom;
+  // A single stroke: outer ring (clockwise) -> bridge -> toggle rectangle (counter-clockwise).
+  // Under the nonzero winding rule, making the inner ring wind opposite to the outer one punches a hole.
+  return `polygon(
+    0px 0px, 100% 0px, 100% 100%, 0px 100%, 0px 0px,
+    ${x1}px ${y1}px, ${x1}px ${y2}px, ${x2}px ${y2}px, ${x2}px ${y1}px, ${x1}px ${y1}px
+  )`;
+}
+
+export function activateBlockingLayer(state, {
+  toggleEl,
+  onBackgroundClick,
+  isLibraryElement,
+  onEscape,
+}) {
+  const layer = createBlockingLayer();
+  document.body.appendChild(layer);
+  state.track(() => layer.remove());
+
+  // --- 1. Keep the clip-path hole following the toggle position ---
+  // If there's no toggle element (programmatic control only), keeping the whole surface blocked with no hole is correct.
+  if (toggleEl) {
+    const updateClip = () => {
+      layer.style.clipPath = buildClipPath(toggleEl.getBoundingClientRect());
+    };
+    const cleanupClipWatch = watchReference(toggleEl, layer, updateClip);
+    state.track(cleanupClipWatch);
+  }
+
+  // Clicking the background (the layer itself) closes the popup
+  if (onBackgroundClick) {
+    layer.addEventListener('click', onBackgroundClick);
+    state.track(() => layer.removeEventListener('click', onBackgroundClick));
+  }
+
+  // --- 2. Focus containment ---
+  // Turning ON happens via a click on the toggle, so don't blur if the active element is the toggle
+  // itself (blurring would leave focus floating). For any other host element, make it let go.
+  const activeEl = document.activeElement;
+  if (
+    activeEl instanceof HTMLElement &&
+    activeEl !== document.body &&
+    activeEl !== toggleEl
+  ) {
+    activeEl.blur();
+  }
+
+  const handleFocusIn = (event) => {
+    if (isLibraryElement(event.target)) {
+      return;
+    }
+    // If focus tries to move to a host element, take it back.
+    // To the toggle if there is one; otherwise blur that element so it isn't handed to the host.
+    event.stopPropagation();
+    if (toggleEl) {
+      toggleEl.focus({ preventScroll: true });
+    } else if (event.target instanceof HTMLElement) {
+      event.target.blur();
+    }
+  };
+  document.addEventListener('focusin', handleFocusIn, true);
+  state.track(() => document.removeEventListener('focusin', handleFocusIn, true));
+
+  // --- 3. Key-input suppression + Escape ---
+  // Shared logic that doesn't pass key input destined outside the library UI through to the host.
+  const blockNonLibrary = (event) => {
+    if (isLibraryElement(event.target)) {
+      return;
+    }
+    event.stopPropagation();
+    event.preventDefault();
+  };
+  // keyup / keypress: don't leak to the host, Escape included (Escape's real handling is on the keydown side).
+  const blockKey = (event) => {
+    if (event.key === 'Escape') {
+      event.stopPropagation();
+      event.preventDefault();
+      return;
+    }
+    blockNonLibrary(event);
+  };
+  const handleKeydown = (event) => {
+    if (event.key === 'Escape') {
+      event.stopPropagation();
+      event.preventDefault();
+      if (onEscape) {
+        onEscape();
+      }
+      return;
+    }
+    blockNonLibrary(event);
+  };
+  document.addEventListener('keydown', handleKeydown, true);
+  document.addEventListener('keyup', blockKey, true);
+  document.addEventListener('keypress', blockKey, true);
+  state.track(() => {
+    document.removeEventListener('keydown', handleKeydown, true);
+    document.removeEventListener('keyup', blockKey, true);
+    document.removeEventListener('keypress', blockKey, true);
+  });
+
+  return layer;
+}

package/src/config.js

@@ -0,0 +1,81 @@
+/**
+ * Validation and normalization of the helpConfig object. A pure function that does no DOM work.
+ */
+
+/**
+ * @typedef {object} HelpEntry
+ * @property {string} title heading shown on the marker / popup (non-empty)
+ * @property {string} text description body (non-empty)
+ * @property {{ top: number, left: number }} [position] if given, becomes a free placement not tied to an element
+ */
+
+/**
+ * The helpConfig itself. For element-bound entries the key is the `data-help-id` value;
+ * for free placement it is any identifier.
+ * @typedef {Object<string, HelpEntry>} HelpConfig
+ */
+
+function isPlainObject(value) {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function isValidPosition(position) {
+  return (
+    isPlainObject(position) &&
+    typeof position.top === 'number' &&
+    typeof position.left === 'number'
+  );
+}
+
+/**
+ * Validate the shape of helpConfig. Throws an Error on any problem (fail fast).
+ */
+export function validateConfig(config) {
+  if (!isPlainObject(config)) {
+    throw new Error('helpConfig must be a plain object');
+  }
+
+  for (const [key, entry] of Object.entries(config)) {
+    if (!isPlainObject(entry)) {
+      throw new Error(`helpConfig["${key}"] must be an object`);
+    }
+    if (typeof entry.title !== 'string' || entry.title === '') {
+      throw new Error(`helpConfig["${key}"].title must be a non-empty string`);
+    }
+    if (typeof entry.text !== 'string' || entry.text === '') {
+      throw new Error(`helpConfig["${key}"].text must be a non-empty string`);
+    }
+    if (entry.position !== undefined && !isValidPosition(entry.position)) {
+      throw new Error(`helpConfig["${key}"].position must be { top: number, left: number }`);
+    }
+  }
+}
+
+/**
+ * Convert a validated helpConfig into the shared array of "help items" the rendering
+ * code works with. The target of kind:'element' is null at this point (DOM matching is
+ * left to matcher.js).
+ */
+export function normalizeConfig(config) {
+  return Object.entries(config).map(([key, entry]) => {
+    if (isValidPosition(entry.position)) {
+      return {
+        key,
+        title: entry.title,
+        text: entry.text,
+        kind: 'free',
+        target: null,
+        position: { top: entry.position.top, left: entry.position.left },
+      };
+    }
+
+    return {
+      key,
+      title: entry.title,
+      text: entry.text,
+      kind: 'element',
+      target: null,
+      position: null,
+    };
+  });
+}