@afixt/test-utils 1.2.0 → 1.2.2

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/getAccessibleText.js

@@ -5,9 +5,16 @@ const { isEmpty } = require('./stringUtils.js');
  * Traverses the DOM subtree collecting text from text nodes, img alt attributes,
  * and input[type="image"] alt attributes.
  * @param {Element} el - The DOM element.
+ * @param {Object} [options] - Configuration options.
+ * @param {boolean} [options.visibleOnly=false] - If true, return only visually rendered text,
+ *        skipping aria-label, img alt, input[type="image"] alt, style, script, and
+ *        aria-hidden="true" elements. Useful for WCAG 2.5.3 Label in Name comparisons.
  * @returns {string} The accessible text.
  */
-function getAccessibleText(el) {
+function getAccessibleText(el, options) {
+    const opts = options || {};
+    const visibleOnly = opts.visibleOnly || false;
+
     if (!el || !(el instanceof Element)) {
         return '';
     }
@@ -16,31 +23,32 @@ function getAccessibleText(el) {
         return '';
     }
 
-    // Check for aria-label first (highest priority)
-    if (el.hasAttribute('aria-label')) {
-        const ariaLabel = el.getAttribute('aria-label').trim();
-        if (ariaLabel) {
-            return ariaLabel;
+    if (!visibleOnly) {
+        // Check for aria-label first (highest priority)
+        if (el.hasAttribute('aria-label')) {
+            const ariaLabel = el.getAttribute('aria-label').trim();
+            if (ariaLabel) {
+                return ariaLabel;
+            }
         }
-    }
 
-    // Check for img alt text when the element itself is an img
-    if (el.tagName.toLowerCase() === 'img' && el.hasAttribute('alt')) {
-        return el.getAttribute('alt').trim();
-    }
+        // Check for img alt text when the element itself is an img
+        if (el.tagName.toLowerCase() === 'img' && el.hasAttribute('alt')) {
+            return el.getAttribute('alt').trim();
+        }
 
-    // Check for input[type="image"] alt text when the element itself is one
-    if (
-        el.tagName.toLowerCase() === 'input' &&
-        el.getAttribute('type') === 'image' &&
-        el.hasAttribute('alt')
-    ) {
-        return el.getAttribute('alt').trim();
+        // Check for input[type="image"] alt text when the element itself is one
+        if (
+            el.tagName.toLowerCase() === 'input' &&
+            el.getAttribute('type') === 'image' &&
+            el.hasAttribute('alt')
+        ) {
+            return el.getAttribute('alt').trim();
+        }
     }
 
-    // Collect accessible text from the subtree, including text nodes
-    // and alt text from embedded images
-    const parts = collectSubtreeText(el);
+    // Collect text from the subtree
+    const parts = collectSubtreeText(el, visibleOnly);
     return parts.join(' ').replace(/\s+/g, ' ').trim();
 }
 
@@ -48,9 +56,10 @@ function getAccessibleText(el) {
  * Recursively collect accessible text parts from an element's subtree.
  * Handles text nodes, img alt text, and input[type="image"] alt text.
  * @param {Node} node - The DOM node to traverse.
+ * @param {boolean} [visibleOnly=false] - If true, skip non-visible content.
  * @returns {string[]} Array of text parts found in the subtree.
  */
-function collectSubtreeText(node) {
+function collectSubtreeText(node, visibleOnly) {
     const parts = [];
 
     for (let child = node.firstChild; child; child = child.nextSibling) {
@@ -62,30 +71,42 @@ function collectSubtreeText(node) {
         } else if (child.nodeType === Node.ELEMENT_NODE) {
             const tag = child.tagName.toLowerCase();
 
-            // img with non-empty alt contributes its alt text
-            if (tag === 'img' && child.hasAttribute('alt')) {
-                const alt = child.getAttribute('alt').trim();
-                if (alt) {
-                    parts.push(alt);
+            // In visibleOnly mode, skip non-rendered content
+            if (visibleOnly) {
+                if (tag === 'style' || tag === 'script') {
+                    continue;
+                }
+                if (child.getAttribute('aria-hidden') === 'true') {
+                    continue;
                 }
-                continue;
             }
 
-            // input[type="image"] with non-empty alt contributes its alt text
-            if (
-                tag === 'input' &&
-                child.getAttribute('type') === 'image' &&
-                child.hasAttribute('alt')
-            ) {
-                const alt = child.getAttribute('alt').trim();
-                if (alt) {
-                    parts.push(alt);
+            if (!visibleOnly) {
+                // img with non-empty alt contributes its alt text
+                if (tag === 'img' && child.hasAttribute('alt')) {
+                    const alt = child.getAttribute('alt').trim();
+                    if (alt) {
+                        parts.push(alt);
+                    }
+                    continue;
+                }
+
+                // input[type="image"] with non-empty alt contributes its alt text
+                if (
+                    tag === 'input' &&
+                    child.getAttribute('type') === 'image' &&
+                    child.hasAttribute('alt')
+                ) {
+                    const alt = child.getAttribute('alt').trim();
+                    if (alt) {
+                        parts.push(alt);
+                    }
+                    continue;
                 }
-                continue;
             }
 
             // Recurse into other element children
-            parts.push(...collectSubtreeText(child));
+            parts.push(...collectSubtreeText(child, visibleOnly));
         }
     }
 

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,
     };
 })();