@afixt/test-utils 2.4.0 → 2.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@afixt/test-utils",
-    "version": "2.4.0",
+    "version": "2.5.0",
     "description": "Various utilities for accessibility testing",
     "main": "src/index.js",
     "scripts": {

package/src/constants.js

@@ -520,6 +520,52 @@ const VALID_ARIA_ROLES = new Set([
     'region',
     'search',
     'timer',
+    // WAI-ARIA Graphics Module roles
+    'graphics-document',
+    'graphics-object',
+    'graphics-symbol',
+    // DPub-ARIA roles
+    'doc-abstract',
+    'doc-acknowledgments',
+    'doc-afterword',
+    'doc-appendix',
+    'doc-backlink',
+    'doc-biblioentry',
+    'doc-bibliography',
+    'doc-biblioref',
+    'doc-chapter',
+    'doc-colophon',
+    'doc-conclusion',
+    'doc-cover',
+    'doc-credit',
+    'doc-credits',
+    'doc-dedication',
+    'doc-endnote',
+    'doc-endnotes',
+    'doc-epigraph',
+    'doc-epilogue',
+    'doc-errata',
+    'doc-example',
+    'doc-footnote',
+    'doc-foreword',
+    'doc-glossary',
+    'doc-glossref',
+    'doc-index',
+    'doc-introduction',
+    'doc-noteref',
+    'doc-notice',
+    'doc-pagebreak',
+    'doc-pagefooter',
+    'doc-pageheader',
+    'doc-pagelist',
+    'doc-part',
+    'doc-preface',
+    'doc-prologue',
+    'doc-pullquote',
+    'doc-qna',
+    'doc-subtitle',
+    'doc-tip',
+    'doc-toc',
 ]);
 
 /**

package/src/detectFocusTrap.js

@@ -0,0 +1,484 @@
+'use strict';
+
+const { getFocusableElements } = require('./getFocusableElements.js');
+const { getEventListeners } = require('./listEventListeners.js');
+
+/**
+ * Default result indicating no focus trap detected.
+ * @returns {{ isTrapped: boolean, focusableCount: number, indicators: string[], trapType: string }}
+ */
+function noTrap() {
+    return { isTrapped: false, focusableCount: 0, indicators: [], trapType: 'none', concerns: [] };
+}
+
+/**
+ * Detects whether a container element appears to implement a focus trap
+ * through static DOM analysis. Does not fire focus events or change page state.
+ * @param {Element} container - The container element to analyze
+ * @returns {{ isTrapped: boolean, focusableCount: number, indicators: string[], trapType: string, concerns: string[] }}
+ */
+function detectFocusTrap(container) {
+    if (!container || typeof container !== 'object' || !container.querySelectorAll) {
+        return noTrap();
+    }
+
+    const indicators = [];
+    let trapType = 'none';
+
+    const focusableCount = getFocusableElements(container).length;
+
+    // Check for modal dialog pattern
+    if (checkModalDialog(container)) {
+        indicators.push('modal-dialog');
+        trapType = 'modal';
+    }
+
+    // Check for inert siblings
+    if (trapType === 'none' && checkInertSiblings(container)) {
+        indicators.push('inert-siblings');
+        trapType = 'inert';
+    }
+
+    // Check for library markers
+    if (checkLibraryMarkers(container)) {
+        indicators.push('library-markers');
+        if (trapType === 'none') {
+            trapType = 'library';
+        }
+    }
+
+    // Check for keyboard event listeners
+    if (checkKeyboardListeners(container)) {
+        indicators.push('keyboard-listeners');
+        if (trapType === 'none') {
+            trapType = 'custom';
+        }
+    }
+
+    // Check for focus event listeners
+    if (checkFocusListeners(container)) {
+        indicators.push('focus-listeners');
+        if (trapType === 'none') {
+            trapType = 'custom';
+        }
+    }
+
+    // Check for aria-hidden siblings (screen reader trap pattern)
+    const hasAriaHiddenSiblings = checkAriaHiddenSiblings(container);
+    if (hasAriaHiddenSiblings) {
+        indicators.push('aria-hidden-siblings');
+        if (trapType === 'none') {
+            trapType = 'custom';
+        }
+    }
+
+    // Check for tabindex manipulation on elements outside the container
+    const hasTabindexManip = checkTabindexManipulation(container);
+    if (hasTabindexManip) {
+        indicators.push('tabindex-manipulation');
+        if (trapType === 'none') {
+            trapType = 'custom';
+        }
+    }
+
+    const isTrapped = indicators.length > 0 && focusableCount > 0;
+
+    // Assess concerns — problematic focus trap patterns
+    const concerns = [];
+    if (isTrapped) {
+        const isModal = trapType === 'modal' || trapType === 'inert';
+
+        // Non-modal trap: focus is constrained without modal dialog semantics
+        if (!isModal) {
+            concerns.push('non-modal-trap');
+        }
+
+        // Single focusable element: user has nowhere to navigate within the trap
+        if (focusableCount === 1) {
+            concerns.push('single-focusable');
+        }
+
+        // No escape mechanism: no close/cancel button and no modal semantics
+        if (!isModal && !hasEscapeMechanism(container)) {
+            concerns.push('no-escape-mechanism');
+        }
+
+        // aria-hidden siblings without modal: screen reader trap
+        if (hasAriaHiddenSiblings && !checkModalDialog(container)) {
+            concerns.push('aria-hidden-no-modal');
+        }
+
+        // tabindex manipulation without modal: manual focus removal on outside elements
+        if (hasTabindexManip && !isModal) {
+            concerns.push('tabindex-manipulation');
+        }
+
+        // Inappropriate role for a focus trap (menus, tooltips, nav, listboxes, etc.)
+        if (hasInappropriateTrapRole(container)) {
+            concerns.push('inappropriate-trap-role');
+        }
+
+        // Nested focus trap: container is inside another focus trap
+        if (isNestedTrap(container)) {
+            concerns.push('nested-trap');
+        }
+
+        // Contenteditable trap: keyboard trap on an editable region
+        if (hasContenteditableTrap(container)) {
+            concerns.push('contenteditable-trap');
+        }
+
+        // Full page trap: focus trap covers the whole page (body or sole child of body)
+        // Modal dialogs are exempt — it's normal for a modal to be the only non-inert element
+        if (!isModal && isFullPageTrap(container)) {
+            concerns.push('full-page-trap');
+        }
+    }
+
+    return { isTrapped, focusableCount, indicators, trapType, concerns };
+}
+
+/**
+ * Check if container or ancestor is a modal dialog
+ * @param {Element} container
+ * @returns {boolean}
+ */
+function checkModalDialog(container) {
+    let el = container;
+    while (el && el !== document.documentElement) {
+        // Native <dialog open>
+        if (el.tagName === 'DIALOG' && el.hasAttribute('open')) {
+            return true;
+        }
+        // ARIA modal dialog
+        const role = el.getAttribute('role');
+        if (
+            (role === 'dialog' || role === 'alertdialog') &&
+            el.getAttribute('aria-modal') === 'true'
+        ) {
+            return true;
+        }
+        el = el.parentElement;
+    }
+    return false;
+}
+
+/**
+ * Check if all sibling elements of the container have the inert attribute
+ * @param {Element} container
+ * @returns {boolean}
+ */
+function checkInertSiblings(container) {
+    const parent = container.parentElement;
+    if (!parent) {
+        return false;
+    }
+    const siblings = Array.from(parent.children).filter(child => child !== container);
+    if (siblings.length === 0) {
+        return false;
+    }
+    return siblings.every(sibling => sibling.hasAttribute('inert'));
+}
+
+/**
+ * Check for common focus trap library markers on container or ancestors
+ * @param {Element} container
+ * @returns {boolean}
+ */
+function checkLibraryMarkers(container) {
+    const libraryAttrs = [
+        'data-focus-trap',
+        'data-focus-lock',
+        'data-focus-guard',
+        'data-focus-lock-disabled',
+        'data-focus-on-hidden',
+        'data-no-focus-lock',
+    ];
+
+    // Check container and ancestors
+    let el = container;
+    while (el && el !== document.documentElement) {
+        for (const attr of libraryAttrs) {
+            if (el.hasAttribute(attr)) {
+                return true;
+            }
+        }
+        el = el.parentElement;
+    }
+
+    // Check for sentinel/guard elements: empty <div tabindex="0"> at container boundaries
+    const children = container.children;
+    if (children.length >= 2) {
+        const first = children[0];
+        const last = children[children.length - 1];
+        if (isSentinelElement(first) || isSentinelElement(last)) {
+            return true;
+        }
+    }
+
+    return false;
+}
+
+/**
+ * Check if element looks like a focus trap sentinel (guard) element
+ * @param {Element} el
+ * @returns {boolean}
+ */
+function isSentinelElement(el) {
+    if (!el) {
+        return false;
+    }
+    return (
+        el.tagName === 'DIV' &&
+        el.getAttribute('tabindex') === '0' &&
+        el.textContent.trim() === '' &&
+        el.children.length === 0
+    );
+}
+
+/**
+ * Check for keyboard event listeners on container or ancestors
+ * @param {Element} container
+ * @returns {boolean}
+ */
+function checkKeyboardListeners(container) {
+    const keyboardEvents = ['keydown', 'keypress'];
+    return hasEventOnChain(container, keyboardEvents);
+}
+
+/**
+ * Check for focus-related event listeners on container or ancestors
+ * @param {Element} container
+ * @returns {boolean}
+ */
+function checkFocusListeners(container) {
+    const focusEvents = ['focusin', 'focusout', 'focus', 'blur'];
+    return hasEventOnChain(container, focusEvents);
+}
+
+/**
+ * Check if any element in the ancestor chain has one of the given event types
+ * @param {Element} container
+ * @param {string[]} eventTypes
+ * @returns {boolean}
+ */
+function hasEventOnChain(container, eventTypes) {
+    let el = container;
+    while (el && el !== document.documentElement) {
+        // Check via getEventListeners (tracks addEventListener + property handlers)
+        const listeners = getEventListeners(el);
+        for (const eventType of eventTypes) {
+            if (listeners[eventType] && listeners[eventType].length > 0) {
+                return true;
+            }
+        }
+        // Check inline attribute handlers
+        for (const eventType of eventTypes) {
+            if (el.hasAttribute('on' + eventType)) {
+                return true;
+            }
+        }
+        el = el.parentElement;
+    }
+    return false;
+}
+
+/**
+ * Selectors for elements that are naturally focusable (before tabindex override)
+ * @type {string}
+ */
+const NATURALLY_FOCUSABLE = 'a[href], button, input:not([type="hidden"]), select, textarea';
+
+/**
+ * Check if siblings of the container have tabindex="-1" on naturally focusable elements,
+ * indicating manual focus removal to create a trap
+ * @param {Element} container
+ * @returns {boolean}
+ */
+function checkTabindexManipulation(container) {
+    const parent = container.parentElement;
+    if (!parent) {
+        return false;
+    }
+    const siblings = Array.from(parent.children).filter(child => child !== container);
+    if (siblings.length === 0) {
+        return false;
+    }
+    // Check if any sibling has naturally focusable descendants with tabindex="-1"
+    for (const sibling of siblings) {
+        const focusable = sibling.querySelectorAll(NATURALLY_FOCUSABLE);
+        if (
+            focusable.length > 0 &&
+            Array.from(focusable).every(el => el.getAttribute('tabindex') === '-1')
+        ) {
+            return true;
+        }
+    }
+    return false;
+}
+
+/**
+ * Check if all sibling elements of the container have aria-hidden="true"
+ * @param {Element} container
+ * @returns {boolean}
+ */
+function checkAriaHiddenSiblings(container) {
+    const parent = container.parentElement;
+    if (!parent) {
+        return false;
+    }
+    const siblings = Array.from(parent.children).filter(child => child !== container);
+    if (siblings.length === 0) {
+        return false;
+    }
+    return siblings.every(sibling => sibling.getAttribute('aria-hidden') === 'true');
+}
+
+/**
+ * Check if container has a visible escape mechanism (close/cancel/dismiss button)
+ * @param {Element} container
+ * @returns {boolean}
+ */
+function hasEscapeMechanism(container) {
+    const escapePatterns = /\b(close|cancel|dismiss|exit|back|done|ok|go\s*back)\b/i;
+    const buttons = container.querySelectorAll(
+        'button, [role="button"], input[type="button"], input[type="submit"]'
+    );
+    for (const btn of buttons) {
+        const text = btn.textContent.trim();
+        const ariaLabel = btn.getAttribute('aria-label') || '';
+        const title = btn.getAttribute('title') || '';
+        if (
+            escapePatterns.test(text) ||
+            escapePatterns.test(ariaLabel) ||
+            escapePatterns.test(title)
+        ) {
+            return true;
+        }
+    }
+    return false;
+}
+
+/**
+ * Roles and element types where a focus trap is inappropriate
+ * @type {Set<string>}
+ */
+const INAPPROPRIATE_TRAP_ROLES = new Set([
+    'menu',
+    'menubar',
+    'tooltip',
+    'listbox',
+    'tree',
+    'grid',
+    'tablist',
+    'tabpanel',
+    'toolbar',
+    'navigation',
+    'complementary',
+    'banner',
+    'contentinfo',
+    'search',
+    'status',
+    'log',
+    'marquee',
+    'timer',
+    'feed',
+]);
+
+/**
+ * HTML elements that map to landmark/widget roles where trapping is inappropriate
+ * @type {Set<string>}
+ */
+const INAPPROPRIATE_TRAP_ELEMENTS = new Set([
+    'NAV',
+    'ASIDE',
+    'HEADER',
+    'FOOTER',
+    'FORM',
+    'SECTION',
+]);
+
+/**
+ * Check if the container has an ARIA role or element type that is inappropriate for focus trapping
+ * @param {Element} container
+ * @returns {boolean}
+ */
+function hasInappropriateTrapRole(container) {
+    const role = container.getAttribute('role');
+    if (role && INAPPROPRIATE_TRAP_ROLES.has(role)) {
+        return true;
+    }
+    if (INAPPROPRIATE_TRAP_ELEMENTS.has(container.tagName)) {
+        return true;
+    }
+    return false;
+}
+
+/**
+ * Check if the container is nested inside another focus trap
+ * @param {Element} container
+ * @returns {boolean}
+ */
+function isNestedTrap(container) {
+    const trapAttrs = [
+        'data-focus-trap',
+        'data-focus-lock',
+        'data-focus-guard',
+        'data-focus-lock-disabled',
+    ];
+    let el = container.parentElement;
+    while (el && el !== document.documentElement) {
+        // Check for modal dialog ancestor
+        if (el.tagName === 'DIALOG' && el.hasAttribute('open')) {
+            return true;
+        }
+        const role = el.getAttribute('role');
+        if (
+            (role === 'dialog' || role === 'alertdialog') &&
+            el.getAttribute('aria-modal') === 'true'
+        ) {
+            return true;
+        }
+        // Check for library trap markers on ancestors (but not the container itself)
+        for (const attr of trapAttrs) {
+            if (el.hasAttribute(attr)) {
+                return true;
+            }
+        }
+        el = el.parentElement;
+    }
+    return false;
+}
+
+/**
+ * Check if the container or its descendants include a contenteditable element
+ * @param {Element} container
+ * @returns {boolean}
+ */
+function hasContenteditableTrap(container) {
+    if (container.getAttribute('contenteditable') === 'true') {
+        return true;
+    }
+    return container.querySelector('[contenteditable="true"]') !== null;
+}
+
+/**
+ * Check if the trap covers the entire page (body or sole child of body)
+ * @param {Element} container
+ * @returns {boolean}
+ */
+function isFullPageTrap(container) {
+    if (container === document.body) {
+        return true;
+    }
+    // Sole child of body (no meaningful siblings)
+    if (container.parentElement === document.body) {
+        const siblings = Array.from(document.body.children).filter(child => child !== container);
+        if (siblings.length === 0) {
+            return true;
+        }
+    }
+    return false;
+}
+
+module.exports = { detectFocusTrap };

package/src/getAccessibleText.js

@@ -73,12 +73,28 @@ function collectSubtreeText(node, visibleOnly) {
 
             // In visibleOnly mode, skip non-rendered content
             if (visibleOnly) {
-                if (tag === 'style' || tag === 'script') {
+                if (tag === 'style' || tag === 'script' || tag === 'noscript') {
                     continue;
                 }
                 if (child.getAttribute('aria-hidden') === 'true') {
                     continue;
                 }
+                if (child.hasAttribute('hidden')) {
+                    continue;
+                }
+                // Stop at nested widget containers — their content is not
+                // part of the parent element's visible label
+                const childRole = child.getAttribute('role');
+                if (
+                    childRole === 'menu' ||
+                    childRole === 'menubar' ||
+                    childRole === 'listbox' ||
+                    childRole === 'tree' ||
+                    childRole === 'grid' ||
+                    childRole === 'tablist'
+                ) {
+                    continue;
+                }
             }
 
             if (!visibleOnly) {
@@ -103,6 +119,15 @@ function collectSubtreeText(node, visibleOnly) {
                     }
                     continue;
                 }
+
+                // Elements with role="img" contribute their aria-label
+                if (child.getAttribute('role') === 'img' && child.hasAttribute('aria-label')) {
+                    const ariaLabel = child.getAttribute('aria-label').trim();
+                    if (ariaLabel) {
+                        parts.push(ariaLabel);
+                    }
+                    continue;
+                }
             }
 
             // Recurse into other element children

package/src/index.js

@@ -45,6 +45,7 @@ const hasAttribute = require('./hasAttribute.js');
 // Focus management
 const getFocusableElements = require('./getFocusableElements.js');
 const isFocusable = require('./isFocusable.js');
+const detectFocusTrap = require('./detectFocusTrap.js');
 
 // Role computation
 const getComputedRole = require('./getComputedRole.js');
@@ -114,6 +115,7 @@ module.exports = {
     ...hasAttribute,
     ...getFocusableElements,
     ...isFocusable,
+    ...detectFocusTrap,
     ...getComputedRole,
     getImageText,
     ...testContrast,