@afixt/test-utils 2.3.0 → 2.5.0

package/.claude/settings.local.json

@@ -18,7 +18,8 @@
       "Bash(node:*)",
       "Bash(npx vitest run:*)",
       "Bash(1)",
-      "Bash(npm run test:playwright:css:*)"
+      "Bash(npm run test:playwright:css:*)",
+      "Bash(npm run:*)"
     ]
   },
   "enableAllProjectMcpServers": false

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@afixt/test-utils",
-    "version": "2.3.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/cssUtils.js

@@ -3,6 +3,53 @@
  * @module cssUtils
  */
 
+const { hasCSSGeneratedContent } = require('./hasCSSGeneratedContent.js');
+
+const ICON_FONT_CLASS_PREFIXES = ['icon-', 'i-'];
+const ICON_FONT_CLASSES = [
+    'fa',
+    'fas',
+    'far',
+    'fal',
+    'fad',
+    'fab',
+    'glyphicon',
+    'material-icons',
+    'material-symbols-outlined',
+    'material-symbols-rounded',
+    'dashicons',
+    'bi',
+    'octicon',
+    'feather',
+    'fi',
+    'typcn',
+    'wi',
+    'zmdi',
+    'icofont',
+];
+
+/**
+ * Check if a single class name matches known icon font patterns.
+ * @param {string} cls - The class name to check
+ * @returns {boolean} True if the class matches an icon font pattern
+ */
+function matchesIconFontPattern(cls) {
+    if (ICON_FONT_CLASSES.includes(cls)) {
+        return true;
+    }
+    for (const prefix of ICON_FONT_CLASS_PREFIXES) {
+        if (cls.startsWith(prefix)) {
+            return true;
+        }
+    }
+    for (const iconClass of ICON_FONT_CLASSES) {
+        if (cls.startsWith(iconClass + '-')) {
+            return true;
+        }
+    }
+    return false;
+}
+
 const cssUtils = {
     /**
      * Check if an element's background is transparent/none.
@@ -29,12 +76,81 @@ const cssUtils = {
         return style.borderStyle === 'none' || parseFloat(style.borderWidth) === 0;
     },
 
+    /**
+     * Check if the element or any descendant has a class matching common icon font patterns.
+     * @param {HTMLElement} element - The element to check
+     * @returns {boolean} True if an icon font class is found
+     */
+    hasIconFontClass(element) {
+        if (!element) {
+            return false;
+        }
+
+        const elements = [element, ...element.querySelectorAll('*')];
+        for (const el of elements) {
+            if (el.classList) {
+                for (const cls of el.classList) {
+                    if (matchesIconFontPattern(cls)) {
+                        return true;
+                    }
+                }
+            }
+        }
+        return false;
+    },
+
+    /**
+     * Check if the element has any visual indicator beyond text styling,
+     * such as CSS-generated content, icon font classes, background images on children,
+     * or inline img/svg elements.
+     * @param {HTMLElement} element - The element to check
+     * @returns {boolean} True if the element has a visual indicator
+     */
+    hasVisualIndicator(element) {
+        if (!element) {
+            return false;
+        }
+
+        // Check for CSS-generated content on the element itself
+        if (hasCSSGeneratedContent(element)) {
+            return true;
+        }
+
+        // Check for icon font classes on element or descendants
+        if (cssUtils.hasIconFontClass(element)) {
+            return true;
+        }
+
+        // Check descendants for background-image, <img>, or <svg>
+        const descendants = element.querySelectorAll('*');
+        for (const child of descendants) {
+            const tagName = child.tagName ? child.tagName.toLowerCase() : '';
+            if (tagName === 'img' || tagName === 'svg') {
+                return true;
+            }
+            try {
+                const childStyle = window.getComputedStyle(child);
+                if (childStyle.backgroundImage && childStyle.backgroundImage !== 'none') {
+                    return true;
+                }
+            } catch {
+                // skip if getComputedStyle fails
+            }
+        }
+
+        return false;
+    },
+
     /**
      * Check if an element looks like regular text (no underline, background, or border).
      * @param {HTMLElement} element - The element to check
      * @returns {boolean} True if element looks like regular text
      */
     looksLikeText(element) {
+        if (cssUtils.hasVisualIndicator(element)) {
+            return false;
+        }
+
         const style = window.getComputedStyle(element);
 
         const noUnderline = !style.textDecoration.toLowerCase().includes('underline');

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 };