@afixt/test-utils 1.0.0

package/src/isComplexTable.js

@@ -0,0 +1,109 @@
+
+/**
+ * Checks if the given table element has multiple rows in the header.
+ *
+ * @param {HTMLElement} el - The table element to check.
+ * @returns {boolean} True if the table has more than one row in the header, otherwise false.
+ */
+export function checkMultiRowsInHeader(el) {
+    return el.querySelectorAll("thead tr").length > 1;
+}
+
+/**
+ * Checks if the given table element has multiple rows with at least
+ * one cell that has a colspan attribute.
+ *
+ * @param {HTMLElement} el - The table element to check.
+ * @returns {boolean} - Returns true if there are more than one row
+ * with at least one cell having a colspan attribute, otherwise false.
+ */
+export function checkMultiRowsWithColspan(el) {
+    let rowsWithColspanCount = 0;
+    el.querySelectorAll("tr").forEach((row) => {
+        if (row.querySelectorAll("td[colspan]").length >= 1) {
+            rowsWithColspanCount++;
+        }
+    });
+    return rowsWithColspanCount > 1;
+}
+
+/**
+ * Checks if a table element has inconsistent row or column spans.
+ *
+ * This function normalizes the table by removing `colspan` and `rowspan` attributes,
+ * and then checks if the number of columns is consistent across all rows.
+ *
+ * @param {HTMLElement} el - The table element to check for inconsistencies.
+ * @returns {boolean} - Returns `true` if the table has inconsistent
+ * row or column spans, otherwise `false`.
+ */
+export function checkInconsistent(el) {
+    let result = false;
+    let clone = el.cloneNode(true);
+
+    // Normalize the table by removing colspan and cloning cells with colspan
+    clone.querySelectorAll("th[colspan], td[colspan]").forEach((cell) => {
+        let count = parseInt(cell.getAttribute("colspan")) - 1;
+        cell.removeAttribute("colspan");
+        while (count > 0) {
+            let newCell = cell.cloneNode(true);
+            cell.parentNode.insertBefore(newCell, cell.nextSibling);
+            count--;
+        }
+    });
+
+    // Normalize the table by removing rowspan and appending empty td
+    // elements in rows below
+    clone.querySelectorAll("th[rowspan], td[rowspan]").forEach((cell) => {
+        let row = cell.parentNode;
+        let count = parseInt(cell.getAttribute("rowspan")) - 1;
+        cell.removeAttribute("rowspan");
+        while (count > 0) {
+            if (!row.nextElementSibling) {
+                let newRow = document.createElement("tr");
+                row.parentNode.appendChild(newRow);
+                row = newRow;
+            } else {
+                row = row.nextElementSibling;
+            }
+            let emptyTd = document.createElement("td");
+            row.appendChild(emptyTd);
+            count--;
+        }
+    });
+
+    // We just count columns. It is sufficient because inconsistent
+    // rowspan would cause unequal number of columns in the following rows
+    let prevNumberCols;
+    clone.querySelectorAll("tr").forEach((row) => {
+        let numCols = row.querySelectorAll("td, th").length;
+        if (prevNumberCols === undefined) {
+            prevNumberCols = numCols;
+        } else if (prevNumberCols !== numCols) {
+            result = true;
+        }
+    });
+    return result;
+}
+
+/**
+ * Determines if a given table element is complex.
+ * A table is considered complex if it has multiple rows in the header,
+ * rows with colspan attributes, or inconsistent structure.
+ *
+ * @param {HTMLElement} el - The table element to check.
+ * @returns {boolean} - Returns true if the table is complex, otherwise false.
+ */
+export function isComplexTable(el) {
+    if (!el) return true;
+    let clone = el.cloneNode(true);
+
+    // Remove nested tables
+    clone.querySelectorAll("table").forEach((table) => table.remove());
+
+    let multiRowsInHeader = checkMultiRowsInHeader(clone);
+    let multiRowsWithColspan = checkMultiRowsWithColspan(clone);
+    let inconsistent = checkInconsistent(clone);
+
+    return multiRowsInHeader || inconsistent || multiRowsWithColspan;
+}

package/src/isDataTable.js

@@ -0,0 +1,239 @@
+// Import using object destructuring for better compatibility with tests
+import { arrayCount } from './arrayUtils.js';
+
+/**
+ * Returns the number of rows in the given table element.
+ *
+ * @param {HTMLTableElement} table - The table element to count rows in.
+ * @returns {number} The number of rows in the table.
+ */
+function rowCount(table) {
+    return table.querySelectorAll('tr').length;
+}
+
+/**
+ * Counts the number of cells (both <td> and <th>) in a given table element.
+ *
+ * @param {HTMLTableElement} table - The table element to count cells in.
+ * @returns {number} The total number of cells in the table.
+ */
+function cellCount(table) {
+    return table.querySelectorAll('td, th').length;
+}
+
+/**
+ * Calculates the percentage of table cells that have a border.
+ *
+ * @param {HTMLTableElement} table - The table element to analyze.
+ * @returns {number} The percentage of table cells that have a border.
+ */
+function countBordersPct(table) {
+    const cells = table.querySelectorAll('td, th');
+    const totalCells = cells.length;
+    if (totalCells === 0) return 0;
+    
+    let borderedCells = 0;
+
+    cells.forEach(cell => {
+        if (window.getComputedStyle(cell).borderWidth !== '0px') {
+            borderedCells++;
+        }
+    });
+
+    return (borderedCells / totalCells) * 100;
+}
+
+/**
+ * Calculates the average number of columns in a given HTML table.
+ *
+ * @param {HTMLTableElement} table - The table element to analyze.
+ * @returns {number} The average number of columns per row in the table.
+ */
+function colCount(table) {
+    const rows = table.querySelectorAll('tr');
+    const rowCnt = rows.length;
+    if (rowCnt === 0) return 0;
+    
+    let totalColumns = 0;
+
+    rows.forEach(row => {
+        totalColumns += row.cells.length;
+    });
+
+    return Math.round(totalColumns / rowCnt);
+}
+
+/**
+ * Checks if the color differences in the table cells exceed the specified limits.
+ *
+ * @param {HTMLTableElement} table - The table element to check.
+ * @param {number} maxColors - The maximum number of unique colors allowed.
+ * @param {number} maxDiffs - The maximum percentage difference allowed for any color.
+ * @returns {boolean} - Returns true if the color differences exceed the specified limits, otherwise false.
+ */
+function cellColorDiffs(table, maxColors, maxDiffs) {
+    const colors = [];
+    const cells = table.querySelectorAll('td, th');
+    
+    if (cells.length === 0) return false;
+
+    cells.forEach(cell => {
+        colors.push(window.getComputedStyle(cell).backgroundColor);
+    });
+
+    const colorObj = arrayCount(colors);
+    // Check if colorObj is undefined or null before using Object.keys
+    if (!colorObj) return false;
+    
+    const uniqueColors = Object.keys(colorObj).length;
+
+    if (uniqueColors > 1) {
+        if (uniqueColors > maxColors) {
+            return true;
+        }
+        return Object.values(colorObj).some(value => {
+            return (value / uniqueColors) * 100 > maxDiffs;
+        });
+    }
+    return false;
+}
+
+// Export the utility functions
+export { rowCount, cellCount, countBordersPct, colCount, cellColorDiffs };
+
+/**
+ * Determines if a given table element is a data table based on various heuristics and options.
+ *
+ * @param {HTMLTableElement} table - The table element to evaluate.
+ * @param {Object} [options={}] - Optional settings to override default heuristics.
+ * @param {number} [options.numDTColumns=5] - Minimum number of columns to consider as a data table.
+ * @param {number} [options.pctCellsWBorder=33] - Minimum percentage of cells with borders to consider as a data table.
+ * @param {number} [options.numDTRows=20] - Minimum number of rows to consider as a data table.
+ * @param {number} [options.maxWidthLT=95] - Maximum width percentage of the viewport to consider as a data table.
+ * @param {number} [options.minCellsLT=10] - Minimum number of cells to consider as a data table.
+ * @param {number} [options.maxCellColors=3] - Maximum number of different cell colors to consider as a data table.
+ * @param {number} [options.maxColorDiffs=30] - Maximum number of color differences to consider as a data table.
+ * @returns {boolean} - Returns true if the table is considered a data table, otherwise false.
+ */
+function isDataTable(table, options = {}) {
+    const defaults = {
+        numDTColumns: 5,
+        pctCellsWBorder: 33,
+        numDTRows: 20,
+        maxWidthLT: 95,
+        minCellsLT: 10,
+        maxCellColors: 3,
+        maxColorDiffs: 30
+    };
+
+    const settings = { ...defaults, ...options };
+
+    if (!table || table.tagName.toLowerCase() !== 'table') {
+        return false;
+    }
+
+
+    if (table.closest && table.closest("[contenteditable='true'], [contenteditable='inherit']")) {
+        return true;
+    }
+
+    if (table.getAttribute && table.getAttribute('role') === 'presentation') {
+        return false;
+    }
+
+    if (table.getAttribute && ['grid', 'treegrid'].includes(table.getAttribute('role'))) {
+        return true;
+    }
+
+    const roleChildren = table.querySelectorAll && table.querySelectorAll('th[role="gridcell"], td[role="rowheader"], td[role="columnheader"]');
+    if (roleChildren && roleChildren.length > 0) {
+        return true;
+    }
+
+    if (table.querySelector && table.querySelector('tr[role="row"]')) {
+        return true;
+    }
+
+    if (table.querySelector && table.querySelector('*[role="rowgroup"]')) {
+        return true;
+    }
+
+    if (table.hasAttribute && table.hasAttribute('datatable') && table.getAttribute('datatable') === '0') {
+        return false;
+    }
+
+    if (table.hasAttribute && table.hasAttribute('datatable') && table.getAttribute('datatable') === '1') {
+        return true;
+    }
+
+    // Check for table elements that indicate it's a data table
+    if (table.hasAttribute && (table.hasAttribute('summary') || table.hasAttribute('rules'))) {
+        return true;
+    }
+    
+    // Look for caption
+    if (table.querySelector && table.querySelector('caption')) {
+        return true;
+    }
+    
+    // Look for other data table indicators
+    if (table.querySelector && table.querySelector('col, colgroup, tfoot, thead, th, td[headers], td[scope], td[abbr], td[axis]')) {
+        return true;
+    }
+
+    if (table.querySelector && table.querySelector('table')) {
+        return false;
+    }
+
+    const rows = rowCount(table);
+    const cells = cellCount(table);
+    
+    if (rows === 1 || cells === 1) {
+        return false;
+    }
+
+    if (colCount(table) >= settings.numDTColumns) {
+        return true;
+    }
+
+    if (table.hasAttribute && table.hasAttribute('border') && table.getAttribute('border') !== '0') {
+        return true;
+    }
+
+    if (countBordersPct(table) > settings.pctCellsWBorder) {
+        return true;
+    }
+
+    try {
+        if (cellColorDiffs(table, settings.maxCellColors, settings.maxColorDiffs)) {
+            return true;
+        }
+    } catch (e) {
+        // Safely ignore errors in color difference calculation
+    }
+
+    if (rows >= settings.numDTRows) {
+        return true;
+    }
+
+    // Check if the table is too wide compared to the viewport
+    if (table.offsetWidth && document.documentElement && document.documentElement.clientWidth) {
+        const viewportWidth = document.documentElement.clientWidth;
+        if ((table.offsetWidth / viewportWidth) * 100 > settings.maxWidthLT) {
+            return false;
+        }
+    }
+    
+    if (cells <= settings.minCellsLT) {
+        return false;
+    }
+
+    if (table.querySelector && table.querySelector('embed, object, applet, iframe')) {
+        return false;
+    }
+
+    return true;
+}
+
+// Export the main function
+export { isDataTable };

package/src/isFocusable.js

@@ -0,0 +1,34 @@
+/**
+ * Determines if an element is focusable.
+ * @param {Element} element - The HTML element to check.
+ * @returns {boolean} - Returns true if the element is focusable, otherwise false.
+ */
+export function isFocusable(element) {
+    if (!element) return false;
+
+    const nodeName = element.nodeName.toLowerCase();
+    const tabIndex = element.getAttribute("tabindex");
+
+    // The element and all of its ancestors must be visible
+    if (element.closest(":hidden")) {
+        return false;
+    }
+
+    // If tabindex is defined, its value must be greater than or equal to 0
+    if (!isNaN(tabIndex) && tabIndex < 0) {
+        return false;
+    }
+
+    // If the element is a standard form control, it must not be disabled
+    if (/input|select|textarea|button|object/.test(nodeName)) {
+        return !element.disabled;
+    }
+
+    // If the element is a link, href must be defined
+    if (nodeName === "a" || nodeName === "area") {
+        return element.hasAttribute("href");
+    }
+
+    // This is some other page element that is not normally focusable
+    return false;
+}

package/src/isHidden.js

@@ -0,0 +1,17 @@
+
+/**
+ * Checks if a given DOM element is hidden.
+ *
+ * An element is considered hidden if its `display` style is set to "none"
+ * or if it has the `hidden` attribute.
+ *
+ * @param {HTMLElement} element - The DOM element to check.
+ * @returns {boolean} - Returns `true` if the element is hidden, otherwise `false`.
+ */
+const isHidden = (element) => {
+    return (
+        element.style.display === "none" || element.hasAttribute("hidden")
+    );
+};
+
+export default isHidden;

package/src/isOffScreen.js

@@ -0,0 +1,16 @@
+/**
+ * Checks if the selected element is off-screen.
+ * @param {Element} element - The element to check.
+ * @returns {boolean} - True if the element is off-screen, otherwise false.
+ */
+export function isOffScreen(element) {
+    if (!element) return false;
+
+    const rect = element.getBoundingClientRect();
+    return (
+        rect.right < 0 ||
+        rect.bottom < 0 ||
+        rect.left > window.innerWidth ||
+        rect.top > window.innerHeight
+    );
+}

package/src/isValidUrl.js

@@ -0,0 +1,13 @@
+/**
+ * Validate if a string is a valid URL.
+ * @param {string} str - The string to validate.
+ * @returns {boolean} - Returns true if the string is a valid URL, otherwise false.
+ */
+export function isValidUrl(str) {
+    try {
+        new URL(str);
+        return true;
+    } catch {
+        return false;
+    }
+}

package/src/isVisible.js

@@ -0,0 +1,62 @@
+/**
+ * Checks if the selected item is visible to assistive technologies.
+ * @param {Element} element - The element to check.
+ * @param {boolean} strict - Option to be more strict about visibility of aria-hidden="true" in addition to CSS display: none.
+ * @returns {boolean}
+ */
+export function isVisible(element, strict = false) {
+    if (!element) return false;
+
+    const id = element.id;
+    let visible = true;
+
+    // These elements are inherently not visible
+    const nonVisibleSelectors = [
+        'base', 'head', 'meta', 'title', 'link', 'style', 'script', 'br', 'nobr', 'col', 'embed',
+        'input[type="hidden"]', 'keygen', 'source', 'track', 'wbr', 'datalist', 'area', 'param', 'noframes', 'ruby > rp'
+    ];
+
+    if (nonVisibleSelectors.some(selector => element.matches(selector))) {
+        return true;
+    }
+
+    const optionalAriaHidden = (el, strictCheck) => strictCheck && el.getAttribute('aria-hidden') === 'true';
+
+    const isElemDisplayed = el => window.getComputedStyle(el).display === 'none';
+
+    const isHidden = () => {
+        if (isElemDisplayed(element)) return true;
+
+        let parent = element.parentElement;
+        while (parent) {
+            if (isElemDisplayed(parent)) return true;
+            parent = parent.parentElement;
+        }
+        return optionalAriaHidden(element, strict);
+    };
+
+    if (isHidden()) {
+        visible = false;
+    }
+
+    // Check if element is referenced by aria-labelledby or aria-describedby
+    document.querySelectorAll(`*[aria-labelledby~="${id}"], *[aria-describedby~="${id}"]`).forEach(referencingElement => {
+        if (window.getComputedStyle(referencingElement).display !== 'none') {
+            visible = true;
+        }
+    });
+
+    // Check if any parent has aria-hidden="true" when strict mode is on
+    if (visible && strict) {
+        let parent = element.parentElement;
+        while (parent) {
+            if (optionalAriaHidden(parent, strict)) {
+                visible = false;
+                break;
+            }
+            parent = parent.parentElement;
+        }
+    }
+
+    return visible;
+}

package/src/stringUtils.js

@@ -0,0 +1,150 @@
+const stringUtils = (function () {
+    /**
+     * Check if a string is empty or only contains whitespace.
+     * @param {string} str - The string to check.
+     * @returns {boolean} Whether the string is empty.
+     */
+    function isEmpty(str) {
+        return !str || str.trim().length === 0;
+    }
+
+    /**
+     * Check if a value is a string.
+     * @param {*} str - The value to check.
+     * @returns {boolean} Whether the value is a string.
+     */
+    function isString(str) {
+        return typeof str === "string" || str instanceof String;
+    }
+
+    /**
+     * Get the length of a trimmed string, or return 0 if not a valid string.
+     * @param {string} str - The string to measure.
+     * @returns {number} The string length or 0.
+     */
+    function strlen(str) {
+        return isString(str) && !isEmpty(str.trim()) ? str.trim().length : 0;
+    }
+
+    /**
+     * Utility function to check if the given string represents a positive integer
+     * @param {String} str to check
+     * @returns {boolean}
+     */
+    function isNormalInteger(str) {
+        const n = ~~Number(str);
+        return String(n) === str && n >= 0;
+    }
+
+    /**
+     * Determines if a string of text is completely uppercase. Allows (ignores) whitespace, numerics, and punctuation
+     * @param {String} str to check
+     * @returns {boolean}
+     */
+    function isUpperCase(str) {
+        if (str === undefined) {
+            return false;
+        }
+        let i = 0;
+        let char;
+        let isUpper = true;
+
+        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 === char.toLowerCase()) {
+                    isUpper = false;
+                }
+            }
+            i++;
+        }
+        return isUpper;
+    }
+
+    /**
+     * Does the string contain only alphanumeric characters?
+     * @param {String} str to check
+     * @returns {boolean}
+     */
+    function isAlphaNumeric(str) {
+        const pattern = "/^[a-zA-Z0-9]+$/";
+        return pattern.test(str);
+    }
+
+    /**
+     * Get the path from a URL
+     * @param {String} url a URL
+     * @returns {String}
+     */
+    function getPathFromUrl(url) {
+        const str = new URL(url);
+        return str.pathname;
+    }
+
+    /**
+     * Extracts and concatenates all text content from a given DOM element, including text from text nodes,
+     * elements with aria-label attributes, and alt attributes of img elements.
+     *
+     * @param {Element} el - The DOM element from which to extract text.
+     * @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
+        );
+        const textNodes = [];
+        let node, text;
+
+        while (walker.nextNode()) {
+            node = walker.currentNode;
+            if (node.nodeType === Node.TEXT_NODE) {
+                text = node.nodeValue.trim();
+                if (text) {
+                    textNodes.push(text);
+                } else {
+                    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"));
+                }
+            }
+        }
+
+        return textNodes.join(" ");
+    }
+
+    /**
+     * Checks if the given element contains any text.
+     *
+     * @param {HTMLElement} element - The element to check for text content.
+     * @returns {boolean} True if the element contains text, false otherwise.
+     */
+    function hasText(element) {
+        return getAllText(element).trim() !== "";
+    }
+
+    return {
+        isEmpty,
+        isString,
+        strlen,
+        isNormalInteger,
+        isUpperCase,
+        isAlphaNumeric,
+        getPathFromUrl,
+        getAllText,
+        hasText
+    };
+})();
+
+module.exports = stringUtils;