@surea11y/core 1.7.0 → 1.8.1

package/src/checks/manual/link-name-quality-manual.js

@@ -24,6 +24,11 @@
  *   enclosing list item/table cell/paragraph's own text, or (format
  *   names only) a table's first-row header) naming what it belongs to.
  * @implementation-notes
+ * - Phrase lists exist for en, de, es, fr and ja. English is always
+ *   checked; the list for the element's own language (nearest lang
+ *   attribute, across shadow roots) is added on top. Matching every list
+ *   everywhere would flag words that are generic in one language and a
+ *   real name in another ("Suite", "Plus" on an English page).
  * - EXACT match only, on purpose, against small, well-established
  *   phrase lists, not a substring/contains check. "Read more about our
  *   privacy policy" does not match "read more"; only the bare phrase
@@ -52,7 +57,7 @@ const id = 'link-name-quality';
 const meta = {
   title: 'Link text should be descriptive, not generic',
   description:
-    'Flags links whose full accessible name is a known non-descriptive phrase (e.g. "click here", "read more", "more") or a bare file-format name (e.g. "HTML", "PDF") with no adjacent context naming what it leads to, for manual review of whether the purpose is clear.',
+    'Flags links whose full accessible name is a known non-descriptive phrase (e.g. "click here", "read more", "more") or a bare file-format name (e.g. "HTML", "PDF") with no adjacent context naming what it leads to, for manual review of whether the purpose is clear. English phrases are always recognized, and German, Spanish, French or Japanese ones when the link is in that language.',
   i18n: {
     titleKey: 'linkNameQuality_title',
     descriptionKey: 'linkNameQuality_description'
@@ -79,7 +84,7 @@ const meta = {
 function runInPage(ctx) {
   const { helpers, rule } = ctx;
 
-  const GENERIC_LINK_TEXT = new Set([
+  const GENERIC_LINK_TEXT_EN = new Set([
     'click here',
     'here',
     'click',
@@ -101,6 +106,100 @@ function runInPage(ctx) {
     'info'
   ]);
 
+  const GENERIC_LINK_TEXT = {
+    en: GENERIC_LINK_TEXT_EN,
+    de: new Set([
+      'hier klicken',
+      'klicken sie hier',
+      'hier',
+      'klicken',
+      'mehr',
+      'mehr info',
+      'mehr infos',
+      'mehr informationen',
+      'weiterlesen',
+      'mehr lesen',
+      'mehr erfahren',
+      'weiter',
+      'details',
+      'mehr details',
+      'link',
+      'dieser link',
+      'los',
+      'herunterladen',
+      'mehr anzeigen',
+      'info'
+    ]),
+    es: new Set([
+      'haga clic aquí',
+      'haz clic aquí',
+      'clic aquí',
+      'pulse aquí',
+      'pincha aquí',
+      'aquí',
+      'clic',
+      'más',
+      'más info',
+      'más información',
+      'leer más',
+      'saber más',
+      'seguir leyendo',
+      'continuar leyendo',
+      'continuar',
+      'detalles',
+      'más detalles',
+      'enlace',
+      'este enlace',
+      'ir',
+      'descargar',
+      'ver más',
+      'info'
+    ]),
+    fr: new Set([
+      'cliquez ici',
+      'cliquer ici',
+      'ici',
+      'cliquez',
+      'plus',
+      "plus d'infos",
+      "plus d'informations",
+      'en savoir plus',
+      'lire la suite',
+      'la suite',
+      'suite',
+      'continuer',
+      'détails',
+      'plus de détails',
+      'lien',
+      'ce lien',
+      'télécharger',
+      'voir plus',
+      'info'
+    ]),
+    ja: new Set([
+      'こちら',
+      'ここ',
+      'こちらをクリック',
+      'ここをクリック',
+      'クリック',
+      '詳しく',
+      '詳しくは',
+      '詳しくはこちら',
+      '詳細',
+      '詳細はこちら',
+      '詳細を見る',
+      'もっと見る',
+      'もっと読む',
+      'さらに詳しく',
+      '続きを読む',
+      '続き',
+      'リンク',
+      'このリンク',
+      'ダウンロード',
+      '情報'
+    ])
+  };
+
   const FORMAT_NAME_LINK_TEXT = new Set([
     'html',
     'pdf',
@@ -124,15 +223,42 @@ function runInPage(ctx) {
 
   const CONTEXT_BLOCK_TAGS = new Set(['td', 'th', 'p', 'dd', 'blockquote', 'figcaption', 'dt']);
 
+  // NFKC folds full-width letters and punctuation (！, ＞) into their ASCII
+  // forms, and the curly apostrophe is folded so "plus d’infos" matches.
+  // Trailing arrows ("Read more »", 「詳しくはこちら→」) are decoration, not
+  // part of the phrase.
   function normalize(s) {
     return (s == null ? '' : String(s))
+      .normalize('NFKC')
+      .replace(/[\u2018\u2019]/g, "'")
       .replace(/\s+/g, ' ')
       .trim()
       .toLowerCase()
-      .replace(/[.,;:!?]+$/g, '')
+      .replace(/[\s.,;:!?。、>»›→]+$/g, '')
       .trim();
   }
 
+  // Primary language subtag of the nearest lang attribute, crossing shadow
+  // roots; '' when none is declared. Phrase lists are matched in English
+  // plus this language, so a word that is generic in one language ("plus"
+  // in French) is not flagged when it is a real name in another.
+  function primaryLangOf(node) {
+    let n = node;
+    while (n) {
+      if (n.nodeType === 1 && n.getAttribute) {
+        const v = n.getAttribute('lang');
+        if (v != null) return v.trim().split('-')[0].toLowerCase();
+      }
+      n = n.parentNode || n.host || null;
+    }
+    return '';
+  }
+
+  function inPhraseList(byLang, normalized, lang) {
+    if (byLang.en.has(normalized)) return true;
+    return !!(lang && lang !== 'en' && byLang[lang] && byLang[lang].has(normalized));
+  }
+
   function ownDirectText(el) {
     let out = '';
     const kids = el.childNodes || [];
@@ -240,7 +366,7 @@ function runInPage(ctx) {
 
     applicableCount += 1;
 
-    const isGeneric = GENERIC_LINK_TEXT.has(normalized);
+    const isGeneric = inPhraseList(GENERIC_LINK_TEXT, normalized, primaryLangOf(el));
     const isFormatName = !isGeneric && FORMAT_NAME_LINK_TEXT.has(normalized);
     if (!isGeneric && !isFormatName) continue;
 

package/src/checks/manual/media-transcript-present-manual.js

@@ -13,6 +13,16 @@
  * @expectation If a strong transcript/text-alternative signal is present (e.g., aria-describedby binding to
  *              a visible transcript block, or a nearby clearly labeled Transcript section/link), no occurrence is reported.
  *              Otherwise, the rule reports cantTell (insufficient evidence) for that media element.
+ * @implementation-notes
+ * - An <audio> without `controls` is hidden by the browser's own stylesheet
+ *   (`display: none`), not by the author, and it still plays. So the rule
+ *   does not use queryAllSmart, whose hidden-content filter would drop it in
+ *   a real browser. It queries <audio>/<video> directly (scope,
+ *   excludeSelectors and open shadow roots honoured) and applies the
+ *   eligibility check to the element itself, except for an <audio> without
+ *   `controls`: there it applies the check to the parent (or shadow host)
+ *   and to the element's own `hidden` and `aria-hidden="true"`, since its
+ *   computed style cannot tell the browser's hiding from the author's.
  */
 
 const id = 'media-alternative-transcript-evidence';
@@ -48,14 +58,24 @@ function runInPage(ctx) {
   const { document, root, helpers, rule } = ctx;
   const safeRoot = root || document;
 
-  // Conservative keyword set (deterministic). Includes common EN/FR terms.
-  // Keep this list strict to avoid false positives.
+  // Conservative keyword set (deterministic), matched in every language at
+  // once: a Japanese page may well link an English transcript. Keep this
+  // list strict to avoid false positives.
   const TRANSCRIPT_TOKENS = [
     'transcript',
     'transcription',
     'texte intégral',
     'compte rendu',
-    'verbatim'
+    'verbatim',
+    'transkript',
+    'transkription',
+    'abschrift',
+    'textfassung',
+    'transcripción',
+    'transcripcion',
+    'トランスクリプト',
+    '文字起こし',
+    '書き起こし'
   ];
 
   // Minimum transcript body length to be considered "substantial" when used as evidence.
@@ -88,7 +108,7 @@ function runInPage(ctx) {
     try {
       if (!el) return '';
       return el.textContent || '';
-    } catch (e) {
+    } catch {
       return '';
     }
   }
@@ -284,12 +304,49 @@ function runInPage(ctx) {
   const occurrences = [];
   let applicableCount = 0;
 
-  const nodes = helpers.queryAllSmart
-    ? helpers.queryAllSmart('audio,video')
-    : helpers.queryAll('audio,video');
+  // Every match in scope, hidden or not (see @implementation-notes).
+  function queryAllUnfiltered(sel) {
+    const engineOptions = ctx.engineOptions || {};
+    const deep =
+      engineOptions.includeShadowDom !== false && typeof helpers.queryAllDeep === 'function';
+    const list = Array.from((deep ? helpers.queryAllDeep(sel) : helpers.queryAll(sel)) || []);
+    return typeof helpers.isExcluded === 'function'
+      ? list.filter((el) => !helpers.isExcluded(el))
+      : list;
+  }
+
+  function hiddenByBrowserStylesheet(el) {
+    return (
+      String(el.tagName || '').toLowerCase() === 'audio' &&
+      !(el.hasAttribute && el.hasAttribute('controls'))
+    );
+  }
+
+  // The eligibility that decides whether the media element is in scope.
+  function getMediaEligibility(el) {
+    if (!hiddenByBrowserStylesheet(el)) return getEligibility(el);
+    if (el.hasAttribute('hidden')) {
+      return { eligible: false, reasons: ['hiddenAttr'], targetSet: 'acc', accEligible: false };
+    }
+    if (
+      String(el.getAttribute('aria-hidden') || '')
+        .trim()
+        .toLowerCase() === 'true'
+    ) {
+      return { eligible: false, reasons: ['ariaHidden'], targetSet: 'acc', accEligible: false };
+    }
+    let parent = el.parentElement;
+    if (!parent) {
+      const rootNode = el.getRootNode ? el.getRootNode() : null;
+      parent = rootNode && rootNode.host ? rootNode.host : null;
+    }
+    return parent ? getEligibility(parent) : getEligibility(el);
+  }
+
+  const nodes = queryAllUnfiltered('audio,video');
 
   for (const el of nodes) {
-    const eligInfo = getEligibility(el);
+    const eligInfo = getMediaEligibility(el);
     if (!eligInfo || !eligInfo.eligible) continue;
 
     applicableCount += 1;

package/src/checks/manual/mouse-only-event-handlers-manual.js

@@ -20,9 +20,14 @@
  *   event equivalents), or `onfocus`/`onblur` (the standard substitute
  *   for hover-triggered behavior: focus/blur are the keyboard-
  *   navigable analog to mouseover/mouseout, per WCAG technique G90).
- *   Otherwise the element's mouse-driven behavior (a hover tooltip, a
- *   custom dropdown, a drag interaction) has no way to be triggered by a
- *   keyboard-only user.
+ *   A handler is reachable only if keyboard events can reach it:
+ *   `onfocus`/`onblur` when the element itself can take focus, and a key
+ *   handler when the element or one of its descendants can (key events
+ *   bubble, focus events do not). Otherwise the element's mouse-driven
+ *   behavior (a hover tooltip, a custom dropdown, a drag interaction) has
+ *   no way to be triggered by a keyboard-only user, and it is flagged with
+ *   a reason saying whether the keyboard handlers are missing or cannot
+ *   run.
  * @implementation-notes
  * - Authored as `type: 'manual'` (cantTell-capped, never fail), not
  *   `automatic`: this can only see inline `on*="..."` HTML attributes.
@@ -93,6 +98,35 @@ function runInPage(ctx) {
     return (v == null ? '' : String(v)).trim();
   }
 
+  const FOCUS_ATTRS = ['onfocus', 'onblur'];
+  const FOCUSABLE_CANDIDATES =
+    'a[href], area[href], button, input, select, textarea, summary, iframe, [tabindex], [contenteditable]';
+
+  function canTakeFocus(el) {
+    if (!helpers.getFocusableInfo) return true;
+    try {
+      const info = helpers.getFocusableInfo(el, ctx);
+      return !!(info && info.focusable);
+    } catch {
+      return true;
+    }
+  }
+
+  // Focus and blur fire only on the element that takes focus. Key events are
+  // dispatched to the focused element and bubble, so a key handler also runs
+  // for a focusable descendant.
+  function keyboardCanReach(el, keyboardAttrs) {
+    if (canTakeFocus(el)) return true;
+    if (keyboardAttrs.every((a) => FOCUS_ATTRS.indexOf(a) !== -1)) return false;
+    let descendants;
+    try {
+      descendants = Array.from(el.querySelectorAll(FOCUSABLE_CANDIDATES));
+    } catch {
+      return true;
+    }
+    return descendants.some((d) => canTakeFocus(d));
+  }
+
   const selector = MOUSE_ONLY_ATTRS.map((a) => `[${a}]`).join(', ');
   const nodes = helpers.queryAllSmart
     ? helpers.queryAllSmart(selector)
@@ -114,13 +148,40 @@ function runInPage(ctx) {
 
     applicableCount += 1;
 
-    const hasKeyboardEquiv = KEYBOARD_EQUIV_ATTRS.some((a) => trim(el.getAttribute(a)));
-    if (hasKeyboardEquiv) continue;
+    const presentKeyboardAttrs = KEYBOARD_EQUIV_ATTRS.filter((a) => trim(el.getAttribute(a)));
+    if (presentKeyboardAttrs.length && keyboardCanReach(el, presentKeyboardAttrs)) continue;
+    const unreachable = presentKeyboardAttrs.length > 0;
 
     const eligInfo = helpers.getEligibilityInfo
       ? helpers.getEligibilityInfo(el, ctx, { targetSet: 'acc' })
       : null;
 
+    if (unreachable) {
+      occurrences.push(
+        helpers.reportOccurrence(el, {
+          summary: `This element has ${presentMouseAttrs.join(', ')} and ${presentKeyboardAttrs.join(', ')}, but it cannot take keyboard focus, so the keyboard handlers never run.`,
+          hint: 'Make the element focusable (use a native control, or add tabindex="0"), or move the handlers to a focusable element, so this functionality is also reachable by keyboard.',
+          i18n: {
+            summaryKey: 'mouseOnlyEventHandlers_summary_cantTell_notFocusable',
+            hintKey: 'mouseOnlyEventHandlers_hint_cantTell_notFocusable',
+            params: {
+              attrs: presentMouseAttrs.join(', '),
+              keyboardAttrs: presentKeyboardAttrs.join(', ')
+            }
+          },
+          data: {
+            details: {
+              reasonCode: 'MOUSE_ONLY_HANDLER_KEYBOARD_EQUIVALENT_NOT_FOCUSABLE',
+              mouseAttrs: presentMouseAttrs,
+              keyboardAttrs: presentKeyboardAttrs
+            },
+            visibilityFilter: eligInfo || { targetSet: 'acc', accEligible: null, reasons: [] }
+          }
+        })
+      );
+      continue;
+    }
+
     occurrences.push(
       helpers.reportOccurrence(el, {
         summary: `This element has ${presentMouseAttrs.join(', ')} but no keyboard-reachable equivalent handler.`,

package/src/checks/manual/no-autoplay-audio-manual.js

@@ -5,11 +5,16 @@
 /**
  * @check no-autoplay-audio
  * @atomic true
- * @summary Autoplaying, unmuted <audio>/<video> should provide a pause/stop or volume-control mechanism
+ * @summary Sound that plays automatically should have a pause/stop or volume-control mechanism
  * @standard WCAG 2.2
  * @sc 1.4.2
  * @applicability
  *   Any <audio autoplay> or <video autoplay> element that is not `muted`.
+ *   Also any <bgsound>, and any <embed> or <object> that loads sound or
+ *   video, or a plugin (Flash) that may play it: its `type` is audio/*,
+ *   video/* or a plugin type, or its `src`/`data` ends in a sound or video
+ *   file extension. An <embed> or <object> with `autostart` or `autoplay`
+ *   set to false (attribute or <param>) is left out.
  * @expectation
  *   SC 1.4.2 only applies when audio plays automatically for MORE than 3
  *   seconds; clip duration is not knowable from static markup (jsdom does
@@ -27,13 +32,22 @@
  * - Elements with `muted` present are not flagged: muted playback is not
  *   audible, so the SC's condition ("plays automatically... audio")
  *   does not apply.
+ * - <embed>, <object> and <bgsound> have no `controls` or `muted` to
+ *   read, so each one found is asked about. <bgsound> is obsolete
+ *   and current browsers ignore it, but it still plays in older ones.
+ * - Sound started by a script cannot be detected.
  * - Custom (JS-built) controls that don't use the native `controls`
  *   attribute cannot be detected statically. That's a documented limitation,
  *   same class as `iframe-focusable-content`'s `contentDocument` gap.
  * - Not gated on `isAccTreeEligible`: unlike most rules, a `display:none`
  *   or `aria-hidden` audio/video element still plays audible sound in a
  *   real browser, so visual/AT-tree eligibility is not a relevant filter
- *   here.
+ *   here. For the same reason the rule does not use queryAllSmart, whose
+ *   hidden-content filter would drop such elements: an <audio> without
+ *   `controls` is always one, since browsers hide it with their own
+ *   stylesheet (`display: none`). It queries the DOM directly (and open
+ *   shadow roots, unless includeShadowDom is false), honouring only the
+ *   scan scope and excludeSelectors.
  */
 
 const id = 'no-autoplay-audio';
@@ -41,7 +55,7 @@ const id = 'no-autoplay-audio';
 const meta = {
   title: 'Autoplaying audio should provide a pause/stop or volume-control mechanism',
   description:
-    'Flags <audio>/<video> elements that autoplay unmuted with no native controls attribute, for manual review against the 3-second exemption in WCAG 1.4.2.',
+    'Flags <audio>/<video> elements that autoplay unmuted with no native controls attribute, and <embed>, <object> or <bgsound> elements that may play sound, for manual review against the 3-second exemption in WCAG 1.4.2.',
   i18n: {
     titleKey: 'noAutoplayAudio_title',
     descriptionKey: 'noAutoplayAudio_description'
@@ -68,9 +82,18 @@ const meta = {
 function runInPage(ctx) {
   const { helpers, rule } = ctx;
 
-  const nodes = helpers.queryAllSmart
-    ? helpers.queryAllSmart('audio[autoplay], video[autoplay]')
-    : helpers.queryAll('audio[autoplay], video[autoplay]');
+  // Every match in scope, hidden or not (see @implementation-notes).
+  function queryAllUnfiltered(sel) {
+    const engineOptions = ctx.engineOptions || {};
+    const deep =
+      engineOptions.includeShadowDom !== false && typeof helpers.queryAllDeep === 'function';
+    const list = Array.from((deep ? helpers.queryAllDeep(sel) : helpers.queryAll(sel)) || []);
+    return typeof helpers.isExcluded === 'function'
+      ? list.filter((el) => !helpers.isExcluded(el))
+      : list;
+  }
+
+  const nodes = queryAllUnfiltered('audio[autoplay], video[autoplay]');
 
   const occurrences = [];
   let applicableCount = 0;
@@ -110,6 +133,70 @@ function runInPage(ctx) {
     }
   }
 
+  // <embed>, <object> and <bgsound>: no controls or muted attribute to read.
+  const MEDIA_EXT =
+    /\.(mp3|wav|wave|ogg|oga|opus|m4a|aac|flac|wma|mid|midi|mp4|m4v|webm|ogv|mov|avi|wmv|mpg|mpeg|swf)(?:[?#]|$)/i;
+  const PLUGIN_TYPES = /^(application\/x-shockwave-flash|application\/futuresplash)$/i;
+
+  function attr(el, name) {
+    return String(el.getAttribute(name) || '').trim();
+  }
+
+  function mayPlaySound(el, urlAttr) {
+    const type = attr(el, 'type').toLowerCase().split(';')[0].trim();
+    if (type) return /^(audio|video)\//.test(type) || PLUGIN_TYPES.test(type);
+    return MEDIA_EXT.test(attr(el, urlAttr));
+  }
+
+  function startsDisabled(el) {
+    const isOff = (v) => /^(false|0|no)$/i.test(String(v || '').trim());
+    if (isOff(el.getAttribute('autostart')) || isOff(el.getAttribute('autoplay'))) return true;
+    return Array.from(el.children || []).some((c) => {
+      if ((c.tagName || '').toLowerCase() !== 'param') return false;
+      const name = attr(c, 'name').toLowerCase();
+      return (
+        (name === 'autostart' || name === 'autoplay' || name === 'play') &&
+        isOff(c.getAttribute('value'))
+      );
+    });
+  }
+
+  // The fallback inside an <object> already asked about is the same sound.
+  const askedObjects = [];
+
+  for (const el of queryAllUnfiltered('embed, object, bgsound')) {
+    if (!el || !el.getAttribute) continue;
+    if (askedObjects.some((o) => o !== el && o.contains(el))) continue;
+    const tag = (el.tagName || '').toLowerCase();
+    if (tag === 'embed' && !mayPlaySound(el, 'src')) continue;
+    if (tag === 'object' && !mayPlaySound(el, 'data')) continue;
+    if (tag !== 'bgsound' && startsDisabled(el)) continue;
+
+    applicableCount += 1;
+    if (tag === 'object') askedObjects.push(el);
+
+    const baseOccurrence = {
+      selector: helpers.buildSelector ? helpers.buildSelector(el) : 'html',
+      html: helpers.getOuterHtmlSnippet ? helpers.getOuterHtmlSnippet(el) : el.outerHTML || '',
+      summary: 'This element may play sound as soon as the page loads.',
+      hint: 'Check whether it plays sound on its own. If the sound lasts more than 3 seconds, users need a way to pause or stop it, or to change its volume without changing the system volume.',
+      i18n: {
+        summaryKey: 'noAutoplayAudio_summary_cantTell_embedded',
+        hintKey: 'noAutoplayAudio_hint_cantTell_embedded',
+        params: { element: tag }
+      },
+      data: {
+        details: { reasonCode: 'EMBEDDED_SOUND_SOURCE', mediaTag: tag }
+      }
+    };
+
+    if (helpers && typeof helpers.reportOccurrence === 'function') {
+      occurrences.push(helpers.reportOccurrence(el, baseOccurrence));
+    } else {
+      occurrences.push(baseOccurrence);
+    }
+  }
+
   if (applicableCount === 0) {
     return { ruleId: rule.ruleId, outcome: 'notApplicable', severity: 'minor', occurrences: [] };
   }