@afixt/test-utils 2.1.1 → 2.2.0

package/.claude/settings.local.json

@@ -18,7 +18,8 @@
       "Bash(node:*)",
       "Bash(npx vitest run:*)",
       "Bash(1)",
-      "Bash(npm run test:playwright:css:*)"
+      "Bash(npm run test:playwright:css:*)",
+      "Bash(gh issue:*)"
     ]
   },
   "enableAllProjectMcpServers": false

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@afixt/test-utils",
-    "version": "2.1.1",
+    "version": "2.2.0",
     "description": "Various utilities for accessibility testing",
     "main": "src/index.js",
     "scripts": {

package/src/constants.js

@@ -404,6 +404,7 @@ const NON_VISIBLE_SELECTORS = [
     'param',
     'noframes',
     'ruby > rp',
+    'template',
 ];
 
 /**

package/src/domUtils.js

@@ -7,6 +7,17 @@ const {
     INTERACTIVE_HANDLER_ATTRIBUTES,
 } = require('./constants.js');
 
+/**
+ * Escapes a string for use inside a CSS selector.
+ * Uses the native CSS.escape when available (all modern browsers),
+ * falls back to identity for environments that lack it (e.g. JSDOM).
+ *
+ * @param {string} value
+ * @returns {string}
+ */
+const cssEscape =
+    typeof CSS !== 'undefined' && typeof CSS.escape === 'function' ? CSS.escape : value => value;
+
 const domUtils = {
     /**
      * Checks if the specified element has the given attribute.
@@ -108,7 +119,7 @@ const domUtils = {
                 duplicates.push(id);
             }
         });
-        return duplicates.map(id => document.querySelector(`#${id}`));
+        return duplicates.map(id => document.querySelector(`#${cssEscape(id)}`));
     },
 
     /**
@@ -162,7 +173,7 @@ const domUtils = {
         }
 
         // CSS-escape the ID for use in attribute selectors
-        const escaped = CSS.escape(id);
+        const escaped = cssEscape(id);
 
         // Direct attribute references
         if (document.querySelector('[for="' + escaped + '"]')) {
@@ -226,10 +237,31 @@ const domUtils = {
         if (!element) {
             return false;
         }
-        return (
+
+        // Check aria-hidden (self or ancestor)
+        if (
             element.getAttribute('aria-hidden') === 'true' ||
             (element.closest && !!element.closest('[aria-hidden="true"]'))
-        );
+        ) {
+            return true;
+        }
+
+        // Check inert (self or ancestor) — inert elements are removed from the a11y tree
+        let el = element;
+        while (el) {
+            if (el.hasAttribute && el.hasAttribute('inert')) {
+                return true;
+            }
+            el = el.parentElement;
+        }
+
+        // Check content-visibility: hidden — genuinely hides content from AT
+        const style = window.getComputedStyle(element);
+        if (style.contentVisibility === 'hidden') {
+            return true;
+        }
+
+        return false;
     },
 
     /**
@@ -397,3 +429,4 @@ const domUtils = {
 };
 
 module.exports = domUtils;
+module.exports.cssEscape = cssEscape;

package/src/formUtils.js

@@ -3,6 +3,8 @@
  * @module formUtils
  */
 
+const { isHiddenFromAT } = require('./domUtils.js');
+
 const formUtils = {
     /**
      * Check if an element is a labellable form control per HTML spec.
@@ -50,7 +52,7 @@ const formUtils = {
             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()) {
+                if (labelEl && !isHiddenFromAT(labelEl) && labelEl.textContent.trim()) {
                     return true;
                 }
             }

package/src/getAccessibleName.js

@@ -1,4 +1,4 @@
-const { isEmpty } = require('./stringUtils.js');
+const { isEmptyOrWhitespace } = require('./stringUtils.js');
 const { getAccessibleText } = require('./getAccessibleText.js');
 const {
     TEXT_ROLES,
@@ -6,6 +6,8 @@ const {
     LANDMARK_ROLES,
     LANDMARK_ELEMENT_MAP,
 } = require('./constants.js');
+const { cssEscape } = require('./domUtils.js');
+const { isA11yVisible } = require('./isA11yVisible.js');
 
 /**
  * Gets the accessible name of an element according to the accessible name calculation algorithm
@@ -26,9 +28,21 @@ function getAccessibleName(element) {
     // the title won't be used in any meaningful way by Accessibility APIs
     const unlabellable = 'head *, hr, param, caption, colgroup, col, tbody, tfoot, thead, tr';
 
-    // STEP 0 - verify item is visible and can be labelled
-    // if it isn't visible or can't be labelled then just bail
-    if (isNotVisible(element) || matchesSelector(element, unlabellable)) {
+    if (matchesSelector(element, unlabellable)) {
+        return false;
+    }
+
+    // Skip inherently non-visible semantic elements (script, style, template, etc.)
+    // but exclude 'area' since area elements have accessible names via alt attribute
+    const nonVisibleSelectorsWithoutArea = NON_VISIBLE_SELECTORS.filter(s => s !== 'area');
+    if (nonVisibleSelectorsWithoutArea.some(selector => matchesSelector(element, selector))) {
+        return false;
+    }
+
+    // STEP 0 - Use isA11yVisible (strict mode) for visibility check.
+    // This respects aria-labelledby/describedby references, preventing false
+    // negatives for display:none elements that provide names to other elements.
+    if (!isA11yVisible(element, true)) {
         return false;
     }
 
@@ -58,7 +72,7 @@ function getAccessibleName(element) {
     // STEP 2.1 - if aria-label exists, return the text in it
     if (element.hasAttribute('aria-label')) {
         const ariaLabel = element.getAttribute('aria-label');
-        if (ariaLabel) {
+        if (!isEmptyOrWhitespace(ariaLabel)) {
             return ariaLabel;
         }
         // there is no 'else' here because an empty aria-label is/ should be ignored and calculation continued
@@ -75,7 +89,7 @@ function getAccessibleName(element) {
             // Use getAccessibleText which handles both text nodes and
             // image alt text in the subtree (not just textContent)
             const text = getAccessibleText(element);
-            if (!isEmpty(text)) {
+            if (!isEmptyOrWhitespace(text)) {
                 return text;
             }
         }
@@ -95,12 +109,12 @@ function getAccessibleName(element) {
         )
     ) {
         // first we choose the explicit relationship over all others.
-        if (element.id && document.querySelector('label[for="' + element.id + '"]')) {
+        if (element.id && document.querySelector('label[for="' + cssEscape(element.id) + '"]')) {
             id = element.id;
             // Use only the *first* label that matches this ID.
             // Sometimes JS libraries screw this up by hiding one of the
             // labels or misnaming one
-            label = document.querySelector('label[for="' + id + '"]');
+            label = document.querySelector('label[for="' + cssEscape(id) + '"]');
             if (label) {
                 return getAccessibleText(label);
             }
@@ -210,11 +224,11 @@ function getAccessibleName(element) {
         )
     ) {
         // first we choose the explicit relationship over all others.
-        if (element.id && document.querySelector('label[for="' + element.id + '"]')) {
+        if (element.id && document.querySelector('label[for="' + cssEscape(element.id) + '"]')) {
             id = element.id;
 
             //Use only the *first* label that matches this ID. Sometimes ppl screw this up
-            label = document.querySelector('label[for="' + id + '"]');
+            label = document.querySelector('label[for="' + cssEscape(id) + '"]');
             if (label) {
                 return getAccessibleText(label);
             }
@@ -359,7 +373,7 @@ function getAccessibleName(element) {
         if (element.tagName.toLowerCase() === 'meter') {
             // Check for label with for attribute
             if (element.id) {
-                const label = document.querySelector('label[for="' + element.id + '"]');
+                const label = document.querySelector('label[for="' + cssEscape(element.id) + '"]');
                 if (label && strlen(getAccessibleText(label)) > 0) {
                     return getAccessibleText(label);
                 }
@@ -474,44 +488,6 @@ function getAccessibleName(element) {
     }
 }
 
-/**
- * Helper function to check if element is NOT visible
- * @param {Element} element - The element to check
- * @returns {boolean} True if element is not visible, false otherwise
- */
-function isNotVisible(element) {
-    // Importing isVisible would be better, but for this standalone function we'll check it this way
-    if (!element) {
-        return true;
-    }
-
-    // Note: 'area' is filtered out because area elements DO have accessible names
-    // via the alt attribute and should participate in accessible name calculation
-    const nonVisibleSelectorsWithoutArea = NON_VISIBLE_SELECTORS.filter(s => s !== 'area');
-
-    if (nonVisibleSelectorsWithoutArea.some(selector => matchesSelector(element, selector))) {
-        return true; // Not visible in accessibility tree
-    }
-
-    // Check if display is none
-    const isElemDisplayed = el => window.getComputedStyle(el).display === 'none';
-
-    if (isElemDisplayed(element)) {
-        return true;
-    }
-
-    // Check parent elements
-    let parent = element.parentElement;
-    while (parent) {
-        if (isElemDisplayed(parent)) {
-            return true;
-        }
-        parent = parent.parentElement;
-    }
-
-    return element.getAttribute('aria-hidden') === 'true';
-}
-
 /**
  * Helper function to check if an element matches a selector
  * @param {Element} element - Element to check
@@ -541,7 +517,7 @@ function matchesSelector(element, selector) {
  * @returns {number} The string length or 0
  */
 function strlen(str) {
-    return typeof str === 'string' && !isEmpty(str.trim()) ? str.trim().length : 0;
+    return typeof str === 'string' && !isEmptyOrWhitespace(str) ? str.trim().length : 0;
 }
 
 // Export the function for CommonJS module usage

package/src/getAccessibleText.js

@@ -1,4 +1,4 @@
-const { isEmpty } = require('./stringUtils.js');
+const { isEmptyOrWhitespace } = require('./stringUtils.js');
 
 /**
  * Get all accessible text for an element, including aria-labels and content from children.
@@ -27,7 +27,7 @@ function getAccessibleText(el, options) {
         // Check for aria-label first (highest priority)
         if (el.hasAttribute('aria-label')) {
             const ariaLabel = el.getAttribute('aria-label').trim();
-            if (ariaLabel) {
+            if (!isEmptyOrWhitespace(ariaLabel)) {
                 return ariaLabel;
             }
         }
@@ -65,7 +65,7 @@ function collectSubtreeText(node, visibleOnly) {
     for (let child = node.firstChild; child; child = child.nextSibling) {
         if (child.nodeType === Node.TEXT_NODE) {
             const text = child.nodeValue.trim();
-            if (!isEmpty(text)) {
+            if (!isEmptyOrWhitespace(text)) {
                 parts.push(text);
             }
         } else if (child.nodeType === Node.ELEMENT_NODE) {

package/src/getComputedRole.js

@@ -1,65 +1,65 @@
 const roleMapping = {
-    'a': {
+    a: {
         '[href]': 'link',
-        ':not([href])': 'text'
+        ':not([href])': 'text',
     },
-    'abbr': 'text',
-    'address': 'text',
-    'area': {
+    abbr: 'text',
+    address: 'text',
+    area: {
         '[href]': 'link',
-        ':not([href])': 'text'
+        ':not([href])': 'text',
     },
-    'article': 'article',
-    'aside': 'complementary',
-    'audio': 'group',
-    'b': 'text',
-    'base': 'noRole',
-    'bdi': 'noRole',
-    'bdo': 'text',
-    'blockquote': 'text',
-    'body': 'document',
-    'br': 'noRole',
-    'button': 'button',
-    'canvas': 'image',
-    'caption': 'text',
-    'cite': 'text',
-    'code': 'text',
-    'col': 'noRole',
-    'colgroup': 'group',
-    'data': 'noRole',
-    'datalist': 'listbox',
-    'dd': 'definition',
-    'del': 'text',
-    'details': 'group',
-    'dfn': 'term',
-    'dialog': 'dialog',
-    'div': 'group',
-    'dl': 'list',
-    'dt': 'term',
-    'em': 'text',
-    'embed': 'noRole',
-    'fieldset': 'group',
-    'figcaption': 'text',
-    'figure': 'figure',
-    'footer': 'contentinfo',
-    'form': 'form',
-    'h1': 'heading',
-    'h2': 'heading',
-    'h3': 'heading',
-    'h4': 'heading',
-    'h5': 'heading',
-    'h6': 'heading',
-    'head': 'noRole',
-    'header': 'banner',
-    'hr': 'separator',
-    'html': 'noRole',
-    'i': 'text',
-    'iframe': 'noRole',
-    'img': {
+    article: 'article',
+    aside: 'complementary',
+    audio: 'group',
+    b: 'text',
+    base: 'noRole',
+    bdi: 'noRole',
+    bdo: 'text',
+    blockquote: 'text',
+    body: 'document',
+    br: 'noRole',
+    button: 'button',
+    canvas: 'image',
+    caption: 'text',
+    cite: 'text',
+    code: 'text',
+    col: 'noRole',
+    colgroup: 'group',
+    data: 'noRole',
+    datalist: 'listbox',
+    dd: 'definition',
+    del: 'text',
+    details: 'group',
+    dfn: 'term',
+    dialog: 'dialog',
+    div: 'group',
+    dl: 'list',
+    dt: 'term',
+    em: 'text',
+    embed: 'noRole',
+    fieldset: 'group',
+    figcaption: 'text',
+    figure: 'figure',
+    footer: 'contentinfo',
+    form: 'form',
+    h1: 'heading',
+    h2: 'heading',
+    h3: 'heading',
+    h4: 'heading',
+    h5: 'heading',
+    h6: 'heading',
+    head: 'noRole',
+    header: 'banner',
+    hr: 'separator',
+    html: 'noRole',
+    i: 'text',
+    iframe: 'noRole',
+    img: {
         '[alt=""]': 'presentation',
-        'img': 'image'
+        img: 'image',
     },
-    'input': {
+    input: {
         '[type="button"]': 'button',
         '[type="checkbox"]': 'checkbox',
         '[type="hidden"]': 'noRole',
@@ -74,85 +74,150 @@ const roleMapping = {
         '[type="search"]': 'searchbox',
         '[type="tel"]': 'textbox',
         '[type="text"]': 'textbox',
-        '[type="url"]': 'textbox'
+        '[type="url"]': 'textbox',
     },
-    'ins': 'text',
-    'kbd': 'text',
-    'label': 'text',
-    'legend': 'text',
-    'li': 'listitem',
-    'link': 'noRole',
-    'main': 'main',
-    'map': 'noRole',
-    'mark': 'text',
-    'math': 'math',
-    'menu': 'menu',
-    'meta': 'noRole',
-    'meter': 'text',
-    'nav': 'navigation',
-    'noscript': 'noRole',
-    'object': 'noRole',
-    'ol': 'list',
-    'optgroup': 'group',
-    'option': 'option',
-    'output': 'status',
-    'p': 'text',
-    'param': 'noRole',
-    'picture': 'noRole',
-    'pre': 'text',
-    'progress': 'progressbar',
-    'q': 'text',
-    'rb': 'noRole',
-    'rp': 'noRole',
-    'rt': 'text',
-    'rtc': 'noRole',
-    'ruby': 'text',
-    's': 'text',
-    'samp': 'text',
-    'script': 'noRole',
-    'section': 'region',
-    'select': 'combobox',
-    'small': 'text',
-    'source': 'noRole',
-    'span': 'group',
-    'strong': 'text',
-    'style': 'noRole',
-    'sub': 'text',
-    'summary': 'button',
-    'sup': 'text',
-    'svg': 'noRole',
-    'table': 'table',
-    'tbody': 'rowgroup',
-    'td': 'cell',
-    'template': 'noRole',
-    'textarea': 'textbox',
-    'tfoot': 'rowgroup',
-    'th': 'columnheader',
-    'thead': 'rowgroup',
-    'time': 'text',
-    'title': 'noRole',
-    'tr': 'row',
-    'track': 'noRole',
-    'u': 'text',
-    'ul': 'list',
-    'var': 'text',
-    'video': 'group',
-    'wbr': 'noRole'
+    ins: 'text',
+    kbd: 'text',
+    label: 'text',
+    legend: 'text',
+    li: 'listitem',
+    link: 'noRole',
+    main: 'main',
+    map: 'noRole',
+    mark: 'text',
+    math: 'math',
+    menu: 'menu',
+    meta: 'noRole',
+    meter: 'text',
+    nav: 'navigation',
+    noscript: 'noRole',
+    object: 'noRole',
+    ol: 'list',
+    optgroup: 'group',
+    option: 'option',
+    output: 'status',
+    p: 'text',
+    param: 'noRole',
+    picture: 'noRole',
+    pre: 'text',
+    progress: 'progressbar',
+    q: 'text',
+    rb: 'noRole',
+    rp: 'noRole',
+    rt: 'text',
+    rtc: 'noRole',
+    ruby: 'text',
+    s: 'text',
+    samp: 'text',
+    script: 'noRole',
+    section: 'region',
+    select: 'combobox',
+    small: 'text',
+    source: 'noRole',
+    span: 'group',
+    strong: 'text',
+    style: 'noRole',
+    sub: 'text',
+    summary: 'button',
+    sup: 'text',
+    svg: 'noRole',
+    table: 'table',
+    tbody: 'rowgroup',
+    td: 'cell',
+    template: 'noRole',
+    textarea: 'textbox',
+    tfoot: 'rowgroup',
+    th: 'columnheader',
+    thead: 'rowgroup',
+    time: 'text',
+    title: 'noRole',
+    tr: 'row',
+    track: 'noRole',
+    u: 'text',
+    ul: 'list',
+    var: 'text',
+    video: 'group',
+    wbr: 'noRole',
 };
 
 /**
- * Gets the computed role of an HTML element.
+ * Sectioning elements that change the implicit role of header/footer
+ * from landmark (banner/contentinfo) to generic.
+ */
+const SECTIONING_ELEMENTS = ['article', 'aside', 'main', 'nav', 'section'];
+
+/**
+ * Check if an element has an ancestor with a given role or tag name.
+ * @param {HTMLElement} element - The element to check
+ * @param {Object} options - Search options
+ * @param {string[]} [options.roles] - ARIA roles to match
+ * @param {string[]} [options.tags] - Tag names (lowercase) to match
+ * @returns {boolean} True if a matching ancestor is found
+ */
+function hasAncestor(element, { roles = [], tags = [] }) {
+    let ancestor = element.parentElement;
+    while (ancestor) {
+        const ancestorRole = (ancestor.getAttribute('role') || '').toLowerCase();
+        if (roles.length && roles.includes(ancestorRole)) {
+            return true;
+        }
+        const ancestorTag = ancestor.tagName.toLowerCase();
+        if (tags.length && tags.includes(ancestorTag)) {
+            return true;
+        }
+        ancestor = ancestor.parentElement;
+    }
+    return false;
+}
+
+/**
+ * Gets the computed role of an HTML element, considering ancestor context
+ * for context-dependent implicit roles per HTML-AAM.
  *
  * @param {HTMLElement} element - The HTML element to get the role for.
  * @returns {string|undefined} The computed role of the element, or undefined if no role is found.
  */
 function getComputedRole(element) {
-    if (!element) return undefined;
+    if (!element) {
+        return undefined;
+    }
 
     const roleAttr = element.getAttribute('role');
-    if (roleAttr) return roleAttr;
+    if (roleAttr) {
+        return roleAttr;
+    }
 
     const tagName = element.tagName.toLowerCase();
+
+    // Context-dependent implicit roles per HTML-AAM
+    if (tagName === 'td') {
+        if (hasAncestor(element, { roles: ['grid', 'treegrid'] })) {
+            return 'gridcell';
+        }
+        return 'cell';
+    }
+
+    if (tagName === 'th') {
+        if (hasAncestor(element, { roles: ['grid', 'treegrid'] })) {
+            return 'columnheader';
+        }
+        return 'columnheader';
+    }
+
+    if (tagName === 'header') {
+        if (hasAncestor(element, { tags: SECTIONING_ELEMENTS })) {
+            return 'generic';
+        }
+        return 'banner';
+    }
+
+    if (tagName === 'footer') {
+        if (hasAncestor(element, { tags: SECTIONING_ELEMENTS })) {
+            return 'generic';
+        }
+        return 'contentinfo';
+    }
+
     const role = roleMapping[tagName];
 
     if (typeof role === 'string') {
@@ -170,5 +235,5 @@ function getComputedRole(element) {
 
 module.exports = {
     roleMapping,
-    getComputedRole
+    getComputedRole,
 };

package/src/getImageText.js

@@ -26,7 +26,10 @@ async function getImageText(imagePath, options = {}) {
     try {
         const {
             data: { text },
-        } = await _internal.recognize(imagePath, lang, { logger, ...tesseractOptions });
+            // errorHandler silences the bare `throw` in tesseract.js createWorker.js when a
+            // job is rejected — without it the throw escapes try/catch and becomes an uncaught
+            // exception in the host process. The promise rejection is still caught below.
+        } = await _internal.recognize(imagePath, lang, { logger, errorHandler: () => {}, ...tesseractOptions });
 
         const extractedText = text.trim();
         return extractedText.length > 0 ? extractedText : false;

package/src/isA11yVisible.js

@@ -1,5 +1,6 @@
 const { NON_VISIBLE_SELECTORS } = require('./constants.js');
 const isHidden = require('./isHidden.js');
+const { cssEscape } = require('./domUtils.js');
 
 /**
  * Checks if an element is visible to assistive technologies (AT).
@@ -67,8 +68,11 @@ function isA11yVisible(element, strict = false) {
     }
 
     // Check if element is referenced by aria-labelledby or aria-describedby
+    // Use CSS.escape(id) to handle IDs containing special characters like colons
+    // (e.g. Radix UI generates IDs like "radix-:rj:-tab-account")
+    const escapedId = id ? cssEscape(id) : '';
     document
-        .querySelectorAll(`*[aria-labelledby~="${id}"], *[aria-describedby~="${id}"]`)
+        .querySelectorAll(`*[aria-labelledby~="${escapedId}"], *[aria-describedby~="${escapedId}"]`)
         .forEach(referencingElement => {
             if (window.getComputedStyle(referencingElement).display !== 'none') {
                 visible = true;