@adobe/helix-rum-enhancer 2.36.5 → 2.37.0

package/CHANGELOG.md

@@ -1,3 +1,16 @@
+# [2.37.0](https://github.com/adobe/helix-rum-enhancer/compare/v2.36.5...v2.37.0) (2025-07-08)
+
+
+### Bug Fixes
+
+* audience reporting ([9f02657](https://github.com/adobe/helix-rum-enhancer/commit/9f0265703aba8ce01fa2850dadc36f993e9e2496))
+
+
+### Features
+
+* **a11y:** add a new accessibility plugin to categorize audience and detect common bugs ([033b425](https://github.com/adobe/helix-rum-enhancer/commit/033b4250ddfd3a3a8887b6fbebd18b92543c70a5))
+* **a11y:** add a new accessibility plugin to flag accessible audience and detect common bugs ([5a39aff](https://github.com/adobe/helix-rum-enhancer/commit/5a39aff315213187ce2b35928f72ad44fcd0e869))
+
 ## [2.36.5](https://github.com/adobe/helix-rum-enhancer/compare/v2.36.4...v2.36.5) (2025-06-20)
 
 

package/eslint.config.js

@@ -0,0 +1,34 @@
+import { defineConfig, globalIgnores } from '@eslint/config-helpers'
+import { recommended, source, test } from '@adobe/eslint-config-helix';
+import globals from "globals";
+
+export default defineConfig([
+  globalIgnores([
+    '.vscode/*',
+    'coverage/*',
+    'src/*',
+  ]), {
+    languageOptions: {
+      globals: {
+        ...globals.browser,
+        ...globals.mocha,
+      },
+    },
+  rules: {
+    'import/no-extraneous-dependencies': ['error', {
+      devDependencies: [
+          '**/test/**',
+          'rollup.config.js',
+          'web-test-runner.config.js',
+          'eslint.config.js',
+      ],
+    }],
+    },
+    plugins: {
+      import: recommended.plugins.import,
+    },
+    extends: [recommended],
+  },
+  source,
+  test,
+]);

package/modules/fflags.js

@@ -20,4 +20,5 @@ export const fflags = {
   example: [543, 770, 1136],
   language: [543, 959, 1139, 620],
   allresources: [1139],
+  a11y: [557, 781, 897, 955, 959],
 };

package/modules/index.js

@@ -34,6 +34,7 @@ const pluginBasePath = new URL(document.currentScript.src).href.replace(/index(\
 
 const PLUGINS = {
   cwv: `${pluginBasePath}/cwv.js`,
+  a11y: `${pluginBasePath}/a11y.js`,
   // Interactive elements
   form: { url: `${pluginBasePath}/form.js`, when: () => document.querySelector('form'), isBlockDependent: true },
   video: { url: `${pluginBasePath}/video.js`, when: () => document.querySelector('video'), isBlockDependent: true },
@@ -106,8 +107,7 @@ function loadPlugin(key, params) {
     pluginCache.set(key, import(`${plugin.url || plugin}`));
   }
 
-  const pluginLoadPromise = pluginCache.get(key);
-  return pluginLoadPromise
+  return pluginCache.get(key)
     .then((p) => (p.default && p.default(params)) || (typeof p === 'function' && p(params)))
     .catch(() => { /* silent plugin error catching */ });
 }
@@ -147,22 +147,19 @@ function trackCheckpoint(checkpoint, data, t) {
   const { weight, id } = window.hlx.rum;
   if (isSelected && maxEvents) {
     maxEvents -= 1;
-    const sendPing = (pdata = data) => {
-      // eslint-disable-next-line object-curly-newline, max-len
-      const body = JSON.stringify({ weight, id, referer: urlSanitizers[window.hlx.RUM_MASK_URL || 'path'](), checkpoint, t, ...data }, KNOWN_PROPERTIES);
-      const urlParams = window.RUM_PARAMS ? `?${new URLSearchParams(window.RUM_PARAMS).toString()}` : '';
-      const { href: url, origin } = new URL(`.rum/${weight}${urlParams}`, sampleRUM.collectBaseURL);
-      if (window.location.origin === origin) {
-        const headers = { type: 'application/json' };
-        navigator.sendBeacon(url, new Blob([body], headers));
-        /* c8 ignore next 3 */
-      } else {
-        navigator.sendBeacon(url, body);
-      }
-      // eslint-disable-next-line no-console
-      console.debug(`ping:${checkpoint}`, pdata);
-    };
-    sendPing(data);
+    // eslint-disable-next-line object-curly-newline, max-len
+    const body = JSON.stringify({ weight, id, referer: urlSanitizers[window.hlx.RUM_MASK_URL || 'path'](), checkpoint, t, ...data }, KNOWN_PROPERTIES);
+    const urlParams = window.RUM_PARAMS ? `?${new URLSearchParams(window.RUM_PARAMS).toString()}` : '';
+    const { href: url, origin } = new URL(`.rum/${weight}${urlParams}`, sampleRUM.collectBaseURL);
+    if (window.location.origin === origin) {
+      const headers = { type: 'application/json' };
+      navigator.sendBeacon(url, new Blob([body], headers));
+      /* c8 ignore next 3 */
+    } else {
+      navigator.sendBeacon(url, body);
+    }
+    // eslint-disable-next-line no-console
+    console.debug(`ping:${checkpoint}`, data);
   }
 }
 
@@ -223,14 +220,15 @@ function addNavigationTracking() {
 function addLoadResourceTracking() {
   const observer = new PerformanceObserver((list) => {
     try {
-      list.getEntries()
+      const entries = list.getEntries();
+      entries
         .filter((e) => !e.responseStatus || e.responseStatus < 400)
         .filter((e) => window.location.hostname === new URL(e.name).hostname || fflags.has('allresources'))
         .filter((e) => new URL(e.name).pathname.match('.*(\\.plain\\.html$|\\.json|graphql|api)'))
         .forEach((e) => {
           sampleRUM('loadresource', { source: e.name, target: Math.round(e.duration) });
         });
-      list.getEntries()
+      entries
         .filter((e) => e.responseStatus >= 400)
         .filter((e) => !(new URL(e.name).pathname.match('.*(/\\.rum/1[0-9]{0,3})')))
         .forEach((e) => {
@@ -343,7 +341,7 @@ function addTrackingFromConfig() {
   });
 }
 
-function initEnhancer() {
+function init() {
   try {
     if (sampleRUM) {
       addTrackingFromConfig();
@@ -356,4 +354,4 @@ function initEnhancer() {
   }
 }
 
-initEnhancer();
+init();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adobe/helix-rum-enhancer",
-  "version": "2.36.5",
+  "version": "2.37.0",
   "description": "Helix RUM Enhancer",
   "main": "src/index.js",
   "type": "module",
@@ -33,36 +33,38 @@
     "reporter-options": "configFile=.mocha-multi.json"
   },
   "devDependencies": {
-    "@adobe/eslint-config-helix": "2.0.9",
+    "@adobe/eslint-config-helix": "3.0.7",
     "@adobe/helix-rum-js": "2.12.1",
+    "@adobe/rollup-plugin-checksum": "1.2.0",
+    "@eslint/config-helpers": "0.3.0",
     "@esm-bundle/chai": "4.3.4-fix.0",
     "@rollup/plugin-babel": "6.0.4",
     "@semantic-release/changelog": "6.0.3",
     "@semantic-release/exec": "7.1.0",
     "@semantic-release/git": "10.0.1",
-    "@semantic-release/npm": "12.0.1",
+    "@semantic-release/npm": "12.0.2",
     "@web/test-runner": "0.20.2",
     "@web/test-runner-commands": "0.9.0",
     "@web/test-runner-junit-reporter": "0.8.0",
     "@web/test-runner-mocha": "0.9.0",
-    "@web/test-runner-playwright": "0.11.0",
+    "@web/test-runner-playwright": "0.11.1",
     "c8": "10.1.3",
     "codecov": "3.8.3",
-    "eslint": "8.57.1",
+    "eslint": "9.30.1",
     "eslint-plugin-header": "3.1.1",
-    "eslint-plugin-import": "2.31.0",
+    "eslint-plugin-import": "2.32.0",
+    "globals": "16.3.0",
     "husky": "9.1.7",
     "jsdoc-to-markdown": "9.1.1",
     "junit-report-builder": "5.1.1",
-    "lint-staged": "16.1.0",
-    "mocha": "11.6.0",
+    "lint-staged": "16.1.2",
+    "mocha": "11.7.1",
     "mocha-multi-reporters": "1.5.1",
-    "rollup": "4.42.0",
-    "@adobe/rollup-plugin-checksum": "1.2.0",
+    "rollup": "4.44.2",
     "rollup-plugin-eslint-bundle": "9.0.0",
-    "semantic-release": "24.2.5",
+    "semantic-release": "24.2.6",
     "semantic-release-slack-bot": "^4.0.2",
-    "web-vitals": "5.0.2"
+    "web-vitals": "5.0.3"
   },
   "lint-staged": {
     "*.js": "eslint",

package/plugins/a11y.js

@@ -0,0 +1,232 @@
+/*
+ * Copyright 2024 Adobe. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+
+const MEDIA_QUERY_PREFERENCES = [
+  '(prefers-reduced-motion: reduce)',
+  '(prefers-contrast: high)',
+  '(prefers-contrast: more)',
+  '(forced-colors: active)',
+  '(prefers-color-scheme: dark)',
+  '(prefers-reduced-transparency: reduce)',
+];
+
+const KEYBOARD_RELEVANT_KEYS = [
+  'Tab', 'ArrowUp', 'ArrowDown', 'ArrowLeft', 'ArrowRight', 'Enter', ' ', 'Escape',
+];
+
+const HIGH_ZOOM_LEVEL = 200;
+const MEDIUM_ZOOM_LEVEL = 125;
+
+const BEHAVIORAL_MIN_EVENTS = 10;
+
+const FOCUSTRAP_MAX_HISTORY = 25;
+const FOCUS_TRAP_MIN_HISTORY = 4;
+const FOCUS_TRAP_PING_PONG_DURATION = 3000;
+const FOCUS_TRAP_MIN_REPEATS = 3;
+
+/**
+ * Detects approximate zoom level using the Visual Viewport API.
+ * This is a pure utility function.
+ * @returns {Number} Estimated zoom percentage.
+ */
+function getZoom() {
+  if (window.visualViewport && window.visualViewport.width > 0) {
+    return Math.round((window.innerWidth / window.visualViewport.width) * 100);
+  }
+  /* c8 ignore next 1 */
+  return 100;
+}
+
+/**
+ * Minimal accessibility audience detection plugin for helix-rum-enhancer.
+ * @param {Object} params Plugin parameters from enhancer.
+ * @param {Function} params.sampleRUM RUM tracking function.
+ * @param {Function} params.sourceSelector Function to generate a selector for an element.
+ */
+export default function addAccessibilityAudienceTracking({ sampleRUM, sourceSelector }) {
+  const focusHistory = [];
+  let score = 0;
+  let reported = false;
+  let focusTrapDetected = false;
+  let keyboardCount = 0;
+  let totalCount = 0;
+  let lastFocusTime = 0;
+  let hadMeaningfulFocus = false;
+
+  const reportAudience = () => {
+    /* c8 ignore next 3 */
+    if (reported) {
+      return;
+    }
+    reported = true;
+    const audience = score >= 1 ? 'on' : 'off';
+    sampleRUM('a11y', { source: audience, target: 'on:off' });
+  };
+
+  const reportFocusTrap = (trapType, elements) => {
+    /* c8 ignore next 3 */
+    if (focusTrapDetected) {
+      return;
+    }
+    focusTrapDetected = true;
+    const elementDescriptions = elements.slice(0, 3).map(sourceSelector);
+    sampleRUM('error', {
+      source: `focus-trap:${trapType}`,
+      target: elementDescriptions.join(', '),
+    });
+  };
+
+  const detectRepeatingSequence = (elements, seqLength) => {
+    const totalLength = seqLength * FOCUS_TRAP_MIN_REPEATS;
+    /* c8 ignore next 3 */
+    if (elements.length < totalLength) {
+      return false;
+    }
+    const recent = elements.slice(-totalLength);
+    const baseSequence = recent.slice(0, seqLength);
+    for (let i = 1; i < FOCUS_TRAP_MIN_REPEATS; i += 1) {
+      const nextSequence = recent.slice(i * seqLength, (i + 1) * seqLength);
+      if (nextSequence.length !== seqLength
+        || !nextSequence.every((el, j) => el === baseSequence[j])) {
+        return false;
+      }
+    }
+    reportFocusTrap('sequence', baseSequence);
+    return true;
+  };
+
+  const detectFocusTrap = () => {
+    if (focusHistory.length < FOCUS_TRAP_MIN_HISTORY || focusTrapDetected) {
+      return;
+    }
+    const elements = focusHistory.map((h) => h.element);
+    const timestamps = focusHistory.map((h) => h.timestamp);
+
+    if (elements.slice(-3).every((el) => el === elements[elements.length - 1])) {
+      reportFocusTrap('single', [elements[elements.length - 1]]);
+      return;
+    }
+
+    const recent4 = elements.slice(-4);
+    const unique = [...new Set(recent4)];
+    const timeDiff = timestamps[timestamps.length - 1] - timestamps[timestamps.length - 4];
+    if (unique.length === 2 && timeDiff < FOCUS_TRAP_PING_PONG_DURATION) {
+      reportFocusTrap('ping-pong', unique);
+      return;
+    }
+
+    const minSeqLength = 2 * FOCUS_TRAP_MIN_HISTORY + 1;
+    if (focusHistory.length >= minSeqLength) {
+      for (let seqLength = 2; seqLength <= 4; seqLength += 1) {
+        if (detectRepeatingSequence(elements, seqLength)) {
+          return;
+        }
+      }
+    }
+  };
+
+  const trackFocusForTrap = (event) => {
+    setTimeout(() => {
+      const { activeElement } = document;
+      /* c8 ignore next 3 */
+      if (!activeElement || activeElement === document.body) {
+        return;
+      }
+      focusHistory.push({
+        element: activeElement,
+        timestamp: performance.now(),
+        shiftKey: event.shiftKey,
+      });
+      /* c8 ignore next 3 */
+      if (focusHistory.length > FOCUSTRAP_MAX_HISTORY) {
+        focusHistory.shift();
+      }
+      detectFocusTrap();
+    }, 0);
+  };
+
+  const checkBehavioralScore = () => {
+    if (totalCount >= BEHAVIORAL_MIN_EVENTS && !reported) {
+      if (keyboardCount / totalCount > 0.7) {
+        score += 2;
+      }
+      reportAudience();
+    }
+  };
+
+  // --- Static Scoring ---
+  score += MEDIA_QUERY_PREFERENCES.filter((q) => window.matchMedia(q).matches).length;
+
+  const zoom = getZoom();
+  if (zoom >= HIGH_ZOOM_LEVEL) {
+    score += 3;
+  } else if (zoom >= MEDIUM_ZOOM_LEVEL) {
+    score += 2;
+  }
+
+  if (navigator.maxTouchPoints === 0 && !window.matchMedia('(pointer: coarse)').matches) {
+    score += 2;
+  }
+
+  // --- Event Listeners & Observers ---
+  document.addEventListener('keydown', (event) => {
+    if (KEYBOARD_RELEVANT_KEYS.includes(event.key)) {
+      keyboardCount += 1;
+      totalCount += 1;
+      if (event.key === 'Tab') {
+        trackFocusForTrap(event);
+      }
+      checkBehavioralScore();
+    }
+  });
+
+  document.addEventListener('click', () => {
+    totalCount += 1;
+    checkBehavioralScore();
+  });
+
+  document.addEventListener('focusin', (event) => {
+    if (event.target !== document.body) {
+      lastFocusTime = performance.now();
+      hadMeaningfulFocus = true;
+    }
+  });
+
+  const focusLossObserver = new MutationObserver((mutations) => {
+    if (hadMeaningfulFocus
+        && document.activeElement === document.body
+        && (performance.now() - lastFocusTime > 100)) {
+      /* c8 ignore next 9 */
+      const mutation = mutations.find((m) => (
+        m.type === 'childList' && (m.addedNodes.length > 0 || m.removedNodes.length > 0)
+      ));
+      sampleRUM('error', {
+        source: 'focus-loss',
+        target: sourceSelector(mutation?.target),
+      });
+      hadMeaningfulFocus = false; // Prevent spam
+    }
+  });
+
+  focusLossObserver.observe(document, { childList: true, subtree: true });
+
+  // --- Final Reporting ---
+  if (score >= 1) {
+    reportAudience();
+  } else {
+    setTimeout(
+      () => reportAudience(),
+      /* c8 ignore next 1 */
+      window.hlx.A11Y_REPORT_DELAY || 10_000,
+    );
+  }
+}

package/src/index.js

@@ -21,7 +21,8 @@
     redirect: [620, 1139],
     example: [543, 770, 1136],
     language: [543, 959, 1139, 620],
-    allresources: [1139]
+    allresources: [1139],
+    a11y: [557, 781, 897, 955, 959]
   };
 
   const KNOWN_PROPERTIES = ['weight', 'id', 'referer', 'checkpoint', 't', 'source', 'target', 'cwv', 'CLS', 'FID', 'LCP', 'INP', 'TTFB'];
@@ -129,6 +130,7 @@
   const pluginBasePath = new URL(document.currentScript.src).href.replace(/index(\.map)?\.js/, 'plugins');
   const PLUGINS = {
     cwv: `${pluginBasePath}/cwv.js`,
+    a11y: `${pluginBasePath}/a11y.js`,
     form: {
       url: `${pluginBasePath}/form.js`,
       when: () => document.querySelector('form'),
@@ -207,8 +209,7 @@
     if (!pluginCache.has(key)) {
       pluginCache.set(key, import(`${plugin.url || plugin}`));
     }
-    const pluginLoadPromise = pluginCache.get(key);
-    return pluginLoadPromise.then(p => p.default && p.default(params) || typeof p === 'function' && p(params)).catch(() => {});
+    return pluginCache.get(key).then(p => p.default && p.default(params) || typeof p === 'function' && p(params)).catch(() => {});
   }
   function loadPlugins(filter = () => true, params = PLUGIN_PARAMETERS) {
     Object.entries(PLUGINS).filter(([, plugin]) => filter(plugin)).map(([key]) => loadPlugin(key, params));
@@ -237,31 +238,28 @@
     } = window.hlx.rum;
     if (isSelected && maxEvents) {
       maxEvents -= 1;
-      const sendPing = (pdata = data) => {
-        const body = JSON.stringify({
-          weight,
-          id,
-          referer: urlSanitizers[window.hlx.RUM_MASK_URL || 'path'](),
-          checkpoint,
-          t,
-          ...data
-        }, KNOWN_PROPERTIES);
-        const urlParams = window.RUM_PARAMS ? `?${new URLSearchParams(window.RUM_PARAMS).toString()}` : '';
-        const {
-          href: url,
-          origin
-        } = new URL(`.rum/${weight}${urlParams}`, sampleRUM.collectBaseURL);
-        if (window.location.origin === origin) {
-          const headers = {
-            type: 'application/json'
-          };
-          navigator.sendBeacon(url, new Blob([body], headers));
-        } else {
-          navigator.sendBeacon(url, body);
-        }
-        console.debug(`ping:${checkpoint}`, pdata);
-      };
-      sendPing(data);
+      const body = JSON.stringify({
+        weight,
+        id,
+        referer: urlSanitizers[window.hlx.RUM_MASK_URL || 'path'](),
+        checkpoint,
+        t,
+        ...data
+      }, KNOWN_PROPERTIES);
+      const urlParams = window.RUM_PARAMS ? `?${new URLSearchParams(window.RUM_PARAMS).toString()}` : '';
+      const {
+        href: url,
+        origin
+      } = new URL(`.rum/${weight}${urlParams}`, sampleRUM.collectBaseURL);
+      if (window.location.origin === origin) {
+        const headers = {
+          type: 'application/json'
+        };
+        navigator.sendBeacon(url, new Blob([body], headers));
+      } else {
+        navigator.sendBeacon(url, body);
+      }
+      console.debug(`ping:${checkpoint}`, data);
     }
   }
   function processQueue() {
@@ -316,13 +314,14 @@
   function addLoadResourceTracking() {
     const observer = new PerformanceObserver(list => {
       try {
-        list.getEntries().filter(e => !e.responseStatus || e.responseStatus < 400).filter(e => window.location.hostname === new URL(e.name).hostname || fflags.has('allresources')).filter(e => new URL(e.name).pathname.match('.*(\\.plain\\.html$|\\.json|graphql|api)')).forEach(e => {
+        const entries = list.getEntries();
+        entries.filter(e => !e.responseStatus || e.responseStatus < 400).filter(e => window.location.hostname === new URL(e.name).hostname || fflags.has('allresources')).filter(e => new URL(e.name).pathname.match('.*(\\.plain\\.html$|\\.json|graphql|api)')).forEach(e => {
           sampleRUM('loadresource', {
             source: e.name,
             target: Math.round(e.duration)
           });
         });
-        list.getEntries().filter(e => e.responseStatus >= 400).filter(e => !new URL(e.name).pathname.match('.*(/\\.rum/1[0-9]{0,3})')).forEach(e => {
+        entries.filter(e => e.responseStatus >= 400).filter(e => !new URL(e.name).pathname.match('.*(/\\.rum/1[0-9]{0,3})')).forEach(e => {
           sampleRUM('missingresource', {
             source: e.name,
             target: e.responseStatus
@@ -419,7 +418,7 @@
       });
     });
   }
-  function initEnhancer() {
+  function init() {
     try {
       if (sampleRUM) {
         addTrackingFromConfig();
@@ -428,6 +427,6 @@
       }
     } catch (error) {}
   }
-  initEnhancer();
+  init();
 
 })();

package/src/index.md5

@@ -1 +1 @@
-553c68a2b55034ef8e3f0c52cd6ccb50
+9ba349a918f32b3e7ab28953b112e1e3

package/src/index.sri

@@ -1 +1 @@
-sha384-CjLEkhzEseDSIYhgHR+ei0ZCRsITHEnViPh3w6rZZQKtbNW6hU7EY76328h4Ce/8
+sha384-aqtOVXFtjtaolB7x98Nxy+5pQMlMsfcgRSYyTEkx+BucLpCtD+Zor5pu0VVOXSkP