help-layer 1.1.0 → 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

@@ -35,15 +35,23 @@ export function makeVirtualElement(getDocRect: () => {
  * @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.1.0",
+  "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/*"
   },
@@ -38,7 +39,7 @@
     "build:types": "tsc -p jsconfig.json --declaration --emitDeclarationOnly --noEmit false --rootDir src --outDir dist/types",
     "build": "npm run build:bundle && npm run build:types",
     "record:gif": "npm run build:demos && node scripts/record-demo.js",
-    "prepublishOnly": "npm run build",
+    "prepack": "npm run build",
     "demo": "npm run build:demos && node scripts/serve.js"
   },
   "devDependencies": {

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

@@ -71,6 +71,27 @@ export function isFixedReference(reference) {
   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.)
@@ -94,9 +115,11 @@ 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`.
@@ -104,7 +127,27 @@ export function anchorMarker(reference, markerEl, onPlaced, placement = 'top-end
   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,

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/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() {