@surea11y/core 1.5.0 → 1.6.0

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

@@ -2,6 +2,24 @@
 
 'use strict';
 
+/**
+ * @check menuitem-name-present
+ * @atomic true
+ * @summary Menu items must have an accessible name
+ * @standard WCAG 2.2
+ * @sc 4.1.2
+ * @applicability
+ *   Applies to elements carrying role="menuitem", role="menuitemcheckbox" or
+ *   role="menuitemradio" (the attribute must name one of those roles alone,
+ *   not a fallback list) that are included in the accessibility tree.
+ * @expectation
+ *   The element has a non-empty accessible name from aria-label, from an
+ *   aria-labelledby that resolves to non-empty text, from title, or, all
+ *   three roles being name-from-content, from its own subtree text, where a
+ *   descendant's own name (an <img alt>, aria-label or title) counts as that
+ *   descendant's contribution rather than only its text nodes.
+ */
+
 const id = 'menuitem-name-present';
 
 const meta = {
@@ -52,7 +70,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
@@ -71,7 +89,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).

package/src/checks/automatic/meta-refresh-no-exceptions.js

@@ -9,20 +9,24 @@
  * @standard WCAG 2.2
  * @sc 2.2.4, 3.2.5
  * @applicability
- *   Applies to any <meta http-equiv="refresh"> element with a non-empty
- *   content attribute.
+ *   Applies to the first <meta http-equiv="refresh"> element, in document
+ *   order, with a valid content attribute, per HTML's shared declarative
+ *   refresh steps, a document only ever acts on its first valid meta
+ *   refresh, so a later one (valid or not) is inert and out of scope.
  * @expectation
- *   No meta refresh is present, regardless of delay. This is the
- *   stricter AAA-level counterpart of meta-refresh-timing-absent
- *   (the A-level rule, which only forbids a positive delay and allows
- *   delay="0" as an immediate redirect). At AAA, WCAG 2.2.4
- *   (Interruptions) and 3.2.5 (Change on Request) require that automatic
- *   context changes — including an immediate meta-refresh redirect —
- *   happen only at the user's request, with no exception for a zero
- *   delay.
+ *   Running the shared declarative refresh steps against that element's
+ *   content value results in a delay of exactly 0. An immediate (delay=0)
+ *   redirect still passes at AAA, same as the A-level rule. There is
+ *   nothing for a user to be interrupted mid-read by when nothing is
+ *   displayed first. Any positive delay fails, with none of the A-level
+ *   rule's >20-hour exemption: at AAA, WCAG 2.2.4 (Interruptions) and
+ *   3.2.5 (Change on Request) require that a *timed* automatic context
+ *   change happen only at the user's request, regardless of how long the
+ *   timer is.
  * @implementation-notes
- * - Distinct, atomic decision from meta-refresh-timing-absent:
- *   that rule's delay="0" pass case is this rule's fail case.
+ * - Distinct, atomic decision from meta-refresh-timing-absent: that
+ *   rule's >20-hour exemption for a positive delay is this rule's fail
+ *   case (no exemption at AAA), but delay=0 passes in both rules.
  * - A <meta> nested inside <noscript> is excluded: it only ever takes
  *   effect when scripting is disabled, which is never the case for any
  *   context capable of running accessibility tooling in the first place
@@ -35,7 +39,7 @@ const id = 'meta-refresh-no-exceptions';
 const meta = {
   title: 'Page must not use a meta refresh at all (AAA)',
   description:
-    'Checks that <meta http-equiv="refresh"> is not present at all, regardless of delay — the stricter AAA-level counterpart of the A-level positive-delay-only check.',
+    'Checks that <meta http-equiv="refresh"> is not present at all, regardless of delay. This is the stricter AAA-level counterpart of the A-level positive-delay-only check.',
   i18n: {
     titleKey: 'metaRefreshNoExceptions_title',
     descriptionKey: 'metaRefreshNoExceptions_description'
@@ -122,10 +126,16 @@ function runInPage(ctx) {
     if (el.closest && el.closest('noscript')) continue; // never applies with scripting enabled
     const raw = String(el.getAttribute('content') || '').trim();
     if (!raw) continue;
-    if (parseRefreshDelay(raw) === null) continue;
+    const delay = parseRefreshDelay(raw);
+    if (delay === null) continue;
 
+    // Only the first valid meta refresh in document order is ever acted
+    // on by a browser -- any later one is inert and stops being evaluated
+    // entirely once a winner has been found.
     applicableCount += 1;
 
+    if (delay === 0) break; // an immediate redirect is not a timed interruption
+
     occurrences.push(
       helpers.reportOccurrence(el, {
         summary:
@@ -141,6 +151,7 @@ function runInPage(ctx) {
         }
       })
     );
+    break;
   }
 
   if (applicableCount === 0) {

package/src/checks/automatic/meta-refresh-timing-absent.js

@@ -9,8 +9,11 @@
  * @standard WCAG 2.2
  * @sc 2.2.1
  * @applicability
- *   Applies to <meta http-equiv="refresh"> elements that carry a non-empty
- *   content attribute with a parseable leading delay value.
+ *   Applies to the first <meta http-equiv="refresh"> element, in document
+ *   order, whose content attribute has a parseable leading delay value.
+ *   Per HTML's shared declarative refresh steps, a document only ever
+ *   acts on its first valid meta refresh; any later one (valid or not)
+ *   is inert markup a browser never processes, so it is not evaluated.
  * @expectation
  *   The delay is 0 (an immediate redirect, which users cannot be caught by
  *   mid-read), or exceeds 20 hours. Any other positive delay refreshes or
@@ -19,13 +22,13 @@
  *   be possible.
  * @implementation-notes
  * - An unparseable content value (no leading numeric delay) is not
- *   flagged — this rule only reports a clearly-detected timed refresh,
+ *   flagged, this rule only reports a clearly-detected timed refresh,
  *   matching this engine's no-false-positives policy.
  * - WCAG 2.2.1 Exception 3 exempts time limits longer than 20 hours (the
  *   rationale being that a delay this long gives users enough real-world
  *   time to act, so "adjustable" ceases to be a meaningful requirement).
  *   A delay over 72000 seconds is therefore not flagged.
- * - A <meta> nested inside <noscript> is excluded — see
+ * - A <meta> nested inside <noscript> is excluded, see
  *   meta-refresh-no-exceptions's header comment for why.
  */
 
@@ -109,17 +112,20 @@ function runInPage(ctx) {
 
   for (const el of nodes) {
     if (!el || !el.getAttribute) continue;
-    if (el.closest && el.closest('noscript')) continue; // never applies with scripting enabled — see meta-refresh-no-exceptions.js's header comment
+    if (el.closest && el.closest('noscript')) continue; // never applies with scripting enabled, see meta-refresh-no-exceptions.js's header comment
     const raw = String(el.getAttribute('content') || '').trim();
     if (!raw) continue;
 
     const delay = parseRefreshDelay(raw);
     if (delay === null) continue;
 
+    // Only the first valid meta refresh in document order is ever acted
+    // on by a browser -- any later one is inert and stops being evaluated
+    // entirely once a winner has been found.
     applicableCount += 1;
 
-    if (!(delay > 0)) continue;
-    if (delay > EXEMPT_DELAY_SECONDS) continue; // WCAG 2.2.1 Exception 3 (>20 hours)
+    if (!(delay > 0)) break;
+    if (delay > EXEMPT_DELAY_SECONDS) break; // WCAG 2.2.1 Exception 3 (>20 hours)
 
     occurrences.push(
       helpers.reportOccurrence(el, {
@@ -135,6 +141,7 @@ function runInPage(ctx) {
         }
       })
     );
+    break;
   }
 
   if (applicableCount === 0) {

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

@@ -2,6 +2,25 @@
 
 'use strict';
 
+/**
+ * @check meter-name-present
+ * @atomic true
+ * @summary Elements with role="meter" must have an accessible name
+ * @standard WCAG 2.2
+ * @sc 1.1.1
+ * @applicability
+ *   Applies to elements carrying role="meter" (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="meter" is name-from-author-only, so subtree text is never
+ *   accepted: text sitting inside a custom meter widget is not reliably
+ *   exposed as its name.
+ */
+
 const id = 'meter-name-present';
 
 const meta = {
@@ -54,7 +73,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).
@@ -106,8 +125,8 @@ function runInPage(ctx) {
     if (title) return { ok: true, method: 'title' };
 
     // role="meter" is name-from-author-only per WAI-ARIA: aria-label,
-    // aria-labelledby, or title — no content-based naming method at all.
-    // It must NOT fall back to subtree content — visible text near/inside a
+    // aria-labelledby, or title, no content-based naming method at all.
+    // It must NOT fall back to subtree content, visible text near/inside a
     // custom meter widget is not reliably exposed as its accessible name.
     return { ok: false, method: 'none' };
   }
@@ -137,7 +156,7 @@ function runInPage(ctx) {
     occurrences.push(
       helpers.reportOccurrence(el, {
         summary: 'This meter has no accessible name.',
-        hint: "Provide aria-label, aria-labelledby, or a title attribute — visible text content is not exposed as this meter's accessible name.",
+        hint: "Provide aria-label, aria-labelledby, or a title attribute. Visible text content is not exposed as this meter's accessible name.",
         i18n: {
           summaryKey: 'meterNamePresent_summary_fail',
           hintKey: 'meterNamePresent_hint_fail',

package/src/checks/automatic/nested-interactive-controls-absent.js

@@ -14,13 +14,13 @@
  *   ARIA widget role: button, link, checkbox, radio, switch, tab, textbox,
  *   combobox, listbox, menuitem, menuitemcheckbox, menuitemradio, option,
  *   slider, spinbutton, searchbox, treeitem). The container is applicable
- *   regardless of whether it is itself focusable — focusability is only
+ *   regardless of whether it is itself focusable, focusability is only
  *   used to decide whether a *descendant* nests an interactive control.
  * @expectation
  *   The element does not contain, as a descendant, another *operable*
  *   interactive control (e.g. a <button> wrapping a <select>, or a link
  *   containing a checkbox). Nested interactive controls are not reliably
- *   announced or operable via assistive technology — activating the outer
+ *   announced or operable via assistive technology, activating the outer
  *   control and the inner one become ambiguous, and some AT only exposes
  *   one of the two.
  * @implementation-notes
@@ -89,7 +89,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 INTERACTIVE_SELECTOR = [
     'a[href]',
@@ -228,8 +228,8 @@ function runInPage(ctx) {
         // A composite-owned child (option in a listbox/combobox, tab in a
         // tablist, ...) is not a nested interactive control: its container
         // owns it and drives its focus (roving tabindex or
-        // aria-activedescendant). Treat it as an attribution boundary — do not
-        // count it, and do not descend past it. Any control genuinely nested
+        // aria-activedescendant). Treat it as an attribution boundary, do not
+        // count it, and do not descend past it. Any control nested
         // inside it is attributed to the child itself (examined as its own
         // container in the main loop), keeping the report at the nearest
         // interactive ancestor rather than bubbling up to the composite.

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

@@ -2,11 +2,30 @@
 
 'use strict';
 
+/**
+ * @check option-name-present
+ * @atomic true
+ * @summary Elements with role="option" must have an accessible name
+ * @standard WCAG 2.2
+ * @sc 4.1.2
+ * @applicability
+ *   Applies to elements carrying role="option" (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, from title, or,
+ *   role="option" being name-from-content, from its own subtree text, where
+ *   a descendant's own name (an <img alt>, aria-label or title) counts as
+ *   that descendant's contribution rather than only its text nodes.
+ */
+
 const id = 'option-name-present';
 
 const meta = {
-  title: 'Accessible name is present',
-  description: 'Checks that elements expose a non-empty accessible name.',
+  title: 'Options have an accessible name',
+  description: 'Checks that elements with role="option" expose a non-empty accessible name.',
   i18n: {
     titleKey: 'optionNamePresent_title',
     descriptionKey: 'optionNamePresent_description'
@@ -51,7 +70,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
@@ -70,7 +89,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).

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

@@ -2,11 +2,29 @@
 
 'use strict';
 
+/**
+ * @check page-title-present
+ * @atomic true
+ * @summary The document must have a non-empty title
+ * @standard WCAG 2.2
+ * @sc 2.4.2
+ * @applicability
+ *   Applies to a run over a whole document. A run narrowed by
+ *   contextSelector, or by engineOptions.fragment, is notApplicable: whether
+ *   the page has a title is not a property any subtree can answer.
+ * @expectation
+ *   The document has a <title> element, and document.title with whitespace
+ *   collapsed is non-empty. The element is looked for anywhere in the
+ *   document, not only inside <head>: a <title> the parser leaves outside
+ *   <head> is still the document title in every browser. Whether that title
+ *   describes the page is page-title-patterns' question.
+ */
+
 const id = 'page-title-present';
 
 const meta = {
-  title: 'Page title is present and non-empty',
-  description: 'Checks that the document has a non-empty <title> element (WCAG 2.2 SC 2.4.2).',
+  title: 'Page has a non-empty title',
+  description: 'Checks that the page includes a non-empty <title> element.',
   i18n: {
     titleKey: 'pageTitlePresent_title',
     descriptionKey: 'pageTitlePresent_description'
@@ -47,7 +65,7 @@ function runInPage(ctx) {
   // Not restricted to `head > title`: per HTML parsing, a <title> encountered
   // after <head> has closed is not re-parented into <head>, yet the browser
   // (and document.title, used below) still recognizes it as the document's
-  // title — matching that here avoids a false "missing title" report for a
+  // title, matching that here avoids a false "missing title" report for a
   // <title> that legitimately ended up outside <head>.
   const titleEl = document.querySelector('title');
   const titleText = (document.title || '').replace(/\s+/g, ' ').trim();