@surea11y/core 1.6.0 → 1.8.0

package/src/checks/manual/password-paste-enabled-manual.js

@@ -0,0 +1,255 @@
+/* SPDX-License-Identifier: MPL-2.0 */
+
+'use strict';
+
+/**
+ * @check password-paste-enabled
+ * @atomic true
+ * @summary An authentication field must not block pasting into it
+ * @standard WCAG 2.2
+ * @sc 3.3.8
+ * @applicability
+ *   Applies to any control whose autocomplete token is current-password,
+ *   new-password or one-time-code, and to <input type="password"> unless its
+ *   autocomplete names another purpose. A disabled or readonly field takes no
+ *   input to block, and one outside the accessibility tree is not being asked
+ *   for, so neither is in scope.
+ * @expectation
+ *   A reviewer confirms the field can still be pasted into. Remembering a
+ *   password is a cognitive function test, and 3.3.8 asks for a mechanism
+ *   that helps the user through one; a password manager, or the clipboard
+ *   for a one-time code, is that mechanism.
+ * @implementation-notes
+ * - Advisory and capped at cantTell. Whether a handler really stops the user
+ *   depends on script the markup does not carry, so no reading of it is safe
+ *   enough to fail on: a split one-time-code field cancels the default paste
+ *   and then spreads the digits across its boxes. The two cases are reported
+ *   apart -- a handler that only cancels, and one that goes on to do more --
+ *   so a reviewer knows which to look at first. `return true` allows the
+ *   paste and reports nothing.
+ * - type="password" masks rather than authenticates, and a card security code
+ *   is masked the same way, so an autocomplete naming another purpose puts the
+ *   field out of scope. A masked field with no autocomplete cannot be told
+ *   apart, which is the one case left.
+ * - `autocomplete="off"` is not reported. Browsers override it for password
+ *   fields so password managers keep working, and the mechanism survives.
+ * - A handler attached with addEventListener leaves nothing to read, the
+ *   limit every static scan shares.
+ * - 3.3.8 also excuses the test where the process offers another
+ *   authentication method. A sibling button proves nothing about whether it
+ *   works or replaces this step, so it is not inferred; the facet is recorded
+ *   as partial for that reason.
+ */
+
+const id = 'password-paste-enabled';
+
+const meta = {
+  title: 'Authentication fields must not block pasting',
+  description:
+    'Checks that a password or one-time-code field carries no inline paste handler that cancels the paste, which would remove the password manager or clipboard that WCAG 3.3.8 relies on as the assisting mechanism.',
+  i18n: {
+    titleKey: 'passwordPasteEnabled_title',
+    descriptionKey: 'passwordPasteEnabled_description'
+  },
+  helpUrl: null,
+  tags: ['wcag22aa', 'wcag338', 'forms', 'authentication', 'atomic', 'manual', 'acc'],
+  wcagSc: ['3.3.8'],
+  normativeMappings: [
+    {
+      standard: 'WCAG',
+      version: '2.2',
+      requirement: '3.3.8',
+      title: 'Accessible Authentication (Minimum)',
+      conformanceLevel: 'AA'
+    }
+  ],
+  defaultSeverity: 'serious',
+  category: 'understandable',
+  type: 'manual',
+  defaultConfidence: 'medium',
+  coverage: { facetsBySc: { '3.3.8': ['authentication-paste-not-blocked'] } }
+};
+
+function runInPage(ctx) {
+  const { helpers, rule } = ctx;
+
+  // Declared inside runInPage; see scripts/build-core.js header
+  // ("runInPage MUST be self-contained").
+  const AUTH_AUTOCOMPLETE_TOKENS = ['current-password', 'new-password', 'one-time-code'];
+
+  function normalizeWs(s) {
+    return String(s || '')
+      .replace(/\s+/g, ' ')
+      .trim();
+  }
+
+  function autocompleteTokens(el) {
+    return normalizeWs(el.getAttribute && el.getAttribute('autocomplete'))
+      .toLowerCase()
+      .split(' ')
+      .filter(Boolean);
+  }
+
+  // A field an authentication step reads: a password input, or any control
+  // whose autocomplete token names an authentication secret. The autocomplete
+  // route matters for one-time codes, which are ordinary text inputs.
+  //
+  // type="password" is a masking control, not only an authentication one: a
+  // card security code is routinely masked the same way. An explicit
+  // autocomplete purpose that is not an authentication one says so, and takes
+  // the field back out of scope.
+  function isAuthField(el) {
+    const tag = el.tagName ? el.tagName.toLowerCase() : '';
+    if (tag !== 'input' && tag !== 'textarea') return false;
+
+    const tokens = autocompleteTokens(el);
+    if (AUTH_AUTOCOMPLETE_TOKENS.some((t) => tokens.includes(t))) return true;
+
+    const type = normalizeWs(el.getAttribute && el.getAttribute('type')).toLowerCase();
+    if (tag !== 'input' || type !== 'password') return false;
+
+    const declaresOtherPurpose = tokens.some(
+      (t) => t !== 'on' && t !== 'off' && !AUTH_AUTOCOMPLETE_TOKENS.includes(t)
+    );
+    return !declaresOtherPurpose;
+  }
+
+  // A field that takes no input at all cannot be pasted into either, so a
+  // paste handler on it blocks nothing.
+  function acceptsInput(el) {
+    if (el.hasAttribute && (el.hasAttribute('disabled') || el.hasAttribute('readonly'))) {
+      return false;
+    }
+    return true;
+  }
+
+  // Classifies an inline handler as 'cancelOnly', 'opaque' or 'none'.
+  //
+  // Cancelling is not the same as blocking. Replacing the default paste is
+  // how a split one-time-code field distributes the digits across its boxes,
+  // and how a password field strips stray whitespace from what was pasted --
+  // both call preventDefault and then insert the text themselves, which
+  // helps the user rather than stopping them. So a handler counts as
+  // blocking only when cancelling is the whole of what it does. Anything
+  // further -- a call, an assignment, a condition -- may well be putting the
+  // text back, and the markup does not say, so it reports cantTell.
+  function classifyHandler(source) {
+    const src = String(source || '').trim();
+    if (!src) return 'none';
+
+    const CANCEL = [
+      /\breturn\s+false\b/gi,
+      /\breturn\s*!1\b/gi,
+      /\bpreventDefault\s*\(\s*\)/gi,
+      /\breturnValue\s*=\s*(?:false|!1)\b/gi
+    ];
+    // Says "yes, paste" outright, so it blocks nothing.
+    const ALLOW = [/\breturn\s+true\b/gi, /\breturn\s*!0\b/gi];
+    // Neither cancels nor re-inserts.
+    const NEUTRAL = [/\bstop(?:Immediate)?Propagation\s*\(\s*\)/gi, /\breturn\b/gi];
+    // What is left of an object reference once its method call is removed.
+    const REFS = /\b(?:window|document|this|event|evt|ev|e|arguments\[0\])\b/gi;
+    const ONLY_PUNCTUATION = /^[\s;.,()[\]{}]*$/;
+
+    let rest = src;
+    let sawCancel = false;
+    for (const re of CANCEL) {
+      const next = rest.replace(re, ' ');
+      if (next !== rest) sawCancel = true;
+      rest = next;
+    }
+
+    if (!sawCancel) {
+      for (const re of ALLOW) rest = rest.replace(re, ' ');
+      for (const re of NEUTRAL) rest = rest.replace(re, ' ');
+      rest = rest.replace(REFS, ' ');
+      return ONLY_PUNCTUATION.test(rest) ? 'none' : 'opaque';
+    }
+
+    for (const re of NEUTRAL) rest = rest.replace(re, ' ');
+    rest = rest.replace(REFS, ' ');
+    // Anything left beyond punctuation is the handler doing more than cancel.
+    return ONLY_PUNCTUATION.test(rest) ? 'cancelOnly' : 'opaque';
+  }
+
+  const nodes = helpers.queryAllSmart
+    ? helpers.queryAllSmart('input, textarea')
+    : helpers.queryAll('input, textarea');
+
+  const cancelling = [];
+  const undetermined = [];
+
+  for (const el of nodes) {
+    if (!el || !el.getAttribute) continue;
+    if (!isAuthField(el)) continue;
+
+    if (!acceptsInput(el)) continue;
+
+    const eligResult = helpers.isAccTreeEligible ? helpers.isAccTreeEligible(el, ctx) : true;
+    const eligible =
+      typeof eligResult === 'boolean' ? eligResult : !!(eligResult && eligResult.eligible);
+    if (!eligible) continue;
+
+    const handler = el.getAttribute('onpaste');
+    if (handler === null) continue;
+
+    const verdict = classifyHandler(handler);
+    if (verdict === 'none') continue;
+
+    const eligInfo = helpers.getEligibilityInfo
+      ? helpers.getEligibilityInfo(el, ctx, { targetSet: 'acc' })
+      : { targetSet: 'acc', accEligible: null, reasons: [] };
+
+    if (verdict === 'cancelOnly') {
+      cancelling.push(
+        helpers.reportOccurrence(el, {
+          summary:
+            'This authentication field has a paste handler whose only effect is to cancel the paste.',
+          hint: 'Confirm by hand whether pasting still works. If it is blocked, remove the handler so a password manager, or the clipboard for a one-time code, can fill the field.',
+          i18n: {
+            summaryKey: 'passwordPasteEnabled_summary_fail',
+            hintKey: 'passwordPasteEnabled_hint_fail',
+            params: {}
+          },
+          data: {
+            visibilityFilter: eligInfo,
+            details: { reasonCode: 'PASTE_CANCELLED', handler: normalizeWs(handler) }
+          }
+        })
+      );
+      continue;
+    }
+
+    // An inline handler that delegates: whether it cancels lives in code the
+    // markup does not carry.
+    undetermined.push(
+      helpers.reportOccurrence(el, {
+        summary:
+          'This authentication field has a paste handler, and whether it cancels pasting could not be determined.',
+        hint: 'Check by hand that pasting into the field still works, so a password manager or the clipboard can fill it.',
+        i18n: {
+          summaryKey: 'passwordPasteEnabled_summary_cantTell',
+          hintKey: 'passwordPasteEnabled_hint_cantTell',
+          params: {}
+        },
+        data: {
+          visibilityFilter: eligInfo,
+          details: { reasonCode: 'PASTE_HANDLER_OPAQUE', handler: normalizeWs(handler) }
+        }
+      })
+    );
+  }
+
+  const occurrences = cancelling.concat(undetermined);
+  if (!occurrences.length) {
+    return { ruleId: rule.ruleId, outcome: 'notApplicable', severity: 'minor', occurrences: [] };
+  }
+  return {
+    ruleId: rule.ruleId,
+    outcome: 'cantTell',
+    severity: rule.defaultSeverity || 'serious',
+    occurrences
+  };
+}
+
+module.exports = { id, meta, runInPage };

package/src/checks/manual/skip-link-manual.js

@@ -8,15 +8,19 @@
  * @summary A "skip" link must resolve to a real, usable target
  * @standard Best Practices (no formal WCAG Success Criterion)
  * @applicability
- *   Applies to <a href="#fragment"> elements whose accessible name
- *   matches a common "skip to ..." / "jump to ..." authoring convention
- *   (case-insensitive "skip" or "jump to" in the name), the recognizable
- *   pattern for a skip-navigation link, not every same-page anchor link
- *   on the page. "jump to" is included alongside "skip" since real skip
- *   links use both conventions (e.g. a "Jump to section" link, which a
- *   purely positional match would catch but a "skip"-only text pattern
- *   would miss). Text-pattern matching itself stays intentional (see
- *   implementation-notes); this only widens the known-convention list.
+ *   Applies to <a href="#fragment"> elements that are skip links by one of
+ *   two signs:
+ *   - the accessible name follows a common skip-link wording in one of the
+ *     shipped locales: "skip" or "jump to" (English); "aller au contenu",
+ *     "passer au contenu", "accéder au contenu", "accès direct", "évitement"
+ *     (French); "springen", "überspringen", "direkt zum", "zum Inhalt"
+ *     (German); "saltar", "ir al contenido" (Spanish); "スキップ", "本文へ"
+ *     (Japanese). "jump to" sits beside "skip" because real skip links use
+ *     both conventions (e.g. a "Jump to section" link);
+ *   - or it is the first link in the document, and it comes before the
+ *     `main` element (or `[role="main"]`): the usual place of a skip link
+ *     whatever its wording.
+ *   Other same-page anchor links are not skip links and are left alone.
  * @expectation
  *   The link's fragment resolves to a real element in the document
  *   (via a matching id, or a legacy <a name="...">), and that target is
@@ -28,10 +32,12 @@
  * - Not WCAG-normative, authored as an advisory, cantTell-capped
  *   `type: 'manual'` rule; see landmark-banner-is-top-level's
  *   header comment for the shared rationale/precedent.
- * - Keyed on the "skip" text-pattern convention rather than positional
- *   heuristics (first link in tab order, etc.), matching the same
- *   deliberate-leniency reasoning documented in
- *   bypass-blocks-present's implementation notes.
+ * - Keyed mainly on the wording, matching the same deliberate-leniency
+ *   reasoning documented in bypass-blocks-present's implementation notes.
+ *   The one positional sign is narrow on purpose: only the page's very
+ *   first link, and only when a main landmark follows it, so an ordinary
+ *   in-page link (a "Menu" toggle after other links, a table of contents)
+ *   is not taken for a skip link.
  */
 
 const id = 'skip-link';
@@ -109,10 +115,32 @@ function runInPage(ctx) {
 
   const geometrySupported = hasReliableGeometrySupport();
 
+  // Skip-link wording in the shipped locales, one list for every rule that
+  // looks for a skip link (helpers.hasSkipLinkWording, docs/RULE_HELPERS.md).
+  const hasSkipWording = (name) => helpers.hasSkipLinkWording(name);
+
   const nodes = helpers.queryAllSmart
     ? helpers.queryAllSmart('a[href]')
     : helpers.queryAll('a[href]');
 
+  // The page's first link, when it comes before the main landmark, is where a
+  // skip link sits whatever its wording.
+  let positionalSkipLink = null;
+  try {
+    const main = document.querySelector('main, [role="main"]');
+    const first = nodes.length ? nodes[0] : null;
+    if (
+      main &&
+      first &&
+      typeof first.compareDocumentPosition === 'function' &&
+      first.compareDocumentPosition(main) & 4 // Node.DOCUMENT_POSITION_FOLLOWING
+    ) {
+      positionalSkipLink = first;
+    }
+  } catch {
+    positionalSkipLink = null;
+  }
+
   const occurrences = [];
   let applicableCount = 0;
 
@@ -123,7 +151,7 @@ function runInPage(ctx) {
     if (href.length < 2 || href.charAt(0) !== '#') continue;
 
     const name = getAccessibleNameText(el);
-    if (!/skip/i.test(name) && !/jump\s*to/i.test(name)) continue;
+    if (el !== positionalSkipLink && !hasSkipWording(name)) continue;
 
     applicableCount += 1;
 

package/src/checks/manual/table-fake-caption-manual.js

@@ -11,7 +11,12 @@
  * @applicability
  *   `<table>` elements with no `<caption>` child, at least two rows, and
  *   a first row containing exactly one non-empty-text cell while at
- *   least one other row has more than one cell.
+ *   least one other row has more than one cell. Left out: a table whose
+ *   role (first token) is anything but table, grid or treegrid, such as a
+ *   layout table with role="presentation", which needs no caption; and a
+ *   table already named by a non-empty aria-label, an aria-labelledby that
+ *   resolves to text, or a non-empty title, which WCAG accepts as the
+ *   table's title.
  * @expectation
  *   A single lone cell in the first row, sitting above rows that clearly
  *   have multiple columns, strongly suggests the author is using it as a
@@ -79,6 +84,31 @@ function runInPage(ctx) {
     }
   }
 
+  const getAriaNameInfo =
+    helpers && typeof helpers.getAriaNameInfo === 'function' ? helpers.getAriaNameInfo : null;
+
+  const TABLE_ROLES = ['table', 'grid', 'treegrid'];
+
+  function hasOtherRole(table) {
+    const role = trim(table.getAttribute('role')).toLowerCase().split(/\s+/)[0];
+    return !!role && !TABLE_ROLES.includes(role);
+  }
+
+  // A name from aria-labelledby, aria-label or title already gives the table
+  // a title that assistive technology announces.
+  function isNamed(table) {
+    if (trim(table.getAttribute('title'))) return true;
+    if (getAriaNameInfo) {
+      try {
+        const aria = getAriaNameInfo(table, ctx);
+        return !!(aria && aria.present && trim(aria.value));
+      } catch {
+        return false;
+      }
+    }
+    return !!trim(table.getAttribute('aria-label'));
+  }
+
   const nodes = helpers.queryAllSmart ? helpers.queryAllSmart('table') : helpers.queryAll('table');
 
   const occurrences = [];
@@ -89,6 +119,7 @@ function runInPage(ctx) {
 
     const hasCaption = !!(table.querySelector && table.querySelector('caption'));
     if (hasCaption) continue;
+    if (hasOtherRole(table) || isNamed(table)) continue;
 
     // An aria-hidden row (or cell) isn't part of the AT-perceived table
     // structure at all -- it must not be treated as the table's "first

package/src/checks/manual/video-caption-manual.js

@@ -19,14 +19,15 @@
  *   fail), matching the precedent set by
  *   `media-alternative-transcript-evidence` for the same class
  *   of "normatively mapped but not statically verifiable" gap. A <video>
- *   with a `<track kind="captions">` (or `kind="subtitles"`, commonly
- *   used interchangeably in the wild even though captions and subtitles
- *   serve technically distinct purposes) whose `src` is non-empty is not
- *   flagged; everything else is flagged for human review.
+ *   with a `<track kind="captions">` whose `src` is non-empty is not
+ *   flagged; everything else is flagged for human review. A video whose
+ *   only text tracks are subtitles (`kind="subtitles"`, or no `kind`,
+ *   which HTML treats as subtitles) gets its own question: subtitles may
+ *   be a translation of the dialogue only, without the speaker and sound
+ *   information captions carry.
  * @implementation-notes
  * - Does not attempt to verify the referenced track file's content,
- *   only that a captions/subtitles track is declared with a non-empty
- *   `src`.
+ *   only that a captions track is declared with a non-empty `src`.
  */
 
 const id = 'video-caption';
@@ -34,7 +35,7 @@ const id = 'video-caption';
 const meta = {
   title: 'Prerecorded video should provide a captions track',
   description:
-    'Flags <video> elements with no <track kind="captions"|"subtitles"> child, for manual review of whether the video has an audio track that needs captions.',
+    'Flags <video> elements with no <track kind="captions"> child, for manual review of whether the video has an audio track that needs captions; a subtitles track alone may be a translation only.',
   i18n: {
     titleKey: 'videoCaption_title',
     descriptionKey: 'videoCaption_description'
@@ -72,14 +73,20 @@ function runInPage(ctx) {
     applicableCount += 1;
 
     let hasCaptionsTrack = false;
+    let hasSubtitlesTrack = false;
     const tracks = el.querySelectorAll('track');
     for (const t of tracks) {
-      const kind = (t.getAttribute('kind') || '').trim().toLowerCase();
+      // A missing kind means subtitles (HTML's missing-value default).
+      const kind = t.hasAttribute('kind')
+        ? (t.getAttribute('kind') || '').trim().toLowerCase()
+        : 'subtitles';
       const src = (t.getAttribute('src') || '').trim();
-      if ((kind === 'captions' || kind === 'subtitles') && src) {
+      if (!src) continue;
+      if (kind === 'captions') {
         hasCaptionsTrack = true;
         break;
       }
+      if (kind === 'subtitles') hasSubtitlesTrack = true;
     }
 
     if (hasCaptionsTrack) continue;
@@ -87,20 +94,36 @@ function runInPage(ctx) {
     const stableSelector = helpers.buildSelector ? helpers.buildSelector(el) : 'html';
     const html = helpers.getOuterHtmlSnippet ? helpers.getOuterHtmlSnippet(el) : el.outerHTML || '';
 
-    const baseOccurrence = {
-      selector: stableSelector,
-      html,
-      summary: 'This video has no captions (or subtitles) track.',
-      hint: 'If this video has an audio track that conveys information, add a <track kind="captions" src="..."> with the captioned content.',
-      i18n: {
-        summaryKey: 'videoCaption_summary_cantTell',
-        hintKey: 'videoCaption_hint_cantTell',
-        params: {}
-      },
-      data: {
-        details: { reasonCode: 'CAPTIONS_TRACK_NOT_DETECTED' }
-      }
-    };
+    const baseOccurrence = hasSubtitlesTrack
+      ? {
+          selector: stableSelector,
+          html,
+          summary:
+            'This video has only subtitles tracks, which may translate the dialogue without the speaker and sound information captions carry.',
+          hint: 'If this video has an audio track that conveys information, check that a subtitles track is in fact captions, and mark it <track kind="captions">; otherwise add a captions track.',
+          i18n: {
+            summaryKey: 'videoCaption_summary_cantTell_subtitlesOnly',
+            hintKey: 'videoCaption_hint_cantTell_subtitlesOnly',
+            params: {}
+          },
+          data: {
+            details: { reasonCode: 'SUBTITLES_TRACK_ONLY' }
+          }
+        }
+      : {
+          selector: stableSelector,
+          html,
+          summary: 'This video has no captions track.',
+          hint: 'If this video has an audio track that conveys information, add a <track kind="captions" src="..."> with the captioned content.',
+          i18n: {
+            summaryKey: 'videoCaption_summary_cantTell',
+            hintKey: 'videoCaption_hint_cantTell',
+            params: {}
+          },
+          data: {
+            details: { reasonCode: 'CAPTIONS_TRACK_NOT_DETECTED' }
+          }
+        };
 
     if (helpers && typeof helpers.reportOccurrence === 'function') {
       occurrences.push(helpers.reportOccurrence(el, baseOccurrence));
@@ -123,7 +146,7 @@ function runInPage(ctx) {
   }
 
   // Manual rules may only emit cantTell/notApplicable (never pass/fail):
-  // every <video> already has a captions/subtitles track.
+  // every <video> already has a captions track.
   return { ruleId: rule.ruleId, outcome: 'notApplicable', severity: 'minor', occurrences: [] };
 }
 

package/src/checks/manual-review.js

@@ -63,10 +63,6 @@ const meta = {
       url: 'https://www.w3.org/TR/WCAG22/#focus-visible'
     },
 
-    { standard: 'EN 301 549', version: 'V3.2.1', requirement: '9.2.1.1', title: 'Keyboard' },
-    { standard: 'EN 301 549', version: 'V3.2.1', requirement: '9.2.4.3', title: 'Focus Order' },
-    { standard: 'EN 301 549', version: 'V3.2.1', requirement: '9.2.4.7', title: 'Focus Visible' },
-
     {
       standard: 'WCAG',
       version: '2.2',