@afixt/test-utils 1.2.0 → 1.2.2

package/eslint.config.mjs

@@ -53,7 +53,7 @@ export default [
     },
     {
         // ESM file overrides
-        files: ['**/*.mjs'],
+        files: ['**/*.mjs', 'vitest.config.js'],
         languageOptions: {
             sourceType: 'module',
         },

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@afixt/test-utils",
-    "version": "1.2.0",
+    "version": "1.2.2",
     "description": "Various utilities for accessibility testing",
     "main": "src/index.js",
     "scripts": {
@@ -53,6 +53,7 @@
     "devDependencies": {
         "@eslint/js": "^9.39.2",
         "@playwright/test": "^1.57.0",
+        "@vitest/coverage-istanbul": "^3.2.4",
         "@vitest/coverage-v8": "^3.0.9",
         "clean-jsdoc-theme": "^4.3.0",
         "eslint": "^9.39.2",

package/src/constants.js

@@ -0,0 +1,231 @@
+/**
+ * @file Shared constants for accessibility testing
+ * @module constants
+ */
+
+/**
+ * CSS selector string for interactive elements.
+ * Matches native HTML interactive elements and ARIA widget roles.
+ * @type {string}
+ */
+const INTERACTIVE_SELECTOR = [
+    'a[href]',
+    'button',
+    'input:not([type="hidden"])',
+    'select',
+    'textarea',
+    '[tabindex]:not([tabindex="-1"])',
+    '[role="button"]',
+    '[role="link"]',
+    '[role="checkbox"]',
+    '[role="menuitem"]',
+    '[role="menuitemcheckbox"]',
+    '[role="menuitemradio"]',
+    '[role="tab"]',
+    '[role="switch"]',
+    '[role="option"]',
+    '[role="radio"]',
+    '[role="slider"]',
+    '[role="spinbutton"]',
+    '[role="textbox"]',
+    '[role="combobox"]',
+    '[role="listbox"]',
+    '[role="searchbox"]',
+    '[role="gridcell"]',
+    '[role="treeitem"]',
+].join(', ');
+
+/**
+ * CSS selector string for naturally focusable elements.
+ * These elements are focusable by default (unless disabled).
+ * @type {string}
+ */
+const FOCUSABLE_SELECTOR = [
+    'a[href]',
+    'button:not([disabled])',
+    'input:not([disabled]):not([type="hidden"])',
+    'select:not([disabled])',
+    'textarea:not([disabled])',
+    '[tabindex]',
+    'audio[controls]',
+    'video[controls]',
+    'embed',
+    'iframe',
+    'object',
+    '[contenteditable]:not([contenteditable="false"])',
+].join(', ');
+
+/**
+ * Labellable elements per HTML spec that can be associated with a <label>.
+ * @type {string[]}
+ */
+const LABELLABLE_ELEMENTS = [
+    'input',
+    'select',
+    'textarea',
+    'button',
+    'meter',
+    'output',
+    'progress',
+];
+
+/**
+ * Elements that validly support the alt attribute per HTML spec.
+ * @type {string[]}
+ */
+const VALID_ALT_ELEMENTS = ['IMG', 'AREA', 'INPUT', 'APPLET'];
+
+/**
+ * ISO 639-1 codes for right-to-left languages.
+ * @type {string[]}
+ */
+const RTL_LANGUAGES = [
+    'ar', // Arabic
+    'he', // Hebrew
+    'fa', // Persian/Farsi
+    'ur', // Urdu
+    'sd', // Sindhi
+    'yi', // Yiddish
+    'ps', // Pashto
+    'ku', // Kurdish (some dialects)
+    'ug', // Uyghur
+    'dv', // Divehi/Maldivian
+];
+
+/**
+ * Generic, non-descriptive, or meaningless frame/iframe titles.
+ * @type {string[]}
+ */
+const GENERIC_TITLES = ['iframe', 'frame', 'untitled', 'title', 'content', 'main', 'page'];
+
+/**
+ * Generic or useless table summaries commonly found in the wild.
+ * Merged from multiple detection contexts.
+ * @type {string[]}
+ */
+const GENERIC_SUMMARIES = [
+    'table',
+    'data',
+    'data table',
+    'information',
+    'content',
+    'main content',
+    'layout',
+    'layout table',
+    'for layout',
+    'table for layout purposes',
+    'structural table',
+    'this table is used for page layout',
+    'header',
+    'footer',
+    'navigation',
+    'nav',
+    'body',
+    'combobox',
+    'links design table',
+    'title and navigation',
+    'main heading',
+    'spacer',
+    'spacer table',
+    'menu',
+    'n/a',
+    'na',
+    'none',
+    'null',
+    'empty',
+    'blank',
+    'undefined',
+    'table summary',
+    'summary',
+];
+
+/**
+ * Phrases indicating structure-focused rather than content-focused table summary.
+ * @type {string[]}
+ */
+const STRUCTURE_PHRASES = [
+    'rows and columns',
+    'grid format',
+    'for display purposes',
+    'arranged in a grid',
+    'the following table shows',
+];
+
+/**
+ * Phrases indicating vague/rambling table summary content.
+ * @type {string[]}
+ */
+const VAGUE_PHRASES = [
+    'might find interesting',
+    'depending on their needs',
+    'users might find',
+    'may be useful',
+];
+
+/**
+ * Valid ARIA parent-child interactive role combinations per the WAI-ARIA spec.
+ * These composite widget patterns require interactive children by design.
+ * Key = parent role, Value = array of valid child roles.
+ * @type {Object.<string, string[]>}
+ */
+const VALID_ARIA_NESTING = {
+    listbox: ['option'],
+    menu: ['menuitem', 'menuitemcheckbox', 'menuitemradio', 'menu'],
+    menubar: ['menuitem', 'menuitemcheckbox', 'menuitemradio', 'menu'],
+    menuitem: ['menu', 'menubar'],
+    tablist: ['tab'],
+    tree: ['treeitem', 'group'],
+    treeitem: ['group', 'tree'],
+    grid: ['gridcell', 'row', 'rowgroup'],
+    row: ['gridcell', 'columnheader', 'rowheader', 'cell'],
+    rowgroup: ['row'],
+    radiogroup: ['radio'],
+    combobox: ['listbox', 'textbox', 'tree', 'grid', 'dialog'],
+};
+
+/**
+ * Thresholds for determining table complexity.
+ * @type {Object}
+ */
+const COMPLEXITY_THRESHOLDS = {
+    MAX_COLUMNS: 10,
+    MAX_HEADER_COLSPAN: 4,
+    MAX_ROWSPAN: 3,
+    MIN_HEADER_ROWS_FOR_COMPLEX: 3,
+};
+
+/**
+ * WCAG 2.5.5 minimum target size in CSS pixels.
+ * @type {number}
+ */
+const MIN_TARGET_SIZE = 44;
+
+/**
+ * Phrases that indicate a warning about new window/tab behavior.
+ * @type {string[]}
+ */
+const NEW_WINDOW_WARNINGS = [
+    'new window',
+    'new tab',
+    'opens in new',
+    'opens in a new',
+    'opens new',
+    'external link',
+    'external site',
+];
+
+module.exports = {
+    INTERACTIVE_SELECTOR,
+    FOCUSABLE_SELECTOR,
+    LABELLABLE_ELEMENTS,
+    VALID_ALT_ELEMENTS,
+    RTL_LANGUAGES,
+    GENERIC_TITLES,
+    GENERIC_SUMMARIES,
+    STRUCTURE_PHRASES,
+    VAGUE_PHRASES,
+    VALID_ARIA_NESTING,
+    COMPLEXITY_THRESHOLDS,
+    MIN_TARGET_SIZE,
+    NEW_WINDOW_WARNINGS,
+};

package/src/cssUtils.js

@@ -0,0 +1,77 @@
+/**
+ * @file CSS styling inspection utilities
+ * @module cssUtils
+ */
+
+const cssUtils = {
+    /**
+     * Check if an element's background is transparent/none.
+     * @param {CSSStyleDeclaration} style - The computed style
+     * @returns {boolean} True if background is transparent
+     */
+    hasTransparentBackground(style) {
+        const bg = style.backgroundColor;
+        const bgImage = style.backgroundImage;
+
+        if (bgImage && bgImage !== 'none') {
+            return false;
+        }
+
+        return bg === 'rgba(0, 0, 0, 0)' || bg === 'transparent' || bg === '';
+    },
+
+    /**
+     * Check if an element has no visible border.
+     * @param {CSSStyleDeclaration} style - The computed style
+     * @returns {boolean} True if no border
+     */
+    hasNoBorder(style) {
+        return style.borderStyle === 'none' || parseFloat(style.borderWidth) === 0;
+    },
+
+    /**
+     * 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) {
+        const style = window.getComputedStyle(element);
+
+        const noUnderline = !style.textDecoration.toLowerCase().includes('underline');
+        const noBackground = cssUtils.hasTransparentBackground(style);
+        const noBorder = cssUtils.hasNoBorder(style);
+
+        return noUnderline && noBackground && noBorder;
+    },
+
+    /**
+     * Check if an element has link-like styling (underline).
+     * @param {HTMLElement} element - The element to check
+     * @returns {boolean} True if element has link-like styling
+     */
+    hasLinkStyling(element) {
+        const style = window.getComputedStyle(element);
+        return style.textDecoration.toLowerCase().includes('underline');
+    },
+
+    /**
+     * Check if an element has button-like styling (background/border with padding).
+     * @param {HTMLElement} element - The element to check
+     * @returns {boolean} True if element has button-like styling
+     */
+    hasButtonStyling(element) {
+        const style = window.getComputedStyle(element);
+
+        const hasBackground = !cssUtils.hasTransparentBackground(style);
+        const hasBorder = !cssUtils.hasNoBorder(style);
+        const hasPadding =
+            parseFloat(style.paddingTop) > 2 ||
+            parseFloat(style.paddingBottom) > 2 ||
+            parseFloat(style.paddingLeft) > 4 ||
+            parseFloat(style.paddingRight) > 4;
+
+        return (hasBackground || hasBorder) && hasPadding;
+    },
+};
+
+module.exports = cssUtils;

package/src/domUtils.js

@@ -18,10 +18,8 @@ const domUtils = {
      * @returns {Array} - An array of elements that have at least one attribute starting with the specified prefix.
      */
     attrBegins(elements, prefix) {
-        return Array.from(elements).filter((element) => {
-            return Array.from(element.attributes).some((attr) =>
-                attr.name.startsWith(prefix)
-            );
+        return Array.from(elements).filter(element => {
+            return Array.from(element.attributes).some(attr => attr.name.startsWith(prefix));
         });
     },
 
@@ -43,7 +41,9 @@ const domUtils = {
      * @returns {Object} An object containing the element's attributes as key-value pairs.
      */
     getAttributes(element) {
-        if (!element) return {};
+        if (!element) {
+            return {};
+        }
         return [...element.attributes].reduce((attrs, attr) => {
             attrs[attr.name] = attr.value;
             return attrs;
@@ -80,7 +80,7 @@ const domUtils = {
      * @returns {number} The length of the document's HTML content without whitespace.
      */
     getDocumentSize() {
-        return document.documentElement.outerHTML.replace(/\s+/g, "").length;
+        return document.documentElement.outerHTML.replace(/\s+/g, '').length;
     },
 
     /**
@@ -89,17 +89,17 @@ const domUtils = {
      * @returns {Element[]} An array of elements that have duplicate IDs.
      */
     getElementsWithDuplicateIds() {
-        const nodes = document.querySelectorAll("[id]");
+        const nodes = document.querySelectorAll('[id]');
         const ids = {};
         const duplicates = [];
-        nodes.forEach((node) => {
+        nodes.forEach(node => {
             const id = node.id.trim();
             ids[id] = (ids[id] || 0) + 1;
             if (ids[id] > 1 && !duplicates.includes(id)) {
                 duplicates.push(id);
             }
         });
-        return duplicates.map((id) => document.querySelector(`#${id}`));
+        return duplicates.map(id => document.querySelector(`#${id}`));
     },
 
     /**
@@ -119,13 +119,17 @@ const domUtils = {
      * @returns {string} The XPath string representing the element's location in the DOM.
      */
     getXPath(element) {
-        if (!element) return "";
-        let path = "";
+        if (!element) {
+            return '';
+        }
+        let path = '';
         while (element && element.nodeType === Node.ELEMENT_NODE) {
             let index = 1;
             let sibling = element.previousElementSibling;
             while (sibling) {
-                if (sibling.nodeName === element.nodeName) index++;
+                if (sibling.nodeName === element.nodeName) {
+                    index++;
+                }
                 sibling = sibling.previousElementSibling;
             }
             path = `/${element.nodeName.toLowerCase()}[${index}]` + path;
@@ -134,6 +138,258 @@ const domUtils = {
         return path;
     },
 
+    /**
+     * Checks if a given ID is referenced by other elements in the document.
+     * References include label[for], aria-labelledby, aria-describedby,
+     * aria-controls, aria-owns, aria-activedescendant, aria-flowto,
+     * aria-errormessage, href="#id", headers, and list attributes.
+     *
+     * @param {string} id - The ID value to check for references.
+     * @returns {boolean} True if the ID is referenced by another element.
+     */
+    isIdReferenced(id) {
+        if (!id) {
+            return false;
+        }
+
+        // CSS-escape the ID for use in attribute selectors
+        const escaped = CSS.escape(id);
+
+        // Direct attribute references
+        if (document.querySelector('[for="' + escaped + '"]')) {
+            return true;
+        }
+
+        // ARIA token-list attributes that reference IDs
+        const ariaTokenAttrs = [
+            'aria-labelledby',
+            'aria-describedby',
+            'aria-controls',
+            'aria-owns',
+            'aria-flowto',
+        ];
+        for (const attr of ariaTokenAttrs) {
+            const elements = document.querySelectorAll('[' + attr + ']');
+            for (const el of elements) {
+                const ids = el.getAttribute(attr).trim().split(/\s+/);
+                if (ids.includes(id)) {
+                    return true;
+                }
+            }
+        }
+
+        // Single-ID ARIA references
+        const ariaSingleAttrs = ['aria-activedescendant', 'aria-errormessage'];
+        for (const attr of ariaSingleAttrs) {
+            if (document.querySelector('[' + attr + '="' + escaped + '"]')) {
+                return true;
+            }
+        }
+
+        // Fragment references in href
+        if (document.querySelector('a[href="#' + escaped + '"]')) {
+            return true;
+        }
+
+        // Table headers attribute (space-separated list of IDs)
+        const headerElements = document.querySelectorAll('[headers]');
+        for (const el of headerElements) {
+            const ids = el.getAttribute('headers').trim().split(/\s+/);
+            if (ids.includes(id)) {
+                return true;
+            }
+        }
+
+        // list attribute on input elements
+        if (document.querySelector('input[list="' + escaped + '"]')) {
+            return true;
+        }
+
+        return false;
+    },
+
+    /**
+     * Check if an element is hidden from assistive technology.
+     * @param {HTMLElement} element - The element to check
+     * @returns {boolean} True if element or ancestor has aria-hidden="true"
+     */
+    isHiddenFromAT(element) {
+        if (!element) {
+            return false;
+        }
+        return (
+            element.getAttribute('aria-hidden') === 'true' ||
+            (element.closest && !!element.closest('[aria-hidden="true"]'))
+        );
+    },
+
+    /**
+     * Check if an element is effectively interactive (not disabled, not hidden from AT,
+     * not role=presentation/none).
+     * @param {HTMLElement} element - The element to check
+     * @returns {boolean} True if the element is interactive
+     */
+    isEffectivelyInteractive(element) {
+        if (element.disabled || element.getAttribute('aria-disabled') === 'true') {
+            return false;
+        }
+        if (element.getAttribute('aria-hidden') === 'true') {
+            return false;
+        }
+        const role = element.getAttribute('role');
+        if (role === 'presentation' || role === 'none') {
+            return false;
+        }
+        return true;
+    },
+
+    /**
+     * Check if a parent-child pair constitutes a valid ARIA composite widget nesting.
+     * @param {HTMLElement} parent - The parent interactive element
+     * @param {HTMLElement} child - The nested interactive element
+     * @returns {boolean} True if this is a valid ARIA nesting pattern
+     */
+    isValidAriaNesting(parent, child) {
+        const VALID_ARIA_NESTING = {
+            listbox: ['option'],
+            menu: ['menuitem', 'menuitemcheckbox', 'menuitemradio', 'menu'],
+            menubar: ['menuitem', 'menuitemcheckbox', 'menuitemradio', 'menu'],
+            menuitem: ['menu', 'menubar'],
+            tablist: ['tab'],
+            tree: ['treeitem', 'group'],
+            treeitem: ['group', 'tree'],
+            grid: ['gridcell', 'row', 'rowgroup'],
+            row: ['gridcell', 'columnheader', 'rowheader', 'cell'],
+            rowgroup: ['row'],
+            radiogroup: ['radio'],
+            combobox: ['listbox', 'textbox', 'tree', 'grid', 'dialog'],
+        };
+
+        const parentRole = (parent.getAttribute('role') || '').toLowerCase();
+        const childRole = (child.getAttribute('role') || '').toLowerCase();
+
+        if (parentRole && VALID_ARIA_NESTING[parentRole]) {
+            if (VALID_ARIA_NESTING[parentRole].includes(childRole)) {
+                return true;
+            }
+        }
+
+        if (parent.tagName === 'LABEL' && child.closest('label') === parent) {
+            return true;
+        }
+
+        return false;
+    },
+
+    /**
+     * Check if element has event handlers that suggest interactivity.
+     * @param {HTMLElement} element - The element to check
+     * @returns {boolean} True if element has interactive handlers
+     */
+    hasInteractiveHandler(element) {
+        return (
+            element.hasAttribute('onclick') ||
+            element.hasAttribute('onmousedown') ||
+            element.hasAttribute('onmouseup') ||
+            element.hasAttribute('ontouchstart') ||
+            element.hasAttribute('onkeydown') ||
+            element.hasAttribute('onkeyup')
+        );
+    },
+
+    /**
+     * Check if an element is within a navigation context (nav, menu, menubar).
+     * @param {HTMLElement} element - The element to check
+     * @returns {boolean} True if element is within a navigation context
+     */
+    isWithinNavContext(element) {
+        let ancestor = element.parentElement;
+        while (ancestor) {
+            const tag = ancestor.tagName;
+            const role = (ancestor.getAttribute('role') || '').toLowerCase();
+            if (tag === 'NAV' || role === 'navigation' || role === 'menu' || role === 'menubar') {
+                return true;
+            }
+            ancestor = ancestor.parentElement;
+        }
+        return false;
+    },
+
+    /**
+     * Check if an element is a landmark element.
+     * @param {HTMLElement} element - The element to check
+     * @returns {boolean} True if element is a landmark
+     */
+    isLandmark(element) {
+        const landmarkTags = ['NAV', 'MAIN', 'HEADER', 'FOOTER', 'ASIDE', 'SECTION'];
+        const landmarkRoles = [
+            'navigation',
+            'main',
+            'banner',
+            'contentinfo',
+            'complementary',
+            'region',
+            'search',
+            'form',
+        ];
+        if (landmarkTags.includes(element.tagName)) {
+            return true;
+        }
+        const role = (element.getAttribute('role') || '').toLowerCase();
+        return landmarkRoles.includes(role);
+    },
+
+    /**
+     * Get the nearest semantic container for an element.
+     * @param {HTMLElement} el - The element
+     * @returns {HTMLElement|null} The nearest semantic container
+     */
+    getSemanticContainer(el) {
+        const containerTags = ['ARTICLE', 'SECTION', 'LI', 'TD', 'TH', 'BLOCKQUOTE', 'FIGURE'];
+        let ancestor = el.parentElement;
+        while (ancestor && ancestor !== document.body) {
+            if (containerTags.includes(ancestor.tagName) || ancestor.hasAttribute('role')) {
+                return ancestor;
+            }
+            ancestor = ancestor.parentElement;
+        }
+        return null;
+    },
+
+    /**
+     * Gets the heading level from an element.
+     * Supports native heading elements (h1-h6) and ARIA headings (role="heading" with aria-level).
+     * @param {HTMLElement} element - The element to check
+     * @returns {number|null} The heading level (1-6+) or null if not a valid heading
+     */
+    getHeadingLevel(element) {
+        const tagName = element.tagName.toUpperCase();
+        const role = element.getAttribute('role');
+        const ariaLevel = element.getAttribute('aria-level');
+
+        if (role === 'heading') {
+            if (ariaLevel) {
+                const level = parseInt(ariaLevel, 10);
+                if (!isNaN(level) && level >= 1) {
+                    return level;
+                }
+            }
+            return null;
+        }
+
+        if (/^H[1-6]$/.test(tagName)) {
+            if (ariaLevel) {
+                const lvl = parseInt(ariaLevel, 10);
+                if (!isNaN(lvl) && lvl >= 1) {
+                    return lvl;
+                }
+            }
+            return parseInt(tagName.charAt(1), 10);
+        }
+
+        return null;
+    },
+
     /**
      * Checks if the given element has focus.
      *