help-layer 1.0.1 → 1.2.0

package/dist/types/aria-isolation.d.ts

@@ -0,0 +1,10 @@
+/**
+ * @param {object} state teardown registry
+ * @param {object} params
+ * @param {HTMLElement|null} params.toggleEl the toggle (must stay reachable), or null for programmatic-only
+ * @param {(el: Element) => boolean} params.isLibraryNode whether a body child belongs to the library UI
+ */
+export function isolateBackgroundFromAT(state: object, { toggleEl, isLibraryNode }: {
+    toggleEl: HTMLElement | null;
+    isLibraryNode: (el: Element) => boolean;
+}): void;

package/dist/types/floating.d.ts

@@ -23,15 +23,35 @@ export function makeVirtualElement(getDocRect: () => {
         height: number;
     };
 };
+/**
+ * Whether the reference lives in a `position: fixed` subtree. Such a reference stays put in the
+ * viewport while the page scrolls, so an absolutely-positioned floating element (which scrolls with
+ * the document) would have to be re-corrected every frame and visibly jitters. For these we switch the
+ * floating element to Floating UI's `fixed` strategy (and position:fixed) so both live in the same
+ * viewport space and stay glued without per-frame correction.
+ *
+ * Virtual elements (free placements) aren't in the DOM and already track scroll via their getRect, so
+ * they report false. Walks across shadow boundaries via the host so Shadow DOM targets are handled too.
+ * @param {Element|object} reference
+ */
+export function isFixedReference(reference: Element | object): boolean;
+/**
+ * Whether a reference element is currently not rendered (hidden). Free placements use a virtual
+ * element with no host node, so they are never "hidden" (return false).
+ * @param {Element|object} reference
+ */
+export function isReferenceHidden(reference: Element | object): boolean;
 /**
  * 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'
+ * @param {() => void} [onHidden] called once each time the target transitions from visible to hidden
+ *   (lets the caller close a popup that was open on this now-hidden marker)
  * @returns {() => void} cleanup
  */
-export function anchorMarker(reference: Element | object, markerEl: HTMLElement, onPlaced?: () => void, placement?: import("@floating-ui/dom").Placement): () => void;
+export function anchorMarker(reference: Element | object, markerEl: HTMLElement, onPlaced?: () => void, placement?: import("@floating-ui/dom").Placement, onHidden?: () => void): () => void;
 /**
  * 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.

package/dist/types/markers.d.ts

@@ -3,12 +3,15 @@
  * @param {object} options
  * @param {(record: import('./matcher.js').HelpRecord, markerEl: HTMLElement) => void} options.onMarkerClick
  * @param {() => void} [options.onOverlapResolved]
+ * @param {(record: import('./matcher.js').HelpRecord) => void} [options.onMarkerHidden] called when a
+ *   marker's target transitions to hidden (e.g. display:none) — lets the caller close a popup open on it
  * @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, }: {
+export function createMarkerManager(state: object, { onMarkerClick, onOverlapResolved, onMarkerHidden, markerLabel, markerPlacement, }: {
     onMarkerClick: (record: import("./matcher.js").HelpRecord, markerEl: HTMLElement) => void;
     onOverlapResolved?: () => void;
+    onMarkerHidden?: (record: import("./matcher.js").HelpRecord) => void;
     markerLabel?: string;
     markerPlacement?: import("@floating-ui/dom").Placement;
 }): {

package/package.json

@@ -1,18 +1,19 @@
 {
   "name": "help-layer",
-  "version": "1.0.1",
+  "version": "1.2.0",
   "type": "module",
   "sideEffects": false,
   "engines": {
     "node": ">=18"
   },
-  "main": "src/index.js",
+  "main": "dist/help-layer.esm.js",
+  "module": "dist/help-layer.esm.js",
   "unpkg": "dist/help-layer.iife.js",
   "types": "dist/types/index.d.ts",
   "exports": {
     ".": {
       "types": "./dist/types/index.d.ts",
-      "import": "./src/index.js"
+      "import": "./dist/help-layer.esm.js"
     },
     "./dist/*": "./dist/*"
   },
@@ -32,11 +33,14 @@
     "lint:fix": "eslint src tests --fix",
     "typecheck": "tsc -p jsconfig.json",
     "check": "npm run lint && npm run typecheck && npm test",
+    "build:site": "node demo/build-site.js",
+    "build:demos": "node demo/build-framework-demos.js",
     "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"
+    "record:gif": "npm run build:demos && node scripts/record-demo.js",
+    "prepack": "npm run build",
+    "demo": "npm run build:demos && node scripts/serve.js"
   },
   "devDependencies": {
     "@playwright/test": "^1.61.0",
@@ -45,8 +49,10 @@
     "eslint-plugin-import": "^2.32.0",
     "eslint-plugin-n": "^17.24.0",
     "eslint-plugin-promise": "^7.2.1",
+    "gifenc": "^1.0.3",
     "jest": "^29.7.0",
     "jest-environment-jsdom": "^29.7.0",
+    "pngjs": "^7.0.0",
     "react": "^19.2.7",
     "react-dom": "^19.2.7",
     "typescript": "^6.0.3",

package/src/aria-isolation.js

@@ -0,0 +1,67 @@
+/**
+ * Semantic background blocking for assistive technology (AT).
+ *
+ * The clip-path layer / focus containment / key suppression block pointer, physical focus, and
+ * physical keys, but a screen reader's virtual cursor (browse mode) reads and can activate background
+ * content regardless of focus or hit-testing. So while ON we also remove the host from the
+ * accessibility tree with `inert` (which both excludes from the a11y tree and suppresses interaction),
+ * giving AT users the same "host is inactive" guarantee.
+ *
+ * Why operate at document.body's top level: `inert` is inherited and cannot be cancelled on a
+ * descendant of an inert subtree. The toggle is host-owned and may be deeply nested, so—exactly like
+ * the clip-path "hole" that lets the toggle show through—we inert each body child that is neither a
+ * library node nor the branch containing the toggle. The toggle's own top-level branch stays
+ * reachable (a bounded leak when the toggle is nested; none when it's a direct body child).
+ */
+
+const ELEMENT_NODE = 1;
+
+/**
+ * @param {object} state teardown registry
+ * @param {object} params
+ * @param {HTMLElement|null} params.toggleEl the toggle (must stay reachable), or null for programmatic-only
+ * @param {(el: Element) => boolean} params.isLibraryNode whether a body child belongs to the library UI
+ */
+export function isolateBackgroundFromAT(state, { toggleEl, isLibraryNode }) {
+  /** @type {Set<Element>} */
+  const isolated = new Set();
+
+  /** @param {Node} node */
+  function isolate(node) {
+    if (node.nodeType !== ELEMENT_NODE) {
+      return;
+    }
+    const el = /** @type {Element} */ (node);
+    // Skip library UI, the toggle's branch, and anything the host already made inert (so restore
+    // doesn't clobber the host's own inert state).
+    if (
+      isLibraryNode(el) ||
+      (toggleEl && (el === toggleEl || el.contains(toggleEl))) ||
+      el.hasAttribute('inert')
+    ) {
+      return;
+    }
+    el.toggleAttribute('inert', true);
+    isolated.add(el);
+  }
+
+  for (const child of [...document.body.children]) {
+    isolate(child);
+  }
+
+  // The host may add top-level nodes while ON (SPA route changes, portals, ...). Keep them isolated
+  // too. Only direct body children matter here, so childList without subtree is enough.
+  const observer = new MutationObserver((records) => {
+    for (const record of records) {
+      record.addedNodes.forEach(isolate);
+    }
+  });
+  observer.observe(document.body, { childList: true });
+
+  state.track(() => {
+    observer.disconnect();
+    // Remove inert only from the nodes we added it to (leave any host-owned inert untouched).
+    isolated.forEach((el) => el.removeAttribute('inert'));
+    isolated.clear();
+  });
+}

package/src/dom-builder.js

@@ -7,7 +7,10 @@
  * - The popup uses role="dialog" + aria-labelledby (the title element) to describe itself to assistive tech.
  */
 
-const POPUP_TITLE_ID = 'help-layer-popup-title';
+// Each initHelpLayer instance builds its own popup; a fixed id would collide when the
+// library is initialized more than once on a page (invalid duplicate id + ambiguous
+// aria-labelledby). Hand out a unique id per popup instead.
+let popupSeq = 0;
 
 export function createBlockingLayer() {
   const layer = document.createElement('div');
@@ -33,15 +36,21 @@ export function createMarker(title, label = '?') {
  * Also returns references to titleEl/textEl (used to update the content) and the close button closeEl.
  */
 export function createPopup() {
+  const titleId = `help-layer-popup-title-${popupSeq++}`;
+
   const root = document.createElement('div');
   root.className = 'help-layer-popup';
   root.setAttribute('role', 'dialog');
-  root.setAttribute('aria-labelledby', POPUP_TITLE_ID);
+  // aria-modal tells AT that content outside the dialog is inert while it's shown (the host is also
+  // inert'd at the document level during help mode). Harmless when hidden: display:none drops the
+  // popup from the a11y tree.
+  root.setAttribute('aria-modal', 'true');
+  root.setAttribute('aria-labelledby', titleId);
   root.tabIndex = -1;
 
   const titleEl = document.createElement('div');
   titleEl.className = 'help-layer-popup__title';
-  titleEl.id = POPUP_TITLE_ID;
+  titleEl.id = titleId;
 
   const textEl = document.createElement('div');
   textEl.className = 'help-layer-popup__text';

package/src/floating.js

@@ -40,6 +40,58 @@ function place(el, x, y) {
   el.style.top = `${y}px`;
 }
 
+/**
+ * Whether the reference lives in a `position: fixed` subtree. Such a reference stays put in the
+ * viewport while the page scrolls, so an absolutely-positioned floating element (which scrolls with
+ * the document) would have to be re-corrected every frame and visibly jitters. For these we switch the
+ * floating element to Floating UI's `fixed` strategy (and position:fixed) so both live in the same
+ * viewport space and stay glued without per-frame correction.
+ *
+ * Virtual elements (free placements) aren't in the DOM and already track scroll via their getRect, so
+ * they report false. Walks across shadow boundaries via the host so Shadow DOM targets are handled too.
+ * @param {Element|object} reference
+ */
+export function isFixedReference(reference) {
+  if (!(reference instanceof Element)) {
+    return false;
+  }
+  let node = reference;
+  while (node) {
+    if (getComputedStyle(node).position === 'fixed') {
+      return true;
+    }
+    const parent = node.parentElement;
+    if (parent) {
+      node = parent;
+    } else {
+      const root = node.getRootNode();
+      node = root instanceof ShadowRoot ? root.host : null;
+    }
+  }
+  return false;
+}
+
+/**
+ * Whether a reference element is currently not rendered (hidden). Free placements use a virtual
+ * element with no host node, so they are never "hidden" (return false).
+ * @param {Element|object} reference
+ */
+export function isReferenceHidden(reference) {
+  if (!(reference instanceof Element)) {
+    return false;
+  }
+  // checkVisibility() catches display:none (incl. an ancestor), content-visibility, and—with the
+  // option—visibility:hidden, in one cheap call without any extra observers. NOTE: do NOT use
+  // offsetParent here; it is null for position:fixed elements too (which this lib supports as
+  // targets) and would wrongly hide their markers. Engines without checkVisibility fall back to the
+  // rect: a display:none element measures 0x0 (the worst case — the marker would jump to 0,0).
+  if (typeof reference.checkVisibility === 'function') {
+    return !reference.checkVisibility({ visibilityProperty: true, contentVisibilityAuto: true });
+  }
+  const r = reference.getBoundingClientRect();
+  return r.width === 0 && r.height === 0;
+}
+
 // 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.)
@@ -63,12 +115,42 @@ function markerOffset(placement) {
  * @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'
+ * @param {() => void} [onHidden] called once each time the target transitions from visible to hidden
+ *   (lets the caller close a popup that was open on this now-hidden marker)
  * @returns {() => void} cleanup
  */
-export function anchorMarker(reference, markerEl, onPlaced, placement = 'top-end') {
+export function anchorMarker(reference, markerEl, onPlaced, placement = 'top-end', onHidden) {
+  // Match the floating element's strategy to the reference: a fixed reference needs a fixed marker, or
+  // it jitters while scrolling (see isFixedReference). Inline !important beats the stylesheet's
+  // `position: absolute !important`.
+  const strategy = isFixedReference(reference) ? 'fixed' : 'absolute';
+  if (strategy === 'fixed') {
+    markerEl.style.setProperty('position', 'fixed', 'important');
+  }
+  // Track the visible/hidden state so onHidden fires only on the transition, not every frame.
+  let hiddenNow = false;
   const update = () => {
+    if (isReferenceHidden(reference)) {
+      // Target went hidden (e.g. display:none) while ON. Hide the marker too instead of leaving it
+      // stranded (a display:none target measures 0x0, which would otherwise fling the marker to 0,0).
+      // Inline !important beats the stylesheet's `display:block !important`; skip computePosition while
+      // hidden. autoUpdate({animationFrame:true}) keeps polling, so the marker is restored on reshow.
+      markerEl.style.setProperty('display', 'none', 'important');
+      if (!hiddenNow && onHidden) {
+        onHidden(); // notify on the visible -> hidden edge (e.g. close a popup open on this marker)
+      }
+      hiddenNow = true;
+      if (onPlaced) {
+        onPlaced(); // let the overlap pass re-pack without this now-hidden marker
+      }
+      return;
+    }
+    hiddenNow = false;
+    // Revert to the stylesheet's `display:block` (no-op when we never hid it).
+    markerEl.style.removeProperty('display');
     computePosition(reference, markerEl, {
       placement,
+      strategy,
       middleware: [offset(markerOffset(placement))],
     }).then(({ x, y }) => {
       place(markerEl, x, y);
@@ -95,9 +177,15 @@ export function anchorMarker(reference, markerEl, onPlaced, placement = 'top-end
  *   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') {
+  // The reference is the clicked marker. If it's fixed (anchored to a fixed target), the popup must be
+  // fixed too or it jitters on scroll. Set position every open so reopening on a normal marker restores
+  // absolute. Inline !important beats the stylesheet's `position: absolute !important`.
+  const strategy = isFixedReference(reference) ? 'fixed' : 'absolute';
+  popupEl.style.setProperty('position', strategy, 'important');
   const update = () => {
     computePosition(reference, popupEl, {
       placement,
+      strategy,
       middleware: [offset(8), flip({ padding: 8 }), shift({ padding: 8 })],
     }).then(({ x, y }) => {
       place(popupEl, x, y);

package/src/markers.js

@@ -34,12 +34,15 @@ function referenceFor(record) {
  * @param {object} options
  * @param {(record: import('./matcher.js').HelpRecord, markerEl: HTMLElement) => void} options.onMarkerClick
  * @param {() => void} [options.onOverlapResolved]
+ * @param {(record: import('./matcher.js').HelpRecord) => void} [options.onMarkerHidden] called when a
+ *   marker's target transitions to hidden (e.g. display:none) — lets the caller close a popup open on it
  * @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,
+  onMarkerHidden,
   markerLabel = '?',
   markerPlacement = 'top-end',
 }) {
@@ -51,7 +54,10 @@ export function createMarkerManager(state, {
 
   function runOverlapPass() {
     rafId = null;
-    const entries = [...markers.values()];
+    // Exclude hidden markers (floating.js sets inline display:none when a target goes display:none):
+    // such a marker measures 0x0 at the origin, so leaving it in would make it count toward the
+    // "<=1, skip" check and push visible markers away from (0,0).
+    const entries = [...markers.values()].filter((e) => e.el.style.display !== 'none');
     // 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
@@ -105,7 +111,13 @@ export function createMarkerManager(state, {
     const handleClick = () => onMarkerClick(record, el);
     el.addEventListener('click', handleClick);
 
-    const cleanupAnchor = anchorMarker(referenceFor(record), el, scheduleOverlapPass, markerPlacement);
+    const cleanupAnchor = anchorMarker(
+      referenceFor(record),
+      el,
+      scheduleOverlapPass,
+      markerPlacement,
+      () => onMarkerHidden && onMarkerHidden(record),
+    );
 
     // 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".

package/src/style.js

@@ -48,7 +48,9 @@ const CSS = `
   border: none;
   /* Structural properties are !important so a host's broad rules (e.g. button { display:none }) can't
      hide or distort the marker. top/left stay non-important because place() writes them inline per
-     frame; !important there would override that and pin the marker to 0,0. Theme stays var()-driven. */
+     frame; !important there would override that and pin the marker to 0,0. Theme stays var()-driven.
+     Note: for targets in a position:fixed subtree, floating.js overrides this with an inline
+     position:fixed !important (inline important beats this rule) so the marker doesn't jitter. */
   position: absolute !important;
   display: block !important;
   visibility: visible !important;

package/src/toggle.js

@@ -3,6 +3,7 @@
  * Starts each subsystem (style injection, marker manager, popup, blocking layer, DOM observation)
  * and aggregates their teardown into the cleanup registry (state).
  */
+import { isolateBackgroundFromAT } from './aria-isolation.js';
 import { activateBlockingLayer } from './blocking-layer.js';
 import { isPlainObject, normalizeConfig, validateConfig } from './config.js';
 import { createMarkerManager } from './markers.js';
@@ -120,6 +121,14 @@ export function createToggleController(options) {
       },
       // When overlap avoidance moves a marker, make the open popup follow.
       onOverlapResolved: () => popup.reposition(),
+      // If a target is hidden (e.g. display:none) while its popup is open, close it (its marker just
+      // collapsed to 0x0) — same as the SPA-removal path. Return focus to the toggle since the marker
+      // is no longer focusable.
+      onMarkerHidden: (record) => {
+        if (popup.isOpen(record.id)) {
+          popup.close(toggleEl ?? undefined);
+        }
+      },
     });
 
     // Initial mount (free placements + elements currently in the DOM, including Shadow DOM)
@@ -151,7 +160,7 @@ export function createToggleController(options) {
         popup.root.contains(target) ||
         (typeof target.closest === 'function' && !!target.closest('.help-layer-marker')));
 
-    activateBlockingLayer(state, {
+    const layer = activateBlockingLayer(state, {
       toggleEl,
       onBackgroundClick: () => popup.close(),
       isLibraryElement,
@@ -163,6 +172,15 @@ export function createToggleController(options) {
         }
       },
     });
+
+    // Semantic blocking for assistive tech: remove the host from the a11y tree while ON (the layer/
+    // popup/markers and the toggle stay reachable). Runs last so the just-mounted library nodes are
+    // present and skipped by the initial scan.
+    const isLibraryNode = (el) =>
+      el === layer ||
+      el === popup.root ||
+      (!!el.classList && el.classList.contains('help-layer-marker'));
+    isolateBackgroundFromAT(state, { toggleEl, isLibraryNode });
   }
 
   function turnOff() {