@surea11y/core 1.0.0

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

@@ -0,0 +1,200 @@
+'use strict';
+
+const id = 'tab-name-present';
+
+const meta = {
+  title: 'Tabs have an accessible name',
+  description: 'Checks that elements with role="tab" expose a non-empty accessible name.',
+  i18n: {
+    titleKey: 'tabNamePresent_title',
+    descriptionKey: 'tabNamePresent_description'
+  },
+  helpUrl: null,
+  tags: ['wcag2a','wcag412','navigation','atomic','automatic','name','tab'],
+  wcagSc: ['4.1.2'],
+  normativeMappings: [
+    { standard: 'WCAG', version: '2.2', requirement: '4.1.2', title: 'Name, Role, Value', conformanceLevel: 'A' }
+  ],
+  defaultSeverity: 'serious',
+  category: 'robust',
+  type: 'automatic',
+  defaultConfidence: 'high',
+  coverage: { facetsBySc: { '4.1.2': ['tab-name-present'] } }
+};
+
+function runInPage(ctx) {
+  const { document, root, helpers, rule } = ctx;
+  const getEligibilityInfo = helpers && typeof helpers.getEligibilityInfo === 'function'
+      ? helpers.getEligibilityInfo
+      : null;
+  const safeRoot = root || document;
+
+
+  function normalizeWs(s) {
+    return String(s || '').replace(/\s+/g, ' ').trim();
+  }
+
+  function getAttr(el, name) {
+    try {
+      if (!el || !el.getAttribute) return '';
+      return normalizeWs(el.getAttribute(name));
+    } catch { return ''; }
+  }
+
+  function hasAttr(el, name) {
+    try { return !!(el && el.hasAttribute && el.hasAttribute(name)); } catch { return false; }
+  }
+
+  function isExplicitProgrammatic(el) {
+    // Programmatic name mechanisms we treat as authoritative (presence-only):
+    // - aria-label (non-empty)
+    // - aria-labelledby (non-empty)
+    // - title (non-empty) [weak but allowed for presence]
+    const al = getAttr(el, 'aria-label');
+    if (al) return true;
+    const alb = getAttr(el, 'aria-labelledby');
+    if (alb) return true;
+    const t = getAttr(el, 'title');
+    if (t) return true;
+    return false;
+  }
+
+  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
+    // it has one, not just literal text nodes. See getContentNameInfo's
+    // header comment in src/core/dom-helpers.js for the full rationale
+    // (this replaced a text-node-only TreeWalker that missed the common
+    // "<a><img alt='...'></a>" logo-link / "<button><img alt='...'></button>"
+    // icon-button pattern).
+    if (helpers.getContentNameInfo) {
+      const info = helpers.getContentNameInfo(container, ctx);
+      return info && info.present ? info.value : '';
+    }
+    const t = (container && container.textContent) ? String(container.textContent) : '';
+    return t.replace(/\s+/g, ' ').trim();
+  }
+
+  function resolveAriaLabelledbyText(document, el, maxRefs) {
+    const raw = getAttr(el, 'aria-labelledby');
+    if (!raw) return '';
+    // Delegates to the shared getTextFromIdRefs helper instead of computing
+    // name-from-content of the referenced element — see dialog-name-
+    // present.js's identical fix for the full rationale (an <iframe>
+    // aria-labelledby target's only name source is its title attribute,
+    // which name-from-content alone can never see).
+    if (helpers.getTextFromIdRefs) {
+      try {
+        const r = helpers.getTextFromIdRefs(raw, ctx, { maxRefs: maxRefs || 8 });
+        return normalizeWs(r && r.text);
+      } catch {}
+    }
+    return '';
+  }
+
+  function getInputValueName(el) {
+    try {
+      const type = getAttr(el, 'type').toLowerCase();
+      if (type !== 'button' && type !== 'submit' && type !== 'reset') return '';
+      const v = getAttr(el, 'value');
+      return v;
+    } catch { return ''; }
+  }
+
+  function isEligibleAcc(helpers, el, ctx) {
+    const fn = helpers && typeof helpers.isAccTreeEligible === 'function' ? helpers.isAccTreeEligible : null;
+    if (!fn) return true;
+    try {
+      const r = fn(el, ctx);
+      if (typeof r === 'boolean') return r;
+      return !!(r && r.eligible);
+    } catch {
+      return true;
+    }
+  }
+
+
+  const occurrences = [];
+  let applicableCount = 0;
+
+  const selector = '[role="tab"]';
+  const nodes = helpers.queryAllSmart ? helpers.queryAllSmart(selector, safeRoot) : helpers.queryAll(selector, safeRoot);
+
+
+  function evaluate(el) {
+    const ariaLabel = getAttr(el, 'aria-label');
+    if (ariaLabel) return { ok: true, method: 'aria-label' };
+
+    const ariaLabelledby = resolveAriaLabelledbyText(document, el, 8);
+    if (ariaLabelledby) return { ok: true, method: 'aria-labelledby' };
+
+    const title = getAttr(el, 'title');
+    if (title) return { ok: true, method: 'title' };
+
+    const t = getConservativeSubtreeText(document, el);
+    if (t) return { ok: true, method: 'content' };
+
+    return { ok: false, method: 'none' };
+  }
+
+  for (const el of nodes) {
+    if (!el) continue;
+    if (!isEligibleAcc(helpers, el, ctx)) continue;
+
+    const role = getAttr(el, 'role').toLowerCase();
+    if (role !== 'tab') continue;
+
+    applicableCount += 1;
+
+    const res = evaluate(el);
+    if (res.ok) continue;
+
+    const eligInfo = getEligibilityInfo
+        ? (() => { try { return getEligibilityInfo(el, ctx, { targetSet: 'acc' }); } catch { return null; } })()
+        : null;
+    const stableSelector = helpers.buildSelector ? helpers.buildSelector(el) : 'html';
+    const html = helpers.getOuterHtmlSnippet ? helpers.getOuterHtmlSnippet(el) : (el.outerHTML || '');
+
+    occurrences.push({
+      selector: stableSelector,
+      html,
+      summary: 'This tab has no accessible name.',
+      hint: 'Provide tab text that is not hidden from assistive technologies, or provide aria-label or aria-labelledby.',
+      i18n: {
+        summaryKey: 'tabNamePresent_summary_fail',
+        hintKey: 'tabNamePresent_hint_fail',
+        params: {}
+      },
+      data: {
+        details: { reasonCode: 'name_missing', controlType: 'tab', methodTried: res.method },
+        visibilityFilter: eligInfo || { targetSet: 'acc', accEligible: null, reasons: [] }
+      }
+    });
+  }
+
+
+  if (applicableCount === 0) {
+    return { ruleId: rule.ruleId, outcome: 'notApplicable', severity: 'minor', occurrences: [] };
+  }
+  if (occurrences.length) {
+    return { ruleId: rule.ruleId, outcome: 'fail', severity: rule.defaultSeverity || 'minor', occurrences };
+  }
+  return { ruleId: rule.ruleId, outcome: 'pass', severity: 'minor', occurrences: [] };
+}
+
+module.exports = { id, meta, runInPage };

package/src/checks/automatic/table-headers-attr-valid.js

@@ -0,0 +1,122 @@
+'use strict';
+
+/**
+ * @check table-headers-attr-valid
+ * @atomic true
+ * @summary Table cell "headers" attribute must reference real <th> cells in the same table
+ * @standard WCAG 2.2
+ * @sc 1.3.1
+ * @applicability
+ *   Applies to <td>/<th> elements that carry a non-empty headers attribute.
+ * @expectation
+ *   Every id token in the headers attribute resolves to an element that:
+ *   (a) exists, (b) is a <th> element, (c) is inside the same <table> as
+ *   the referencing cell, and (d) is not the cell itself.
+ * @implementation-notes
+ * - One occurrence per offending cell (not per bad token), listing every
+ *   invalid reference — matches a widely-used reference engine's
+ *   td-headers-attr reporting granularity.
+ * - Not gated on isAccTreeEligible: this is a static markup property.
+ */
+
+const id = 'table-headers-attr-valid';
+
+const meta = {
+  title: 'Table cell "headers" attribute must reference valid header cells',
+  description: 'Checks that each id in a <td>/<th> headers attribute resolves to a <th> element within the same table (not missing, not a non-th element, not itself).',
+  i18n: {
+    titleKey: 'tableHeadersAttrValid_title',
+    descriptionKey: 'tableHeadersAttrValid_description'
+  },
+  helpUrl: null,
+  tags: ['wcag2a', 'wcag131', 'structure', 'atomic', 'automatic', 'table'],
+  wcagSc: ['1.3.1'],
+  normativeMappings: [
+    { standard: 'WCAG', version: '2.2', requirement: '1.3.1', title: 'Info and Relationships', conformanceLevel: 'A' }
+  ],
+  defaultSeverity: 'serious',
+  category: 'perceivable',
+  type: 'automatic',
+  defaultConfidence: 'high',
+  coverage: { facetsBySc: { '1.3.1': ['table-headers-attr-valid'] } }
+};
+
+function runInPage(ctx) {
+  const { document, root, helpers, rule } = ctx;
+  const safeRoot = root || document;
+
+  const nodes = helpers.queryAllSmart ? helpers.queryAllSmart('td[headers], th[headers]', safeRoot) : helpers.queryAll('td[headers], th[headers]', safeRoot);
+
+  const occurrences = [];
+  let applicableCount = 0;
+
+  for (const el of nodes) {
+    if (!el || !el.getAttribute) continue;
+
+    const raw = String(el.getAttribute('headers') || '').trim();
+    if (!raw) continue;
+    const ids = raw.split(/\s+/).filter(Boolean);
+    if (!ids.length) continue;
+
+    applicableCount += 1;
+
+    const table = el.closest ? el.closest('table') : null;
+    const invalid = [];
+
+    for (const headerId of ids) {
+      let ref = null;
+      try {
+        ref = document.getElementById(headerId);
+      } catch {
+        ref = null;
+      }
+
+      if (!ref) {
+        invalid.push({ id: headerId, reason: 'missing' });
+        continue;
+      }
+      if (ref === el) {
+        invalid.push({ id: headerId, reason: 'self-reference' });
+        continue;
+      }
+      if (!ref.tagName || ref.tagName.toLowerCase() !== 'th') {
+        invalid.push({ id: headerId, reason: 'not-a-th' });
+        continue;
+      }
+      if (table && (!ref.closest || ref.closest('table') !== table)) {
+        invalid.push({ id: headerId, reason: 'different-table' });
+      }
+    }
+
+    if (!invalid.length) continue;
+
+    const tag = el.tagName.toLowerCase();
+    const stableSelector = helpers.buildSelector ? helpers.buildSelector(el) : 'html';
+    const html = helpers.getOuterHtmlSnippet ? helpers.getOuterHtmlSnippet(el) : (el.outerHTML || '');
+
+    occurrences.push({
+      selector: stableSelector,
+      html,
+      summary: 'This cell’s headers attribute references one or more invalid header cells.',
+      hint: 'Update the headers attribute so every id refers to a <th> element within the same table.',
+      i18n: {
+        summaryKey: 'tableHeadersAttrValid_summary_fail',
+        hintKey: 'tableHeadersAttrValid_hint_fail',
+        params: { element: tag, invalidIds: invalid.map((i) => i.id).join(', ') }
+      },
+      data: {
+        details: { reasonCode: 'TABLE_HEADERS_ATTR_INVALID', element: tag, invalid }
+      }
+    });
+  }
+
+  if (applicableCount === 0) {
+    return { ruleId: rule.ruleId, outcome: 'notApplicable', severity: 'minor', occurrences: [] };
+  }
+  if (occurrences.length) {
+    return { ruleId: rule.ruleId, outcome: 'fail', severity: rule.defaultSeverity || 'serious', occurrences };
+  }
+  return { ruleId: rule.ruleId, outcome: 'pass', severity: 'minor', occurrences: [] };
+}
+
+module.exports = { id, meta, runInPage };

package/src/checks/automatic/table-th-has-data-cells.js

@@ -0,0 +1,117 @@
+'use strict';
+
+/**
+ * @check table-th-has-data-cells
+ * @atomic true
+ * @summary <th> elements must describe at least one data cell
+ * @standard WCAG 2.2
+ * @sc 1.3.1
+ * @applicability
+ *   Applies to <table> elements that contain at least one <th>.
+ * @expectation
+ *   The table also contains at least one <td> somewhere in it.
+ * @implementation-notes
+ * - DELIBERATELY SCOPED (see aria-helpers.js file header for the same
+ *   conservative-scope rationale used throughout this engine): this rule
+ *   does NOT implement the full HTML5 header-association algorithm
+ *   (resolving which specific data cells a given <th scope="row"|"col">
+ *   describes, accounting for colspan/rowspan and default-scope
+ *   inference). That algorithm is one of the more error-prone parts of
+ *   the HTML spec to reimplement correctly, and a wrong positional match
+ *   would risk a false `fail` — unacceptable for this engine's fail-
+ *   integrity bar.
+ * - Instead, this rule only catches the single unambiguous case: a table
+ *   that has <th> elements but ZERO <td> elements anywhere. In that case
+ *   every <th> in the table trivially describes no data cell — no
+ *   positional analysis is needed to know that. A table that has at
+ *   least one <td> somewhere is not evaluated further by this rule, even
+ *   if some particular <th> in it doesn't actually describe any cell
+ *   (false negative, not a false positive — acceptable under this
+ *   engine's philosophy).
+ * - Not gated on isAccTreeEligible: this is a static markup property.
+ */
+
+const id = 'table-th-has-data-cells';
+
+const meta = {
+  title: '<th> elements must describe at least one data cell',
+  description: 'Checks that a table containing <th> elements also contains at least one <td> data cell for those headers to describe.',
+  i18n: {
+    titleKey: 'tableThHasDataCells_title',
+    descriptionKey: 'tableThHasDataCells_description'
+  },
+  helpUrl: null,
+  tags: ['wcag2a', 'wcag131', 'structure', 'atomic', 'automatic', 'table'],
+  wcagSc: ['1.3.1'],
+  normativeMappings: [
+    { standard: 'WCAG', version: '2.2', requirement: '1.3.1', title: 'Info and Relationships', conformanceLevel: 'A' }
+  ],
+  defaultSeverity: 'moderate',
+  category: 'perceivable',
+  type: 'automatic',
+  defaultConfidence: 'high',
+  coverage: { facetsBySc: { '1.3.1': ['table-th-has-data-cells'] } }
+};
+
+function runInPage(ctx) {
+  const { document, root, helpers, rule } = ctx;
+  const safeRoot = root || document;
+
+  const tables = helpers.queryAllSmart ? helpers.queryAllSmart('table', safeRoot) : helpers.queryAll('table', safeRoot);
+
+  const occurrences = [];
+  let applicableCount = 0;
+
+  for (const table of tables) {
+    if (!table || !table.querySelectorAll) continue;
+
+    let ths = [];
+    try {
+      ths = table.querySelectorAll('th');
+    } catch {
+      ths = [];
+    }
+    if (!ths.length) continue;
+
+    applicableCount += 1;
+
+    let hasDataCell = false;
+    try {
+      hasDataCell = table.querySelectorAll('td').length > 0;
+    } catch {
+      hasDataCell = false;
+    }
+    if (hasDataCell) continue;
+
+    for (const th of ths) {
+      if (!th) continue;
+      const stableSelector = helpers.buildSelector ? helpers.buildSelector(th) : 'html';
+      const html = helpers.getOuterHtmlSnippet ? helpers.getOuterHtmlSnippet(th) : (th.outerHTML || '');
+
+      occurrences.push({
+        selector: stableSelector,
+        html,
+        summary: 'This table has header cells but no data cells for them to describe.',
+        hint: 'Add data cells (<td>) to the table, or remove the header cells if the table has no data.',
+        i18n: {
+          summaryKey: 'tableThHasDataCells_summary_fail',
+          hintKey: 'tableThHasDataCells_hint_fail',
+          params: {}
+        },
+        data: {
+          details: { reasonCode: 'TABLE_TH_NO_DATA_CELLS' }
+        }
+      });
+    }
+  }
+
+  if (applicableCount === 0) {
+    return { ruleId: rule.ruleId, outcome: 'notApplicable', severity: 'minor', occurrences: [] };
+  }
+  if (occurrences.length) {
+    return { ruleId: rule.ruleId, outcome: 'fail', severity: rule.defaultSeverity || 'moderate', occurrences };
+  }
+  return { ruleId: rule.ruleId, outcome: 'pass', severity: 'minor', occurrences: [] };
+}
+
+module.exports = { id, meta, runInPage };