@surea11y/core 1.7.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
@@ -475,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);

package/src/checks/manual/input-image-alt-quality-manual.js

@@ -10,20 +10,25 @@
  * @sc 1.1.1
  * @type manual
  * @applicability
- *   Applies to <input type="image"> elements whose alt attribute is present
- *   and non-empty: an image button whose alt is its label. The element must
- *   be included in the accessibility tree, and role="presentation"/"none"
- *   takes it out of scope unless it is focusable, which restores its role.
+ *   Applies to <input type="image"> elements that get a non-empty text
+ *   alternative from any source: aria-labelledby (resolving to text),
+ *   aria-label, alt or title. An element whose alt is present but empty is
+ *   left to input-image-alt-decorative, which asks about that case. The
+ *   element must be included in the accessibility tree, and
+ *   role="presentation"/"none" takes it out of scope unless it is
+ *   focusable, which restores its role.
  * @expectation
- *   Human review is required to confirm that the provided text alternative is accurate and appropriate.
+ *   Human review is required to confirm that the provided text alternative is
+ *   accurate and appropriate. Each occurrence lists every source present
+ *   (data.details.sources), so the reviewer checks each one.
  */
 
 const id = 'input-image-alt-quality';
 
 const meta = {
-  title: '<input type="image"> alt text must be appropriate (manual review)',
+  title: '<input type="image"> text alternative must be appropriate (manual review)',
   description:
-    'Flags <input type="image"> elements with non-empty alt text for human review of appropriateness.',
+    'Flags <input type="image"> elements with a non-empty text alternative (alt, aria-label, aria-labelledby or title) for human review of appropriateness.',
   i18n: {
     titleKey: 'inputImage_altQuality_title',
     descriptionKey: 'inputImage_altQuality_description'
@@ -112,6 +117,53 @@ function runInPage(ctx) {
     return !focusable;
   }
 
+  const getAriaNameInfo =
+    helpers && typeof helpers.getAriaNameInfo === 'function' ? helpers.getAriaNameInfo : null;
+
+  // Every non-empty text-alternative source on the element, in accessible-name
+  // order: aria-labelledby (when it resolves to text), aria-label, alt, title.
+  // aria-labelledby wins over aria-label in the name, but a present aria-label
+  // is still listed, so each attribute present is asked about.
+  function collectTextAlternativeSources(el) {
+    const attr = (name) => {
+      try {
+        const v = el.getAttribute(name);
+        return v == null ? '' : String(v).trim();
+      } catch {
+        return '';
+      }
+    };
+    const sources = [];
+    let name = '';
+    let aria = null;
+    if (getAriaNameInfo) {
+      try {
+        aria = getAriaNameInfo(el, ctx);
+      } catch {
+        aria = null;
+      }
+    }
+    if (aria && aria.present && aria.value) {
+      name = String(aria.value).trim();
+      sources.push(aria.mechanism);
+      if (aria.mechanism === 'aria-labelledby' && attr('aria-label')) sources.push('aria-label');
+    } else if (!getAriaNameInfo && attr('aria-label')) {
+      name = attr('aria-label');
+      sources.push('aria-label');
+    }
+    const altText = attr('alt');
+    if (altText) {
+      sources.push('alt');
+      if (!name) name = altText;
+    }
+    const titleText = attr('title');
+    if (titleText) {
+      sources.push('title');
+      if (!name) name = titleText;
+    }
+    return { sources, name, alt: altText };
+  }
+
   const els = (() => {
     try {
       return Array.from(
@@ -146,24 +198,40 @@ function runInPage(ctx) {
 
     if (isRolePresentationExcluded(el)) continue;
 
-    // Rule-specific applicability (only elements that already have a text alternative mechanism)
-    if (!(el.getAttribute('alt') != null && String(el.getAttribute('alt')).trim() !== '')) continue;
+    // alt="" with another name is input-image-alt-decorative's question, so
+    // it is left there rather than asked twice.
+    let altRaw;
+    try {
+      altRaw = el.getAttribute('alt');
+    } catch {
+      altRaw = null;
+    }
+    if (altRaw != null && String(altRaw).trim() === '') continue;
+
+    // Applies when any text-alternative source gives the control a non-empty
+    // name; each present source is listed so the reviewer checks all of them.
+    const alt = collectTextAlternativeSources(el);
+    if (!alt.sources.length) continue;
 
     applicableCount += 1;
 
     const eligInfo = getEligibilityInfo ? getEligibilityInfo(el, ctx, { targetSet: 'acc' }) : null;
+    const sourcesText = alt.sources.join(', ');
+
+    const details = { name: alt.name, sources: alt.sources.slice() };
+    if (alt.alt) details.alt = alt.alt;
 
     const baseOccurrence = {
-      summary: 'Review alt text on <input type="image"> for accuracy and appropriateness.',
-      hint: 'Ensure the alt text describes the control’s action (e.g., “Search”, “Submit order”) in context.',
+      summary: `Review the text alternative of this <input type="image"> (${sourcesText}) for accuracy and appropriateness.`,
+      hint: 'Ensure each listed text alternative describes the control’s action (e.g., “Search”, “Submit order”) in context.',
       i18n: {
         summaryKey: 'inputImage_altQuality_summary_cantTell',
         hintKey: 'inputImage_altQuality_hint_cantTell',
-        params: { element: 'input[type=image]' }
+        params: { element: 'input[type=image]', sources: sourcesText }
       },
       data: {
         visibilityFilter: eligInfo || { targetSet: 'acc', accEligible: null, reasons: [] },
-        details: { alt: String(el.getAttribute('alt') || '') } // optional but useful
+        details
       }
     };