@adobe/helix-rum-enhancer 2.36.5 → 2.37.1

package/CHANGELOG.md

@@ -1,3 +1,24 @@
+## [2.37.1](https://github.com/adobe/helix-rum-enhancer/compare/v2.37.0...v2.37.1) (2025-07-14)
+
+
+### Bug Fixes
+
+* **a11y:** audience is flagged as using accessibility too often ([4449970](https://github.com/adobe/helix-rum-enhancer/commit/444997021c49b45d9162a4a09035e6b75c0360fc))
+* **a11y:** audience is flagged as using accessibility too often ([03e9f1b](https://github.com/adobe/helix-rum-enhancer/commit/03e9f1b185574649741ca4e3a50ecce13165819d))
+
+# [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

@@ -32,8 +32,26 @@ const hasCookieKey = (key) => document.cookie.split(';').some((c) => c.trim().st
 // Set the base path for the plugins
 const pluginBasePath = new URL(document.currentScript.src).href.replace(/index(\.map)?\.js/, 'plugins');
 
+const CONSENT_PROVIDERS = [
+  {
+    name: 'onetrust',
+    detect: () => hasCookieKey('OptanonAlertBoxClosed') || document.querySelector('#onetrust-banner-sdk, #onetrust-pc-sdk'),
+  },
+  {
+    name: 'trustarc',
+    detect: () => ['notice_gdpr_prefs', 'notice_preferences'].some(hasCookieKey) || document.querySelector('#truste-consent-track, #consent_blackbar'),
+  },
+  {
+    name: 'usercentrics',
+    detect: () => window.localStorage.getItem('uc_gcm') || document.querySelector('#usercentrics-root'),
+  },
+];
+
+const getConsentProvider = () => CONSENT_PROVIDERS.find(({ detect }) => detect());
+
 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 },
@@ -44,9 +62,8 @@ const PLUGINS = {
   },
   // Martech
   martech: { url: `${pluginBasePath}/martech.js`, when: ({ urlParameters }) => urlParameters.size > 0 },
-  onetrust: {
-    url: `${pluginBasePath}/onetrust.js`,
-    when: () => (hasCookieKey('OptanonAlertBoxClosed') || document.querySelector('#onetrust-consent-sdk')),
+  consent: {
+    when: () => getConsentProvider(),
     isBlockDependent: true,
     mutationObserverParams: {
       target: document.body,
@@ -102,12 +119,15 @@ function loadPlugin(key, params) {
     return null;
   }
 
+  if (key === 'consent') {
+    plugin.url = `${pluginBasePath}/${getConsentProvider().name}.js`;
+  }
+
   if (!pluginCache.has(key)) {
     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 +167,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 +240,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 +361,7 @@ function addTrackingFromConfig() {
   });
 }
 
-function initEnhancer() {
+function init() {
   try {
     if (sampleRUM) {
       addTrackingFromConfig();
@@ -356,4 +374,4 @@ function initEnhancer() {
   }
 }
 
-initEnhancer();
+init();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adobe/helix-rum-enhancer",
-  "version": "2.36.5",
+  "version": "2.37.1",
   "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.8",
     "@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.45.0",
     "rollup-plugin-eslint-bundle": "9.0.0",
-    "semantic-release": "24.2.5",
+    "semantic-release": "24.2.7",
     "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,231 @@
+/*
+ * 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-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/plugins/onetrust.js

@@ -9,36 +9,30 @@
  * OF ANY KIND, either express or implied. See the License for the specific language
  * governing permissions and limitations under the License.
  */
-let hasSentData = false;
-export default function addCookieConsentTracking({ sampleRUM }) {
-  const sampleRUMOnce = (...args) => {
-    if (!hasSentData) {
-      sampleRUM(...args);
-      hasSentData = true;
-    }
-  };
+function trackConsent() {
   const cmpCookie = document.cookie.split(';')
     .map((c) => c.trim())
     .find((cookie) => cookie.startsWith('OptanonAlertBoxClosed='));
 
   if (cmpCookie) {
-    sampleRUMOnce('consent', { source: 'onetrust', target: 'hidden' });
-    return;
+    return 'hidden';
   }
 
-  const bannersdk = document.querySelector('#onetrust-banner-sdk');
+  const banner = document.querySelector('#onetrust-banner-sdk') || document.querySelector('#onetrust-pc-sdk');
 
-  if (bannersdk && bannersdk.offsetHeight > 0) {
-    sampleRUMOnce('consent', { source: 'onetrust', target: 'show' });
-    return;
+  if (banner && banner.offsetHeight > 0) {
+    return 'show';
   }
 
-  const pcsdk = document.querySelector('#onetrust-pc-sdk');
+  return 'suppressed';
+}
 
-  if (pcsdk && pcsdk.offsetHeight > 0) {
-    sampleRUMOnce('consent', { source: 'onetrust', target: 'show' });
+let hasSentData = false;
+export default function addCookieConsentTracking({ sampleRUM }) {
+  if (hasSentData) {
     return;
   }
 
-  sampleRUMOnce('consent', { source: 'onetrust', target: 'suppressed' });
+  sampleRUM('consent', { source: 'onetrust', target: trackConsent() });
+  hasSentData = true;
 }

package/plugins/trustarc.js

@@ -0,0 +1,38 @@
+/*
+ * Copyright 2025 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.
+ */
+function trackConsent() {
+  const cookies = document.cookie.split(';')
+    .map((c) => c.trim())
+    .filter((cookie) => (cookie.startsWith('notice_gdpr_prefs=') || cookie.startsWith('notice_preferences=')));
+
+  if (cookies.length === 2) {
+    return 'hidden';
+  }
+
+  const banner = document.querySelector('#truste-consent-track') || document.querySelector('#truste-consent-content');
+
+  if (banner && banner.offsetHeight > 0) {
+    return 'show';
+  }
+
+  return 'suppressed';
+}
+
+let hasSentData = false;
+export default function addCookieConsentTracking({ sampleRUM }) {
+  if (hasSentData) {
+    return;
+  }
+
+  sampleRUM('consent', { source: 'trustarc', target: trackConsent() });
+  hasSentData = true;
+}

package/plugins/usercentrics.js

@@ -0,0 +1,35 @@
+/*
+ * Copyright 2025 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.
+ */
+function trackConsent() {
+  if (localStorage.getItem('uc_gcm')) {
+    return 'hidden';
+  }
+
+  const { shadowRoot } = document.querySelector('#usercentrics-root');
+  const banner = shadowRoot.querySelector('#uc-center-container') || shadowRoot.querySelector('#uc-fading-wrapper');
+
+  if (banner && banner.offsetHeight > 0) {
+    return 'show';
+  }
+
+  return 'suppressed';
+}
+
+let hasSentData = false;
+export default function addCookieConsentTracking({ sampleRUM }) {
+  if (hasSentData) {
+    return;
+  }
+
+  sampleRUM('consent', { source: 'usercentrics', target: trackConsent() });
+  hasSentData = true;
+}