@afixt/test-utils 1.2.0 → 1.2.1

package/src/formUtils.js

@@ -0,0 +1,175 @@
+/**
+ * @file Form-related accessibility utilities
+ * @module formUtils
+ */
+
+const formUtils = {
+    /**
+     * Check if an element is a labellable form control per HTML spec.
+     * @param {Element} element - The element to check
+     * @returns {boolean} True if the element is labellable
+     */
+    isLabellable(element) {
+        if (!element) {
+            return false;
+        }
+        const labellable = ['input', 'select', 'textarea', 'button', 'meter', 'output', 'progress'];
+        const tagName = element.tagName.toLowerCase();
+        return labellable.includes(tagName);
+    },
+
+    /**
+     * Check if an element is a hidden input.
+     * @param {Element} element - The element to check
+     * @returns {boolean} True if the element is a hidden input
+     */
+    isHiddenInput(element) {
+        if (!element) {
+            return false;
+        }
+        return (
+            element.tagName.toLowerCase() === 'input' &&
+            (element.getAttribute('type') || '').toLowerCase() === 'hidden'
+        );
+    },
+
+    /**
+     * Checks if an element has an explicit accessible name via aria-labelledby, aria-label, or title.
+     * Text content is NOT checked (useful for containers like radiogroup/group where
+     * text content is not a valid accessible name source).
+     * @param {Element} element - The element to check
+     * @returns {boolean} True if element has an explicit accessible name
+     */
+    hasExplicitAccessibleName(element) {
+        if (element.hasAttribute('aria-labelledby')) {
+            const ids = element.getAttribute('aria-labelledby').trim().split(/\s+/);
+            for (let i = 0; i < ids.length; i++) {
+                const labelEl = document.getElementById(ids[i]);
+                if (labelEl && labelEl.textContent.trim()) {
+                    return true;
+                }
+            }
+        }
+
+        if (element.hasAttribute('aria-label')) {
+            const ariaLabel = element.getAttribute('aria-label').trim();
+            if (ariaLabel) {
+                return true;
+            }
+        }
+
+        if (element.hasAttribute('title')) {
+            const title = element.getAttribute('title').trim();
+            if (title) {
+                return true;
+            }
+        }
+
+        return false;
+    },
+
+    /**
+     * Checks if a form control is properly grouped with an accessible label.
+     * Proper grouping means inside a fieldset with a legend, or inside an element
+     * with role="radiogroup" or role="group" that has an explicit accessible name.
+     * @param {HTMLElement} control - The form control to check
+     * @param {string} [groupRole='radiogroup'] - The ARIA group role to look for
+     * @returns {boolean} True if properly grouped
+     */
+    isProperlyGrouped(control, groupRole) {
+        groupRole = groupRole || 'radiogroup';
+
+        const fieldset = control.closest('fieldset');
+        if (fieldset) {
+            const legend = fieldset.querySelector('legend');
+            if (legend && legend.textContent.trim()) {
+                return true;
+            }
+            return false;
+        }
+
+        const group = control.closest('[role="' + groupRole + '"]');
+        if (group) {
+            if (formUtils.hasExplicitAccessibleName(group)) {
+                return true;
+            }
+            return false;
+        }
+
+        return false;
+    },
+
+    /**
+     * Finds the grouping ancestor for an element (fieldset, form, or ARIA group).
+     * @param {Element} element - The element to start from
+     * @returns {Element} The grouping ancestor or document.body if none found
+     */
+    findGroupingAncestor(element) {
+        let current = element.parentElement;
+
+        while (current && current !== document.body) {
+            const tagName = current.tagName;
+            const role = current.getAttribute('role');
+
+            if (
+                tagName === 'FIELDSET' ||
+                tagName === 'FORM' ||
+                role === 'radiogroup' ||
+                role === 'group'
+            ) {
+                return current;
+            }
+
+            current = current.parentElement;
+        }
+
+        return document.body;
+    },
+
+    /**
+     * Check if a native form element has an associated label.
+     * Checks label[for], wrapping label, aria-label, aria-labelledby, and title.
+     * @param {HTMLElement} element - The element to check
+     * @returns {boolean} True if the element has an associated label
+     */
+    hasAssociatedLabel(element) {
+        if (element.id) {
+            const label = document.querySelector('label[for="' + element.id + '"]');
+            if (label && label.textContent.trim()) {
+                return true;
+            }
+        }
+
+        const parentLabel = element.closest('label');
+        if (parentLabel && parentLabel.textContent.trim()) {
+            return true;
+        }
+
+        return false;
+    },
+
+    /**
+     * Get the text content of an element, excluding form control children.
+     * Useful for wrapped labels like <label><input type="checkbox"> Remember me</label>
+     * where the input element should not contribute to label text.
+     * @param {Element} element - The element to get text from
+     * @returns {string} The text content excluding form controls
+     */
+    getTextContentExcludingControls(element) {
+        let text = '';
+        for (let i = 0; i < element.childNodes.length; i++) {
+            const node = element.childNodes[i];
+            if (node.nodeType === Node.TEXT_NODE) {
+                text += node.textContent;
+            } else if (node.nodeType === Node.ELEMENT_NODE) {
+                const tagName = node.tagName.toLowerCase();
+                if (!['input', 'select', 'textarea', 'button'].includes(tagName)) {
+                    text += formUtils.getTextContentExcludingControls(node);
+                }
+            }
+        }
+        return text;
+    },
+};
+
+module.exports = formUtils;

package/src/getCSSGeneratedContent.js

@@ -1,44 +1,66 @@
+/**
+ * Checks if a CSS content value is meaningful (non-empty, non-whitespace).
+ * Strips surrounding quotes and checks for actual visible content.
+ *
+ * @param {string} rawValue - The raw CSS content value from getComputedStyle
+ * @returns {string|false} The cleaned content string or false if empty/whitespace
+ */
+function extractMeaningfulContent(rawValue) {
+    if (!rawValue || rawValue === 'none' || rawValue === 'normal') {
+        return false;
+    }
+
+    // Remove surrounding quotes (single or double)
+    let cleaned = rawValue.replace(/^["'](.*)["']$/, '$1');
+
+    // Trim whitespace - content that is only whitespace is not meaningful
+    cleaned = cleaned.trim();
+
+    return cleaned.length > 0 ? cleaned : false;
+}
+
 /**
  * Gets the CSS generated content for an element's ::before or ::after pseudo-elements.
  * This function only checks for content added via the CSS `content` property,
- * not the element's own text content.
+ * not the element's own text content. Empty, whitespace-only, and blank content
+ * values are filtered out as they do not convey meaningful information.
  *
  * @param {Element} el - The DOM element to check
  * @param {string} [pseudoElement='both'] - Which pseudo-element to check ('before', 'after', or 'both')
  * @returns {string|boolean} The generated content as a string or false if none exists
  */
 function getCSSGeneratedContent(el, pseudoElement = 'both') {
-    if (!el) return false;
+    if (!el) {
+        return false;
+    }
 
     let content = '';
 
-    if (pseudoElement === 'before' || pseudoElement === 'both') {
-        const style = window.getComputedStyle(el, '::before');
-        const before = style.getPropertyValue('content');
-        if (before && before !== 'none' && before !== 'normal' && before !== '""' && before !== "''") {
-            // Remove surrounding quotes if present
-            const cleanBefore = before.replace(/^["'](.*)["']$/, '$1');
+    try {
+        if (pseudoElement === 'before' || pseudoElement === 'both') {
+            const style = window.getComputedStyle(el, '::before');
+            const before = style.getPropertyValue('content');
+            const cleanBefore = extractMeaningfulContent(before);
             if (cleanBefore) {
                 content += cleanBefore;
             }
         }
-    }
 
-    if (pseudoElement === 'after' || pseudoElement === 'both') {
-        const style = window.getComputedStyle(el, '::after');
-        const after = style.getPropertyValue('content');
-        if (after && after !== 'none' && after !== 'normal' && after !== '""' && after !== "''") {
-            // Remove surrounding quotes if present
-            const cleanAfter = after.replace(/^["'](.*)["']$/, '$1');
+        if (pseudoElement === 'after' || pseudoElement === 'both') {
+            const style = window.getComputedStyle(el, '::after');
+            const after = style.getPropertyValue('content');
+            const cleanAfter = extractMeaningfulContent(after);
             if (cleanAfter) {
                 content += (content ? ' ' : '') + cleanAfter;
             }
         }
+    } catch (_e) {
+        return false;
     }
 
     return content ? content.trim() : false;
 }
 
 module.exports = {
-    getCSSGeneratedContent
-};
+    getCSSGeneratedContent,
+};

package/src/index.js

@@ -63,6 +63,18 @@ const isValidUrl = require('./isValidUrl.js');
 // String utilities
 const stringUtils = require('./stringUtils.js');
 
+// Constants
+const constants = require('./constants.js');
+
+// CSS utilities
+const cssUtils = require('./cssUtils.js');
+
+// Form utilities
+const formUtils = require('./formUtils.js');
+
+// Table utilities
+const tableUtils = require('./tableUtils.js');
+
 // Query cache utilities
 const queryCache = require('./queryCache.js');
 
@@ -102,6 +114,10 @@ module.exports = {
     ...testOrder,
     ...isValidUrl,
     ...stringUtils,
+    ...constants,
+    ...cssUtils,
+    ...formUtils,
+    ...tableUtils,
     ...queryCache,
-    ...listEventListeners
-};
+    ...listEventListeners,
+};

package/src/stringUtils.js

@@ -132,6 +132,149 @@ const stringUtils = (function () {
         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 {
         isEmpty,
         isString,
@@ -142,6 +285,12 @@ const stringUtils = (function () {
         getPathFromUrl,
         getAllText,
         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

@@ -25,13 +25,47 @@ function getComputedBackgroundColor(el, options) {
     if (bgImage === 'none') {
         const bgColor = styles.getPropertyValue('background-color');
 
-        if (bgColor === 'rgba(0, 0, 0, 0)') {
+        // 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) {