@surea11y/core 1.6.0 → 1.8.0

package/src/checks/automatic/deprecated-elements-not-used.js

@@ -5,34 +5,36 @@
 /**
  * @check deprecated-elements-not-used
  * @atomic true
- * @summary Obsolete non-stoppable elements must not be used
+ * @summary Scrolling <marquee> content needs a way to pause, stop, or hide it
  * @standard WCAG 2.2
  * @sc 2.2.2
  * @applicability
- *   Applies to any <blink> or <marquee> element present in scope. These are
- *   obsolete, non-standard HTML elements whose defining behavior (blinking
- *   or auto-scrolling text) has no built-in user mechanism to pause, stop,
- *   or hide it.
+ *   Applies to any scan scope; whether it contains a <marquee> element is
+ *   always an answerable question. <marquee> is an obsolete, non-standard
+ *   HTML element that browsers still render as auto-scrolling text, with no
+ *   built-in user mechanism to pause, stop, or hide it.
  * @expectation
- *   Neither element is present. Since their movement can never be paused,
- *   stopped, or hidden by the user, presence is itself the violation. This
- *   rule has no partial-pass case (it reports only when the element is
- *   found).
+ *   Each <marquee> is reported as cantTell: the scrolling itself is certain,
+ *   but a page can offer its own pause or stop control (a button calling the
+ *   element's stop() method, for example), and then failure F16 does not
+ *   apply. Whether such a control exists is for a person to check. A scope
+ *   with no <marquee> passes; there is no separate not-applicable case.
  * @implementation-notes
- * - Not rule-gated on isAccTreeEligible: presence in markup is itself the
- *   violation, independent of visibility (moving/blinking content inside a
- *   hidden ancestor could still become visible later without a code
- *   change, so hiding it today does not remove the underlying defect).
- *   Engine-level hidden-subtree filtering still applies unless
- *   engineOptions.includeHiddenElements is true.
+ * - <blink> is not reported. No current browser makes it blink: it renders
+ *   as an unknown inline element, so it holds no blinking content for 2.2.2
+ *   to govern.
+ * - Not rule-gated on isAccTreeEligible: presence in markup is what the rule
+ *   asks about, independent of visibility. Engine-level hidden-subtree
+ *   filtering still applies unless engineOptions.includeHiddenElements is
+ *   true.
  */
 
 const id = 'deprecated-elements-not-used';
 
 const meta = {
-  title: 'Obsolete non-stoppable elements (<blink>, <marquee>) must not be used',
+  title: 'Scrolling <marquee> content must be possible to pause, stop, or hide',
   description:
-    'Checks that deprecated, non-standard HTML elements whose blinking/scrolling content cannot be paused, stopped, or hidden by the user (<blink>, <marquee>) are not present.',
+    'Asks, for each obsolete <marquee> element, whether the page offers a way to pause, stop, or hide its auto-scrolling content, since the element itself has none.',
   i18n: {
     titleKey: 'deprecatedElements_title',
     descriptionKey: 'deprecatedElements_description'
@@ -60,47 +62,50 @@ function runInPage(ctx) {
   const { helpers, rule } = ctx;
 
   const nodes = helpers.queryAllSmart
-    ? helpers.queryAllSmart('blink, marquee')
-    : helpers.queryAll('blink, marquee');
+    ? helpers.queryAllSmart('marquee')
+    : helpers.queryAll('marquee');
 
   const occurrences = [];
-  let applicableCount = 0;
 
   for (const el of nodes) {
     if (!el || !el.tagName) continue;
 
-    applicableCount += 1;
-
     const tag = el.tagName.toLowerCase();
 
     occurrences.push(
       helpers.reportOccurrence(el, {
-        summary: 'This element’s content cannot be paused, stopped, or hidden by the user.',
-        hint: 'Remove this element; use static content, or an animation with a user-facing pause/stop control, instead.',
+        summary:
+          'This <marquee> scrolls its content, and the element itself gives the user no way to pause, stop, or hide it.',
+        hint: 'Check that the page offers a control that pauses, stops, or hides this content. Better: replace it with static content, or with an animation that has a pause/stop control.',
+        occurrenceOutcome: 'cantTell',
         i18n: {
-          summaryKey: 'deprecatedElements_summary_fail',
-          hintKey: 'deprecatedElements_hint_fail',
+          summaryKey: 'deprecatedElements_summary_cantTell',
+          hintKey: 'deprecatedElements_hint_cantTell',
           params: { element: tag }
         },
+        uncertainty: {
+          code: 'runtime-dependent',
+          needed:
+            'Whether the page provides a control that pauses, stops, or hides the scrolling content.',
+          evidence: { element: tag }
+        },
         data: {
-          details: { reasonCode: 'DEPRECATED_NON_STOPPABLE_ELEMENT', element: tag }
+          details: { reasonCode: 'MARQUEE_PAUSE_MECHANISM_UNKNOWN', element: tag }
         }
       })
     );
   }
 
-  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
-    };
+  // No <marquee> in scope is itself the passing case (see @expectation above).
+  if (!occurrences.length) {
+    return { ruleId: rule.ruleId, outcome: 'pass', 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/dialog-name-present.js

@@ -5,14 +5,16 @@
 /**
  * @check dialog-name-present
  * @atomic true
- * @summary Elements with role="dialog"/"alertdialog" must have an accessible name
+ * @summary Dialogs (role="dialog"/"alertdialog" or a native <dialog>) must have an accessible name
  * @standard WCAG 2.2
  * @sc 4.1.2
  * @applicability
- *   Applies to elements carrying role="dialog" or role="alertdialog" (the
- *   attribute must name one of those roles alone, not a fallback list) that
- *   are included in the accessibility tree. A native <dialog> without an
- *   explicit role is out of scope.
+ *   Applies to elements included in the accessibility tree whose role is
+ *   dialog or alertdialog: an element whose role attribute resolves to one
+ *   of those roles (the first token that names a concrete ARIA role wins,
+ *   so role="alertdialog dialog" is an alertdialog), and a native <dialog>
+ *   whose role attribute is absent or names no concrete role (its implicit
+ *   role is dialog). A closed <dialog> is hidden and so not in scope.
  * @expectation
  *   The element has a non-empty accessible name from aria-label, from an
  *   aria-labelledby that resolves to non-empty text, or from title. Both
@@ -25,7 +27,7 @@ const id = 'dialog-name-present';
 const meta = {
   title: 'Dialogs have an accessible name',
   description:
-    'Checks that elements with role="dialog" or role="alertdialog" expose a non-empty accessible name.',
+    'Checks that dialogs (elements with role="dialog" or role="alertdialog", and native <dialog> elements) expose a non-empty accessible name.',
   i18n: {
     titleKey: 'dialogNamePresent_title',
     descriptionKey: 'dialogNamePresent_description'
@@ -115,7 +117,8 @@ function runInPage(ctx) {
   const occurrences = [];
   let applicableCount = 0;
 
-  const selector = '[role="dialog"],[role="alertdialog"]';
+  // Filtered below by the resolved role.
+  const selector = 'dialog,[role]';
   const nodes = helpers.queryAllSmart
     ? helpers.queryAllSmart(selector)
     : helpers.queryAll(selector);
@@ -137,12 +140,28 @@ function runInPage(ctx) {
     return { ok: false, method: 'none' };
   }
 
+  // The role the browser uses: the first token of the role attribute that
+  // names a concrete ARIA role, else the element's implicit role (dialog for
+  // a native <dialog>; the others are not in scope here).
+  const aria = helpers && helpers.aria;
+  function resolveRole(el) {
+    const tokens = getAttr(el, 'role').toLowerCase().split(' ').filter(Boolean);
+    for (const t of tokens) {
+      const concrete =
+        aria && typeof aria.isValidConcreteRole === 'function'
+          ? aria.isValidConcreteRole(t)
+          : t === 'dialog' || t === 'alertdialog';
+      if (concrete) return t;
+    }
+    return String(el.tagName || '').toLowerCase() === 'dialog' ? 'dialog' : '';
+  }
+
   for (const el of nodes) {
     if (!el) continue;
-    if (!isEligibleAcc(helpers, el, ctx)) continue;
 
-    const role = getAttr(el, 'role').toLowerCase();
+    const role = resolveRole(el);
     if (role !== 'dialog' && role !== 'alertdialog') continue;
+    if (!isEligibleAcc(helpers, el, ctx)) continue;
 
     applicableCount += 1;
 

package/src/checks/automatic/duplicate-id-aria.js

@@ -128,6 +128,11 @@ function runInPage(ctx) {
             hintKey: 'duplicateIdAria_hint_cantTell',
             params: { id: refId, duplicateCount: String(els.length) }
           },
+          uncertainty: {
+            code: 'judgement-required',
+            needed: 'Whether the first element carrying this id is the intended target.',
+            evidence: { id: refId, duplicateCount: els.length, resolvesTo: 'first' }
+          },
           data: {
             details: {
               reasonCode: 'DUPLICATE_ID_ARIA_REFERENCED',

package/src/checks/automatic/duplicate-id.js

@@ -14,19 +14,25 @@
  *   element renders or not, which is why ACT 3ea0c8 evaluates hidden
  *   elements too.
  * @expectation
- *   No other element in the same tree carries the same id value. Ids are
+ *   No other element in the same tree carries the same id value, compared
+ *   exactly as written (id="a " and id="a" are different ids). Ids are
  *   scoped per document tree and per shadow tree, so the same id inside
  *   two different shadow roots is not a duplicate.
  * @implementation-notes
  * - WCAG-VERSION SCOPED. SC 4.1.1 Parsing was removed in WCAG 2.2, so this
- *   rule is tagged `wcag2a` (its 2.0/2.1 origin) plus `wcag22-removed`. A
- *   consumer targeting WCAG 2.2 excludes it with
- *   `excludeTags: ['wcag22-removed']`; one targeting 2.0 or 2.1 keeps it
- *   and gets a real 4.1.1 result. The alternative, dropping the SC
- *   mapping entirely, would have made a genuine 2.0/2.1 failure
- *   invisible to anyone conformance-testing against those versions. See
- *   `docs/ENGINE_OPTIONS.md` for the tag, and `docs/DESIGN_CHALLENGES.md`
- *   for the decision this reverses.
+ *   rule is tagged `wcag2a` (its 2.0/2.1 origin) plus `wcag22-removed`.
+ *   The engine acts on that tag itself: under a 2.2 target, which is the
+ *   default, this rule still runs and still reports every duplicate it
+ *   finds, but its fail is coerced to `cantTell` with a `wcagVersionScope`
+ *   field saying why (see scopeOutcomeToWcagVersion in
+ *   `src/core/dom-runner.js`). A consumer targeting 2.0 or 2.1
+ *   (`engineOptions.wcagVersion`, or a tag set that implies it) gets the
+ *   real 4.1.1 failure; one that would rather not see the rule at all
+ *   under 2.2 still excludes it with `excludeTags: ['wcag22-removed']`.
+ *   The alternative, dropping the SC mapping entirely, would have made a
+ *   genuine 2.0/2.1 failure invisible to anyone conformance-testing
+ *   against those versions. See `docs/ENGINE_OPTIONS.md` for the option
+ *   and the tag, and `docs/DESIGN_CHALLENGES.md` for the decision history.
  * - The defect outlives its Success Criterion: a duplicate id breaks
  *   `<label for>` association, fragment navigation, `getElementById`, and
  *   every ID-reference attribute, none of which stopped mattering when
@@ -121,7 +127,10 @@ function runInPage(ctx) {
 
   for (const el of all) {
     if (!el || el.nodeType !== 1 || !el.getAttribute) continue;
-    const value = String(el.getAttribute('id') || '').trim();
+    // Compared as written: "a " and "a" are different ids in the DOM, and
+    // getElementById does not trim. Whitespace inside an id is a separate
+    // validity error, not a duplicate.
+    const value = String(el.getAttribute('id') || '');
     if (!value) continue;
 
     applicableCount += 1;

package/src/checks/automatic/form-control-single-label.js

@@ -173,6 +173,15 @@ function runInPage(ctx) {
             hintKey: 'formControlSingleLabel_hint_cantTell',
             params: { element: tag, labelCount: String(eligibleLabels.size) }
           },
+          uncertainty: {
+            code: 'spec-only',
+            needed: 'Whether the empty label is filled in at runtime or is simply redundant.',
+            evidence: {
+              element: tag,
+              labelCount: eligibleLabels.size,
+              contributingLabelCount: contributing.length
+            }
+          },
           data: {
             details: {
               reasonCode: 'FORM_FIELD_EXTRA_EMPTY_LABEL',

package/src/checks/automatic/identical-iframes-same-purpose.js

@@ -0,0 +1,229 @@
+/* SPDX-License-Identifier: MPL-2.0 */
+
+'use strict';
+
+/**
+ * @check identical-iframes-same-purpose
+ * @atomic true
+ * @summary Frames sharing an accessible name must embed the same resource
+ * @standard WCAG 2.2
+ * @sc 4.1.2
+ * @applicability
+ *   Applies to each set of two or more <iframe>/<frame> elements that are
+ *   included in the accessibility tree and share the same non-empty
+ *   accessible name, compared with whitespace collapsed. A frame named
+ *   only by a mechanism that names nothing, or hidden from the
+ *   accessibility tree, is not part of a set; a set needs two surviving
+ *   members to exist at all.
+ * @expectation
+ *   Every frame in a set resolves to the same resource. A shared name
+ *   describes one resource, so two frames answering to it must embed the
+ *   same one.
+ * @implementation-notes
+ * - Frames are grouped by the computed accessible name, not the title
+ *   attribute, so a title that aria-label or aria-labelledby overrides does
+ *   not count. It replaces iframe-title-unique, deprecated in 1.8.0, which
+ *   grouped them by the title attribute.
+ * - src values are compared as resolved absolute URLs with the fragment
+ *   removed and a trailing slash normalised away, so a directory written
+ *   both with and without one is a single resource.
+ * - Frames that resolve to different URLs are reported cantTell, never
+ *   fail. Different resources can still be equivalent — differently worded
+ *   copies of one page, or two adverts serving the same purpose — and
+ *   nothing in the markup settles it. Comparing the embedded documents
+ *   would not settle it either, since content differing is exactly what
+ *   those equivalent cases look like.
+ */
+
+const id = 'identical-iframes-same-purpose';
+
+const meta = {
+  title: 'Frames with the same name embed the same resource',
+  description:
+    'Checks that <iframe>/<frame> elements sharing an accessible name embed the same resource, since one name can only describe one resource.',
+  i18n: {
+    titleKey: 'identicalIframesSamePurpose_title',
+    descriptionKey: 'identicalIframesSamePurpose_description'
+  },
+  helpUrl: null,
+  tags: ['wcag2a', 'wcag412', 'structure', 'atomic', 'automatic', 'name', 'iframe'],
+  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: 'automatic',
+  defaultConfidence: 'medium',
+  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');
+
+  function normalizedName(el) {
+    if (!helpers.getAccessibleNameInfo) return '';
+    let info;
+    try {
+      info = helpers.getAccessibleNameInfo(el, ctx, { maxRefs: 8 });
+    } catch {
+      return '';
+    }
+    if (!info || !info.present || !info.value) return '';
+    return String(info.value).replace(/\s+/g, ' ').trim();
+  }
+
+  // A light-DOM child of a shadow host with no slot to land in is absent from
+  // the flat tree and so renders nowhere, which the shared eligibility helper
+  // does not model.
+  function isUnslotted(el) {
+    try {
+      let cur = el;
+      let guard = 0;
+      while (cur && cur.nodeType === 1 && guard++ < 100) {
+        const parent = cur.parentNode;
+        if (!parent || parent.nodeType !== 1) return false;
+        if (parent.shadowRoot && cur.assignedSlot == null) return true;
+        cur = parent;
+      }
+      return false;
+    } catch {
+      return false;
+    }
+  }
+
+  function inAccessibilityTree(el) {
+    if (isUnslotted(el)) return false;
+    if (!helpers.isIncludedInAccessibilityTree) return true;
+    try {
+      return !!helpers.isIncludedInAccessibilityTree(el);
+    } catch {
+      return false;
+    }
+  }
+
+  // A directory written with and without its trailing slash is one resource,
+  // and a fragment selects within a resource rather than naming another.
+  function resourceKey(el) {
+    let raw;
+    try {
+      raw = el.getAttribute('src');
+    } catch {
+      return null;
+    }
+    if (raw == null || !String(raw).trim()) return null;
+
+    const doc = (ctx && ctx.document) || (el.ownerDocument ? el.ownerDocument : null);
+    const base = doc && doc.baseURI ? doc.baseURI : undefined;
+    try {
+      const u = new URL(String(raw).trim(), base);
+      let pathname = u.pathname;
+      if (pathname.length > 1 && pathname.charAt(pathname.length - 1) === '/') {
+        pathname = pathname.slice(0, -1);
+      }
+      return u.protocol + '//' + u.host + pathname + u.search;
+    } catch {
+      return null;
+    }
+  }
+
+  const groups = new Map();
+
+  for (const el of nodes) {
+    if (!el || !el.tagName) continue;
+    if (!inAccessibilityTree(el)) continue;
+
+    const name = normalizedName(el);
+    if (!name) continue;
+
+    const list = groups.get(name);
+    if (list) list.push(el);
+    else groups.set(name, [el]);
+  }
+
+  const sets = [];
+  for (const [name, els] of groups) {
+    if (els.length >= 2) sets.push([name, els]);
+  }
+
+  if (!sets.length) {
+    return { ruleId: rule.ruleId, outcome: 'notApplicable', severity: 'minor', occurrences: [] };
+  }
+
+  const occurrences = [];
+
+  for (const [name, els] of sets) {
+    const keys = els.map(resourceKey);
+    const resolved = keys.filter((k) => k != null);
+    const allResolved = resolved.length === keys.length;
+    const allSame = allResolved && resolved.every((k) => k === resolved[0]);
+    if (allSame) continue;
+
+    for (let i = 0; i < els.length; i++) {
+      const el = els[i];
+      const tag = el.tagName.toLowerCase();
+      occurrences.push(
+        helpers.reportOccurrence(el, {
+          summary:
+            'This frame shares its accessible name with another frame that embeds a different resource.',
+          hint: 'Give each frame a name describing the resource it embeds, or point them at the same resource.',
+          i18n: {
+            summaryKey: 'identicalIframesSamePurpose_summary_cantTell',
+            hintKey: 'identicalIframesSamePurpose_hint_cantTell',
+            params: { element: tag, name }
+          },
+          uncertainty:
+            keys[i] == null
+              ? {
+                  code: 'not-computable',
+                  needed: 'A resolvable src for this frame.',
+                  evidence: { element: tag, name, setSize: els.length }
+                }
+              : {
+                  code: 'equivalence-unknown',
+                  needed: 'Whether the two resources serve the same purpose despite differing.',
+                  evidence: {
+                    element: tag,
+                    name,
+                    resource: keys[i],
+                    otherResources: resolved.filter((k) => k !== keys[i]),
+                    setSize: els.length
+                  }
+                },
+          data: {
+            details: {
+              reasonCode:
+                keys[i] == null ? 'IFRAME_RESOURCE_UNRESOLVED' : 'IFRAME_RESOURCE_DIFFERS',
+              element: tag,
+              name,
+              resource: keys[i],
+              setSize: els.length
+            }
+          }
+        })
+      );
+    }
+  }
+
+  if (occurrences.length) {
+    return {
+      ruleId: rule.ruleId,
+      outcome: 'cantTell',
+      severity: rule.defaultSeverity || 'moderate',
+      occurrences
+    };
+  }
+  return { ruleId: rule.ruleId, outcome: 'pass', severity: 'minor', occurrences: [] };
+}
+
+module.exports = { id, meta, runInPage };

package/src/checks/automatic/iframe-focusable-content.js

@@ -386,10 +386,18 @@ function runInPage(ctx) {
     if (runtimeProbe && runtimeProbe.redirected) {
       cantTellOccurrences.push(
         helpers.reportOccurrence(el, {
-          summary:
-            'This frame has tabindex="-1" and a focusable candidate, but focus moves immediately to another target. Verify keyboard reachability in a real browser.',
-          hint: 'If this is an intentional focus handoff, ensure keyboard users cannot remain on hidden/intermediate frame content.',
-          i18n: null,
+          summary: `This <${tag}> has tabindex="-1" and focusable content, but focus moves immediately to another target. Verify keyboard reachability in a real browser.`,
+          hint: 'If this is an intentional focus handoff, make sure keyboard users cannot remain on hidden or intermediate frame content.',
+          i18n: {
+            summaryKey: 'iframeFocusableContent_summary_cantTell_redirect',
+            hintKey: 'iframeFocusableContent_hint_cantTell_redirect',
+            params: { element: tag }
+          },
+          uncertainty: {
+            code: 'runtime-dependent',
+            needed: 'Whether a keyboard user can reach this frame’s content in a real browser.',
+            evidence: { element: tag, focusRedirected: true }
+          },
           data: {
             details: {
               reasonCode: 'IFRAME_TABINDEX_NEGATIVE_CONTENT_RUNTIME_REDIRECT',