@afixt/test-utils 1.1.8 → 1.2.1

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.
      *

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