@surea11y/core 1.5.0 → 1.7.0

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

@@ -2,6 +2,26 @@
 
 'use strict';
 
+/**
+ * @check combobox-name-present
+ * @atomic true
+ * @summary Elements with role="combobox" must have an accessible name
+ * @standard WCAG 2.2
+ * @sc 4.1.2
+ * @applicability
+ *   Applies to elements carrying role="combobox" (the attribute must name
+ *   that role alone, not a fallback list) that are included in the
+ *   accessibility tree. An element with the matching implicit role but no
+ *   role attribute is out of 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.
+ *   role="combobox" is name-from-author-only, so subtree text is never
+ *   accepted: text sitting inside a custom combobox widget is not reliably
+ *   exposed as its name. On a labelable element (<input role="combobox">) an
+ *   associated <label> counts as well.
+ */
+
 const id = 'combobox-name-present';
 
 const meta = {
@@ -66,7 +86,7 @@ function runInPage(ctx) {
   }
 
   function getConservativeSubtreeText(document, container) {
-    // "Name from content" — recurses into descendants and uses each one's
+    // "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
@@ -83,7 +103,7 @@ function runInPage(ctx) {
 
   // A <label> contributes a name via its own aria-label/aria-labelledby
   // (checked first, same ARIA-over-content precedence any element's
-  // accessible name gives — e.g. <label aria-label="Search"><svg
+  // accessible name gives, e.g. <label aria-label="Search"><svg
   // aria-hidden="true">...</svg></label> names its control "Search" even
   // though the label's only child content is aria-hidden) or, failing
   // that, its rendered content (getConservativeSubtreeText).
@@ -98,10 +118,10 @@ function runInPage(ctx) {
     if (content) return content;
     // Final fallback per the general accname text-alternative algorithm,
     // which applies to any element being asked for its name regardless of
-    // why (own aria-label, an aria-labelledby reference, or — here — native
+    // why (own aria-label, an aria-labelledby reference, or, here, native
     // <label for> association): title, when nothing else yields a name.
     // Purely additive (only fills in a name where there was none before),
-    // so it carries no false-positive risk — see dialog-name-present.js's
+    // so it carries no false-positive risk, see dialog-name-present.js's
     // identical <iframe>-title-fallback fix for the concrete real-world
     // trigger this same accname step covers elsewhere.
     return getAttr(lab, 'title');
@@ -111,7 +131,7 @@ function runInPage(ctx) {
     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-
+    // 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).
@@ -235,7 +255,7 @@ function runInPage(ctx) {
     occurrences.push(
       helpers.reportOccurrence(el, {
         summary: 'This combobox has no accessible name.',
-        hint: "Provide aria-label, aria-labelledby, or a title attribute — visible text content is not exposed as this combobox's accessible name.",
+        hint: "Provide aria-label, aria-labelledby, or a title attribute. Visible text content is not exposed as this combobox's accessible name.",
         i18n: {
           summaryKey: 'comboboxNamePresent_summary_fail',
           hintKey: 'comboboxNamePresent_hint_fail',

package/src/checks/automatic/contrast-computable.js

@@ -2,6 +2,37 @@
 
 'use strict';
 
+/**
+ * @check contrast-computable
+ * @atomic true
+ * @summary Color contrast must be computable from CSS for rendered text
+ * @standard WCAG 2.2
+ * @sc 1.4.3
+ * @sc 1.4.6
+ * @applicability
+ *   Applies to every visible text node in scope, plus the label of <input
+ *   type="button">/[type="submit"]/[type="reset"], which is rendered from
+ *   the value attribute and so is invisible to a text-node walk. Text counts
+ *   only when its element is DOM-visible under the run's visibility mode, is
+ *   not clipped out of sight by the sr-only technique (clip or clip-path),
+ *   and belongs neither to a disabled control nor to the label of one,
+ *   WCAG's inactive-user-interface-component exception. Subtrees excluded
+ *   via engineOptions.excludeSelectors are skipped, and open shadow roots
+ *   are walked as roots in their own right.
+ * @expectation
+ *   Both sides of the contrast calculation can be established from CSS for
+ *   every applicable text node: an effective background resolving to an
+ *   opaque color, and a parsable foreground color. Where either cannot be,
+ *   a background image or gradient, mix-blend-mode, a filter or
+ *   backdrop-filter, a text-shadow (which may add contrast this engine has
+ *   no glyph-rendering model to account for), ancestor opacity, a root
+ *   background that never becomes opaque, or a color that does not parse,
+ *   the result is cantTell naming the blocker. This rule is the one that
+ *   reports that uncertainty, which is what lets contrast-minimum and
+ *   contrast-enhanced stay silent on the same text instead of guessing at
+ *   a ratio.
+ */
+
 const id = 'contrast-computable';
 
 const meta = {
@@ -118,6 +149,7 @@ function runInPage(ctx) {
         else summaryKey = 'contrastComputable_cantTell_filterOrBackdropFilter';
       } else if (rc === 'BACKGROUND_NOT_OPAQUE_AT_ROOT')
         summaryKey = 'contrastComputable_cantTell_rootNotOpaque';
+      else if (rc === 'TEXT_SHADOW') summaryKey = 'contrastComputable_cantTell_textShadow';
 
       const details = Object.assign(
         { reasonCode: rc },
@@ -146,6 +178,16 @@ function runInPage(ctx) {
               : {}
           )
         },
+        uncertainty: {
+          code: 'not-computable',
+          needed: 'A contrast ratio for this text, which this page composition blocks.',
+          evidence: {
+            reasonCode: rc,
+            blockerProperty: details.blockerProperty || null,
+            blockerValue: details.blockerValue || null,
+            backgroundAlpha: details.backgroundAlpha === undefined ? null : details.backgroundAlpha
+          }
+        },
         data: { details }
       };
 

package/src/checks/automatic/contrast-enhanced.js

@@ -2,10 +2,30 @@
 
 'use strict';
 
+/**
+ * @check contrast-enhanced
+ * @atomic true
+ * @summary Text must meet the WCAG AAA contrast ratio for its size
+ * @standard WCAG 2.2
+ * @sc 1.4.6
+ * @applicability
+ *   Applies to the visible text contrast-computable applies to, see that
+ *   rule for the eligibility gates, narrowed to text whose background and
+ *   foreground are actually computable. Eligible text that is not computable
+ *   leaves this rule notApplicable rather than cantTell: reporting that
+ *   uncertainty belongs to contrast-computable, so the two never report the
+ *   same text twice.
+ * @expectation
+ *   Every computable text node reaches the ratio SC 1.4.6 requires for its
+ *   size: 4.5:1 for large text, 7:1 for everything else. Text is large at
+ *   24px or more, or at 14pt (about 18.667px) or more when the computed font
+ *   weight is 700 or higher.
+ */
+
 const id = 'contrast-enhanced';
 
 const meta = {
-  title: 'Text must meet the enhanced color contrast ratio',
+  title: 'Text meets enhanced color contrast (AAA)',
   description:
     'Checks that visible text has a contrast ratio of at least 7:1 (normal) or 4.5:1 (large), when contrast is computable from CSS.',
   i18n: {
@@ -196,6 +216,17 @@ function runInPage(ctx) {
 
       const det = details && typeof details === 'object' ? details : { reasonCode: 'UNKNOWN' };
 
+      // The background is the only input this rule can fail to resolve; every other
+      // reason code here describes a ratio it did compute.
+      const uncertainty =
+        det.reasonCode === 'BACKGROUND_NOT_COMPUTABLE'
+          ? {
+              code: 'not-computable',
+              needed: 'The effective background colour behind this text.',
+              evidence: { reasonCode: det.reasonCode, foreground: det.fg || null }
+            }
+          : null;
+
       const occBase = {
         selector: '',
         html: '',
@@ -206,6 +237,7 @@ function runInPage(ctx) {
           hintKey: '',
           params: params && typeof params === 'object' ? params : {}
         },
+        ...(uncertainty ? { uncertainty } : {}),
         data: { details: det }
       };
 

package/src/checks/automatic/contrast-minimum.js

@@ -2,10 +2,30 @@
 
 'use strict';
 
+/**
+ * @check contrast-minimum
+ * @atomic true
+ * @summary Text must meet the WCAG AA contrast ratio for its size
+ * @standard WCAG 2.2
+ * @sc 1.4.3
+ * @applicability
+ *   Applies to the visible text contrast-computable applies to, see that
+ *   rule for the eligibility gates, narrowed to text whose background and
+ *   foreground are actually computable. Eligible text that is not computable
+ *   leaves this rule notApplicable rather than cantTell: reporting that
+ *   uncertainty belongs to contrast-computable, so the two never report the
+ *   same text twice.
+ * @expectation
+ *   Every computable text node reaches the ratio SC 1.4.3 requires for its
+ *   size: 3:1 for large text, 4.5:1 for everything else. Text is large at
+ *   24px or more, or at 14pt (about 18.667px) or more when the computed font
+ *   weight is 700 or higher.
+ */
+
 const id = 'contrast-minimum';
 
 const meta = {
-  title: 'Text must meet the minimum color contrast ratio',
+  title: 'Text meets minimum color contrast (AA)',
   description:
     'Checks that visible text has a contrast ratio of at least 4.5:1 (normal) or 3:1 (large), when contrast is computable from CSS.',
   i18n: {
@@ -193,6 +213,17 @@ function runInPage(ctx) {
 
       const det = details && typeof details === 'object' ? details : { reasonCode: 'UNKNOWN' };
 
+      // The background is the only input this rule can fail to resolve; every other
+      // reason code here describes a ratio it did compute.
+      const uncertainty =
+        det.reasonCode === 'BACKGROUND_NOT_COMPUTABLE'
+          ? {
+              code: 'not-computable',
+              needed: 'The effective background colour behind this text.',
+              evidence: { reasonCode: det.reasonCode, foreground: det.fg || null }
+            }
+          : null;
+
       const occBase = {
         selector: '',
         html: '',
@@ -203,6 +234,7 @@ function runInPage(ctx) {
           hintKey: '',
           params: params && typeof params === 'object' ? params : {}
         },
+        ...(uncertainty ? { uncertainty } : {}),
         data: { details: det }
       };
 

package/src/checks/automatic/css-orientation-lock.js

@@ -9,13 +9,13 @@
  * @standard WCAG 2.2
  * @sc 1.3.4
  * @applicability
- *   Any accessible (same-document, non-cross-origin) stylesheet — inline
+ *   Any accessible (same-document, non-cross-origin) stylesheet, inline
  *   `<style>` blocks and same-origin `<link>` stylesheets already loaded
  *   into `document.styleSheets`.
  * @expectation
  *   No `@media (orientation: portrait)` or `@media (orientation:
  *   landscape)` block sets a `transform`/`-webkit-transform`/`rotate`
- *   rotation of approximately 90 degrees (mod 180, i.e. ~90 or ~270) —
+ *   rotation of approximately 90 degrees (mod 180, i.e. ~90 or ~270),
  *   the well-known technique for visually forcing one orientation
  *   regardless of the device's actual orientation, which defeats WCAG
  *   1.3.4's requirement that content not restrict its view to a single
@@ -27,14 +27,15 @@
  *   lock. Compute the actual rotation angle and only flag ~90/~270 degrees,
  *   excluding ~0/~180 (a no-op or a flip, neither of which changes
  *   portrait<->landscape).
- * - Only `rotate`/`rotateZ` (transform functions) and the standalone CSS
- *   `rotate` property are parsed for degrees, from the two sources
- *   `style.transform`/`style.rotate`; `matrix()`/`matrix3d()`/`rotate3d()`
- *   are not decomposed into an equivalent angle (deliberately deferred as
- *   the same class of higher-complexity/lower-value work deferred elsewhere,
- *   e.g. `table-th-has-data-cells`'s narrower positional-header algorithm).
+ * - `rotate`/`rotateZ`, the standalone CSS `rotate` property, and
+ *   `rotate3d(x, y, z, angle)`/`matrix()`/`matrix3d()` are all parsed for
+ *   degrees. The matrix forms only yield an angle when they resolve to a
+ *   pure rotation about the Z axis (no scale, skew, translation, or
+ *   rotation combined with another axis). Anything else contributes 0,
+ *   same as an unrecognized value, rather than guessing at an angle a
+ *   general 3D matrix doesn't uniquely have.
  * - Cross-origin stylesheets throw on `.cssRules` access (browser
- *   security model) and are skipped — same class of limitation as any
+ *   security model) and are skipped, same class of limitation as any
  *   check that can only see same-origin/inspectable content (compare
  *   `iframe-focusable-content`).
  * - Not per-element: this is a whole-document/whole-stylesheet concern,
@@ -107,25 +108,98 @@ function runInPage(ctx) {
     return value; // deg
   }
 
-  // Sums the degrees of every rotate()/rotateZ() function found in a
-  // transform value (a real transform can legitimately compose more than
-  // one, e.g. "translate(-50%) rotate(90deg)").
+  function parseNumberList(argsStr) {
+    return trim(argsStr)
+      .split(',')
+      .map((s) => parseFloat(s.trim()));
+  }
+
+  // A 2D linear map (a, b, c, d) -- the first four arguments of
+  // `matrix(a, b, c, d, e, f)`, or the top-left of `matrix3d`'s 4x4 --
+  // is a pure rotation only when its columns are unit length and
+  // orthogonal (no scale/skew/reflection): a = cos(theta), b = sin(theta),
+  // c = -sin(theta), d = cos(theta). Returns degrees, or null when the
+  // map isn't a pure rotation.
+  function decomposeMatrix2dRotation(a, b, c, d) {
+    const EPS = 1e-3;
+    if (Math.abs(a - d) > EPS || Math.abs(b + c) > EPS) return null;
+    if (Math.abs(a * a + b * b - 1) > EPS) return null;
+    if (Math.abs(a * d - b * c - 1) > EPS) return null;
+    return (Math.atan2(b, a) * 180) / Math.PI;
+  }
+
+  // The 16 column-major values of `matrix3d(...)` represent a pure Z-axis
+  // rotation only when the 3rd/4th columns still match the identity (no
+  // translation, perspective, or rotation around another axis) and the
+  // top-left 2x2 block is a pure 2D rotation.
+  function decomposeMatrix3dZRotation(v) {
+    if (v.length !== 16 || !v.every(Number.isFinite)) return null;
+    const EPS = 1e-3;
+    const near = (x, t) => Math.abs(x - t) < EPS;
+    if (!(near(v[2], 0) && near(v[3], 0) && near(v[6], 0) && near(v[7], 0))) return null;
+    if (!(near(v[8], 0) && near(v[9], 0) && near(v[10], 1) && near(v[11], 0))) return null;
+    if (!(near(v[12], 0) && near(v[13], 0) && near(v[14], 0) && near(v[15], 1))) return null;
+    return decomposeMatrix2dRotation(v[0], v[1], v[4], v[5]);
+  }
+
+  // Sums the degrees of every rotate()/rotateZ()/rotate3d()/matrix()/
+  // matrix3d() function found in a transform value (a real transform can
+  // legitimately compose more than one, e.g. "translate(-50%)
+  // rotate(90deg)"). The matrix forms only contribute when they decompose
+  // to a pure Z rotation; anything else contributes 0, same as no match.
   function rotateDegreesFromTransform(t) {
     if (!t) return 0;
     let total = 0;
-    const re = /rotate(?:Z)?\s*\(([^)]*)\)/gi;
     let m;
-    while ((m = re.exec(t)) !== null) {
+
+    const rotateRe = /rotate(?:Z)?\s*\(([^)]*)\)/gi;
+    while ((m = rotateRe.exec(t)) !== null) {
       total += angleToDegrees(m[1]);
     }
+
+    const rotate3dRe = /rotate3d\s*\(([^)]*)\)/gi;
+    while ((m = rotate3dRe.exec(t)) !== null) {
+      const parts = m[1].split(',');
+      if (parts.length !== 4) continue;
+      const x = parseFloat(parts[0]);
+      const y = parseFloat(parts[1]);
+      const z = parseFloat(parts[2]);
+      const deg = angleToDegrees(parts[3]);
+      if (!Number.isFinite(x) || !Number.isFinite(y) || !Number.isFinite(z) || !deg) continue;
+      const EPS = 1e-3;
+      if (Math.abs(x) < EPS && Math.abs(y) < EPS && Math.abs(Math.abs(z) - 1) < EPS) {
+        total += z < 0 ? -deg : deg;
+      }
+    }
+
+    const matrixRe = /matrix\s*\(([^)]*)\)/gi;
+    while ((m = matrixRe.exec(t)) !== null) {
+      const vals = parseNumberList(m[1]);
+      if (vals.length === 6 && vals.every(Number.isFinite)) {
+        const deg = decomposeMatrix2dRotation(vals[0], vals[1], vals[2], vals[3]);
+        if (deg != null) total += deg;
+      }
+    }
+
+    const matrix3dRe = /matrix3d\s*\(([^)]*)\)/gi;
+    while ((m = matrix3dRe.exec(t)) !== null) {
+      const deg = decomposeMatrix3dZRotation(parseNumberList(m[1]));
+      if (deg != null) total += deg;
+    }
+
     return total;
   }
 
   // Whole-page-orientation-lock detection (see @implementation-notes): a
   // rotation near 0 or 180 degrees (mod 180) is a no-op or a flip, neither
   // of which changes portrait<->landscape, so it's NOT a lock; only a
-  // rotation near 90 or 270 degrees (mod 90, once the 0/180 case is
-  // excluded) is.
+  // rotation near 90 or 270 degrees is. "Near" is a tolerance window, not
+  // exact equality: a `rad`/`grad`/`turn` value converts to a 90-degree
+  // rotation with floating-point remainder (e.g. `1.5708rad` is
+  // 90.0000210...deg, never exactly 90), and ACT's own failed examples
+  // include a -inexact 92.5deg, both must still register as a
+  // lock, which exact-modulo-equality (`% 90 === 0`) never does.
+  const LOCK_TOLERANCE_DEG = 5;
   function isLockingRotation(styleDecl) {
     if (!styleDecl) return false;
     const transformVal =
@@ -141,9 +215,12 @@ function runInPage(ctx) {
 
     if (!degrees) return false;
 
-    const abs = Math.abs(degrees);
-    if (Math.abs(abs - 180) % 180 <= 0) return false; // near 0/180: not a lock
-    return Math.abs(abs - 90) % 90 <= 0; // near 90/270: a lock
+    // Normalize into [0, 180): a rotation and its mirror (rotation + 180)
+    // swap the same two axes, so only the position within one half-turn
+    // matters. A value near the 90-degree midpoint of that range is near
+    // 90 OR 270 in the original full-turn range.
+    const normalized = ((degrees % 180) + 180) % 180;
+    return Math.abs(normalized - 90) <= LOCK_TOLERANCE_DEG;
   }
 
   function isOrientationMedia(mediaText) {
@@ -163,6 +240,7 @@ function runInPage(ctx) {
 
   const findings = [];
   let sheetCount = 0;
+  let unreadableSheetCount = 0;
 
   try {
     const sheets = document.styleSheets || [];
@@ -171,7 +249,10 @@ function runInPage(ctx) {
       try {
         rules = sheet && sheet.cssRules ? sheet.cssRules : null;
       } catch {
-        continue; // cross-origin stylesheet, not inspectable
+        // Cross-origin, not inspectable. Counted, since a lock could be
+        // declared there and a `pass` would claim more than was checked.
+        unreadableSheetCount += 1;
+        continue;
       }
       if (!rules) continue;
       sheetCount += 1;
@@ -187,15 +268,48 @@ function runInPage(ctx) {
     // no-throw: treat as no accessible stylesheets
   }
 
-  if (sheetCount === 0) {
-    return { ruleId: rule.ruleId, outcome: 'notApplicable', severity: 'minor', occurrences: [] };
-  }
+  const scanTarget = document.documentElement || document.body || null;
 
+  // A lock found in a readable sheet is still a lock, so `fail` outranks the
+  // uncertainty below.
   if (!findings.length) {
+    if (unreadableSheetCount > 0) {
+      return {
+        ruleId: rule.ruleId,
+        outcome: 'cantTell',
+        severity: rule.defaultSeverity || 'serious',
+        confidence: 'low',
+        occurrences: [
+          helpers.reportOccurrence(scanTarget, {
+            summary: `${unreadableSheetCount} stylesheet(s) could not be read, so whether this page locks its orientation could not be determined.`,
+            hint: 'Cross-origin stylesheets are not inspectable from the page. Check any third-party CSS for an orientation media query containing a rotate() transform, or re-run the scan with those stylesheets served same-origin.',
+            i18n: {
+              summaryKey: 'cssOrientationLock_summary_cantTell_unreadableSheets',
+              hintKey: 'cssOrientationLock_hint_cantTell_unreadableSheets',
+              params: { count: String(unreadableSheetCount) }
+            },
+            uncertainty: {
+              code: 'not-computable',
+              needed: 'The contents of the stylesheets this scan could not read.',
+              evidence: { unreadableSheetCount, reasonCode: 'STYLESHEETS_NOT_READABLE' }
+            },
+            data: {
+              details: {
+                reasonCode: 'STYLESHEETS_NOT_READABLE',
+                unreadableSheetCount
+              }
+            }
+          })
+        ]
+      };
+    }
+    if (sheetCount === 0) {
+      return { ruleId: rule.ruleId, outcome: 'notApplicable', severity: 'minor', occurrences: [] };
+    }
     return { ruleId: rule.ruleId, outcome: 'pass', severity: 'minor', occurrences: [] };
   }
 
-  const target = document.documentElement || document.body || null;
+  const target = scanTarget;
   const occurrences = findings.map((f) =>
     helpers.reportOccurrence(target, {
       summary: f.selectorText

package/src/checks/automatic/definition-list-children-valid.js

@@ -16,17 +16,16 @@
  *   level of wrapping div is allowed, matching how authors commonly group
  *   dt/dd pairs). If the flattened set contains any <dt> or <dd> at all, it
  *   must contain BOTH (an unbalanced dt-without-dd or dd-without-dt is
- *   invalid) — a flattened set with neither is vacuously fine, not a
+ *   invalid). A flattened set with neither is vacuously fine, not a
  *   violation (see implementation-notes). Any other direct or wrapped child
  *   breaks the description-list semantics assistive technologies rely on.
  * @implementation-notes
- * - Only one level of <div> wrapping is flattened — a <div> nested inside
+ * - Only one level of <div> wrapping is flattened, a <div> nested inside
  *   another wrapping <div> is not flattened further and its contents are
  *   reported invalid.
  * - The dt/dd pairing is only required "when not empty". A flattened set
- *   with NEITHER dt nor dd
- *   — whether from an empty wrapping <div>, only <script>/<template>/
- *   <style> content, or a genuinely childless <dl> — is not flagged; only
+ *   with NEITHER dt nor dd, whether from an empty wrapping <div>, only
+ *   <script>/<template>/<style> content, or a childless <dl>, is not flagged; only
  *   an unbalanced dt/dd pairing is a real structural problem.
  * - Distinct, atomic decision from dlitem-parent-valid (the
  *   inverse relationship: does a given <dt>/<dd> have a valid parent).
@@ -64,7 +63,7 @@ const meta = {
 function runInPage(ctx) {
   const { helpers, rule } = ctx;
 
-  // Declared inside runInPage — see scripts/build-core.js header
+  // Declared inside runInPage, see scripts/build-core.js header
   // ("runInPage MUST be self-contained").
   const PASSTHROUGH_TAGS = new Set(['dt', 'dd', 'script', 'template', 'style']);
 
@@ -109,8 +108,8 @@ function runInPage(ctx) {
     }
     const dedupedInvalidTags = [...new Set(invalidTags)];
 
-    // The dt/dd pairing is only required "when not empty" — a <dl> with
-    // NEITHER dt nor dd (whether genuinely childless after flattening, only
+    // The dt/dd pairing is only required "when not empty", a <dl> with
+    // NEITHER dt nor dd (whether childless after flattening, only
     // passthrough script/template/style content, or an empty wrapping div)
     // is vacuously fine, not a violation. Only an UNBALANCED pairing (dt
     // present without any dd, or vice versa) is a real structural problem.

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

@@ -15,7 +15,7 @@
  *   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
+ *   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).
  * @implementation-notes

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

@@ -2,6 +2,24 @@
 
 'use strict';
 
+/**
+ * @check dialog-name-present
+ * @atomic true
+ * @summary Elements with role="dialog"/"alertdialog" 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.
+ * @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
+ *   roles are name-from-author-only, so the heading or body text inside the
+ *   dialog is not accepted as its name unless aria-labelledby points at it.
+ */
+
 const id = 'dialog-name-present';
 
 const meta = {
@@ -54,13 +72,13 @@ function runInPage(ctx) {
   function resolveAriaLabelledbyText(document, el, maxRefs) {
     const raw = getAttr(el, 'aria-labelledby');
     if (!raw) return '';
-    // Resolve via the shared getTextFromIdRefs helper — computes each
+    // Resolve via the shared getTextFromIdRefs helper, computes each
     // referenced element's own ACCESSIBLE NAME (aria-label, then
     // aria-labelledby, then a value-like name, then content, then title),
     // not just its content text. This matters when aria-labelledby points
     // at an <iframe title="..."> (e.g. BBC News' cookie-consent dialog,
     // pointing at an `<iframe title="SP Consent Message">`), whose only
-    // name source is its title attribute — an iframe's content is
+    // name source is its title attribute, an iframe's content is
     // opaque/cross-origin per HTML-AAM, so "name from content" is always
     // empty. Computing only name-from-content of the referenced node would
     // silently miss the title fallback and report no accessible name at

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

@@ -20,8 +20,10 @@
  *   still computed. Whether that element is the intended target depends on
  *   author intent, which markup does not carry, so the outcome is cantTell.
  * @implementation-notes
- * - Scoped deliberately to ids referenced by ARIA, not the broader/
- *   deprecated page-wide duplicate-id check (see ROADMAP.md's "Skip" list).
+ * - Scoped to ids referenced by ARIA. The page-wide check
+ *   lives in its own rule, `duplicate-id`, mapped to the WCAG 2.0/2.1 SC
+ *   4.1.1 that WCAG 2.2 removed; the two overlap on referenced ids and
+ *   answer different questions there (see that rule's header).
  * - Document-wide by design: id uniqueness and ARIA id references are a
  *   whole-document property, not scoped to a sub-root. Reported occurrences are
  *   limited to the scanned scope.
@@ -59,7 +61,7 @@ const meta = {
 function runInPage(ctx) {
   const { document, helpers, rule } = ctx;
 
-  // Declared inside runInPage — see scripts/build-core.js header
+  // Declared inside runInPage, see scripts/build-core.js header
   // ("runInPage MUST be self-contained").
   const IDREF_ATTRS = [
     'aria-labelledby',
@@ -126,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',