@afixt/test-utils 1.1.8 → 1.2.1

package/src/stringUtils.js

@@ -14,7 +14,7 @@ const stringUtils = (function () {
      * @returns {boolean} Whether the value is a string.
      */
     function isString(str) {
-        return typeof str === "string" || str instanceof String;
+        return typeof str === 'string' || str instanceof String;
     }
 
     /**
@@ -32,7 +32,7 @@ const stringUtils = (function () {
      * @returns {boolean}
      */
     function isNormalInteger(str) {
-        const n = ~~Number(str);
+        const n = Math.trunc(Number(str));
         return String(n) === str && n >= 0;
     }
 
@@ -49,14 +49,11 @@ const stringUtils = (function () {
         let char;
         let isUpper = true;
 
-        str = str.replace(/[^\w\s]|_/g, "").replace(/\s+/g, " ");
+        str = str.replace(/[^\w\s]|_/g, '').replace(/\s+/g, ' ');
 
         while (i <= str.length) {
             char = str.charAt(i);
-            if (
-                char.trim() !== "" &&
-                false === (!isNaN(parseFloat(char)) && isFinite(char))
-            ) {
+            if (char.trim() !== '' && false === (!isNaN(parseFloat(char)) && isFinite(char))) {
                 if (char === char.toLowerCase()) {
                     isUpper = false;
                 }
@@ -94,14 +91,15 @@ const stringUtils = (function () {
      * @returns {string} A string containing all concatenated text content from the element.
      */
     function getAllText(el) {
-        const walker = document.createTreeWalker(
-            el,
-            NodeFilter.SHOW_ALL,
-            null,
-            false
-        );
+        // Check for form element value (input, textarea, select)
+        if (el.value !== undefined && el.value !== '') {
+            return el.value;
+        }
+
+        const walker = document.createTreeWalker(el, NodeFilter.SHOW_ALL, null, false);
         const textNodes = [];
-        let node, text;
+        let node;
+        let text;
 
         while (walker.nextNode()) {
             node = walker.currentNode;
@@ -113,15 +111,15 @@ const stringUtils = (function () {
                     textNodes.push(node.textContent.trim());
                 }
             } else if (node.nodeType === Node.ELEMENT_NODE) {
-                if (node.hasAttribute("aria-label")) {
-                    textNodes.push(node.getAttribute("aria-label"));
-                } else if (node.tagName === "IMG" && node.hasAttribute("alt")) {
-                    textNodes.push(node.getAttribute("alt"));
+                if (node.hasAttribute('aria-label')) {
+                    textNodes.push(node.getAttribute('aria-label'));
+                } else if (node.tagName === 'IMG' && node.hasAttribute('alt')) {
+                    textNodes.push(node.getAttribute('alt'));
                 }
             }
         }
 
-        return textNodes.join(" ");
+        return textNodes.join(' ');
     }
 
     /**
@@ -131,7 +129,150 @@ const stringUtils = (function () {
      * @returns {boolean} True if the element contains text, false otherwise.
      */
     function hasText(element) {
-        return getAllText(element).trim() !== "";
+        return getAllText(element).trim() !== '';
+    }
+
+    /**
+     * Checks if a string is empty or contains only whitespace/invisible characters,
+     * including zero-width spaces, no-break spaces, and other Unicode whitespace.
+     * @param {string} str - The string to check
+     * @returns {boolean} True if empty or whitespace/invisible only
+     */
+    function isEmptyOrWhitespace(str) {
+        if (!str) {
+            return true;
+        }
+        // eslint-disable-next-line no-misleading-character-class
+        const cleaned = str.replace(/[\s\u00A0\u200B\u200C\u200D\u2060\uFEFF]/g, '');
+        return cleaned.length === 0;
+    }
+
+    /**
+     * Checks if a title is generic, meaningless, or placeholder-like.
+     * @param {string} title - The title to check
+     * @returns {boolean} True if the title is generic/meaningless
+     */
+    function isGenericTitle(title) {
+        if (!title) {
+            return false;
+        }
+        const genericTitles = ['iframe', 'frame', 'untitled', 'title', 'content', 'main', 'page'];
+        const normalized = title.toLowerCase().trim();
+
+        if (genericTitles.includes(normalized)) {
+            return true;
+        }
+
+        if (/^(frame|iframe|untitled|title)\d*$/i.test(normalized)) {
+            return true;
+        }
+
+        return false;
+    }
+
+    /**
+     * Checks if the given text is generic/meaningless link text.
+     * @param {string} text - The accessible name to check
+     * @param {string[]} [genericList] - Optional custom list of generic link text
+     * @returns {boolean} True if the text is generic
+     */
+    function isGenericLinkText(text, genericList) {
+        if (!text) {
+            return false;
+        }
+        const defaults = [
+            'click here',
+            'here',
+            'more',
+            'read more',
+            'learn more',
+            'click',
+            'link',
+            'this',
+            'page',
+            'article',
+            'continue',
+            'go',
+            'see more',
+            'view',
+            'download',
+            'pdf',
+            'document',
+            'form',
+            'submit',
+            'button',
+            'press',
+            'select',
+            'choose',
+        ];
+        const list = genericList || defaults;
+        const lowerText = text.toLowerCase().trim();
+        return list.some(function (generic) {
+            return lowerText === generic;
+        });
+    }
+
+    /**
+     * Get the actual visible text content of an element, ignoring aria-label.
+     * @param {Element} element - The DOM element
+     * @returns {string} The visible text content
+     */
+    function getActualVisibleText(element) {
+        if (!element) {
+            return '';
+        }
+        return (element.textContent || '').trim();
+    }
+
+    /**
+     * Checks if text contains a warning about new window/tab behavior.
+     * @param {string} text - The text to check
+     * @returns {boolean} True if the text contains a warning
+     */
+    function hasNewWindowWarning(text) {
+        if (!text) {
+            return false;
+        }
+        const warnings = [
+            'new window',
+            'new tab',
+            'opens in new',
+            'opens in a new',
+            'opens new',
+            'external link',
+            'external site',
+        ];
+        const lowerText = text.toLowerCase();
+        return warnings.some(function (warning) {
+            return lowerText.includes(warning);
+        });
+    }
+
+    /**
+     * Extracts DOM text content from an element, including img alt text,
+     * but excluding ARIA attributes (aria-label, aria-labelledby).
+     * Useful for detecting actual visible/DOM text that may conflict with ARIA labels.
+     *
+     * @param {Element} root - The DOM element from which to extract text.
+     * @returns {string} Concatenated text from text nodes and img alt attributes.
+     */
+    function textIncludingImgAlt(root) {
+        let out = '';
+        const walker = document.createTreeWalker(
+            root,
+            NodeFilter.SHOW_TEXT | NodeFilter.SHOW_ELEMENT // eslint-disable-line no-bitwise
+        );
+        let n = walker.currentNode;
+        while (n) {
+            if (n.nodeType === Node.TEXT_NODE) {
+                out += n.nodeValue;
+            }
+            if (n.nodeType === Node.ELEMENT_NODE && n.tagName === 'IMG') {
+                out += n.getAttribute('alt') || '';
+            }
+            n = walker.nextNode();
+        }
+        return out;
     }
 
     return {
@@ -143,7 +284,13 @@ const stringUtils = (function () {
         isAlphaNumeric,
         getPathFromUrl,
         getAllText,
-        hasText
+        hasText,
+        textIncludingImgAlt,
+        isEmptyOrWhitespace,
+        isGenericTitle,
+        isGenericLinkText,
+        getActualVisibleText,
+        hasNewWindowWarning,
     };
 })();
 

package/src/tableUtils.js

@@ -0,0 +1,180 @@
+/**
+ * @file Table-related accessibility utilities
+ * @module tableUtils
+ */
+
+const tableUtils = {
+    /**
+     * Check if table has multiple header rows (rows containing th elements).
+     * @param {HTMLElement} table - The table element
+     * @returns {boolean} True if table has multiple header rows
+     */
+    hasMultipleHeaderRows(table) {
+        const rows = table.querySelectorAll('tr');
+        let headerRowCount = 0;
+
+        for (let i = 0; i < rows.length; i++) {
+            const thCells = rows[i].querySelectorAll('th');
+            const tdCells = rows[i].querySelectorAll('td');
+
+            if (thCells.length > 0 && thCells.length >= tdCells.length) {
+                headerRowCount++;
+            }
+        }
+
+        return headerRowCount >= 3;
+    },
+
+    /**
+     * Check if table has header cells with large colspan/rowspan values.
+     * @param {HTMLElement} table - The table element
+     * @param {number} [maxColspan=4] - Maximum acceptable colspan
+     * @param {number} [maxRowspan=3] - Maximum acceptable rowspan
+     * @returns {boolean} True if table has complex header spans
+     */
+    hasComplexHeaderSpans(table, maxColspan, maxRowspan) {
+        maxColspan = maxColspan || 4;
+        maxRowspan = maxRowspan || 3;
+
+        const headerCells = table.querySelectorAll('th[colspan], th[rowspan]');
+
+        for (let i = 0; i < headerCells.length; i++) {
+            const colspan = parseInt(headerCells[i].getAttribute('colspan'), 10) || 1;
+            const rowspan = parseInt(headerCells[i].getAttribute('rowspan'), 10) || 1;
+
+            if (colspan > maxColspan || rowspan > maxRowspan) {
+                return true;
+            }
+        }
+
+        return false;
+    },
+
+    /**
+     * Count effective columns in a table (accounting for colspan).
+     * @param {HTMLElement} table - The table element
+     * @returns {number} Maximum column count
+     */
+    getMaxColumnCount(table) {
+        const rows = table.querySelectorAll('tr');
+        let maxCols = 0;
+
+        for (let i = 0; i < rows.length; i++) {
+            let colCount = 0;
+            const cells = rows[i].querySelectorAll('td, th');
+
+            for (let j = 0; j < cells.length; j++) {
+                const colspan = parseInt(cells[j].getAttribute('colspan'), 10) || 1;
+                colCount += colspan;
+            }
+
+            if (colCount > maxCols) {
+                maxCols = colCount;
+            }
+        }
+
+        return maxCols;
+    },
+
+    /**
+     * Check if table has multiple rows with colspan/rowspan on header cells,
+     * indicating multi-level grouped headers.
+     * @param {HTMLElement} table - The table element
+     * @returns {boolean} True if table has complex header groupings
+     */
+    hasMultiLevelHeaderGroupings(table) {
+        const rows = table.querySelectorAll('tr');
+        let rowsWithHeaderSpans = 0;
+
+        for (let i = 0; i < rows.length; i++) {
+            const spannedHeaders = rows[i].querySelectorAll('th[colspan], th[rowspan]');
+            if (spannedHeaders.length > 0) {
+                rowsWithHeaderSpans++;
+            }
+        }
+
+        return rowsWithHeaderSpans >= 2;
+    },
+
+    /**
+     * Checks if an HTML table has only header cells (th) and no data cells (td).
+     * Indicates headers potentially separated from their data.
+     * @param {HTMLTableElement} table - The table element to check
+     * @returns {boolean} True if table has only headers, no data
+     */
+    isHeaderOnlyTable(table) {
+        const hasHeaders = table.querySelectorAll('th').length > 0;
+        const hasDataCells = table.querySelectorAll('td').length > 0;
+        return hasHeaders && !hasDataCells;
+    },
+
+    /**
+     * Checks if an ARIA table has only header roles and no cell roles.
+     * @param {HTMLElement} ariaTable - The element with role="table"
+     * @returns {boolean} True if ARIA table has only headers, no data cells
+     */
+    isHeaderOnlyAriaTable(ariaTable) {
+        const hasHeaders =
+            ariaTable.querySelectorAll('[role="columnheader"], [role="rowheader"]').length > 0;
+        const hasDataCells =
+            ariaTable.querySelectorAll('[role="cell"], [role="gridcell"]').length > 0;
+        return hasHeaders && !hasDataCells;
+    },
+
+    /**
+     * Checks if a string contains only punctuation characters.
+     * @param {string} str - The string to check
+     * @returns {boolean} True if the string contains only punctuation
+     */
+    isPunctuationOnly(str) {
+        return /^[\p{P}\p{S}]+$/u.test(str);
+    },
+
+    /**
+     * Checks if a summary is generic/useless.
+     * @param {string} summary - The summary text to check
+     * @param {string[]} [genericList] - Optional custom list of generic summaries
+     * @returns {boolean} True if the summary is generic
+     */
+    isGenericSummary(summary, genericList) {
+        const GENERIC_SUMMARIES = genericList || [
+            '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',
+        ];
+        const normalized = summary.toLowerCase().trim();
+        return GENERIC_SUMMARIES.includes(normalized);
+    },
+};
+
+module.exports = tableUtils;

package/src/testContrast.js

@@ -1,13 +1,21 @@
 /**
  * Get the computed background color for an element.
  * @param  {Element} el - the element to be tested
+ * @param  {Object} [options] - Configuration options
+ * @param  {string} [options.fallbackColor='rgb(255, 255, 255)'] - Color to use when background can't be determined
+ * @param  {boolean} [options.skipBackgroundImages=true] - If true (default), return false for background images. If false, use fallbackColor instead.
  * @returns {string|boolean} background color or false
  */
-function getComputedBackgroundColor(el) {
+function getComputedBackgroundColor(el, options) {
     if (!window.getComputedStyle || !el || el.nodeType === 9) {
         return false;
     }
 
+    const opts = options || {};
+    const fallbackColor = opts.fallbackColor || 'rgb(255, 255, 255)';
+    const skipBackgroundImages =
+        opts.skipBackgroundImages !== undefined ? opts.skipBackgroundImages : true;
+
     const styles = window.getComputedStyle(el);
     if (!styles) {
         return false;
@@ -17,12 +25,52 @@ function getComputedBackgroundColor(el) {
     if (bgImage === 'none') {
         const bgColor = styles.getPropertyValue('background-color');
 
-        if (bgColor === 'rgba(0, 0, 0, 0)' && el.parentElement) {
-            return getComputedBackgroundColor(el.parentElement);
+        // Check for any fully transparent background (not just rgba(0,0,0,0))
+        const parsed = parseRGB(bgColor);
+        if (
+            bgColor === 'rgba(0, 0, 0, 0)' ||
+            bgColor === 'transparent' ||
+            (parsed && parsed[4] !== undefined && parseFloat(parsed[4]) === 0)
+        ) {
+            if (el.parentElement) {
+                return getComputedBackgroundColor(el.parentElement, options);
+            }
+            return opts.fallbackColor !== undefined ? fallbackColor : false;
+        }
+
+        // Handle semi-transparent backgrounds by blending with parent
+        if (parsed && parsed[4] !== undefined && parseFloat(parsed[4]) < 1) {
+            const alpha = parseFloat(parsed[4]);
+            const parentBg = el.parentElement
+                ? getComputedBackgroundColor(el.parentElement, options)
+                : fallbackColor;
+
+            if (parentBg && parentBg !== false) {
+                const parentParsed = parseRGB(parentBg);
+                if (parentParsed) {
+                    // Alpha composite: result = fg * alpha + bg * (1 - alpha)
+                    const r = Math.round(
+                        parseInt(parsed[1], 10) * alpha +
+                            parseInt(parentParsed[1], 10) * (1 - alpha)
+                    );
+                    const g = Math.round(
+                        parseInt(parsed[2], 10) * alpha +
+                            parseInt(parentParsed[2], 10) * (1 - alpha)
+                    );
+                    const b = Math.round(
+                        parseInt(parsed[3], 10) * alpha +
+                            parseInt(parentParsed[3], 10) * (1 - alpha)
+                    );
+                    return 'rgb(' + r + ', ' + g + ', ' + b + ')';
+                }
+            }
         }
 
         return bgColor;
     } else {
+        if (!skipBackgroundImages) {
+            return fallbackColor;
+        }
         return false;
     }
 }
@@ -40,9 +88,9 @@ function luminance(R8bit, G8bit, B8bit) {
     const GsRGB = G8bit / 255;
     const BsRGB = B8bit / 255;
 
-    const R = (RsRGB <= 0.03928) ? RsRGB / 12.92 : Math.pow((RsRGB + 0.055) / 1.055, 2.4);
-    const G = (GsRGB <= 0.03928) ? GsRGB / 12.92 : Math.pow((GsRGB + 0.055) / 1.055, 2.4);
-    const B = (BsRGB <= 0.03928) ? BsRGB / 12.92 : Math.pow((BsRGB + 0.055) / 1.055, 2.4);
+    const R = RsRGB <= 0.03928 ? RsRGB / 12.92 : Math.pow((RsRGB + 0.055) / 1.055, 2.4);
+    const G = GsRGB <= 0.03928 ? GsRGB / 12.92 : Math.pow((GsRGB + 0.055) / 1.055, 2.4);
+    const B = BsRGB <= 0.03928 ? BsRGB / 12.92 : Math.pow((BsRGB + 0.055) / 1.055, 2.4);
 
     // For the sRGB colorspace, the relative luminance of a color is defined as:
     const L = 0.2126 * R + 0.7152 * G + 0.0722 * B;
@@ -50,6 +98,24 @@ function luminance(R8bit, G8bit, B8bit) {
     return L;
 }
 
+/**
+ * Calculate relative luminance from an RGB object.
+ * Wrapper around luminance() that accepts an object instead of three separate arguments.
+ * @param {{ r: number, g: number, b: number }} rgb - Object with r, g, b properties (0-255)
+ * @returns {number|null} Relative luminance value (0-1) or null if input is invalid
+ */
+function getRelativeLuminance(rgb) {
+    if (
+        !rgb ||
+        typeof rgb.r !== 'number' ||
+        typeof rgb.g !== 'number' ||
+        typeof rgb.b !== 'number'
+    ) {
+        return null;
+    }
+    return luminance(rgb.r, rgb.g, rgb.b);
+}
+
 /**
  * Parse an RGB or RGBA color string into its components
  * @param  {string} rgb - RGB(A) color string (e.g., "rgb(255, 0, 0)" or "rgba(255, 0, 0, 0.5)")
@@ -60,6 +126,57 @@ function parseRGB(rgb) {
     return rgbvals;
 }
 
+/**
+ * Parse an RGB/RGBA color string into a structured object.
+ * @param {string} colorStr - e.g., 'rgb(255, 128, 0)' or 'rgba(255, 128, 0, 0.5)'
+ * @returns {{ r: number, g: number, b: number, a?: number } | null}
+ */
+function parseColor(colorStr) {
+    if (!colorStr) {
+        return null;
+    }
+
+    const match = parseRGB(colorStr);
+    if (!match) {
+        return null;
+    }
+
+    const result = {
+        r: parseInt(match[1], 10),
+        g: parseInt(match[2], 10),
+        b: parseInt(match[3], 10),
+    };
+
+    if (match[4] !== undefined) {
+        result.a = parseFloat(match[4]);
+    }
+
+    return result;
+}
+
+/**
+ * Calculate contrast ratio between two color strings.
+ * @param {string} color1 - e.g., 'rgb(0, 0, 0)'
+ * @param {string} color2 - e.g., 'rgb(255, 255, 255)'
+ * @returns {number|null} Contrast ratio (1 to 21) or null if colors can't be parsed
+ */
+function getContrastRatio(color1, color2) {
+    const c1 = parseColor(color1);
+    const c2 = parseColor(color2);
+
+    if (!c1 || !c2) {
+        return null;
+    }
+
+    const lum1 = luminance(c1.r, c1.g, c1.b);
+    const lum2 = luminance(c2.r, c2.g, c2.b);
+
+    const lighter = Math.max(lum1, lum2);
+    const darker = Math.min(lum1, lum2);
+
+    return Math.round(((lighter + 0.05) / (darker + 0.05)) * 100) / 100;
+}
+
 /**
  * Calculate color contrast ratio between foreground and background
  * @param  {Element} el - DOM element to check
@@ -105,7 +222,7 @@ function getColorContrast(el) {
         lighter = fgLuminance;
     }
 
-    return Math.round((lighter + 0.05) / (darker + 0.05) * 100) / 100;
+    return Math.round(((lighter + 0.05) / (darker + 0.05)) * 100) / 100;
 }
 
 /**
@@ -132,10 +249,11 @@ function testContrast(el, options = { level: 'AA' }) {
 
     // Check if element is offscreen
     const rect = el.getBoundingClientRect();
-    const selfOffscreen = rect.left + rect.width <= 0 ||
-                          rect.top + rect.height <= 0 ||
-                          rect.left >= window.innerWidth ||
-                          rect.top >= window.innerHeight;
+    const selfOffscreen =
+        rect.left + rect.width <= 0 ||
+        rect.top + rect.height <= 0 ||
+        rect.left >= window.innerWidth ||
+        rect.top >= window.innerHeight;
 
     // Get direct text (excluding child elements)
     let selfDirectText = '';
@@ -157,14 +275,6 @@ function testContrast(el, options = { level: 'AA' }) {
         return true;
     }
 
-    // JSDOM Test Compatibility: Handle test case for identical colors
-    if (selfFG === selfBG || (selfFG === 'rgb(0, 0, 0)' && selfBG === 'rgb(0, 0, 0)')) {
-        // Special case for test
-        if (el.textContent === 'Test text') {
-            return false;
-        }
-    }
-
     // Determine the contrast required based on the level passed to the function
     if (level === 'AA') {
         if (selfSize < 18) {
@@ -209,8 +319,10 @@ function testContrast(el, options = { level: 'AA' }) {
         // Only test contrast if there's a difference between the element and its parent
         // in terms of colors, font size, or font weight
         if (
-            (selfFG !== parentFG || selfBG !== parentBG) ||
-            (selfSize !== parentSize || selfWeight !== parentWeight)
+            selfFG !== parentFG ||
+            selfBG !== parentBG ||
+            selfSize !== parentSize ||
+            selfWeight !== parentWeight
         ) {
             const contrast = getColorContrast(el);
 
@@ -237,5 +349,8 @@ module.exports = {
     getComputedBackgroundColor,
     luminance,
     parseRGB,
-    getColorContrast
+    parseColor,
+    getRelativeLuminance,
+    getContrastRatio,
+    getColorContrast,
 };