@surea11y/core 1.2.0 → 1.4.0

package/src/checks/manual/skip-link-manual.js

@@ -1,20 +1,21 @@
+/* SPDX-License-Identifier: MPL-2.0 */
+
 'use strict';
 
 /**
  * @check skip-link
  * @atomic true
  * @summary A "skip" link must resolve to a real, usable target
- * @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 to <a href="#fragment"> elements whose accessible name
  *   matches a common "skip to ..." / "jump to ..." authoring convention
  *   (case-insensitive "skip" or "jump to" in the name) — the recognizable
  *   pattern for a skip-navigation link, not every same-page anchor link
- *   on the page. "jump to" added 2026-07-23 after a real page (Wish.com)
- *   surfaced a skip link reading "Jump to section" with a genuinely
- *   missing target — invisible to the original "skip"-only pattern,
- *   while a widely-used reference engine's own (purely positional, not text-based) matching
- *   caught it. Text-pattern matching itself stays deliberate (see
+ *   on the page. "jump to" is included alongside "skip" since real skip
+ *   links use both conventions (e.g. a "Jump to section" link, which a
+ *   purely positional match would catch but a "skip"-only text pattern
+ *   would miss). Text-pattern matching itself stays deliberate (see
  *   implementation-notes) — this only widens the known-convention list.
  * @expectation
  *   The link's fragment resolves to a real element in the document
@@ -37,7 +38,8 @@ const id = 'skip-link';
 
 const meta = {
   title: 'Skip link must have a resolvable, usable target',
-  description: 'Checks that a "skip to ..." link\'s href fragment resolves to a real, currently usable element in the document.',
+  description:
+    'Checks that a "skip to ..." link\'s href fragment resolves to a real, currently usable element in the document.',
   i18n: {
     titleKey: 'skipLink_title',
     descriptionKey: 'skipLink_description'
@@ -57,7 +59,9 @@ function runInPage(ctx) {
   const { document, helpers, rule } = ctx;
 
   function normalizeWs(s) {
-    return String(s || '').replace(/\s+/g, ' ').trim();
+    return String(s || '')
+      .replace(/\s+/g, ' ')
+      .trim();
   }
 
   function getAccessibleNameText(el) {
@@ -105,7 +109,9 @@ function runInPage(ctx) {
 
   const geometrySupported = hasReliableGeometrySupport();
 
-  const nodes = helpers.queryAllSmart ? helpers.queryAllSmart('a[href]') : helpers.queryAll('a[href]');
+  const nodes = helpers.queryAllSmart
+    ? helpers.queryAllSmart('a[href]')
+    : helpers.queryAll('a[href]');
 
   const occurrences = [];
   let applicableCount = 0;
@@ -147,18 +153,29 @@ function runInPage(ctx) {
       const accEligibility = toEligibility(
         helpers.getEligibilityInfo
           ? helpers.getEligibilityInfo(target, ctx, { targetSet: 'acc' })
-          : (helpers.isAccTreeEligible ? helpers.isAccTreeEligible(target, ctx) : { eligible: true, reasons: [] })
+          : helpers.isAccTreeEligible
+            ? helpers.isAccTreeEligible(target, ctx)
+            : { eligible: true, reasons: [] }
       );
 
       let geometryEligibility = null;
       let geometryReasonCode = null;
       if (geometrySupported && helpers.isDomVisibleEligible) {
         geometryEligibility = toEligibility(
-          helpers.isDomVisibleEligible(target, ctx, { visibilityMode: 'styleAndGeometry', ignoreOpacity: true })
+          helpers.isDomVisibleEligible(target, ctx, {
+            visibilityMode: 'styleAndGeometry',
+            ignoreOpacity: true
+          })
         );
-        if (!geometryEligibility.eligible && geometryEligibility.reasons.includes('noClientRects')) {
+        if (
+          !geometryEligibility.eligible &&
+          geometryEligibility.reasons.includes('noClientRects')
+        ) {
           geometryReasonCode = 'NO_CLIENT_RECTS';
-        } else if (!geometryEligibility.eligible && geometryEligibility.reasons.includes('zeroArea')) {
+        } else if (
+          !geometryEligibility.eligible &&
+          geometryEligibility.reasons.includes('zeroArea')
+        ) {
           geometryReasonCode = 'ZERO_AREA_TARGET';
         }
       }
@@ -168,7 +185,9 @@ function runInPage(ctx) {
       if (!unusableByAcc && !unusableByGeometry) continue;
 
       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,
@@ -202,13 +221,13 @@ function runInPage(ctx) {
     }
 
     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,
       html,
-      summary: 'This skip link\'s target does not exist.',
-      hint: 'Point the skip link\'s href at an id that exists in the document, or add the missing target element.',
+      summary: "This skip link's target does not exist.",
+      hint: "Point the skip link's href at an id that exists in the document, or add the missing target element.",
       i18n: {
         summaryKey: 'skipLink_summary_cantTell',
         hintKey: 'skipLink_hint_cantTell',
@@ -224,7 +243,12 @@ function runInPage(ctx) {
     return { ruleId: rule.ruleId, outcome: 'notApplicable', severity: 'minor', occurrences: [] };
   }
   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: [] };
 }

package/src/checks/manual/svg-text-alternative-quality-manual.js

@@ -1,3 +1,5 @@
+/* SPDX-License-Identifier: MPL-2.0 */
+
 'use strict';
 
 /**
@@ -11,199 +13,240 @@
  *   Human review is required to confirm that the provided text alternative is accurate and appropriate.
  */
 
-const id = "svg-text-alternative-quality";
+const id = 'svg-text-alternative-quality';
 
 const meta = {
-    title: "<svg> text alternative must be appropriate (manual review)",
-    description: "Flags applicable <svg> graphics with a detected text alternative for human review of appropriateness.",
-    i18n: {
-        titleKey: "svg_textAltQuality_title",
-        descriptionKey: "svg_textAltQuality_description"
-    },
-    helpUrl: null,
-    tags: ["wcag2a", "wcag111", "nontext", "svg", "manual", "atomic"],
-    wcagSc: ['1.1.1'],
-    normativeMappings: [
-        {standard: 'WCAG', version: '2.2', requirement: '1.1.1', title: 'Non-text Content', conformanceLevel: 'A'}
-    ],
-    defaultSeverity: 'minor',
-    category: 'perceivable',
-    type: 'manual',
-    defaultConfidence: 'medium',
-    coverage: {
-        facetsBySc: {
-            '1.1.1': ['text-alternative-quality']
-        }
+  title: '<svg> text alternative must be appropriate (manual review)',
+  description:
+    'Flags applicable <svg> graphics with a detected text alternative for human review of appropriateness.',
+  i18n: {
+    titleKey: 'svg_textAltQuality_title',
+    descriptionKey: 'svg_textAltQuality_description'
+  },
+  helpUrl: null,
+  tags: ['wcag2a', 'wcag111', 'nontext', 'svg', 'manual', 'atomic'],
+  wcagSc: ['1.1.1'],
+  normativeMappings: [
+    {
+      standard: 'WCAG',
+      version: '2.2',
+      requirement: '1.1.1',
+      title: 'Non-text Content',
+      conformanceLevel: 'A'
     }
+  ],
+  defaultSeverity: 'minor',
+  category: 'perceivable',
+  type: 'manual',
+  defaultConfidence: 'medium',
+  coverage: {
+    facetsBySc: {
+      '1.1.1': ['text-alternative-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 queryAll = helpers && typeof helpers.queryAll === 'function'
-        ? helpers.queryAll
-        : (sel) => {
-            try { return safeRoot && safeRoot.querySelectorAll ? Array.from(safeRoot.querySelectorAll(sel)) : []; }
-            catch { return []; }
+  const { document, root, helpers, rule } = ctx;
+  const safeRoot = root || document;
+
+  const queryAllSmart =
+    helpers && typeof helpers.queryAllSmart === 'function' ? helpers.queryAllSmart : null;
+  const queryAll =
+    helpers && typeof helpers.queryAll === 'function'
+      ? helpers.queryAll
+      : (sel) => {
+          try {
+            return safeRoot && safeRoot.querySelectorAll
+              ? Array.from(safeRoot.querySelectorAll(sel))
+              : [];
+          } catch {
+            return [];
+          }
         };
 
-    const buildSelector = helpers && typeof helpers.buildSelector === 'function'
-        ? helpers.buildSelector
-        : (el) => {
-            try {
-                if (!el || !el.tagName) return 'html';
-                const tag = (el.tagName || 'html').toLowerCase();
-                return el.id ? `${tag}#${el.id}` : tag;
-            } catch {
-                return 'html';
-            }
+  const buildSelector =
+    helpers && typeof helpers.buildSelector === 'function'
+      ? helpers.buildSelector
+      : (el) => {
+          try {
+            if (!el || !el.tagName) return 'html';
+            const tag = (el.tagName || 'html').toLowerCase();
+            return el.id ? `${tag}#${el.id}` : tag;
+          } catch {
+            return 'html';
+          }
         };
 
-    const getOuterHtmlSnippet = helpers && typeof helpers.getOuterHtmlSnippet === 'function'
-        ? helpers.getOuterHtmlSnippet
-        : (el) => { try { return (el && el.outerHTML) ? String(el.outerHTML).slice(0, 2000) : ''; } catch { return ''; } };
-
-    const getEligibilityInfo = helpers && typeof helpers.getEligibilityInfo === 'function'
-        ? helpers.getEligibilityInfo
-        : null;
-
-    const isAccTreeEligible = helpers && typeof helpers.isAccTreeEligible === 'function'
-        ? helpers.isAccTreeEligible
-        : null;
-
-    const getFocusableInfo = helpers && typeof helpers.getFocusableInfo === 'function'
-        ? helpers.getFocusableInfo
-        : null;
-
-    function isRolePresentationExcluded(el) {
-        const role = (() => {
-            try {
-                return String(el.getAttribute('role') || '').trim().toLowerCase();
-            } catch {
-                return '';
-            }
-        })();
-        if (role !== 'presentation' && role !== 'none') return false;
-
-        // Exclude only when NOT focusable (mirrors img-alt-present policy)
-        let focusable = false;
-        if (getFocusableInfo) {
-            const fi = (() => {
-                try {
-                    return getFocusableInfo(el, ctx);
-                } catch {
-                    return null;
-                }
-            })();
-            focusable = !!(fi && fi.focusable);
-        } else {
-            const tabindex = el.getAttribute('tabindex');
-            focusable = tabindex != null && String(tabindex).trim() !== '' && !Number.isNaN(Number(String(tabindex).trim()));
-        }
-        return !focusable;
-    }
+  const getOuterHtmlSnippet =
+    helpers && typeof helpers.getOuterHtmlSnippet === 'function'
+      ? helpers.getOuterHtmlSnippet
+      : (el) => {
+          try {
+            return el && el.outerHTML ? String(el.outerHTML).slice(0, 2000) : '';
+          } catch {
+            return '';
+          }
+        };
+
+  const getEligibilityInfo =
+    helpers && typeof helpers.getEligibilityInfo === 'function' ? helpers.getEligibilityInfo : null;
 
+  const isAccTreeEligible =
+    helpers && typeof helpers.isAccTreeEligible === 'function' ? helpers.isAccTreeEligible : null;
 
-    const els = (() => {
+  const getFocusableInfo =
+    helpers && typeof helpers.getFocusableInfo === 'function' ? helpers.getFocusableInfo : null;
+
+  function isRolePresentationExcluded(el) {
+    const role = (() => {
+      try {
+        return String(el.getAttribute('role') || '')
+          .trim()
+          .toLowerCase();
+      } catch {
+        return '';
+      }
+    })();
+    if (role !== 'presentation' && role !== 'none') return false;
+
+    // Exclude only when NOT focusable (mirrors img-alt-present policy)
+    let focusable;
+    if (getFocusableInfo) {
+      const fi = (() => {
         try {
-            return Array.from((queryAllSmart ? queryAllSmart('svg') : queryAll('svg')) || []);
+          return getFocusableInfo(el, ctx);
         } catch {
-            return queryAll('svg');
+          return null;
         }
-    })();
-
-    if (!els.length) {
-        return {ruleId: rule.ruleId, outcome: 'notApplicable', severity: 'minor', occurrences: []};
+      })();
+      focusable = !!(fi && fi.focusable);
+    } else {
+      const tabindex = el.getAttribute('tabindex');
+      focusable =
+        tabindex != null &&
+        String(tabindex).trim() !== '' &&
+        !Number.isNaN(Number(String(tabindex).trim()));
     }
+    return !focusable;
+  }
+
+  const els = (() => {
+    try {
+      return Array.from((queryAllSmart ? queryAllSmart('svg') : queryAll('svg')) || []);
+    } catch {
+      return queryAll('svg');
+    }
+  })();
 
-    const occurrences = [];
-    let applicableCount = 0;
-
-    const trim = (v) => (v == null ? '' : String(v)).trim();
-
-    for (const el of els) {
-        if (!el || !el.getAttribute) continue;
+  if (!els.length) {
+    return { ruleId: rule.ruleId, outcome: 'notApplicable', severity: 'minor', occurrences: [] };
+  }
 
-        // acc eligibility
-        if (isAccTreeEligible) {
-            const elig = (() => { try { return isAccTreeEligible(el, ctx); } catch { return { eligible: true, reasons: [] }; } })();
-            if (elig && elig.eligible === false) continue;
-        }
+  const occurrences = [];
+  let applicableCount = 0;
 
-        if (isRolePresentationExcluded(el)) continue;
+  const trim = (v) => (v == null ? '' : String(v)).trim();
 
-        // Detect mechanisms once
-        let titleText = '';
-        let descText = '';
-        let ariaLabel = '';
-        let ariaLabelledBy = '';
-        let labelledByText = '';
+  for (const el of els) {
+    if (!el || !el.getAttribute) continue;
 
+    // acc eligibility
+    if (isAccTreeEligible) {
+      const elig = (() => {
         try {
-            const titleEl = el.querySelector ? el.querySelector('title') : null;
-            const descEl = el.querySelector ? el.querySelector('desc') : null;
-            titleText = trim(titleEl && titleEl.textContent);
-            descText = trim(descEl && descEl.textContent);
-
-            ariaLabel = trim(el.getAttribute('aria-label'));
-            ariaLabelledBy = trim(el.getAttribute('aria-labelledby'));
-        } catch {}
-
-        if (!ariaLabel && ariaLabelledBy && helpers && typeof helpers.getTextFromIdRefs === 'function') {
-            try {
-                const t = helpers.getTextFromIdRefs(ariaLabelledBy, ctx);
-                labelledByText = trim(t && t.text);
-            } catch {}
+          return isAccTreeEligible(el, ctx);
+        } catch {
+          return { eligible: true, reasons: [] };
         }
+      })();
+      if (elig && elig.eligible === false) continue;
+    }
 
-        const hasNonEmptyTitle = !!titleText;
-        const hasNonEmptyDesc = !!descText;
-        const hasAriaLabel = !!ariaLabel;
-        const hasResolvedLabelledBy = !!labelledByText;
-
-        const hasMechanism = hasNonEmptyTitle || hasNonEmptyDesc || hasAriaLabel || hasResolvedLabelledBy;
-        if (!hasMechanism) continue;
-
-        applicableCount += 1;
-
-        const eligInfo = getEligibilityInfo ? getEligibilityInfo(el, ctx, { targetSet: 'acc' }) : null;
-
-        const baseOccurrence = {
-            summary: 'Review text alternative for <svg> for accuracy and appropriateness.',
-            hint: 'Confirm the <title>/<desc> or ARIA name conveys the meaning/purpose of the graphic in context.',
-            i18n: {
-                summaryKey: 'svg_textAltQuality_summary_cantTell',
-                hintKey: 'svg_textAltQuality_hint_cantTell',
-                params: { element: 'svg' }
-            },
-            data: {
-                visibilityFilter: eligInfo || { targetSet: 'acc', accEligible: null, reasons: [] },
-                details: {
-                    hasNonEmptyTitle,
-                    hasNonEmptyDesc,
-                    ariaLabel: ariaLabel || null,
-                    ariaLabelledBy: ariaLabelledBy || null,
-                    ariaLabelledByText: labelledByText ? labelledByText.slice(0, 120) : null // deterministic truncation
-                }
-            }
-        };
+    if (isRolePresentationExcluded(el)) continue;
+
+    // Detect mechanisms once
+    let titleText = '';
+    let descText = '';
+    let ariaLabel = '';
+    let ariaLabelledBy = '';
+    let labelledByText = '';
+
+    try {
+      const titleEl = el.querySelector ? el.querySelector('title') : null;
+      const descEl = el.querySelector ? el.querySelector('desc') : null;
+      titleText = trim(titleEl && titleEl.textContent);
+      descText = trim(descEl && descEl.textContent);
+
+      ariaLabel = trim(el.getAttribute('aria-label'));
+      ariaLabelledBy = trim(el.getAttribute('aria-labelledby'));
+    } catch {}
+
+    if (
+      !ariaLabel &&
+      ariaLabelledBy &&
+      helpers &&
+      typeof helpers.getTextFromIdRefs === 'function'
+    ) {
+      try {
+        const t = helpers.getTextFromIdRefs(ariaLabelledBy, ctx);
+        labelledByText = trim(t && t.text);
+      } catch {}
+    }
 
-        if (helpers && typeof helpers.reportOccurrence === 'function') {
-            occurrences.push(helpers.reportOccurrence(el, baseOccurrence));
-        } else {
-            const selectorStr = (() => { try { return buildSelector(el); } catch { return 'html'; } })();
-            const html = getOuterHtmlSnippet(el);
-            occurrences.push({ selector: selectorStr, html, ...baseOccurrence });
+    const hasNonEmptyTitle = !!titleText;
+    const hasNonEmptyDesc = !!descText;
+    const hasAriaLabel = !!ariaLabel;
+    const hasResolvedLabelledBy = !!labelledByText;
+
+    const hasMechanism =
+      hasNonEmptyTitle || hasNonEmptyDesc || hasAriaLabel || hasResolvedLabelledBy;
+    if (!hasMechanism) continue;
+
+    applicableCount += 1;
+
+    const eligInfo = getEligibilityInfo ? getEligibilityInfo(el, ctx, { targetSet: 'acc' }) : null;
+
+    const baseOccurrence = {
+      summary: 'Review text alternative for <svg> for accuracy and appropriateness.',
+      hint: 'Confirm the <title>/<desc> or ARIA name conveys the meaning/purpose of the graphic in context.',
+      i18n: {
+        summaryKey: 'svg_textAltQuality_summary_cantTell',
+        hintKey: 'svg_textAltQuality_hint_cantTell',
+        params: { element: 'svg' }
+      },
+      data: {
+        visibilityFilter: eligInfo || { targetSet: 'acc', accEligible: null, reasons: [] },
+        details: {
+          hasNonEmptyTitle,
+          hasNonEmptyDesc,
+          ariaLabel: ariaLabel || null,
+          ariaLabelledBy: ariaLabelledBy || null,
+          ariaLabelledByText: labelledByText ? labelledByText.slice(0, 120) : null // deterministic truncation
         }
-    }
+      }
+    };
 
-    if (applicableCount === 0) {
-        return {ruleId: rule.ruleId, outcome: 'notApplicable', severity: 'minor', occurrences: []};
+    if (helpers && typeof helpers.reportOccurrence === 'function') {
+      occurrences.push(helpers.reportOccurrence(el, baseOccurrence));
+    } else {
+      const selectorStr = (() => {
+        try {
+          return buildSelector(el);
+        } catch {
+          return 'html';
+        }
+      })();
+      const html = getOuterHtmlSnippet(el);
+      occurrences.push({ selector: selectorStr, html, ...baseOccurrence });
     }
+  }
+
+  if (applicableCount === 0) {
+    return { ruleId: rule.ruleId, outcome: 'notApplicable', severity: 'minor', occurrences: [] };
+  }
 
-    return {ruleId: rule.ruleId, outcome: 'cantTell', severity: 'minor', occurrences};
+  return { ruleId: rule.ruleId, outcome: 'cantTell', severity: 'minor', occurrences };
 }
 
-module.exports = {id, meta, runInPage};
+module.exports = { id, meta, runInPage };

package/src/checks/manual/tabindex-manual.js

@@ -1,10 +1,12 @@
+/* SPDX-License-Identifier: MPL-2.0 */
+
 'use strict';
 
 /**
  * @check tabindex
  * @atomic true
  * @summary tabindex should not be greater than 0
- * @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 to elements with a tabindex attribute whose value parses as
  *   a valid integer.
@@ -42,7 +44,9 @@ const meta = {
 function runInPage(ctx) {
   const { helpers, rule } = ctx;
 
-  const nodes = helpers.queryAllSmart ? helpers.queryAllSmart('[tabindex]') : helpers.queryAll('[tabindex]');
+  const nodes = helpers.queryAllSmart
+    ? helpers.queryAllSmart('[tabindex]')
+    : helpers.queryAll('[tabindex]');
 
   const occurrences = [];
   let applicableCount = 0;
@@ -59,7 +63,7 @@ function runInPage(ctx) {
     if (n <= 0) continue;
 
     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,
@@ -81,7 +85,12 @@ function runInPage(ctx) {
     return { ruleId: rule.ruleId, outcome: 'notApplicable', severity: 'minor', occurrences: [] };
   }
   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: [] };
 }