@surea11y/core 1.3.0 → 1.4.0

package/src/checks/automatic/aria-roles-valid.js

@@ -1,3 +1,5 @@
+/* SPDX-License-Identifier: MPL-2.0 */
+
 'use strict';
 
 /**

package/src/checks/automatic/aria-valid-attr-value.js

@@ -1,3 +1,5 @@
+/* SPDX-License-Identifier: MPL-2.0 */
+
 'use strict';
 
 /**
@@ -13,25 +15,26 @@
  * @expectation
  *   Each attribute's value conforms to its WAI-ARIA-declared value type:
  *   boolean ("true"/"false"), tristate ("true"/"false"/"mixed"), a token
- *   from a fixed enumerated set, an integer, a real number, or a non-empty
- *   ID reference (list) that resolves to an existing element in the
- *   document.
+ *   from a fixed enumerated set, an integer, a real number, or an empty
+ *   value or ID reference (list) that resolves to an existing element in
+ *   the document.
  * @implementation-notes
  * - Not rule-gated on isAccTreeEligible: this remains a static-markup
  *   property, while engine-level hidden-subtree filtering still applies
  *   unless engineOptions.includeHiddenElements is true.
- * - ID-reference resolution (added 2026-07-20, see aria-helpers.js's
- *   idExists) only flags idref-list attributes (aria-labelledby,
- *   aria-describedby, aria-controls, aria-owns, etc.) when NONE of the
- *   space-separated ids resolve — a partially-dangling list (some ids
- *   exist, some don't) is left unflagged. Verified 2026-07-21 directly
- *   against a widely-used reference engine's own `validateAttrValue` source:
- *   this is not a conservative guess, it's an exact match for that engine's
- *   own behavior (`idrefs(vNode, attr).some(node => !!node)` — that engine
- *   itself only invalidates when every token fails to resolve). Single-idref
- *   attributes (aria-activedescendant, aria-errormessage) are flagged
- *   whenever their one id doesn't resolve, also matching that engine's `idref`
- *   case exactly.
+ * - ID-reference resolution (see aria-helpers.js's idExists) only flags
+ *   idref-list attributes (aria-labelledby, aria-describedby,
+ *   aria-controls, aria-owns, etc.) when NONE of the space-separated ids
+ *   resolve — a partially-dangling list (some ids exist, some don't) is
+ *   left unflagged (only invalidate when every token fails to resolve).
+ *   Single-idref attributes (aria-activedescendant, aria-errormessage) are
+ *   flagged whenever their one id doesn't resolve.
+ * - An explicitly-EMPTY idref/idref-list value (e.g.
+ *   `aria-describedby=""`) is valid, not a violation — `allowEmpty` holds
+ *   for every idref/idref-list ARIA attribute. A common, deliberate pattern
+ *   in templated markup (e.g. React conditionally rendering
+ *   `aria-describedby={hasError ? errorId : ''}`); flagging it would be a
+ *   false positive.
  */
 
 const id = 'aria-valid-attr-value';

package/src/checks/automatic/aria-valid-attr.js

@@ -1,3 +1,5 @@
+/* SPDX-License-Identifier: MPL-2.0 */
+
 'use strict';
 
 /**

package/src/checks/automatic/autocomplete-valid.js

@@ -1,3 +1,5 @@
+/* SPDX-License-Identifier: MPL-2.0 */
+
 'use strict';
 
 /**

package/src/checks/automatic/avoid-inline-spacing.js

@@ -1,3 +1,5 @@
+/* SPDX-License-Identifier: MPL-2.0 */
+
 'use strict';
 
 /**
@@ -19,8 +21,7 @@
  * @implementation-notes
  * - Static text-based parsing of the style attribute string (regex for
  *   the three property names followed by `!important`), not computed
- *   style — matches the property list a widely-used reference engine's avoid-inline-spacing
- *   rule checks.
+ *   style.
  */
 
 const id = 'avoid-inline-spacing';

package/src/checks/automatic/binary-control-name-present.js

@@ -1,3 +1,5 @@
+/* SPDX-License-Identifier: MPL-2.0 */
+
 'use strict';
 
 const id = 'binary-control-name-present';

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

@@ -1,3 +1,5 @@
+/* SPDX-License-Identifier: MPL-2.0 */
+
 'use strict';
 
 // NOTE: Repo ruleId contract requires ENGINE_TAG prefix in the rule id.
@@ -47,9 +49,8 @@ function runInPage(ctx) {
     // 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
-    // (this replaced a text-node-only TreeWalker that missed the common
-    // "<a><img alt='...'></a>" logo-link / "<button><img alt='...'></button>"
-    // icon-button pattern).
+    // (covers the common "<a><img alt='...'></a>" logo-link /
+    // "<button><img alt='...'></button>" icon-button pattern).
     if (helpers.getContentNameInfo) {
       const info = helpers.getContentNameInfo(container, ctx);
       return info && info.present ? info.value : '';
@@ -107,10 +108,9 @@ function runInPage(ctx) {
     // one of these roles is no longer semantically a button — per the WAI-ARIA
     // Accessible Name and Description Computation spec these roles are
     // name-from-author-only, and their rendered content represents a VALUE,
-    // not a NAME. Found on a real page (Spotify's "sort by" control): a
-    // <button role="combobox">List</button> where "List" is the combobox's
-    // currently selected value, not a label for what the combobox is —
-    // crediting it as the accessible name masked a real missing-name bug.
+    // not a NAME. E.g. <button role="combobox">List</button> where "List" is
+    // the combobox's currently selected value, not a label — crediting it as
+    // the accessible name would mask a missing name.
     const VALUE_ROLES = [
       'textbox',
       'progressbar',

package/src/checks/automatic/bypass-blocks-present.js

@@ -1,3 +1,5 @@
+/* SPDX-License-Identifier: MPL-2.0 */
+
 'use strict';
 
 /**
@@ -27,8 +29,8 @@
  *       mechanism (e.g. a screen reader's "jump by heading" command).
  * @implementation-notes
  * - This rule intentionally checks presence, not position, for the
- *   same-page-anchor condition (b): a widely-used reference engine's real bypass algorithm is
- *   heuristic (see ROADMAP.md's Tier 1a note on why this rule was
+ *   same-page-anchor condition (b): a full bypass algorithm is heuristic
+ *   (see ROADMAP.md's Tier 1a note on why this rule was
  *   deferred from the rest of that batch), and getting DOM-order /
  *   keyboard-focus-order positioning exactly right without introducing
  *   false positives is materially harder than the rest of Tier 1a. Being
@@ -115,12 +117,12 @@ function runInPage(ctx) {
   }
 
   // Filters through isAccTreeEligible (hidden/aria-hidden/display:none/inert
-  // don't count as "a bypass mechanism is present") -- see page-has-heading-
-  // one-manual.js's identical fix for the real-world trigger (CDC's flu
-  // page, 2026-07-30: its only <h1> sits inside a display:none ancestor,
+  // don't count as "a bypass mechanism is present") -- see
+  // page-has-heading-one-manual.js for the identical real-world trigger
+  // (e.g. a page whose only <h1> sits inside a display:none ancestor,
   // unreachable by sighted and screen reader users alike). A fully
-  // non-rendered <main>/heading was previously credited here too, wrongly
-  // returning `pass` for a page with zero actual bypass mechanisms.
+  // non-rendered <main>/heading must not be credited here, since that would
+  // wrongly return `pass` for a page with zero actual bypass mechanisms.
   function hasMainLandmark() {
     for (const el of queryAll('main, [role="main"]')) {
       if (el && isExposedToAt(el)) return true;

package/src/checks/automatic/canvas-text-alternative-present.js

@@ -1,3 +1,5 @@
+/* SPDX-License-Identifier: MPL-2.0 */
+
 'use strict';
 
 /**

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

@@ -1,3 +1,5 @@
+/* SPDX-License-Identifier: MPL-2.0 */
+
 'use strict';
 
 const id = 'combobox-name-present';

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

@@ -1,3 +1,5 @@
+/* SPDX-License-Identifier: MPL-2.0 */
+
 'use strict';
 
 const id = 'contrast-computable';

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

@@ -1,3 +1,5 @@
+/* SPDX-License-Identifier: MPL-2.0 */
+
 'use strict';
 
 const id = 'contrast-enhanced';

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

@@ -1,3 +1,5 @@
+/* SPDX-License-Identifier: MPL-2.0 */
+
 'use strict';
 
 const id = 'contrast-minimum';

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

@@ -1,3 +1,5 @@
+/* SPDX-License-Identifier: MPL-2.0 */
+
 'use strict';
 
 /**
@@ -20,25 +22,17 @@
  *   display orientation unless that orientation is essential.
  * @implementation-notes
  * - The rotation DEGREE is what makes this the exploit signature, not
- *   merely the presence of a `rotate()` function — verified against a
- *   widely-used reference engine's own `css-orientation-lock` check
- *   (`cssOrientationLockEvaluate`), which computes the actual rotation angle and only
- *   flags ~90/~270 degrees, explicitly excluding ~0/~180 (a no-op or a
- *   flip, neither of which changes portrait<->landscape). A prior
- *   version of this rule flagged the bare presence of "rotate(" in an
- *   orientation-media-query rule regardless of angle — a real, confirmed
- *   false positive found via the live-DOM cross-engine corpus 2026-07-23
- *   on a real page (Times of India) whose `@media (orientation:portrait)`
- *   block only rotated a small decorative arrow icon 45 degrees, nothing
- *   resembling a page-orientation lock.
+ *   merely the presence of a `rotate()` function: a small decorative icon
+ *   rotated 45 degrees inside an orientation media query is not a page
+ *   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 — matches that reference engine's
- *   own two sources (`style.transform`/`style.rotate`) but, like that engine,
- *   does not attempt to decompose `matrix()`/`matrix3d()`/`rotate3d()` into an
- *   equivalent angle (that engine does handle those; deliberately deferred here
- *   as the same class of "genuinely more complex, lower real-world
- *   value" work already deferred elsewhere in this engine, e.g.
- *   `table-th-has-data-cells`'s narrower positional-header algorithm).
+ *   `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).
  * - Cross-origin stylesheets throw on `.cssRules` access (browser
  *   security model) and are skipped — same class of limitation as any
  *   check that can only see same-origin/inspectable content (compare
@@ -98,9 +92,9 @@ function runInPage(ctx) {
   }
 
   // Converts a rotate()/rotateZ() angle argument (with unit) to degrees.
-  // Matches a widely-used reference engine's own getAngleInDegrees: only deg/grad/rad/turn are
-  // recognized; a unitless or unrecognized value contributes 0 (ignored,
-  // not treated as a lock -- an unparseable angle isn't a confirmed exploit).
+  // Only deg/grad/rad/turn are recognized; a unitless or unrecognized value
+  // contributes 0 (ignored, not treated as a lock -- an unparseable angle
+  // isn't a confirmed exploit).
   function angleToDegrees(raw) {
     const m = /(-?[\d.]+)\s*(deg|grad|rad|turn)/i.exec(raw);
     if (!m) return 0;
@@ -127,17 +121,17 @@ function runInPage(ctx) {
     return total;
   }
 
-  // Whole-page-orientation-lock detection, matching a widely-used reference engine's own degree
-  // math exactly (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 explicitly NOT a lock; only a rotation
-  // near 90 or 270 degrees (mod 90, once the 0/180 case is excluded) is.
+  // 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.
   function isLockingRotation(styleDecl) {
     if (!styleDecl) return false;
     const transformVal =
       trim(styleDecl.transform) ||
       trim(styleDecl.getPropertyValue ? styleDecl.getPropertyValue('-webkit-transform') : '');
-    // The standalone CSS `rotate` property (distinct from `transform: rotate()`) -- that reference engine checks this too.
+    // The standalone CSS `rotate` property (distinct from `transform: rotate()`).
     const rotatePropVal = trim(
       styleDecl.getPropertyValue ? styleDecl.getPropertyValue('rotate') : ''
     );

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

@@ -1,3 +1,5 @@
+/* SPDX-License-Identifier: MPL-2.0 */
+
 'use strict';
 
 /**
@@ -18,12 +20,11 @@
  *   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, matching a widely-used
- *   reference engine's definition-list algorithm — 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.
- * - Verified 2026-07-20 against a widely-used reference engine: the dt/dd pairing is
- *   only required "when not empty". A flattened set with NEITHER dt nor dd
+ * - 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
  *   an unbalanced dt/dd pairing is a real structural problem.
@@ -108,8 +109,7 @@ function runInPage(ctx) {
     }
     const dedupedInvalidTags = [...new Set(invalidTags)];
 
-    // Verified 2026-07-20 against a widely-used reference engine's definition-list check:
-    // the dt/dd pairing is only required "when not empty" — a <dl> with
+    // The dt/dd pairing is only required "when not empty" — a <dl> with
     // NEITHER dt nor dd (whether genuinely 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

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

@@ -1,3 +1,5 @@
+/* SPDX-License-Identifier: MPL-2.0 */
+
 'use strict';
 
 /**
@@ -14,8 +16,8 @@
  * @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, matching a widely-used reference engine's `blink`/`marquee`
- *   rules (which report only when the element is found).
+ *   rule has no partial-pass case (it reports only when the element is
+ *   found).
  * @implementation-notes
  * - Not rule-gated on isAccTreeEligible: presence in markup is itself the
  *   violation, independent of visibility (moving/blinking content inside a

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

@@ -1,3 +1,5 @@
+/* SPDX-License-Identifier: MPL-2.0 */
+
 'use strict';
 
 const id = 'dialog-name-present';
@@ -55,16 +57,14 @@ function runInPage(ctx) {
     // 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. Found via a real page (BBC News' cookie-
-    // consent dialog, 2026-07-22): aria-labelledby pointed at an
-    // <iframe title="SP Consent Message">, whose only name source is its
-    // title attribute (an iframe's content is opaque/cross-origin per
-    // HTML-AAM, so "name from content" is always empty). The previous
-    // version here only ever computed name-from-content of the referenced
-    // node (via getConservativeSubtreeText), silently missing the title
-    // fallback and reporting no accessible name at all — the identical
-    // pattern was hand-copied into 15 other *-name-present rules; all
-    // fixed the same way.
+    // 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
+    // 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
+    // all, the same pattern every other *-name-present rule guards against.
     if (helpers.getTextFromIdRefs) {
       try {
         const r = helpers.getTextFromIdRefs(raw, ctx, { maxRefs: maxRefs || 8 });

package/src/checks/automatic/dlitem-parent-valid.js

@@ -1,3 +1,5 @@
+/* SPDX-License-Identifier: MPL-2.0 */
+
 'use strict';
 
 /**

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

@@ -1,3 +1,5 @@
+/* SPDX-License-Identifier: MPL-2.0 */
+
 'use strict';
 
 /**
@@ -18,9 +20,8 @@
  *   which element the reference resolves to (typically the first, silently
  *   dropping the others).
  * @implementation-notes
- * - Scoped deliberately to ids referenced by ARIA (matching a widely-used
- *   reference engine's duplicate-id-aria, not the broader/deprecated page-wide duplicate-id
- *   check — see ROADMAP.md's "Skip" list).
+ * - Scoped deliberately to ids referenced by ARIA, not the broader/
+ *   deprecated page-wide duplicate-id check (see ROADMAP.md's "Skip" list).
  * - Document-wide by design: id uniqueness and ARIA id references are a
  *   whole-document property, not scoped to a sub-root.
  */

package/src/checks/automatic/embed-text-alternative-present.js

@@ -1,3 +1,5 @@
+/* SPDX-License-Identifier: MPL-2.0 */
+
 'use strict';
 
 /**

package/src/checks/automatic/form-control-programmatic-label-present.js

@@ -1,3 +1,5 @@
+/* SPDX-License-Identifier: MPL-2.0 */
+
 'use strict';
 
 /**

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

@@ -1,3 +1,5 @@
+/* SPDX-License-Identifier: MPL-2.0 */
+
 'use strict';
 
 /**
@@ -17,16 +19,13 @@
  *   are ambiguous: many screen readers only announce one of them, and it
  *   is not deterministic which.
  * @implementation-notes
- * - Matches a widely-used reference engine's form-field-multiple-labels. Distinct, atomic
- *   decision from form-control-programmatic-label-present (that
- *   rule checks a label exists at all; this one checks there is at most
- *   one).
+ * - Distinct, atomic decision from form-control-programmatic-label-present
+ *   (that rule checks a label exists at all; this one checks there is at
+ *   most one).
  * - A label that isn't accessibility-tree-eligible (display:none,
  *   aria-hidden, etc.) is excluded before counting: it can't contribute to
  *   the control's accessible name, so it can't create the ambiguity this
- *   rule exists to catch. Matches the reference engine's own
- *   multiple-label check, which filters hidden labels the same way before
- *   deciding whether there's more than one.
+ *   rule exists to catch.
  */
 
 const id = 'form-control-single-label';

package/src/checks/automatic/html-xml-lang-mismatch.js

@@ -1,3 +1,5 @@
+/* SPDX-License-Identifier: MPL-2.0 */
+
 'use strict';
 
 /**