@surea11y/core 1.2.0 → 1.4.0

package/src/checks/manual/form-control-programmatic-label-quality-manual.js

@@ -1,3 +1,5 @@
+/* SPDX-License-Identifier: MPL-2.0 */
+
 'use strict';
 
 /**
@@ -25,267 +27,228 @@
 const id = 'form-control-programmatic-label-quality';
 
 const meta = {
-    title: 'Form controls should not rely on placeholder or title as the primary label',
-    description:
-        'Flags form controls whose computed accessible name relies on placeholder or title as the primary labeling method. Prefer <label> or aria-labelledby.',
-    i18n: {
-        titleKey: 'formControl_programmaticLabelQuality_title',
-        descriptionKey: 'formControl_programmaticLabelQuality_description'
-    },
-    helpUrl: null,
-    tags: ['wcag2a', 'wcag412', 'forms', 'labels', 'quality', 'atomic', 'manual'],
-    wcagSc: ['4.1.2'],
-    normativeMappings: [
-        { standard: 'WCAG', version: '2.2', requirement: '4.1.2', title: 'Name, Role, Value', conformanceLevel: 'A' }
-    ],
-    defaultSeverity: 'moderate',
-    category: 'robust',
-    type: 'manual',
-    defaultConfidence: 'medium',
-    coverage: {
-        facetsBySc: {
-            '4.1.2': ['form-control-name-quality']
-        }
+  title: 'Form controls should not rely on placeholder or title as the primary label',
+  description:
+    'Flags form controls whose computed accessible name relies on placeholder or title as the primary labeling method. Prefer <label> or aria-labelledby.',
+  i18n: {
+    titleKey: 'formControl_programmaticLabelQuality_title',
+    descriptionKey: 'formControl_programmaticLabelQuality_description'
+  },
+  helpUrl: null,
+  tags: ['wcag2a', 'wcag412', 'forms', 'labels', 'quality', 'atomic', 'manual'],
+  wcagSc: ['4.1.2'],
+  normativeMappings: [
+    {
+      standard: 'WCAG',
+      version: '2.2',
+      requirement: '4.1.2',
+      title: 'Name, Role, Value',
+      conformanceLevel: 'A'
+    }
+  ],
+  defaultSeverity: 'moderate',
+  category: 'robust',
+  type: 'manual',
+  defaultConfidence: 'medium',
+  coverage: {
+    facetsBySc: {
+      '4.1.2': ['form-control-name-quality']
     }
+  }
 };
 
 function runInPage(ctx) {
-    const { document, root, helpers, rule } = ctx;
-    const safeRoot = root || document;
-
-    const queryAllSmart = helpers && typeof helpers.queryAllSmart === 'function' ? helpers.queryAllSmart : null;
-
-    const isAccTreeEligible = helpers && typeof helpers.isAccTreeEligible === 'function' ? helpers.isAccTreeEligible : null;
-    const getEligibilityInfo = helpers && typeof helpers.getEligibilityInfo === 'function' ? helpers.getEligibilityInfo : null;
-
-    const getFocusableInfo = helpers && typeof helpers.getFocusableInfo === 'function' ? helpers.getFocusableInfo : null;
-    const getAriaLabelInfo = helpers && typeof helpers.getAriaLabelInfo === 'function' ? helpers.getAriaLabelInfo : null;
-    const getAriaLabelledByInfo = helpers && typeof helpers.getAriaLabelledByInfo === 'function' ? helpers.getAriaLabelledByInfo : null;
-
-    const getAttributeInfo = helpers && typeof helpers.getAttributeInfo === 'function' ? helpers.getAttributeInfo : null;
-
-    // Optional helper; we validate/normalize if present.
-    const getLabelMethod = helpers && typeof helpers.getLabelMethod === 'function' ? helpers.getLabelMethod : null;
-
-    const trim = (v) => (v == null ? '' : String(v)).trim();
-
-    const metrics = {
-        applicableCount: 0,
-        flaggedCount: 0,
-        byMethod: { label: 0, 'aria-labelledby': 0, 'aria-label': 0, title: 0, placeholder: 0, none: 0 }
-    };
-
-    function safeQueryAll(sel) {
-        try {
-            if (queryAllSmart) return Array.from(queryAllSmart(sel) || []);
-            return safeRoot && safeRoot.querySelectorAll ? Array.from(safeRoot.querySelectorAll(sel)) : [];
-        } catch {
-            return [];
-        }
-    }
-
-    function isEligibleAcc(el) {
-        if (!isAccTreeEligible) return true;
-        try {
-            const r = isAccTreeEligible(el, ctx);
-            if (typeof r === 'boolean') return r;
-            return !!(r && r.eligible);
-        } catch {
-            return true;
-        }
-    }
-
-    function isFocusable(el) {
-        if (!getFocusableInfo) return false;
-        try {
-            const fi = getFocusableInfo(el, ctx);
-            return !!(fi && fi.focusable);
-        } catch {
-            return false;
-        }
-    }
-
-    function getNonEmptyAttr(el, name) {
-        if (!getAttributeInfo) return '';
-        try {
-            const info = getAttributeInfo(el, name);
-            return info && info.present ? trim(info.value) : '';
-        } catch {
-            return '';
-        }
+  const { document, root, helpers, rule } = ctx;
+  const safeRoot = root || document;
+
+  const queryAllSmart =
+    helpers && typeof helpers.queryAllSmart === 'function' ? helpers.queryAllSmart : null;
+
+  const isAccTreeEligible =
+    helpers && typeof helpers.isAccTreeEligible === 'function' ? helpers.isAccTreeEligible : null;
+  const getEligibilityInfo =
+    helpers && typeof helpers.getEligibilityInfo === 'function' ? helpers.getEligibilityInfo : null;
+
+  const getFocusableInfo =
+    helpers && typeof helpers.getFocusableInfo === 'function' ? helpers.getFocusableInfo : null;
+
+  const getLabelMethod =
+    helpers && typeof helpers.getLabelMethod === 'function' ? helpers.getLabelMethod : null;
+
+  const trim = (v) => (v == null ? '' : String(v)).trim();
+
+  const metrics = {
+    applicableCount: 0,
+    flaggedCount: 0,
+    byMethod: { label: 0, 'aria-labelledby': 0, 'aria-label': 0, title: 0, placeholder: 0, none: 0 }
+  };
+
+  function safeQueryAll(sel) {
+    try {
+      if (queryAllSmart) return Array.from(queryAllSmart(sel) || []);
+      return safeRoot && safeRoot.querySelectorAll
+        ? Array.from(safeRoot.querySelectorAll(sel))
+        : [];
+    } catch {
+      return [];
     }
-
-    function hasLabelAssociation(el) {
-        // 1) Native labels API
-        try {
-            if (el && 'labels' in el && el.labels && el.labels.length) return true;
-        } catch {}
-
-        // 2) Wrapped by <label>
-        try {
-            if (el && el.closest) {
-                const wrap = el.closest('label');
-                if (wrap) return true;
-            }
-        } catch {}
-
-        // 3) <label for="id">
-        try {
-            const idAttr = el && el.getAttribute ? trim(el.getAttribute('id')) : '';
-            if (!idAttr || !document || !document.querySelector) return false;
-
-            const esc = idAttr.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
-            const sel = `label[for="${esc}"]`;
-            return !!document.querySelector(sel);
-        } catch {
-            return false;
-        }
+  }
+
+  function isEligibleAcc(el) {
+    if (!isAccTreeEligible) return true;
+    try {
+      const r = isAccTreeEligible(el, ctx);
+      if (typeof r === 'boolean') return r;
+      return !!(r && r.eligible);
+    } catch {
+      return true;
     }
-
-    function computeLabelMethodFallback(el) {
-        // Deterministic priority order:
-        // label > aria-labelledby > aria-label > title > placeholder
-        if (hasLabelAssociation(el)) return { method: 'label', value: '' };
-
-        if (getAriaLabelledByInfo) {
-            try {
-                const info = getAriaLabelledByInfo(el, ctx, { maxRefs: 8 });
-                const v = info && info.present ? trim(info.value) : '';
-                if (v) return { method: 'aria-labelledby', value: v };
-            } catch {}
-        }
-
-        if (getAriaLabelInfo) {
-            try {
-                const info = getAriaLabelInfo(el, ctx);
-                const v = info && info.present ? trim(info.value) : '';
-                if (v) return { method: 'aria-label', value: v };
-            } catch {}
-        }
-
-        const titleV = getNonEmptyAttr(el, 'title');
-        if (titleV) return { method: 'title', value: titleV };
-
-        const phV = getNonEmptyAttr(el, 'placeholder');
-        if (phV) return { method: 'placeholder', value: phV };
-
+  }
+
+  // getLabelMethod is provided by the shared dom-helpers bundle that
+  // dom-runner.js always constructs for every rule execution (built-in or
+  // custom) — see createDomHelpers's own getLabelMethod, which implements
+  // this exact <label>/aria-labelledby/aria-label/title/placeholder
+  // priority order. No local reimplementation is needed as a fallback.
+  function getLabelMethodSafe(el) {
+    if (!getLabelMethod) return { method: 'none', value: '' };
+    try {
+      const r = getLabelMethod(el, ctx);
+      const m = r && typeof r.method === 'string' ? r.method : 'none';
+      const v = r && r.value != null ? trim(r.value) : '';
+      if (!Object.prototype.hasOwnProperty.call(metrics.byMethod, m))
         return { method: 'none', value: '' };
+      return { method: m, value: v };
+    } catch {
+      return { method: 'none', value: '' };
     }
+  }
 
-    function getLabelMethodSafe(el) {
-        if (getLabelMethod) {
-            try {
-                const r = getLabelMethod(el, ctx);
-                const m = r && typeof r.method === 'string' ? r.method : 'none';
-                const v = r && r.value != null ? trim(r.value) : '';
-                if (!Object.prototype.hasOwnProperty.call(metrics.byMethod, m)) return { method: 'none', value: '' };
-                return { method: m, value: v };
-            } catch {
-                // fall through
-            }
-        }
-        return computeLabelMethodFallback(el);
-    }
-
-    // Native controls only (same as your current rule)
-    const selector =
-        'input:not([type="hidden"]):not([type="submit"]):not([type="reset"]):not([type="button"]):not([type="image"]),select,textarea';
+  // Native controls only (same as your current rule)
+  const selector =
+    'input:not([type="hidden"]):not([type="submit"]):not([type="reset"]):not([type="button"]):not([type="image"]),select,textarea';
 
-    const nodes = safeQueryAll(selector);
+  const nodes = safeQueryAll(selector);
 
-    if (!nodes.length) {
-        return { ruleId: rule.ruleId, outcome: 'notApplicable', severity: 'minor', occurrences: [], data: { details: { metrics } } };
+  if (!nodes.length) {
+    return {
+      ruleId: rule.ruleId,
+      outcome: 'notApplicable',
+      severity: 'minor',
+      occurrences: [],
+      data: { details: { metrics } }
+    };
+  }
+
+  const occurrences = [];
+
+  for (const el of nodes) {
+    if (!el || !el.getAttribute) continue;
+
+    if (!isEligibleAcc(el)) continue;
+
+    const role = (() => {
+      try {
+        return trim(el.getAttribute('role')).toLowerCase();
+      } catch {
+        return '';
+      }
+    })();
+
+    let fi = null;
+    if (getFocusableInfo) {
+      try {
+        fi = getFocusableInfo(el, ctx);
+      } catch {
+        fi = null;
+      }
     }
-
-    const occurrences = [];
-
-    for (const el of nodes) {
-        if (!el || !el.getAttribute) continue;
-
-        if (!isEligibleAcc(el)) continue;
-
-        const role = (() => {
-            try {
-                return trim(el.getAttribute('role')).toLowerCase();
-            } catch {
-                return '';
-            }
-        })();
-
-        let fi = null;
-        if (getFocusableInfo) {
-            try { fi = getFocusableInfo(el, ctx); } catch { fi = null; }
-        }
-        const tabbable = !!(fi && fi.tabbable);
-
-        if ((role === 'presentation' || role === 'none') && !tabbable) continue;
-
-        metrics.applicableCount += 1;
-
-        const label = getLabelMethodSafe(el);
-        const method = label && typeof label.method === 'string' ? label.method : 'none';
-        if (Object.prototype.hasOwnProperty.call(metrics.byMethod, method)) metrics.byMethod[method] += 1;
-        else metrics.byMethod.none += 1;
-
-        // Flag only when the *primary* (best) method is title/placeholder
-        const isWeakPrimary = method === 'title' || method === 'placeholder';
-        if (!isWeakPrimary) continue;
-
-        metrics.flaggedCount += 1;
-
-        const vf = getEligibilityInfo ? getEligibilityInfo(el, ctx, { targetSet: 'acc' }) : null;
-
-        const reasonCode = method === 'title' ? 'label_from_title_primary' : 'label_from_placeholder_primary';
-        const methodLabel =
-            method === 'title' ? 'title'
-                : method === 'placeholder' ? 'placeholder'
-                    : 'title or placeholder';
-
-        const baseOccurrence = {
-            summary: 'Form control’s primary label is derived from title or placeholder.',
-            hint: 'Prefer a persistent <label> or aria-labelledby. Avoid relying on placeholder/title as the primary label.',
-            i18n: {
-                summaryKey: 'formControl_programmaticLabelQuality_summary_cantTell',
-                hintKey: 'formControl_programmaticLabelQuality_hint_cantTell',
-                params: { element: (el.tagName || '').toLowerCase(), method, methodLabel }
-            },
-            data: {
-                visibilityFilter: vf || { targetSet: 'acc', accEligible: null, reasons: [] },
-                details: {
-                    reasonCode,
-                    labelMethod: method,
-                    labelStrength: 'weak',
-                    recommendedMethods: ['label', 'aria-labelledby'],
-                    sourceText: (label && label.value ? String(label.value).slice(0, 120) : '')
-                }
-            }
-        };
-
-        if (helpers && typeof helpers.reportOccurrence === 'function') {
-            occurrences.push(helpers.reportOccurrence(el, baseOccurrence));
-        } else {
-            occurrences.push({ selector: '', html: '', ...baseOccurrence });
+    const tabbable = !!(fi && fi.tabbable);
+
+    if ((role === 'presentation' || role === 'none') && !tabbable) continue;
+
+    metrics.applicableCount += 1;
+
+    const label = getLabelMethodSafe(el);
+    const method = label && typeof label.method === 'string' ? label.method : 'none';
+    if (Object.prototype.hasOwnProperty.call(metrics.byMethod, method))
+      metrics.byMethod[method] += 1;
+    else metrics.byMethod.none += 1;
+
+    // Flag only when the *primary* (best) method is title/placeholder
+    const isWeakPrimary = method === 'title' || method === 'placeholder';
+    if (!isWeakPrimary) continue;
+
+    metrics.flaggedCount += 1;
+
+    const vf = getEligibilityInfo ? getEligibilityInfo(el, ctx, { targetSet: 'acc' }) : null;
+
+    const reasonCode =
+      method === 'title' ? 'label_from_title_primary' : 'label_from_placeholder_primary';
+    const methodLabel =
+      method === 'title'
+        ? 'title'
+        : method === 'placeholder'
+          ? 'placeholder'
+          : 'title or placeholder';
+
+    const baseOccurrence = {
+      summary: 'Form control’s primary label is derived from title or placeholder.',
+      hint: 'Prefer a persistent <label> or aria-labelledby. Avoid relying on placeholder/title as the primary label.',
+      i18n: {
+        summaryKey: 'formControl_programmaticLabelQuality_summary_cantTell',
+        hintKey: 'formControl_programmaticLabelQuality_hint_cantTell',
+        params: { element: (el.tagName || '').toLowerCase(), method, methodLabel }
+      },
+      data: {
+        visibilityFilter: vf || { targetSet: 'acc', accEligible: null, reasons: [] },
+        details: {
+          reasonCode,
+          labelMethod: method,
+          labelStrength: 'weak',
+          recommendedMethods: ['label', 'aria-labelledby'],
+          sourceText: label && label.value ? String(label.value).slice(0, 120) : ''
         }
-    }
-
-    if (metrics.applicableCount === 0) {
-        return { ruleId: rule.ruleId, outcome: 'notApplicable', severity: 'minor', occurrences: [], data: { details: { metrics } } };
-    }
+      }
+    };
 
-    if (occurrences.length) {
-        return {
-            ruleId: rule.ruleId,
-            outcome: 'cantTell',
-            severity: rule.defaultSeverity || 'minor',
-            occurrences,
-            data: { details: { metrics } }
-        };
+    if (helpers && typeof helpers.reportOccurrence === 'function') {
+      occurrences.push(helpers.reportOccurrence(el, baseOccurrence));
+    } else {
+      occurrences.push({ selector: '', html: '', ...baseOccurrence });
     }
-
-    // Manual rules may only emit cantTell/notApplicable (never pass/fail) —
-    // no applicable control relied on a weak (title/placeholder) primary
-    // label, so there is nothing to flag for review.
-    return { ruleId: rule.ruleId, outcome: 'notApplicable', severity: 'minor', occurrences: [], data: { details: { metrics } } };
+  }
+
+  if (metrics.applicableCount === 0) {
+    return {
+      ruleId: rule.ruleId,
+      outcome: 'notApplicable',
+      severity: 'minor',
+      occurrences: [],
+      data: { details: { metrics } }
+    };
+  }
+
+  if (occurrences.length) {
+    return {
+      ruleId: rule.ruleId,
+      outcome: 'cantTell',
+      severity: rule.defaultSeverity || 'minor',
+      occurrences,
+      data: { details: { metrics } }
+    };
+  }
+
+  // Manual rules may only emit cantTell/notApplicable (never pass/fail) —
+  // no applicable control relied on a weak (title/placeholder) primary
+  // label, so there is nothing to flag for review.
+  return {
+    ruleId: rule.ruleId,
+    outcome: 'notApplicable',
+    severity: 'minor',
+    occurrences: [],
+    data: { details: { metrics } }
+  };
 }
 
 module.exports = { id, meta, runInPage };

package/src/checks/manual/heading-order-manual.js

@@ -1,10 +1,12 @@
+/* SPDX-License-Identifier: MPL-2.0 */
+
 'use strict';
 
 /**
  * @check heading-order
  * @atomic true
  * @summary Heading levels must not skip a level going deeper
- * @standard Best Practices (a widely-used reference engine's classification; no formal WCAG Success Criterion — see ROADMAP.md Tier 1b)
+ * @standard Best Practices (no formal WCAG Success Criterion — see ROADMAP.md Tier 1b)
  * @applicability
  *   Applies whenever the page contains two or more heading elements
  *   (native <h1>-<h6>, or explicit role="heading" with aria-level —
@@ -47,10 +49,12 @@ const meta = {
 };
 
 function runInPage(ctx) {
-  const { document, helpers, rule } = ctx;
+  const { helpers, rule } = ctx;
 
   function normalizeWs(s) {
-    return String(s || '').replace(/\s+/g, ' ').trim();
+    return String(s || '')
+      .replace(/\s+/g, ' ')
+      .trim();
   }
 
   function getExplicitRoleToken(el) {
@@ -65,20 +69,47 @@ function runInPage(ctx) {
       if (explicit !== 'heading') return 0;
       const raw = normalizeWs(el.getAttribute && el.getAttribute('aria-level'));
       const n = parseInt(raw, 10);
-      return (Number.isFinite(n) && n >= 1) ? n : 2;
+      return Number.isFinite(n) && n >= 1 ? n : 2;
     }
     const tag = el.tagName ? el.tagName.toLowerCase() : '';
     const m = /^h([1-6])$/.exec(tag);
     return m ? parseInt(m[1], 10) : 0;
   }
 
-  const nodes = helpers.queryAllSmart ? helpers.queryAllSmart('h1, h2, h3, h4, h5, h6, [role]') : helpers.queryAll('h1, h2, h3, h4, h5, h6, [role]');
+  const nodes = helpers.queryAllSmart
+    ? helpers.queryAllSmart('h1, h2, h3, h4, h5, h6, [role]')
+    : helpers.queryAll('h1, h2, h3, h4, h5, h6, [role]');
 
   const headings = [];
   const seen = new Set();
   for (const el of nodes) {
     if (!el || seen.has(el)) continue;
     seen.add(el);
+
+    // queryAllSmart's default hidden-content policy only excludes "hard"
+    // CSS-based hiding (display:none, visibility:hidden, etc.) -- it does
+    // NOT exclude aria-hidden, a softer/semantic removal from the
+    // accessibility tree that still leaves an element visually rendered.
+    // A heading order rule whose whole premise is "the document outline
+    // assistive technology users rely on" (see this rule's own header
+    // comment) must not let an aria-hidden heading participate in that
+    // outline at all: it's invisible to exactly the users this rule
+    // exists to protect. Without this check an aria-hidden heading is both
+    // flagged itself (though it isn't part of the AT-perceived outline)
+    // and can mask a real skip immediately after it, by advancing the
+    // "highest level reached so far" tracker on a level no AT user
+    // actually encountered.
+    if (helpers.isAccTreeEligible) {
+      const elig = (() => {
+        try {
+          return helpers.isAccTreeEligible(el, ctx);
+        } catch {
+          return { eligible: true, reasons: [] };
+        }
+      })();
+      if (elig && elig.eligible === false) continue;
+    }
+
     const level = getHeadingLevel(el);
     if (level > 0) headings.push({ el, level });
   }
@@ -95,7 +126,9 @@ function runInPage(ctx) {
 
     if (level > highestSoFar + 1) {
       const stableSelector = helpers.buildSelector ? helpers.buildSelector(el) : 'html';
-      const html = helpers.getOuterHtmlSnippet ? helpers.getOuterHtmlSnippet(el) : (el.outerHTML || '');
+      const html = helpers.getOuterHtmlSnippet
+        ? helpers.getOuterHtmlSnippet(el)
+        : el.outerHTML || '';
 
       occurrences.push({
         selector: stableSelector,
@@ -108,7 +141,11 @@ function runInPage(ctx) {
           params: { fromLevel: String(highestSoFar), toLevel: String(level) }
         },
         data: {
-          details: { reasonCode: 'HEADING_ORDER_SKIPPED_LEVEL', fromLevel: highestSoFar, toLevel: level }
+          details: {
+            reasonCode: 'HEADING_ORDER_SKIPPED_LEVEL',
+            fromLevel: highestSoFar,
+            toLevel: level
+          }
         }
       });
     }
@@ -117,7 +154,12 @@ function runInPage(ctx) {
   }
 
   if (occurrences.length) {
-    return { ruleId: rule.ruleId, outcome: 'cantTell', severity: rule.defaultSeverity || 'minor', occurrences };
+    return {
+      ruleId: rule.ruleId,
+      outcome: 'cantTell',
+      severity: rule.defaultSeverity || 'minor',
+      occurrences
+    };
   }
   return { ruleId: rule.ruleId, outcome: 'notApplicable', severity: 'minor', occurrences: [] };
 }