@surea11y/core 1.6.0 → 1.8.0

package/src/checks/automatic/iframe-title-unique.js

@@ -5,33 +5,43 @@
 /**
  * @check iframe-title-unique
  * @atomic true
- * @summary <iframe>/<frame> title attributes must be unique among frames
+ * @summary Deprecated since 1.8.0, reports notApplicable; see identical-iframes-same-purpose
  * @standard WCAG 2.2
  * @sc 4.1.2
  * @applicability
- *   Applies to <iframe>/<frame> elements that carry a non-empty title
- *   attribute.
+ *   Nothing. The rule is deprecated and reports notApplicable on every
+ *   page. Its id stays in the catalog, with meta.deprecated set and
+ *   deprecation.replacedBy naming the successor, so a runOnly list, a
+ *   stored baseline or an open Code Scanning alert that holds the id keeps
+ *   resolving until the file is removed in 2.0.0 (docs/API_STABILITY.md,
+ *   "Rule-ID deprecation policy").
  * @expectation
- *   No two frames in scope share the same (trimmed, case-sensitive) title
- *   attribute value, a duplicate title prevents assistive technology
- *   users from telling frames apart when scanning by name.
+ *   None. The check this rule used to make, that no two frames share a
+ *   title attribute, is not a WCAG 4.1.2 requirement: the criterion asks
+ *   that a frame's name be programmatically determinable, not unique, and
+ *   ACT rule 4b1c6c accepts identical names on frames that embed equivalent
+ *   resources. identical-iframes-same-purpose asks the question 4b1c6c does
+ *   ask, of the computed accessible name, which for a frame is the title
+ *   attribute unless aria-label or aria-labelledby overrides it.
  * @implementation-notes
- * - Distinct, atomic decision from iframe-name-present (presence):
- *   a frame can have a non-empty title while still failing uniqueness.
- * - Compares the title ATTRIBUTE specifically, not the full computed
- *   accessible name (aria-label could legitimately differ in wording even
- *   when title happens to collide).
- * - Not rule-gated on isAccTreeEligible: duplicate titles are a static
- *   markup property. Engine-level hidden-subtree filtering still applies
- *   unless engineOptions.includeHiddenElements is true.
+ * - Reduced to notApplicable rather than only marked deprecated because a
+ *   deprecated rule keeps running and reporting normally, and leaving the
+ *   old fail alive until 2.0.0 would have kept reporting a violation WCAG
+ *   does not define. docs/DESIGN_CHALLENGES.md records the decision.
+ * - IFRAME_TITLE_DUPLICATE is no longer emitted. It retired with the
+ *   finding it named in 1.8.0 (CHANGELOG.md), so a stored baseline entry or
+ *   alert for it closes.
+ * - The facet this rule covered under SC 4.1.2 is retired; the coverage
+ *   entry points at the successor's facet, so the catalog still shows where
+ *   the question is answered.
  */
 
 const id = 'iframe-title-unique';
 
 const meta = {
-  title: 'Frame titles must be unique',
+  title: 'Frame title uniqueness (deprecated)',
   description:
-    'Checks that no two <iframe>/<frame> elements in scope share the same title attribute value.',
+    'Deprecated since 1.8.0 and always notApplicable: whether frames sharing a name embed the same resource is checked by identical-iframes-same-purpose.',
   i18n: {
     titleKey: 'iframeTitleUnique_title',
     descriptionKey: 'iframeTitleUnique_description'
@@ -52,74 +62,19 @@ const meta = {
   category: 'robust',
   type: 'automatic',
   defaultConfidence: 'high',
-  coverage: { facetsBySc: { '4.1.2': ['iframe-title-unique'] } }
+  deprecated: true,
+  deprecation: {
+    replacedBy: 'identical-iframes-same-purpose',
+    reason:
+      'A repeated title attribute is not a WCAG 4.1.2 violation, and identical-iframes-same-purpose already checks what ACT rule 4b1c6c asks: that frames sharing a name embed the same resource.',
+    sinceVersion: '1.8.0'
+  },
+  coverage: { facetsBySc: { '4.1.2': ['identical-iframes-same-purpose'] } }
 };
 
 function runInPage(ctx) {
-  const { helpers, rule } = ctx;
-
-  const nodes = helpers.queryAllSmart
-    ? helpers.queryAllSmart('iframe, frame')
-    : helpers.queryAll('iframe, frame');
-
-  const groups = new Map(); // trimmed title -> elements[]
-  let applicableCount = 0;
-
-  for (const el of nodes) {
-    if (!el || !el.getAttribute) continue;
-
-    const title = String(el.getAttribute('title') || '').trim();
-    if (!title) continue;
-
-    applicableCount += 1;
-
-    const list = groups.get(title);
-    if (list) list.push(el);
-    else groups.set(title, [el]);
-  }
-
-  if (applicableCount === 0) {
-    return { ruleId: rule.ruleId, outcome: 'notApplicable', severity: 'minor', occurrences: [] };
-  }
-
-  const occurrences = [];
-
-  for (const [title, els] of groups) {
-    if (els.length < 2) continue;
-
-    for (const el of els) {
-      const tag = el.tagName.toLowerCase();
-      occurrences.push(
-        helpers.reportOccurrence(el, {
-          summary: 'This frame’s title is not unique among the frames on this page.',
-          hint: 'Give each frame a distinct title describing its specific content or purpose.',
-          i18n: {
-            summaryKey: 'iframeTitleUnique_summary_fail',
-            hintKey: 'iframeTitleUnique_hint_fail',
-            params: { element: tag, title }
-          },
-          data: {
-            details: {
-              reasonCode: 'IFRAME_TITLE_DUPLICATE',
-              element: tag,
-              title,
-              duplicateCount: els.length
-            }
-          }
-        })
-      );
-    }
-  }
-
-  if (occurrences.length) {
-    return {
-      ruleId: rule.ruleId,
-      outcome: 'fail',
-      severity: rule.defaultSeverity || 'moderate',
-      occurrences
-    };
-  }
-  return { ruleId: rule.ruleId, outcome: 'pass', severity: 'minor', occurrences: [] };
+  const { rule } = ctx;
+  return { ruleId: rule.ruleId, outcome: 'notApplicable', severity: 'minor', occurrences: [] };
 }
 
 module.exports = { id, meta, runInPage };

package/src/checks/automatic/input-image-alt-present.js

@@ -3,7 +3,7 @@
 'use strict';
 
 /**
- * @check inputImage-alt-present
+ * @check input-image-alt-present
  * @atomic true
  * @summary Accessible <input type="image"> elements must have an alt attribute
  * @standard WCAG 2.2
@@ -11,9 +11,12 @@
  * @applicability
  *   Applies to <input type="image"> elements included in the accessibility tree.
  * @expectation
- *   Each applicable <input type="image"> element has an alt attribute, and its
- *   accessible name is not the browser default for an image button.
- *   The alt attribute may be empty (alt="").
+ *   Each applicable <input type="image"> element has a non-empty accessible
+ *   name from aria-labelledby, aria-label, alt or title. An empty name
+ *   fails, whether alt is missing or empty (alt="").
+ *   An author-supplied name that equals a browser default for an image
+ *   button ("Submit", "Submit Query") is not an empty name: it may describe
+ *   the button, so it is reported as cantTell for a person to judge.
  */
 
 const id = 'input-image-alt-present';
@@ -99,6 +102,7 @@ function runInPage(ctx) {
   }
 
   const occurrences = [];
+  const cantTellOccurrences = [];
   let applicableCount = 0;
 
   for (const el of inputs) {
@@ -118,10 +122,12 @@ function runInPage(ctx) {
 
     applicableCount += 1;
 
-    // The browser's own fallback name for an image button carries no
-    // information, so an author-supplied name equal to it is treated as no
-    // name at all (ACT 59796f). Only the English defaults are recognised:
-    // "Submit Query" from HTML-AAM, "Submit" from Chrome.
+    // An author-supplied name equal to the browser's own fallback name for an
+    // image button ("Submit Query" from HTML-AAM, "Submit" from Chrome) may
+    // be the browser default copied by hand, or may describe a submit button
+    // accurately. It is a name, so ACT 59796f passes it; whether it conveys
+    // the button's purpose is asked, not failed. Only the English defaults
+    // are recognised. With no author name at all the control fails below.
     const effectiveName = (() => {
       let v = '';
       if (getAriaNameInfo) {
@@ -149,19 +155,25 @@ function runInPage(ctx) {
         : null;
       const defaultNameOccurrence = {
         summary:
-          'Accessible name is the browser default for an image button, which conveys nothing.',
-        hint: 'Replace it with text describing what the button does, for example "Search".',
+          'The accessible name matches the browser default for an image button; check that it describes what the button does.',
+        hint: 'If the name does not say what the button does, replace it with text that does, for example "Search".',
+        occurrenceOutcome: 'cantTell',
         i18n: {
-          summaryKey: 'inputImage_altPresent_summary_defaultName',
-          hintKey: 'inputImage_altPresent_hint_defaultName',
+          summaryKey: 'inputImage_altPresent_summary_cantTell_defaultName',
+          hintKey: 'inputImage_altPresent_hint_cantTell_defaultName',
           params: { element: 'input[type=image]' }
         },
+        uncertainty: {
+          code: 'judgement-required',
+          needed: 'Whether this default-looking name describes what the button does.',
+          evidence: { name: effectiveName }
+        },
         data: {
           visibilityFilter: eligInfoDefault || { targetSet: 'acc', accEligible: null, reasons: [] },
           details: { reasonCode: 'default_name' }
         }
       };
-      occurrences.push(
+      cantTellOccurrences.push(
         helpers && typeof helpers.reportOccurrence === 'function'
           ? helpers.reportOccurrence(el, defaultNameOccurrence)
           : { selector: '', html: '', ...defaultNameOccurrence }
@@ -220,16 +232,16 @@ function runInPage(ctx) {
     return { ruleId: rule.ruleId, outcome: 'notApplicable', severity: 'minor', occurrences: [] };
   }
 
-  if (!occurrences.length) {
+  if (!occurrences.length && !cantTellOccurrences.length) {
     return { ruleId: rule.ruleId, outcome: 'pass', severity: 'minor', occurrences: [] };
   }
 
-  return {
-    ruleId: rule.ruleId,
-    outcome: 'fail',
-    severity: rule.defaultSeverity || 'minor',
-    occurrences
-  };
+  const resolved = helpers.resolveTieredOutcome(
+    occurrences,
+    cantTellOccurrences,
+    rule.defaultSeverity || 'minor'
+  );
+  return { ruleId: rule.ruleId, ...resolved };
 }
 
 module.exports = { id, meta, runInPage };

package/src/checks/automatic/label-in-name.js

@@ -9,7 +9,7 @@
  * @standard WCAG 2.2
  * @sc 2.5.3
  * @applicability
- *   Applies to controls that carry aria-label or aria-labelledby, are
+ *   Applies to controls named by aria-label or aria-labelledby, are
  *   visually rendered, and have visible label text this engine can extract
  *   deterministically, from an associated <label>, from the control's own
  *   rendered text, or from the elements aria-labelledby points at. The
@@ -18,13 +18,20 @@
  *   menuitemcheckbox, menuitemradio, option, treeitem and gridcell roles,
  *   minus anything hidden or disabled. aria-hidden is not
  *   excluded: it changes nothing about what is rendered on screen, which is
- *   what this SC is about.
+ *   what this SC is about. An aria-label that is empty once trimmed, or an
+ *   aria-labelledby whose ids point at nothing or only at elements with no
+ *   text, names nothing: the accessible name then comes from the next
+ *   source (the content, a <label>, title...), as for a control without
+ *   them, so the control is out of scope.
  * @expectation
  *   The accessible name contains the visible label's words, adjacent and in
  *   order. The comparison is over words rather than characters:
- *   parenthesised text is dropped, case is folded, text is NFKD-normalised,
- *   and every non-letter/digit becomes a separator, so punctuation and
- *   spacing differences never decide the outcome. Four shapes markup cannot
+ *   parenthesised text is dropped, case is folded, text is NFKC-normalised,
+ *   and every character that is not a letter, digit or combining mark
+ *   becomes a separator, so punctuation and spacing differences never
+ *   decide the outcome. Accents are not folded: "Déposer" stays one word,
+ *   and a name that drops an accent ("Deposer") does not contain it. Four
+ *   shapes markup cannot
  *   settle are reported as cantTell instead of fail: a word hyphenated
  *   differently in the two places; a visible word the author may have
  *   abbreviated, marked by its trailing period; visible text rendered
@@ -86,20 +93,23 @@ function runInPage(ctx) {
   }
 
   // WCAG 2.5.3's label-in-name comparison is over words, not characters: drop
-  // parenthesised text, case-fold and NFKD-normalise, then reduce every
-  // non-letter/digit to a space. `hyphensJoin` deletes hyphens instead of
+  // parenthesised text, case-fold and NFKC-normalise, then reduce every
+  // character that is not a letter, digit or combining mark to a space.
+  // NFKC folds compatibility forms (ligatures, full-width letters) but keeps
+  // accented letters whole; with NFKD, "déposer" split at its combining
+  // accent into "de" and "poser". `hyphensJoin` deletes hyphens instead of
   // splitting on them, which distinguishes a real mismatch from one that is
   // only a hyphenation difference.
   function tokenize(s, hyphensJoin) {
     let v = (s == null ? '' : String(s)).replace(/\([^)]*\)/g, ' ').toLowerCase();
     try {
-      v = v.normalize('NFKD');
+      v = v.normalize('NFKC');
     } catch {
       // Realm without String#normalize: the word comparison below still holds.
     }
     if (hyphensJoin) v = v.replace(/[-‐-―−]/g, '');
     return v
-      .replace(/[^\p{L}\p{N}]+/gu, ' ')
+      .replace(/[^\p{L}\p{N}\p{M}]+/gu, ' ')
       .split(' ')
       .filter(Boolean);
   }
@@ -129,7 +139,7 @@ function runInPage(ctx) {
   function abbreviatedWords(s) {
     const out = new Set();
     for (const w of (s == null ? '' : String(s)).split(/\s+/)) {
-      const m = /^([\p{L}\p{N}]+)\.$/u.exec(w);
+      const m = /^([\p{L}\p{N}\p{M}]+)\.$/u.exec(w);
       if (m) out.add(m[1].toLowerCase());
     }
     return out;
@@ -231,7 +241,6 @@ function runInPage(ctx) {
 
     const parts = [];
     let n;
-    // eslint-disable-next-line no-cond-assign
     while ((n = walker.nextNode())) {
       try {
         const raw = n && n.nodeValue != null ? String(n.nodeValue) : '';
@@ -254,55 +263,22 @@ function runInPage(ctx) {
     return parts.join(' ').replace(/\s+/g, ' ').trim();
   }
 
+  // Real <label> elements associated with a native form control -- the
+  // shared dom-helpers.js implementation (a `for`-attribute index plus a
+  // bounded closest('label') walk), not the native `.labels`/`.control`
+  // pair: jsdom implements those as a whole-document walk on every access
+  // (see that function's own header comment for the full explanation),
+  // real cost this engine's Node/jsdom runtime pays, not just a browser
+  // realm this code happens to also run in.
   function getAssociatedLabelElements(control) {
-    const labels = [];
-    try {
-      if (control && control.labels && typeof control.labels.length === 'number') {
-        for (const l of control.labels) labels.push(l);
-      }
-    } catch {
-      // ignore
-    }
-
-    // Fallback: wrapped label
-    try {
-      const w = control && control.closest ? control.closest('label') : null;
-      if (w) labels.push(w);
-    } catch {
-      // ignore
-    }
-
-    // Fallback: label[for=id]. Uses `document` directly rather than
-    // ctx.root -- label[for] association is a document-wide relationship
-    // (IDs are document-unique), not bounded by whatever contextSelector
-    // region happens to be scanned, and ctx.root is an array (multi-region
-    // contextSelector support), not a single element with its own
-    // .querySelector to call directly.
-    try {
-      const idAttribute = control && control.getAttribute ? control.getAttribute('id') || '' : '';
-      const key = String(idAttribute || '').trim();
-      if (key && document && document.querySelector) {
-        const l = document.querySelector('label[for="' + CSS.escape(key) + '"]');
-        if (l) labels.push(l);
-      }
-    } catch {
-      // ignore
-    }
-
-    // De-dupe in document order
-    const seen = new Set();
-    const out = [];
-    for (const l of labels) {
+    if (helpers && typeof helpers.getAssociatedLabelElements === 'function') {
       try {
-        if (!l || !l.tagName) continue;
-        if (seen.has(l)) continue;
-        seen.add(l);
-        out.push(l);
+        return helpers.getAssociatedLabelElements(control) || [];
       } catch {
-        // ignore
+        return [];
       }
     }
-    return out;
+    return [];
   }
 
   function getVisibleTextLabelInfo(el) {
@@ -468,8 +444,6 @@ function runInPage(ctx) {
     // Applicability: only when we can deterministically extract visible label text.
     if (!visibleNorm) continue;
 
-    applicableCount += 1;
-
     let acc = { present: false, value: '', mechanism: 'none', flags: [] };
     try {
       acc = helpers.getAccessibleNameInfo
@@ -478,6 +452,26 @@ function runInPage(ctx) {
     } catch {
       acc = { present: false, value: '', mechanism: 'none', flags: ['exception'] };
     }
+
+    // An aria-label empty once trimmed, or an aria-labelledby that yields no
+    // text, is skipped by the accessible name computation (AccName 1.2 steps
+    // 2B and 2C): the name comes from the next source, the content for a
+    // button or link, as if neither attribute were there. Such a control is
+    // not named by aria-label or aria-labelledby, so it is out of scope.
+    // getAccessibleNameInfo leaves name from content to its callers, which
+    // made `<button aria-labelledby="missing">Save</button>` fail with an
+    // empty name although its name is "Save".
+    const flags = acc && Array.isArray(acc.flags) ? acc.flags : [];
+    const ariaNamed =
+      acc && (acc.mechanism === 'aria-label' || acc.mechanism === 'aria-labelledby');
+    if (
+      !ariaNamed &&
+      (flags.includes('aria-labelledby-empty-or-unresolvable') ||
+        flags.includes('aria-label-empty'))
+    )
+      continue;
+
+    applicableCount += 1;
     const accName = acc && acc.value != null ? String(acc.value) : '';
     const accNorm = norm(accName);
 
@@ -490,44 +484,45 @@ function runInPage(ctx) {
     // character) is not something markup settles: the author may have meant
     // either. Report without asserting a defect instead of failing or
     // staying silent.
-    let uncertainty = '';
+    let uncertainReason = '';
     if (!contains) {
       if (containsWordRun(tokenize(visibleLabel, true), tokenize(accName, true), null)) {
-        uncertainty = 'HYPHENATION_DIFFERS';
+        uncertainReason = 'HYPHENATION_DIFFERS';
       } else {
         const abbreviated = abbreviatedWords(visibleLabel);
         if (abbreviated.size && containsWordRun(labelTokens, nameTokens, abbreviated)) {
-          uncertainty = 'POSSIBLE_ABBREVIATION';
+          uncertainReason = 'POSSIBLE_ABBREVIATION';
         } else if ((labelInfo.sourceElements || []).some(isIconFontElement)) {
-          uncertainty = 'POSSIBLE_ICON_FONT_GLYPH';
+          uncertainReason = 'POSSIBLE_ICON_FONT_GLYPH';
         } else if (isSingleSymbolicCharacter(visibleLabel, accNorm)) {
-          uncertainty = 'POSSIBLE_SYMBOLIC_CHARACTER';
+          uncertainReason = 'POSSIBLE_SYMBOLIC_CHARACTER';
         }
       }
     }
 
     const isSymbolicUncertainty =
-      uncertainty === 'POSSIBLE_ICON_FONT_GLYPH' || uncertainty === 'POSSIBLE_SYMBOLIC_CHARACTER';
+      uncertainReason === 'POSSIBLE_ICON_FONT_GLYPH' ||
+      uncertainReason === 'POSSIBLE_SYMBOLIC_CHARACTER';
 
     if (!contains) {
       occurrences.push(
         helpers.reportOccurrence(el, {
-          ...(uncertainty ? { outcome: 'cantTell' } : null),
-          summary: uncertainty
+          ...(uncertainReason ? { outcome: 'cantTell' } : null),
+          summary: uncertainReason
             ? 'Accessible name may not contain the visible label text.'
             : 'Accessible name does not contain the visible label text.',
-          hint: !uncertainty
+          hint: !uncertainReason
             ? 'Ensure the accessible name includes the visible text label (e.g., update aria-label/aria-labelledby to include the visible wording).'
             : isSymbolicUncertainty
               ? 'Check by hand: the visible text may render as an icon or symbol rather than literal words, which markup cannot settle.'
               : 'Check by hand: the two differ only by an abbreviation or by hyphenation, which markup cannot settle.',
           i18n: {
-            summaryKey: !uncertainty
+            summaryKey: !uncertainReason
               ? 'labelInName_summary_fail'
               : isSymbolicUncertainty
                 ? 'labelInName_summary_cantTell_symbolic'
                 : 'labelInName_summary_cantTell',
-            hintKey: !uncertainty
+            hintKey: !uncertainReason
               ? 'labelInName_hint_fail'
               : isSymbolicUncertainty
                 ? 'labelInName_hint_cantTell_symbolic'
@@ -539,9 +534,23 @@ function runInPage(ctx) {
               nameMechanism: acc && acc.mechanism ? acc.mechanism : 'none'
             }
           },
+          ...(uncertainReason
+            ? {
+                uncertainty: {
+                  code: 'equivalence-unknown',
+                  needed:
+                    'Whether the accessible name and the visible label say the same thing to a user.',
+                  evidence: {
+                    visibleLabel,
+                    accessibleName: accName,
+                    difference: uncertainReason
+                  }
+                }
+              }
+            : null),
           data: {
             details: {
-              reasonCode: uncertainty || 'VISIBLE_LABEL_NOT_IN_ACCESSIBLE_NAME',
+              reasonCode: uncertainReason || 'VISIBLE_LABEL_NOT_IN_ACCESSIBLE_NAME',
               visibleLabel,
               accessibleName: accName,
               normalized: { visibleLabel: visibleNorm, accessibleName: accNorm },

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

@@ -16,16 +16,21 @@
  *
  * @expectation
  *   The <html> element has a lang attribute.
- *   The lang attribute is not empty and contains a syntactically valid language tag.
+ *   The lang attribute is not empty and its primary language subtag (the
+ *   part before the first hyphen) is a registered language subtag, as ACT
+ *   bf051a requires. A malformed later
+ *   subtag (lang="fr-FR-!!") still identifies French, so it passes here;
+ *   it is a markup validity error, not a missing language.
  *
  * @outcomes
  *   Pass:
- *     The <html> element has a non-empty lang attribute with a valid language tag.
+ *     The <html> element has a non-empty lang attribute whose primary subtag is valid.
  *
  *   Fail:
  *     The <html> element does not have a lang attribute.
  *     The <html> element has a lang attribute that is present but empty or whitespace.
- *     The <html> element has a lang attribute with an invalid language tag.
+ *     The <html> element has a lang attribute whose primary subtag is not a
+ *     registered language subtag.
  *
  * @notes
  *   This rule does not verify that the declared language matches the actual language
@@ -143,12 +148,13 @@ function runInPage(ctx) {
     };
   }
 
-  // Minimal BCP47 primary subtag check
+  // Only the primary subtag is judged (ACT bf051a); the shared helper checks
+  // its shape and that the IANA registry lists it.
   const isValidTag =
     helpers && typeof helpers.isValidLanguageTag === 'function'
       ? helpers.isValidLanguageTag
-      : (v) => /^[a-zA-Z]{2,3}(-[a-zA-Z0-9]{2,8})*$/.test(String(v || ''));
-  if (!isValidTag(lang)) {
+      : (v) => /^[a-zA-Z]{2,3}$/.test(String(v || ''));
+  if (!isValidTag(lang.split('-')[0])) {
     return {
       ruleId: rule.ruleId,
       outcome: 'fail',