@surea11y/core 1.6.0 → 1.8.0

package/src/checks/manual/form-control-label-quality-manual.js

@@ -27,6 +27,11 @@
  *   billing), and (c) is the whole of the field's programmatic label, not
  *   the visible fragment of a label whose descriptive part is hidden.
  * @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).
  * - Authored as `type: 'manual'` (cantTell-capped, never fail). Whether a
  *   label describes its field is a reading judgment: ACT cc0f0a fails
  *   `<label>Menu<input type="text" name="fname"></label>` on the meaning
@@ -66,7 +71,7 @@ const id = 'form-control-label-quality';
 const meta = {
   title: 'Form field labels should be descriptive and distinguishable',
   description:
-    'Flags a visible form-field label that is a placeholder ("Label", "Field"), or that repeats another field\'s label with no visible context (heading, legend, or row) telling the two apart.',
+    'Flags a visible form-field label that is a placeholder ("Label", "Field"), or that repeats another field\'s label with no visible context (heading, legend, or row) telling the two apart. English placeholders are always recognized, and German, Spanish, French or Japanese ones when the field is in that language.',
   i18n: {
     titleKey: 'formControlLabelQuality_title',
     descriptionKey: 'formControlLabelQuality_description'
@@ -95,7 +100,7 @@ function runInPage(ctx) {
 
   // Declared inside runInPage; see scripts/build-core.js header
   // ("runInPage MUST be self-contained").
-  const PLACEHOLDER_LABEL_TEXT = new Set([
+  const PLACEHOLDER_LABEL_TEXT_EN = new Set([
     'label',
     'field',
     'form field',
@@ -117,6 +122,79 @@ function runInPage(ctx) {
     'default'
   ]);
 
+  const PLACEHOLDER_LABEL_TEXT = {
+    en: PLACEHOLDER_LABEL_TEXT_EN,
+    de: new Set([
+      'beschriftung',
+      'label',
+      'feld',
+      'formularfeld',
+      'eingabe',
+      'eingabefeld',
+      'text',
+      'textfeld',
+      'text eingeben',
+      'hier eingeben',
+      'wert',
+      'platzhalter',
+      'unbenannt',
+      'test',
+      'beispiel',
+      'standard'
+    ]),
+    es: new Set([
+      'etiqueta',
+      'campo',
+      'campo de formulario',
+      'entrada',
+      'campo de entrada',
+      'texto',
+      'campo de texto',
+      'introduzca texto',
+      'escriba aquí',
+      'valor',
+      'marcador de posición',
+      'sin título',
+      'prueba',
+      'ejemplo',
+      'predeterminado'
+    ]),
+    fr: new Set([
+      'libellé',
+      'étiquette',
+      'champ',
+      'champ de formulaire',
+      'saisie',
+      'champ de saisie',
+      'texte',
+      'champ de texte',
+      'saisir du texte',
+      'saisissez ici',
+      'valeur',
+      'espace réservé',
+      'sans titre',
+      'test',
+      'exemple',
+      'par défaut'
+    ]),
+    ja: new Set([
+      'ラベル',
+      'フィールド',
+      '入力',
+      '入力欄',
+      '入力フィールド',
+      'テキスト',
+      'テキストフィールド',
+      'ここに入力',
+      '値',
+      'プレースホルダー',
+      '無題',
+      '未定',
+      'テスト',
+      'サンプル'
+    ])
+  };
+
   const FIELD_SELECTOR = [
     'input:not([type="hidden"]):not([type="submit"]):not([type="reset"]):not([type="button"]):not([type="image"])',
     'select',
@@ -143,13 +221,35 @@ function runInPage(ctx) {
       .trim();
   }
 
+  // NFKC folds full-width forms (「入力：」 ends in a full-width colon).
   function normalize(s) {
-    return normalizeWs(s)
+    return normalizeWs(String(s || '').normalize('NFKC'))
       .toLowerCase()
-      .replace(/[.,;:!?*]+$/g, '')
+      .replace(/[.,;:!?*。、]+$/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));
+  }
+
   const isDomVisibleEligible =
     helpers && typeof helpers.isDomVisibleEligible === 'function'
       ? helpers.isDomVisibleEligible
@@ -206,29 +306,63 @@ function runInPage(ctx) {
     return out;
   }
 
+  // Index of `<label for="...">` elements by their `for` value, built once
+  // (not the native `el.labels`, deliberately -- see getNativeLabels).
+  const labelsByForId = new Map();
+  try {
+    for (const label of document.querySelectorAll('label[for]')) {
+      const forVal = normalizeWs(label.getAttribute('for'));
+      if (!forVal) continue;
+      const bucket = labelsByForId.get(forVal);
+      if (bucket) bucket.push(label);
+      else labelsByForId.set(forVal, [label]);
+    }
+  } catch {
+    // labelsByForId stays empty; getNativeLabels still has the wrapping-label check
+  }
+
+  // Per HTML's label-control algorithm, a wrapping <label> with no `for`
+  // attribute is associated with its own FIRST labelable descendant only --
+  // these are exactly the tags that count (input excluding type=hidden,
+  // which FIELD_SELECTOR already excludes from `el` itself, but a wrapping
+  // label could still wrap a hidden input ahead of the real field).
+  const LABELABLE_SELECTOR =
+    'input:not([type="hidden"]), select, textarea, button, meter, output, progress';
+
+  // The native `el.labels` accessor is spec-correct but, in this engine's
+  // supported Node/jsdom runtime (see tests/node-runtime-parity.test.js),
+  // jsdom implements it as a live query that walks the WHOLE document on
+  // every access, and for every `<label for>` it passes, calls `.control`
+  // -- itself another whole-document walk to resolve that id (jsdom's
+  // form-controls.js getLabelsForLabelable / HTMLLabelElement-impl.js
+  // `get control`). Called once per field, that's the O(fields * document
+  // size) cost that used to dominate this rule under jsdom (a real browser
+  // maintains an internal id index, so this cost is jsdom-specific, but
+  // jsdom is a real, tested runtime for this engine, not just a benchmark
+  // artifact). A `for`-attribute index built once above, plus a bounded
+  // `closest('label')` walk, answers the same question in O(1) amortized
+  // per field instead.
   function getNativeLabels(el) {
     const labels = [];
-    try {
-      if (el.labels && el.labels.length) {
-        for (const label of el.labels) labels.push(label);
-        return labels;
-      }
-    } catch {
-      // fall through to the manual lookup
-    }
     const idVal = normalizeWs(el.getAttribute && el.getAttribute('id'));
     if (idVal) {
-      try {
-        for (const label of document.querySelectorAll('label[for]')) {
-          if (normalizeWs(label.getAttribute('for')) === idVal) labels.push(label);
-        }
-      } catch {
-        // ignore
+      const forLabels = labelsByForId.get(idVal);
+      if (forLabels) {
+        for (const label of forLabels) labels.push(label);
       }
     }
     try {
       const wrapping = el.closest ? el.closest('label') : null;
-      if (wrapping && labels.indexOf(wrapping) === -1) labels.push(wrapping);
+      const hasForAttr = !!(wrapping && wrapping.hasAttribute && wrapping.hasAttribute('for'));
+      if (wrapping && !hasForAttr && labels.indexOf(wrapping) === -1) {
+        let firstControl = null;
+        try {
+          firstControl = wrapping.querySelector ? wrapping.querySelector(LABELABLE_SELECTOR) : null;
+        } catch {
+          firstControl = null;
+        }
+        if (firstControl === el) labels.push(wrapping);
+      }
     } catch {
       // ignore
     }
@@ -269,15 +403,17 @@ function runInPage(ctx) {
     }
   }
 
+  // Nearest preceding *visible* heading text, per field. Precomputed below
+  // (once `fields` is built) via a single document-order sweep rather than
+  // scanning the full `headings` array backward for every field: `headings`
+  // and `fields` are each already in document order (both come from
+  // querySelectorAll/queryAllSmart), so a two-pointer merge answers every
+  // field in one O(fields + headings) pass instead of the O(fields *
+  // headings) pairwise compareDocumentPosition/isVisible calls a per-field
+  // backward scan requires -- the dominant cost on heading/form-heavy pages.
+  const nearestVisibleHeadingByField = new Map();
   function nearestVisibleHeadingText(el) {
-    for (let i = headings.length - 1; i >= 0; i--) {
-      const heading = headings[i];
-      if (!precedes(heading, el)) continue;
-      if (!isVisible(heading)) continue;
-      const text = normalizeWs(heading.textContent);
-      if (text) return text;
-    }
-    return '';
+    return nearestVisibleHeadingByField.get(el) || '';
   }
 
   function fieldsetLegendText(el) {
@@ -309,6 +445,9 @@ function runInPage(ctx) {
 
   // A table row or list item carries its own context (the product name a
   // repeated "Quantity" field belongs to), so it takes part in the key.
+  // `row.textContent` serializes the whole row subtree, so it's memoized per
+  // row element -- several fields (one per column) commonly share a row.
+  const rowTextCache = new Map();
   function rowContextText(el, labelText) {
     let row;
     try {
@@ -317,7 +456,11 @@ function runInPage(ctx) {
       row = null;
     }
     if (!row || !isVisible(row)) return '';
-    const text = normalizeWs(row.textContent);
+    let text = rowTextCache.get(row);
+    if (text === undefined) {
+      text = normalizeWs(row.textContent);
+      rowTextCache.set(row, text);
+    }
     if (!text) return '';
     return normalizeWs(text.split(labelText).join(' '));
   }
@@ -348,6 +491,73 @@ function runInPage(ctx) {
     });
   }
 
+  // Populate nearestVisibleHeadingByField (declared above nearestVisibleHeadingText)
+  // via a single two-pointer sweep instead of, per field, scanning the full
+  // `headings` array backward and calling compareDocumentPosition/isVisible
+  // against every one of them -- the O(fields * headings) cost that used to
+  // dominate this rule (and the whole engine) on heading/form-heavy pages.
+  //
+  // Two correctness precautions this needs, since a two-pointer merge only
+  // works over sequences that are BOTH already in real document order:
+  //
+  // 1. A field inside a shadow root has no document-order relationship to
+  //    any heading at all: per the DOM spec, compareDocumentPosition
+  //    between nodes in different trees returns an implementation-specific
+  //    (not document-order-derived) PRECEDING/FOLLOWING bit. Merging it in
+  //    would be meaningless and could even desync the sweep for later
+  //    fields, so it's filtered out up front and always answered '' --
+  //    matching the "no light-DOM heading can be this field's visible
+  //    context" reading rather than trusting that arbitrary bit.
+  // 2. `fields` (from queryAllSmart) is NOT guaranteed to be globally
+  //    document-order: it's built root by root (see resolveContextRoots),
+  //    and a multi-region `engineOptions.contextSelector` array is resolved
+  //    in the CALLER's array order, not sorted by document position. A
+  //    fresh copy is sorted by real position before the sweep so the merge
+  //    is correct regardless of contextSelector's region order (this is a
+  //    cheap O(k log k) sort, not the O(n*m) cost being fixed).
+  {
+    const orderedFields = [];
+    for (const field of fields) {
+      let sameRoot;
+      try {
+        sameRoot =
+          typeof field.el.getRootNode !== 'function' || field.el.getRootNode() === document;
+      } catch {
+        sameRoot = true;
+      }
+
+      if (!sameRoot) {
+        nearestVisibleHeadingByField.set(field.el, '');
+        continue;
+      }
+      orderedFields.push(field);
+    }
+
+    orderedFields.sort((a, b) => {
+      try {
+        const bits = a.el.compareDocumentPosition(b.el);
+        if (bits & 4) return -1; // b follows a
+        if (bits & 2) return 1; // b precedes a
+      } catch {
+        /* ignore -- treat as equal/unordered */
+      }
+      return 0;
+    });
+
+    let hIdx = 0;
+    let current = '';
+    for (const field of orderedFields) {
+      while (hIdx < headings.length && precedes(headings[hIdx], field.el)) {
+        const heading = headings[hIdx];
+        hIdx += 1;
+        if (!isVisible(heading)) continue;
+        const text = normalizeWs(heading.textContent);
+        if (text) current = text;
+      }
+      nearestVisibleHeadingByField.set(field.el, current);
+    }
+  }
+
   if (!fields.length) {
     return { ruleId: rule.ruleId, outcome: 'notApplicable', severity: 'minor', occurrences: [] };
   }
@@ -365,7 +575,11 @@ function runInPage(ctx) {
   const occurrences = [];
 
   for (const field of fields) {
-    const isPlaceholder = PLACEHOLDER_LABEL_TEXT.has(field.normalized);
+    const isPlaceholder = inPhraseList(
+      PLACEHOLDER_LABEL_TEXT,
+      field.normalized,
+      primaryLangOf(field.el)
+    );
     const shared = byKey.get(field.key) || [];
     const isDuplicate = shared.length > 1;
     const isPartiallyHidden = field.hiddenParts > 0;

package/src/checks/manual/heading-order-manual.js

@@ -11,6 +11,8 @@
  *   Applies whenever the page contains two or more heading elements
  *   (native <h1>-<h6>, or explicit role="heading" with aria-level;
  *   default level 2 per the ARIA spec when aria-level is absent/invalid).
+ *   A native <hx> with a valid aria-level (a positive integer) takes that
+ *   level, as browsers expose it; otherwise it takes its tag level.
  * @expectation
  *   In document order, each heading's level is no more than one greater
  *   than the highest heading level seen so far. Jumping deeper by more
@@ -73,7 +75,13 @@ function runInPage(ctx) {
     }
     const tag = el.tagName ? el.tagName.toLowerCase() : '';
     const m = /^h([1-6])$/.exec(tag);
-    return m ? parseInt(m[1], 10) : 0;
+    if (!m) return 0;
+    // Browsers expose a valid aria-level on <hx> in place of the tag level.
+    const ariaLevel = normalizeWs(el.getAttribute && el.getAttribute('aria-level'));
+    if (/^[0-9]+$/.test(ariaLevel) && parseInt(ariaLevel, 10) >= 1) {
+      return parseInt(ariaLevel, 10);
+    }
+    return parseInt(m[1], 10);
   }
 
   const nodes = helpers.queryAllSmart

package/src/checks/manual/heading-quality-manual.js

@@ -21,6 +21,11 @@
  *   2", "Section 3"), a filename, or a URL. None of these describe the
  *   topic or purpose of the content they introduce.
  * @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).
  * - Authored as `type: 'manual'` (cantTell-capped, never fail), for the
  *   same reason `link-name-quality` is: whether a heading describes the
  *   content that follows it is a reading-comprehension judgment. What is
@@ -52,7 +57,7 @@ const id = 'heading-quality';
 const meta = {
   title: 'Heading text should be descriptive, not a placeholder',
   description:
-    'Flags headings whose accessible name is a placeholder rather than a description of the content that follows: a generic word ("Heading", "Untitled"), a numbered template slot ("Section 2"), a filename, or a URL.',
+    'Flags headings whose accessible name is a placeholder rather than a description of the content that follows: a generic word ("Heading", "Untitled"), a numbered template slot ("Section 2"), a filename, or a URL. English phrases are always recognized, and German, Spanish, French or Japanese ones when the heading is in that language.',
   i18n: {
     titleKey: 'headingQuality_title',
     descriptionKey: 'headingQuality_description'
@@ -81,7 +86,7 @@ function runInPage(ctx) {
 
   // Declared inside runInPage; see scripts/build-core.js header
   // ("runInPage MUST be self-contained").
-  const PLACEHOLDER_HEADING_TEXT = new Set([
+  const PLACEHOLDER_HEADING_TEXT_EN = new Set([
     'heading',
     'header',
     'headline',
@@ -118,8 +123,101 @@ function runInPage(ctx) {
   // A numbered template slot left as authored: "Heading 2", "Section 3",
   // "Chapter #1". The word alone is already in the set above; this catches
   // the same words carrying an index.
-  const NUMBERED_PLACEHOLDER =
-    /^(heading|header|headline|subheading|title|subtitle|section|chapter|part|step)\s*[-#:.]?\s*\d+$/;
+  // "Inhalt" and "Contenido" are left out: they usually head a table of
+  // contents, which is a real heading.
+  const PLACEHOLDER_HEADING_TEXT = {
+    en: PLACEHOLDER_HEADING_TEXT_EN,
+    de: new Set([
+      'überschrift',
+      'zwischenüberschrift',
+      'titel',
+      'untertitel',
+      'unbenannt',
+      'ohne titel',
+      'abschnitt',
+      'neuer abschnitt',
+      'kapitel',
+      'hauptinhalt',
+      'text',
+      'beispieltext',
+      'blindtext',
+      'platzhalter',
+      'platzhaltertext',
+      'titel hier eingeben',
+      'test',
+      'beispiel',
+      'standard'
+    ]),
+    es: new Set([
+      'encabezado',
+      'título',
+      'subtítulo',
+      'sin título',
+      'sección',
+      'nueva sección',
+      'capítulo',
+      'contenido principal',
+      'texto',
+      'texto de ejemplo',
+      'marcador de posición',
+      'escriba el título aquí',
+      'su título aquí',
+      'por definir',
+      'prueba',
+      'ejemplo',
+      'predeterminado'
+    ]),
+    fr: new Set([
+      'titre',
+      'sous-titre',
+      'sans titre',
+      'section',
+      'nouvelle section',
+      'chapitre',
+      'contenu',
+      'contenu principal',
+      'texte',
+      "texte d'exemple",
+      'espace réservé',
+      'insérer le titre ici',
+      'votre titre ici',
+      'à définir',
+      'test',
+      'exemple',
+      'par défaut'
+    ]),
+    ja: new Set([
+      '見出し',
+      '小見出し',
+      'タイトル',
+      'サブタイトル',
+      '無題',
+      'セクション',
+      '新しいセクション',
+      '章',
+      'コンテンツ',
+      'メインコンテンツ',
+      'テキスト',
+      'サンプルテキスト',
+      'ダミーテキスト',
+      'プレースホルダー',
+      'ここにタイトルを入力',
+      'タイトルを入力',
+      '未定',
+      'テスト',
+      'サンプル'
+    ])
+  };
+
+  // A numbered template slot left as authored: "Heading 2", "Section 3",
+  // "Chapter #1", 「見出し 2」, 「第 1 章」.
+  const NUMBERED_PLACEHOLDER = {
+    en: /^(heading|header|headline|subheading|title|subtitle|section|chapter|part|step)\s*[-#:.]?\s*\d+$/,
+    de: /^(überschrift|titel|abschnitt|kapitel|teil|schritt)\s*[-#:.]?\s*\d+$/,
+    es: /^(encabezado|título|sección|capítulo|parte|paso)\s*[-#:.]?\s*\d+$/,
+    fr: /^(titre|section|chapitre|partie|étape)\s*[-#:.]?\s*\d+$/,
+    ja: /^(?:(見出し|タイトル|セクション|章|ステップ|パート)\s*[-#:.]?\s*\d+|第\s*\d+\s*章)$/
+  };
 
   const FILENAME_LIKE =
     /^[\w\s\-.,()[\]]+\.(png|jpe?g|gif|svg|webp|avif|bmp|ico|tiff?|pdf|docx?|xlsx?|pptx?|html?|txt|csv|zip)$/;
@@ -132,13 +230,36 @@ function runInPage(ctx) {
       .trim();
   }
 
+  // NFKC folds full-width letters and digits (「見出し２」) into ASCII forms.
   function normalize(s) {
-    return normalizeWs(s)
+    return normalizeWs(String(s || '').normalize('NFKC'))
+      .replace(/[\u2018\u2019]/g, "'")
       .toLowerCase()
-      .replace(/[.,;:!?]+$/g, '')
+      .replace(/[.,;:!?。、]+$/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 getExplicitRoleToken(el) {
     const raw = normalizeWs(el.getAttribute && el.getAttribute('role'));
     if (!raw) return '';
@@ -248,8 +369,21 @@ function runInPage(ctx) {
     }
   }
 
-  function classify(normalized) {
-    if (PLACEHOLDER_HEADING_TEXT.has(normalized) || NUMBERED_PLACEHOLDER.test(normalized)) {
+  function isNumberedPlaceholder(normalized, lang) {
+    if (NUMBERED_PLACEHOLDER.en.test(normalized)) return true;
+    return !!(
+      lang &&
+      lang !== 'en' &&
+      NUMBERED_PLACEHOLDER[lang] &&
+      NUMBERED_PLACEHOLDER[lang].test(normalized)
+    );
+  }
+
+  function classify(normalized, lang) {
+    if (
+      inPhraseList(PLACEHOLDER_HEADING_TEXT, normalized, lang) ||
+      isNumberedPlaceholder(normalized, lang)
+    ) {
       return 'PLACEHOLDER_HEADING_TEXT';
     }
     if (URL_LIKE.test(normalized)) return 'URL_LIKE_HEADING';
@@ -282,7 +416,7 @@ function runInPage(ctx) {
 
     applicableCount += 1;
 
-    const reasonCode = classify(normalized);
+    const reasonCode = classify(normalized, primaryLangOf(el));
     if (!reasonCode) continue;
 
     const eligInfo = helpers.getEligibilityInfo

package/src/checks/manual/img-alt-decorative-manual.js

@@ -14,7 +14,8 @@
  *   accessibility tree by any of: an aria-hidden ancestor-or-self, an
  *   explicit role="none"/"presentation" not overridden by focusability, an
  *   <img alt=""> (the native decorative marker, same focusability
- *   override), an unlabeled <svg> whose implicit role is graphics-document
+ *   override; only a literally empty alt, so alt=" " is not one), an
+ *   unlabeled <svg> whose implicit role is graphics-document
  *   (no img/graphics-symbol role restatement, aria-name, <title>/<desc>, or
  *   focusability), or an unlabeled <canvas> with no explicit role at all.
  *   Per ACT e88epe, an element is skipped entirely when any ancestor
@@ -198,12 +199,14 @@ function runInPage(ctx) {
   // Presentational exclusion: explicit role="none"/"presentation", or (img
   // only) the native alt="" marker. Both are overridden by focusability, per
   // ARIA conflict resolution (a focusable element is never presentational).
+  // Only a literally empty alt is the marker: HTML-AAM maps an img to
+  // presentation only for alt="", so alt=" " keeps the img role with an
+  // empty name, which img-alt-present fails.
   function isPresentationallyExcluded(el, tag) {
     const role = getExplicitRole(el);
     let presentational = role === 'presentation' || role === 'none';
     if (!presentational && tag === 'img') {
-      const alt = el.getAttribute('alt');
-      presentational = alt != null && trim(alt) === '';
+      presentational = el.getAttribute('alt') === '';
     }
     if (!presentational) return false;
     return !isFocusable(el);