@surea11y/core 1.7.0 → 1.8.0

package/src/checks/automatic/page-title-present.js

@@ -16,8 +16,11 @@
  *   The document has a <title> element, and document.title with whitespace
  *   collapsed is non-empty. The element is looked for anywhere in the
  *   document, not only inside <head>: a <title> the parser leaves outside
- *   <head> is still the document title in every browser. Whether that title
- *   describes the page is page-title-patterns' question.
+ *   <head> is still the document title in every browser. Only an
+ *   HTML-namespace <title> counts; the <title> of an inline <svg> names the
+ *   graphic, so a page whose only <title> is inside an <svg> is missing its
+ *   title element. Whether that title describes the page is
+ *   page-title-patterns' question.
  */
 
 const id = 'page-title-present';
@@ -66,8 +69,17 @@ function runInPage(ctx) {
   // after <head> has closed is not re-parented into <head>, yet the browser
   // (and document.title, used below) still recognizes it as the document's
   // title, matching that here avoids a false "missing title" report for a
-  // <title> that legitimately ended up outside <head>.
-  const titleEl = document.querySelector('title');
+  // <title> that legitimately ended up outside <head>. Only an HTML-namespace
+  // <title> counts: an inline <svg><title> names the graphic, not the page,
+  // and document.title ignores it.
+  const HTML_NS = 'http://www.w3.org/1999/xhtml';
+  let titleEl = null;
+  for (const t of Array.from(document.getElementsByTagName('title'))) {
+    if (!t.namespaceURI || t.namespaceURI === HTML_NS) {
+      titleEl = t;
+      break;
+    }
+  }
   const titleText = (document.title || '').replace(/\s+/g, ' ').trim();
 
   const missingTitleEl = !titleEl;

package/src/checks/automatic/progressbar-name-present.js

@@ -18,7 +18,8 @@
  *   aria-labelledby that resolves to non-empty text, or from title.
  *   role="progressbar" is name-from-author-only, so subtree text is never
  *   accepted: text sitting inside a custom progressbar widget is not
- *   reliably exposed as its name.
+ *   reliably exposed as its name. On a labelable element
+ *   (<progress role="progressbar">) an associated <label> counts as well.
  */
 
 const id = 'progressbar-name-present';
@@ -124,6 +125,15 @@ function runInPage(ctx) {
     const title = getAttr(el, 'title');
     if (title) return { ok: true, method: 'title' };
 
+    // An associated <label> on a labelable host
+    // (<progress role="progressbar">, <meter role="progressbar">).
+    if (helpers.getNativeHostNameInfo) {
+      try {
+        const host = helpers.getNativeHostNameInfo(el, ctx);
+        if (host && host.present) return { ok: true, method: host.mechanism };
+      } catch {}
+    }
+
     // role="progressbar" is name-from-author-only per WAI-ARIA: aria-label,
     // aria-labelledby, or title, no content-based naming method at all. It
     // must NOT fall back to subtree content: e.g. a <ul role="progressbar">

package/src/checks/automatic/role-img-text-alternative-present.js

@@ -17,9 +17,10 @@
  *   aria-hidden-focus and duplicate-id-aria own those separately). Per ACT
  *   7d6734, this reaches any element carrying one of these roles, not only
  *   the <svg> root, e.g. a <circle role="graphics-symbol"> nested inside a
- *   plain <svg>. The <svg> root itself is left to svg-text-alternative-present's
- *   own (already ACT-clean) title/aria-name handling; the <img> tag is
- *   excluded here since it has its own dedicated rule.
+ *   plain <svg>. Every <svg> element itself is left to
+ *   svg-text-alternative-present's own (already ACT-clean) title/aria-name
+ *   handling, so an unnamed <svg role="img"> is reported once, there; the
+ *   <img> tag is excluded here since it has its own dedicated rule.
  * @expectation
  *   Each applicable element has an accessible text alternative:
  *    - aria-label with a non-empty value; OR
@@ -95,8 +96,11 @@ function runInPage(ctx) {
   };
 
   const imgElements = (() => {
-    // do not consider element "img" because it has its own rule
-    const sel = '[role="img" i]:not(img), [role="graphics-symbol" i], [role="graphics-document" i]';
+    // <img> and <svg> are left out: each has its own rule
+    // (img-alt-present, svg-text-alternative-present), and counting an
+    // unnamed <svg role="img"> here too would report it twice.
+    const sel =
+      '[role="img" i]:not(img):not(svg), [role="graphics-symbol" i]:not(svg), [role="graphics-document" i]:not(svg)';
     try {
       return Array.from((queryAllSmart ? queryAllSmart(sel) : queryAll(sel)) || []);
     } catch {

package/src/checks/automatic/searchbox-name-present.js

@@ -20,6 +20,9 @@
  *   accepted: text sitting inside a custom searchbox widget is not reliably
  *   exposed as its name. On a labelable element (<input role="searchbox">)
  *   an associated <label> counts as well.
+ *   On a text-like <input> or a <textarea>, the placeholder counts last
+ *   (HTML-AAM's final name source): a placeholder-only label is a 3.3.2
+ *   question, not a missing name.
  */
 
 const id = 'searchbox-name-present';
@@ -149,21 +152,6 @@ function runInPage(ctx) {
     }
   }
 
-  function buildLabelForMap(doc) {
-    const map = new Map(); // id -> label element (first)
-    try {
-      const labels = doc && doc.getElementsByTagName ? doc.getElementsByTagName('label') : [];
-      for (let i = 0; i < labels.length; i += 1) {
-        const lab = labels[i];
-        if (!lab || !lab.getAttribute) continue;
-        const f = normalizeWs(lab.getAttribute('for'));
-        if (!f) continue;
-        if (!map.has(f)) map.set(f, lab);
-      }
-    } catch {}
-    return map;
-  }
-
   const occurrences = [];
   let applicableCount = 0;
 
@@ -172,42 +160,27 @@ function runInPage(ctx) {
     ? helpers.queryAllSmart(selector)
     : helpers.queryAll(selector);
 
-  // Precompute label[for] map for searchbox elements that are labelable
-  // native form controls (e.g. <input role="searchbox">).
-  const labelForMap = buildLabelForMap(document);
-
+  // Delegates to the shared, spec-guarded lookup (dom-helpers.js's
+  // getAssociatedLabelElements): a <label> -- wrapping or via `for` --
+  // only ever associates with a genuinely labelable element, so this
+  // correctly returns nothing for role-only widgets a <label> merely sits
+  // next to, and the real thing for a labelable element like
+  // <input role="searchbox">.
   function getNativeLabelText(el) {
+    if (!helpers || typeof helpers.getAssociatedLabelElements !== 'function') return '';
+    let labels;
     try {
-      if ('labels' in el && el.labels && el.labels.length) {
-        const parts = [];
-        const max = Math.min(4, el.labels.length);
-        for (let i = 0; i < max; i += 1) {
-          const lab = el.labels[i];
-          const t = lab ? getLabelText(lab) : '';
-          if (t) parts.push(t);
-        }
-        const joined = normalizeWs(parts.join(' '));
-        if (joined) return joined;
-      }
-    } catch {}
-    try {
-      if (el.closest) {
-        const wrap = el.closest('label');
-        if (wrap) {
-          const t = getLabelText(wrap);
-          if (t) return t;
-        }
-      }
-    } catch {}
-    try {
-      const idAttr = getAttr(el, 'id');
-      if (idAttr && labelForMap.has(idAttr)) {
-        const lab = labelForMap.get(idAttr);
-        const t = lab ? getLabelText(lab) : '';
-        if (t) return t;
-      }
-    } catch {}
-    return '';
+      labels = helpers.getAssociatedLabelElements(el) || [];
+    } catch {
+      labels = [];
+    }
+    const parts = [];
+    const max = Math.min(4, labels.length);
+    for (let i = 0; i < max; i += 1) {
+      const t = getLabelText(labels[i]);
+      if (t) parts.push(t);
+    }
+    return normalizeWs(parts.join(' '));
   }
 
   function hasName(el) {
@@ -224,6 +197,16 @@ function runInPage(ctx) {
     const lab = getNativeLabelText(el);
     if (lab) return { ok: true, method: 'label' };
 
+    // HTML-AAM's last name source for a text-like <input> or a <textarea>,
+    // after title: the placeholder. A placeholder-only label is a 3.3.2
+    // question, not a missing name.
+    if (helpers.getNativeHostNameInfo) {
+      try {
+        const host = helpers.getNativeHostNameInfo(el, ctx, { placeholder: true });
+        if (host && host.present) return { ok: true, method: host.mechanism };
+      } catch {}
+    }
+
     // role="searchbox" is name-from-author-only per WAI-ARIA: it must NOT
     // fall back to subtree content.
     return { ok: false, method: 'none' };

package/src/checks/automatic/server-side-image-map-absent.js

@@ -5,29 +5,34 @@
 /**
  * @check server-side-image-map-absent
  * @atomic true
- * @summary <img> must not use a server-side image map (ismap)
+ * @summary A server-side image map (ismap) needs a keyboard-operable alternative
  * @standard WCAG 2.2
  * @sc 2.1.1
  * @applicability
- *   Applies to <img> elements that carry an ismap attribute.
+ *   Applies to any scan scope. An <img ismap> inside an <a href> is a
+ *   server-side image map: the browser sends the click coordinates to the
+ *   link's URL, which has no keyboard-operable equivalent and exposes no
+ *   individual regions to assistive technology.
  * @expectation
- *   The image does not use ismap at all. Server-side image maps depend on
- *   the browser sending click coordinates to the server, which has no
- *   keyboard-operable equivalent, there is no way to determine or expose
- *   individual clickable regions to assistive technology or keyboard
- *   users. Client-side image maps (<map>/<area>, each with real href/alt)
- *   are the accessible alternative and are not flagged by this rule.
+ *   Each server-side image map is reported as cantTell: 2.1.1 is met when
+ *   the same destinations are also offered as links a keyboard can reach,
+ *   which the rule cannot verify.
+ *   Client-side image maps (<map>/<area>) are not flagged.
+ *   A scope with no <img ismap> passes. One whose only <img ismap> elements
+ *   are outside a link is notApplicable: ismap does nothing there, so there
+ *   is no server-side image map (the misplaced attribute is invalid HTML,
+ *   a matter for the validator).
  * @implementation-notes
- * - Presence of ismap is itself the violation (there is no automatable way
- *   to verify a "usable alternative" exists elsewhere on the page).
+ * - There is no automatable way to verify that a usable alternative exists
+ *   elsewhere on the page, so the rule never fails.
  */
 
 const id = 'server-side-image-map-absent';
 
 const meta = {
-  title: 'Images must not use a server-side image map',
+  title: 'Server-side image maps must have a keyboard-operable alternative',
   description:
-    'Checks that <img> elements do not carry the ismap attribute (server-side image maps have no keyboard-operable equivalent).',
+    'Asks, for each <img ismap> inside a link, whether the page offers the same destinations as links a keyboard can reach, since a server-side image map has no keyboard-operable regions of its own.',
   i18n: {
     titleKey: 'serverSideImageMapAbsent_title',
     descriptionKey: 'serverSideImageMapAbsent_description'
@@ -59,23 +64,36 @@ function runInPage(ctx) {
     : helpers.queryAll('img[ismap]');
 
   const occurrences = [];
-  let applicableCount = 0;
 
   for (const el of nodes) {
     if (!el) continue;
 
-    applicableCount += 1;
+    // ismap does something only on an image inside a hyperlink.
+    let link;
+    try {
+      link = el.closest ? el.closest('a[href]') : null;
+    } catch {
+      link = null;
+    }
+    if (!link) continue;
 
     occurrences.push(
       helpers.reportOccurrence(el, {
         summary:
-          'This image uses a server-side image map, which has no keyboard-operable equivalent.',
-        hint: 'Replace the server-side image map (ismap) with a client-side image map (<map>/<area>) or separate accessible links/buttons.',
+          'This image is a server-side image map (ismap inside a link), whose regions cannot be reached from the keyboard.',
+        hint: 'Check that the page offers the same destinations as separate links. Better: replace the server-side image map with a client-side image map (<map>/<area>) or separate links/buttons.',
+        occurrenceOutcome: 'cantTell',
         i18n: {
-          summaryKey: 'serverSideImageMapAbsent_summary_fail',
-          hintKey: 'serverSideImageMapAbsent_hint_fail',
+          summaryKey: 'serverSideImageMapAbsent_summary_cantTell',
+          hintKey: 'serverSideImageMapAbsent_hint_cantTell',
           params: {}
         },
+        uncertainty: {
+          code: 'equivalence-unknown',
+          needed:
+            'Whether the destinations of this image map are also offered as keyboard-operable links.',
+          evidence: { href: link.getAttribute('href') }
+        },
         data: {
           details: { reasonCode: 'SERVER_SIDE_IMAGE_MAP' }
         }
@@ -83,18 +101,20 @@ function runInPage(ctx) {
     );
   }
 
-  if (applicableCount === 0) {
-    return { ruleId: rule.ruleId, outcome: 'notApplicable', severity: 'minor', occurrences: [] };
+  // No <img ismap> at all is the passing case (see @expectation above);
+  // ismap only outside links means there is no server-side image map.
+  if (!nodes.length) {
+    return { ruleId: rule.ruleId, outcome: 'pass', severity: 'minor', occurrences: [] };
   }
-  if (occurrences.length) {
-    return {
-      ruleId: rule.ruleId,
-      outcome: 'fail',
-      severity: rule.defaultSeverity || 'serious',
-      occurrences
-    };
+  if (!occurrences.length) {
+    return { ruleId: rule.ruleId, outcome: 'notApplicable', severity: 'minor', occurrences: [] };
   }
-  return { ruleId: rule.ruleId, outcome: 'pass', severity: 'minor', occurrences: [] };
+  return {
+    ruleId: rule.ruleId,
+    outcome: 'cantTell',
+    severity: rule.defaultSeverity || 'serious',
+    occurrences
+  };
 }
 
 module.exports = { id, meta, runInPage };

package/src/checks/automatic/slider-name-present.js

@@ -21,6 +21,9 @@
  *   accepted: text sitting inside a custom slider widget is not reliably
  *   exposed as its name. On a labelable element (<input role="slider">) an
  *   associated <label> counts as well.
+ *   On a text-like <input> or a <textarea>, the placeholder counts last
+ *   (HTML-AAM's final name source): a placeholder-only label is a 3.3.2
+ *   question, not a missing name.
  */
 
 const id = 'slider-name-present';
@@ -72,21 +75,6 @@ function runInPage(ctx) {
     }
   }
 
-  function buildLabelForMap(doc) {
-    const map = new Map(); // id -> label element (first)
-    try {
-      const labels = doc && doc.getElementsByTagName ? doc.getElementsByTagName('label') : [];
-      for (let i = 0; i < labels.length; i += 1) {
-        const lab = labels[i];
-        if (!lab || !lab.getAttribute) continue;
-        const f = normalizeWs(lab.getAttribute('for'));
-        if (!f) continue;
-        if (!map.has(f)) map.set(f, lab);
-      }
-    } catch {}
-    return map;
-  }
-
   function getConservativeSubtreeText(document, container) {
     // "Name from content", recurses into descendants and uses each one's
     // own accessible name (img alt, aria-label/aria-labelledby, title) when
@@ -176,41 +164,27 @@ function runInPage(ctx) {
     ? helpers.queryAllSmart(selector)
     : helpers.queryAll(selector);
 
-  // Precompute label[for] map for native range inputs.
-  const labelForMap = buildLabelForMap(document);
-
+  // Delegates to the shared, spec-guarded lookup (dom-helpers.js's
+  // getAssociatedLabelElements): a <label> -- wrapping or via `for` --
+  // only ever associates with a genuinely labelable element, so this
+  // correctly returns nothing for role-only widgets a <label> merely sits
+  // next to, and the real thing for a labelable element like
+  // <input type="range">.
   function getNativeLabelText(el) {
+    if (!helpers || typeof helpers.getAssociatedLabelElements !== 'function') return '';
+    let labels;
     try {
-      if ('labels' in el && el.labels && el.labels.length) {
-        const parts = [];
-        const max = Math.min(4, el.labels.length);
-        for (let i = 0; i < max; i += 1) {
-          const lab = el.labels[i];
-          const t = lab ? getLabelText(lab) : '';
-          if (t) parts.push(t);
-        }
-        const joined = normalizeWs(parts.join(' '));
-        if (joined) return joined;
-      }
-    } catch {}
-    try {
-      if (el.closest) {
-        const wrap = el.closest('label');
-        if (wrap) {
-          const t = getLabelText(wrap);
-          if (t) return t;
-        }
-      }
-    } catch {}
-    try {
-      const idAttr = getAttr(el, 'id');
-      if (idAttr && labelForMap.has(idAttr)) {
-        const lab = labelForMap.get(idAttr);
-        const t = lab ? getLabelText(lab) : '';
-        if (t) return t;
-      }
-    } catch {}
-    return '';
+      labels = helpers.getAssociatedLabelElements(el) || [];
+    } catch {
+      labels = [];
+    }
+    const parts = [];
+    const max = Math.min(4, labels.length);
+    for (let i = 0; i < max; i += 1) {
+      const t = getLabelText(labels[i]);
+      if (t) parts.push(t);
+    }
+    return normalizeWs(parts.join(' '));
   }
 
   function evaluate(el, kind) {
@@ -223,10 +197,22 @@ function runInPage(ctx) {
     const title = getAttr(el, 'title');
     if (title) return { ok: true, method: 'title' };
 
-    if (kind === 'native-slider') {
-      const lab = getNativeLabelText(el);
-      if (lab) return { ok: true, method: 'label' };
-      return { ok: false, method: 'none' };
+    // An associated <label> names any labelable host, whether it is a
+    // native <input type="range"> or carries role="slider"
+    // (<input type="number" role="slider">); getAssociatedLabelElements
+    // returns nothing for a non-labelable one.
+    const lab = getNativeLabelText(el);
+    if (lab) return { ok: true, method: 'label' };
+    if (kind === 'native-slider') return { ok: false, method: 'none' };
+
+    // HTML-AAM's last name source for a text-like <input> or a <textarea>,
+    // after title: the placeholder. A placeholder-only label is a 3.3.2
+    // question, not a missing name.
+    if (helpers.getNativeHostNameInfo) {
+      try {
+        const host = helpers.getNativeHostNameInfo(el, ctx, { placeholder: true });
+        if (host && host.present) return { ok: true, method: host.mechanism };
+      } catch {}
     }
 
     // role="slider" is name-from-author-only per WAI-ARIA (unlike e.g.

package/src/checks/automatic/spinbutton-name-present.js

@@ -20,6 +20,9 @@
  *   accepted: text sitting inside a custom spinbutton widget is not reliably
  *   exposed as its name. On a labelable element (<input role="spinbutton">)
  *   an associated <label> counts as well.
+ *   On a text-like <input> or a <textarea>, the placeholder counts last
+ *   (HTML-AAM's final name source): a placeholder-only label is a 3.3.2
+ *   question, not a missing name.
  */
 
 const id = 'spinbutton-name-present';
@@ -149,21 +152,6 @@ function runInPage(ctx) {
     }
   }
 
-  function buildLabelForMap(doc) {
-    const map = new Map(); // id -> label element (first)
-    try {
-      const labels = doc && doc.getElementsByTagName ? doc.getElementsByTagName('label') : [];
-      for (let i = 0; i < labels.length; i += 1) {
-        const lab = labels[i];
-        if (!lab || !lab.getAttribute) continue;
-        const f = normalizeWs(lab.getAttribute('for'));
-        if (!f) continue;
-        if (!map.has(f)) map.set(f, lab);
-      }
-    } catch {}
-    return map;
-  }
-
   const occurrences = [];
   let applicableCount = 0;
 
@@ -172,42 +160,27 @@ function runInPage(ctx) {
     ? helpers.queryAllSmart(selector)
     : helpers.queryAll(selector);
 
-  // Precompute label[for] map for spinbutton elements that are labelable
-  // native form controls (e.g. <input role="spinbutton">).
-  const labelForMap = buildLabelForMap(document);
-
+  // Delegates to the shared, spec-guarded lookup (dom-helpers.js's
+  // getAssociatedLabelElements): a <label> -- wrapping or via `for` --
+  // only ever associates with a genuinely labelable element, so this
+  // correctly returns nothing for role-only widgets a <label> merely sits
+  // next to, and the real thing for a labelable element like
+  // <input role="spinbutton">.
   function getNativeLabelText(el) {
+    if (!helpers || typeof helpers.getAssociatedLabelElements !== 'function') return '';
+    let labels;
     try {
-      if ('labels' in el && el.labels && el.labels.length) {
-        const parts = [];
-        const max = Math.min(4, el.labels.length);
-        for (let i = 0; i < max; i += 1) {
-          const lab = el.labels[i];
-          const t = lab ? getLabelText(lab) : '';
-          if (t) parts.push(t);
-        }
-        const joined = normalizeWs(parts.join(' '));
-        if (joined) return joined;
-      }
-    } catch {}
-    try {
-      if (el.closest) {
-        const wrap = el.closest('label');
-        if (wrap) {
-          const t = getLabelText(wrap);
-          if (t) return t;
-        }
-      }
-    } catch {}
-    try {
-      const idAttr = getAttr(el, 'id');
-      if (idAttr && labelForMap.has(idAttr)) {
-        const lab = labelForMap.get(idAttr);
-        const t = lab ? getLabelText(lab) : '';
-        if (t) return t;
-      }
-    } catch {}
-    return '';
+      labels = helpers.getAssociatedLabelElements(el) || [];
+    } catch {
+      labels = [];
+    }
+    const parts = [];
+    const max = Math.min(4, labels.length);
+    for (let i = 0; i < max; i += 1) {
+      const t = getLabelText(labels[i]);
+      if (t) parts.push(t);
+    }
+    return normalizeWs(parts.join(' '));
   }
 
   function hasName(el) {
@@ -224,6 +197,16 @@ function runInPage(ctx) {
     const lab = getNativeLabelText(el);
     if (lab) return { ok: true, method: 'label' };
 
+    // HTML-AAM's last name source for a text-like <input> or a <textarea>,
+    // after title: the placeholder. A placeholder-only label is a 3.3.2
+    // question, not a missing name.
+    if (helpers.getNativeHostNameInfo) {
+      try {
+        const host = helpers.getNativeHostNameInfo(el, ctx, { placeholder: true });
+        if (host && host.present) return { ok: true, method: host.mechanism };
+      } catch {}
+    }
+
     // role="spinbutton" is name-from-author-only per WAI-ARIA: it must NOT
     // fall back to subtree content.
     return { ok: false, method: 'none' };

package/src/checks/automatic/target-size-minimum.js

@@ -124,17 +124,6 @@ const meta = {
   }
 };
 
-// ---- constants (deterministic, CSS pixels) ----
-const MIN_SIZE = 24;
-const MIN_RADIUS = 12; // spacing exception circle radius (24px diameter)
-
-// Grid sampling configuration (kept small for perf; only used for undersized targets)
-const GRID_POINTS = 25; // 5x5
-const GRID_N = 5;
-
-// Circle sampling configuration (perimeter)
-const CIRCLE_SAMPLES = 16; // deterministic, fixed
-
 function runInPage(ctx) {
   'use strict';
 

package/src/checks/automatic/td-has-header.js

@@ -12,15 +12,23 @@
  *   `<table>` elements with at least 4 rows and at least 4 columns
  *   (a "large" table, where implicit row/column header association is
  *   useful; small tables are usually self-evident), and with
- *   NO `colspan`/`rowspan` anywhere in the table.
+ *   NO `colspan`/`rowspan` anywhere in the table. A table whose role (first
+ *   token) is anything but table, grid or treegrid, such as a layout table
+ *   with role="presentation", is left out: it has no data cells.
  * @expectation
- *   Every `<td>` has an associated header, via one of:
+ *   Every non-empty `<td>` has an associated header, via one of:
  *     - a non-empty `headers` attribute (trusted here; whether it
  *       resolves to real `<th>` ids is `table-headers-attr-valid`'s
  *       concern, not this rule's), OR
- *     - an implicit column header: some `<th>` in the same column, in an
+ *     - an implicit column header: a header cell in the same column, in an
  *       earlier row, OR
- *     - an implicit row header: some `<th>` earlier in the same row.
+ *     - an implicit row header: a header cell earlier in the same row.
+ *   A header cell is a `<th>` with no other role, or any cell with
+ *   role="columnheader" or role="rowheader" (such a `<td>` is a header,
+ *   not a data cell). A `<td>` with no text and no content that could carry
+ *   a name (an image, a control, an element with an ARIA label) holds no
+ *   data, so it needs no header; the empty corner cell above row headers is
+ *   the usual case.
  * @implementation-notes
  * - Closes the gap `table-th-has-data-cells` deferred (see
  *   that rule's own implementation notes): this is the fuller positional
@@ -84,6 +92,25 @@ function runInPage(ctx) {
     }
   }
 
+  const TABLE_ROLES = ['table', 'grid', 'treegrid'];
+
+  function firstRole(el) {
+    return trim(el.getAttribute('role')).toLowerCase().split(/\s+/)[0];
+  }
+
+  // Content that can carry a name or a value even without text.
+  const NAMED_CONTENT =
+    'img, svg, canvas, input, select, textarea, button, object, embed, video, audio, iframe, meter, progress, [role], [aria-label], [aria-labelledby], [title]';
+
+  function isEmptyCell(cell) {
+    if (trim(cell.textContent)) return false;
+    try {
+      return !cell.querySelector(NAMED_CONTENT);
+    } catch {
+      return false;
+    }
+  }
+
   const tables = helpers.queryAllSmart ? helpers.queryAllSmart('table') : helpers.queryAll('table');
 
   const occurrences = [];
@@ -92,6 +119,9 @@ function runInPage(ctx) {
   for (const table of tables) {
     if (!table || !table.rows) continue;
 
+    const tableRole = firstRole(table);
+    if (tableRole && !TABLE_ROLES.includes(tableRole)) continue;
+
     const rows = Array.from(table.rows);
     if (rows.length < MIN_SIZE) continue;
 
@@ -115,7 +145,10 @@ function runInPage(ctx) {
     // another cell's row/column header, even though it's still structurally
     // a <th>.
     function isHeaderCell(cell) {
-      return !!(cell && cell.tagName && cell.tagName.toLowerCase() === 'th' && isEligible(cell));
+      if (!cell || !cell.tagName || !isEligible(cell)) return false;
+      const role = firstRole(cell);
+      if (role === 'columnheader' || role === 'rowheader') return true;
+      return cell.tagName.toLowerCase() === 'th' && !role;
     }
 
     // "Was there a <th> above this cell's column" and "was there a <th>
@@ -148,6 +181,9 @@ function runInPage(ctx) {
         const headersAttr = trim(cell.getAttribute('headers'));
         if (headersAttr) continue;
 
+        // An empty cell holds no data to associate with a header.
+        if (isEmptyCell(cell)) continue;
+
         if (colHasHeaderAbove[c]) continue;
         if (rowHasHeaderBefore) continue;