@surea11y/core 1.0.0

package/src/checks/automatic/area-alt-present.js

@@ -0,0 +1,225 @@
+'use strict';
+
+/**
+ * @check area-alt-present
+ * @atomic true
+ * @summary Accessible <area> elements must have an alt attribute
+ * @standard WCAG 2.2
+ * @sc 1.1.1
+ * @applicability
+ *   Applies to <area> elements that:
+ *   1) are in a <map> that is referenced by an <img usemap>, AND
+ *   2) the referencing <img> is eligible in the accessibility tree (best-effort), AND
+ *   3) the <area> itself is eligible in the accessibility tree (with engine exceptions).
+ * @expectation
+ *   Each applicable <area> element has an alt attribute.
+ *   The alt attribute may be empty (alt="").
+ */
+
+const id = 'area-alt-present';
+
+const meta = {
+  title: '&lt;area&gt; must have an alt attribute',
+  description: 'Checks that &lt;area&gt; elements provide an alt attribute to support a text alternative mechanism.',
+  i18n: {
+    titleKey: 'area_altPresent_title',
+    descriptionKey: 'area_altPresent_description'
+  },
+  helpUrl: null,
+  tags: ['wcag2a', 'wcag111', 'nontext', 'images', 'imagemap', 'atomic', 'automatic'],
+  wcagSc: ['1.1.1'],
+  normativeMappings: [
+    { standard: 'WCAG', version: '2.2', requirement: '1.1.1', title: 'Non-text Content', conformanceLevel: 'A' }
+  ],
+  defaultSeverity: 'serious',
+  category: 'perceivable',
+  type: 'automatic',
+  defaultConfidence: 'high',
+  coverage: {
+    facetsBySc: {
+      '1.1.1': ['area-alt-attr-present']
+    }
+  }
+};
+
+function runInPage(ctx) {
+  const { document, root, helpers, rule } = ctx;
+  const safeRoot = root || document;
+
+  const queryAllSmart = helpers && typeof helpers.queryAllSmart === 'function' ? helpers.queryAllSmart : null;
+  const queryAll = helpers && typeof helpers.queryAll === 'function'
+      ? helpers.queryAll
+      : (sel) => {
+        try { return safeRoot && safeRoot.querySelectorAll ? Array.from(safeRoot.querySelectorAll(sel)) : []; }
+        catch { return []; }
+      };
+
+  const getEligibilityInfo = helpers && typeof helpers.getEligibilityInfo === 'function'
+      ? helpers.getEligibilityInfo
+      : null;
+
+  const isAccTreeEligible = helpers && typeof helpers.isAccTreeEligible === 'function'
+      ? helpers.isAccTreeEligible
+      : null;
+
+  const getAriaNameInfo = helpers && typeof helpers.getAriaNameInfo === 'function'
+      ? helpers.getAriaNameInfo
+      : null;
+
+  // --- image-map semantics (rule-local) ---
+
+  function normUsemap(val) {
+    try {
+      const s = String(val || '').trim();
+      if (!s) return '';
+      return (s[0] === '#') ? s.slice(1).trim().toLowerCase() : s.toLowerCase();
+    } catch {
+      return '';
+    }
+  }
+
+  function getMapName(mapEl) {
+    try {
+      if (!mapEl || !mapEl.getAttribute) return '';
+      const n = String(mapEl.getAttribute('name') || mapEl.getAttribute('id') || '').trim();
+      return n ? n.toLowerCase() : '';
+    } catch {
+      return '';
+    }
+  }
+
+  // Cache mapName -> first referencing <img> in document order (deterministic)
+  const __usemapIndex = (() => {
+    const idx = new Map();
+    try {
+      const imgs = document && document.querySelectorAll ? document.querySelectorAll('img[usemap]') : [];
+      for (const img of imgs) {
+        if (!img || !img.getAttribute) continue;
+        const u = normUsemap(img.getAttribute('usemap'));
+        if (!u) continue;
+        if (!idx.has(u)) idx.set(u, img); // first in document order wins
+      }
+    } catch {
+      // ignore
+    }
+    return idx;
+  })();
+
+  function getReferencingImgForArea(areaEl) {
+    try {
+      if (!areaEl || !areaEl.closest) return null;
+      const map = areaEl.closest('map');
+      if (!map) return null;
+
+      const mapName = getMapName(map);
+      if (!mapName) return null;
+
+      return __usemapIndex.get(mapName) || null;
+    } catch {}
+    return null;
+  }
+
+  const areas = (() => {
+    try { return Array.from((queryAllSmart ? queryAllSmart('area') : queryAll('area')) || []); }
+    catch { return queryAll('area'); }
+  })();
+
+  if (!areas.length) {
+    return { ruleId: rule.ruleId, outcome: 'notApplicable', severity: 'minor', occurrences: [] };
+  }
+
+  const occurrences = [];
+  let applicableCount = 0;
+
+  for (const el of areas) {
+    if (!el || !el.getAttribute) continue;
+
+    // 0) Must belong to a *used* image map: an <img usemap> must reference its <map>.
+    // If not used, <area> is not applicable (matches your observed focus behavior).
+    const img = getReferencingImgForArea(el);
+    if (!img) continue;
+
+    // 1) The referencing <img> must itself be eligible in the acc tree.
+    // This is the "visibility of map/area doesn't matter; the image does" policy.
+    if (isAccTreeEligible) {
+      const imgElig = (() => {
+        try { return isAccTreeEligible(img, ctx); } catch { return { eligible: true, reasons: [] }; }
+      })();
+      if (imgElig && imgElig.eligible === false) continue;
+    }
+
+    // 2) The <area> itself must be eligible (aria-hidden/inert exceptions handled by helper).
+    if (isAccTreeEligible) {
+      const elig = (() => {
+        try { return isAccTreeEligible(el, ctx); } catch { return { eligible: true, reasons: [] }; }
+      })();
+      if (elig && elig.eligible === false) continue;
+    }
+
+    // From here: applicable
+    applicableCount += 1;
+
+    const hasAlt = el.getAttribute('alt') !== null;
+    if (hasAlt) continue;
+
+    // aria-label / aria-labelledby is also a valid, standards-recognized
+    // text-alternative mechanism for <area> (HTML-AAM accessible name
+    // computation includes ARIA naming before falling back to alt).
+    if (getAriaNameInfo) {
+      let ariaName = null;
+      try {
+        ariaName = getAriaNameInfo(el, ctx);
+      } catch {
+        ariaName = null;
+      }
+      if (ariaName && ariaName.present) continue;
+    }
+
+    // A non-empty title attribute is HTML-AAM's own next fallback naming
+    // source once alt is entirely absent -- also accepted by a widely-used
+    // reference engine's equivalent area-alt rule (non-empty-title, same "any" list as
+    // non-empty-alt/aria-label/aria-labelledby). See img-alt-present's
+    // sibling fix (2026-07-23, AliExpress's title-only logo <img>) for
+    // the real page this was found via -- same gap, same fix, different
+    // element.
+    const titleRaw = (() => { try { return el.getAttribute('title'); } catch { return null; } })();
+    if (titleRaw !== null && String(titleRaw).trim()) continue;
+
+    const eligInfo = getEligibilityInfo ? getEligibilityInfo(el, ctx, { targetSet: 'acc' }) : null;
+
+    const baseOccurrence = {
+      // Leave selector/html empty so the engine can fill them from __node.
+      selector: '',
+      html: '',
+      summary: 'Missing alt attribute on &lt;area&gt;.',
+      hint: 'Add an alt attribute (use alt="" only for decorative areas).',
+      i18n: {
+        summaryKey: 'area_altPresent_summary_fail',
+        hintKey: 'area_altPresent_hint_fail',
+        params: { element: 'area' }
+      },
+      data: {
+        visibilityFilter: eligInfo || { targetSet: 'acc', accEligible: null, reasons: [] }
+      }
+    };
+
+    if (helpers && typeof helpers.reportOccurrence === 'function') {
+      occurrences.push(helpers.reportOccurrence(el, baseOccurrence));
+    } else {
+      // Never compute selector/snippet in the rule.
+      occurrences.push({ ...baseOccurrence });
+    }
+  }
+
+  if (applicableCount === 0) {
+    return { ruleId: rule.ruleId, outcome: 'notApplicable', severity: 'minor', occurrences: [] };
+  }
+
+  if (!occurrences.length) {
+    return { ruleId: rule.ruleId, outcome: 'pass', severity: 'minor', occurrences: [] };
+  }
+
+  return { ruleId: rule.ruleId, outcome: 'fail', severity: rule.defaultSeverity || 'minor', occurrences };
+}
+
+module.exports = { id, meta, runInPage };

package/src/checks/automatic/aria-allowed-attr.js

@@ -0,0 +1,206 @@
+'use strict';
+
+/**
+ * @check aria-allowed-attr
+ * @atomic true
+ * @summary aria-* attributes present must be permitted for the element's role
+ * @standard WCAG 2.2
+ * @sc 4.1.2
+ * @applicability
+ *   Applies to elements with an explicit, valid, non-abstract role that
+ *   also carry at least one recognized aria-* attribute.
+ * @expectation
+ *   Every recognized aria-* attribute present is either: (a) globally
+ *   supported on any element (the "global" ARIA states/properties, e.g.
+ *   aria-label/aria-hidden/aria-describedby), or (b) explicitly listed as
+ *   a required or supported state/property for the element's role.
+ * @implementation-notes
+ * - Only evaluated for elements with an explicit role, since the global
+ *   set already covers implicit-role elements without asserting anything
+ *   role-specific; scope kept deliberately narrow to avoid false positives
+ *   on implicit-role ARIA-in-HTML edge cases not modeled here.
+ * - SUPPORTED_ATTRS_BY_ROLE widened 2026-07-21 (7 new roles), cross-checked
+ *   against a widely-used reference engine's own per-role `allowedAttrs`
+ *   table AND verified each addition is an unambiguous, well-established ARIA
+ *   fact rather than a blind import — that engine's own table has ~68 roles,
+ *   far more than were reconciled here; this pass deliberately took only the
+ *   additions with clear, specific supported attributes (not just the
+ *   near-universal, thin `aria-expanded` that engine allows on most roles), and
+ *   left the rest for a dedicated future full-reconciliation pass rather
+ *   than rushing all 68 through at lower confidence:
+ *   - `searchbox`: identical to the already-covered `textbox` (ARIA
+ *     explicitly defines searchbox as textbox's subclass, same supported
+ *     set).
+ *   - `meter`: valuenow/valuemax/valuemin/valuetext, matching the
+ *     already-covered slider/progressbar/scrollbar/spinbutton pattern
+ *     (valuenow is also separately *required* on meter — see
+ *     `aria-required-attr`'s own 2026-07-21 widening — but the two tables
+ *     aren't unioned automatically, so it needs listing in both places).
+ *   - `columnheader`/`rowheader`: same table-role family already covered
+ *     by `gridcell`/`row` — sort/col-row-index/span are standard WAI-ARIA
+ *     grid-model properties.
+ *   - `dialog`/`alertdialog`: `aria-modal` — the spec-defining property
+ *     that distinguishes a modal from a non-modal dialog; unambiguous.
+ *   - `listitem`: level/posinset/setsize — standard flat-representation-
+ *     of-hierarchy properties, same family as the already-covered
+ *     `treeitem`.
+ *   - `menu`/`menubar`/`toolbar`: activedescendant/orientation — standard
+ *     composite-widget properties, same family as the already-covered
+ *     `tablist`.
+ * - Not gated on isAccTreeEligible: this is a static markup property.
+ */
+
+const id = 'aria-allowed-attr';
+
+const meta = {
+  title: 'aria-* attributes must be permitted for the element’s role',
+  description: 'Checks that every recognized aria-* attribute present on an element with an explicit role is either globally supported or supported by that role.',
+  i18n: {
+    titleKey: 'ariaAllowedAttr_title',
+    descriptionKey: 'ariaAllowedAttr_description'
+  },
+  helpUrl: null,
+  tags: ['wcag2a', 'wcag412', 'aria', 'structure', 'atomic', 'automatic'],
+  wcagSc: ['4.1.2'],
+  normativeMappings: [
+    { standard: 'WCAG', version: '2.2', requirement: '4.1.2', title: 'Name, Role, Value', conformanceLevel: 'A' }
+  ],
+  defaultSeverity: 'moderate',
+  category: 'robust',
+  type: 'automatic',
+  defaultConfidence: 'medium',
+  coverage: { facetsBySc: { '4.1.2': ['aria-attr-allowed-for-role'] } }
+};
+
+function runInPage(ctx) {
+  const { document, root, helpers, rule } = ctx;
+  const safeRoot = root || document;
+
+  const ariaHelpers = helpers && helpers.aria ? helpers.aria : null;
+  if (!ariaHelpers) {
+    return { ruleId: rule.ruleId, outcome: 'notApplicable', severity: 'minor', occurrences: [] };
+  }
+
+  // Global ARIA states/properties supported on (almost) any element,
+  // regardless of role, per the WAI-ARIA "Global States and Properties" list.
+  // Declared inside runInPage (rather than at module scope) because the
+  // build inlines only this function's own source text — see
+  // scripts/build-core.js header ("runInPage MUST be self-contained").
+  const GLOBAL_ATTRS = [
+    'aria-atomic', 'aria-braillelabel', 'aria-brailleroledescription', 'aria-busy',
+    'aria-controls', 'aria-current', 'aria-describedby', 'aria-description',
+    'aria-details', 'aria-disabled', 'aria-dropeffect', 'aria-errormessage',
+    'aria-flowto', 'aria-grabbed', 'aria-haspopup', 'aria-hidden', 'aria-invalid',
+    'aria-keyshortcuts', 'aria-label', 'aria-labelledby', 'aria-live', 'aria-owns',
+    'aria-relevant', 'aria-roledescription'
+  ];
+
+  // Per-role supported (non-global) states/properties. Deliberately
+  // conservative — see src/core/aria-helpers.js file header for the same
+  // confidence-scoping rationale; only well-established, unambiguous
+  // role/attribute pairings from the WAI-ARIA role definitions are listed.
+  const SUPPORTED_ATTRS_BY_ROLE = {
+    alertdialog: ['aria-modal'],
+    checkbox: ['aria-checked', 'aria-readonly', 'aria-required'],
+    columnheader: ['aria-sort', 'aria-colindex', 'aria-colspan', 'aria-readonly', 'aria-required', 'aria-rowindex', 'aria-rowspan', 'aria-selected'],
+    combobox: ['aria-expanded', 'aria-autocomplete', 'aria-readonly', 'aria-required'],
+    dialog: ['aria-modal'],
+    grid: ['aria-multiselectable', 'aria-readonly', 'aria-colcount', 'aria-rowcount'],
+    gridcell: ['aria-selected', 'aria-readonly', 'aria-required', 'aria-colindex', 'aria-colspan', 'aria-rowindex', 'aria-rowspan'],
+    heading: ['aria-level'],
+    listbox: ['aria-multiselectable', 'aria-readonly', 'aria-required', 'aria-orientation'],
+    listitem: ['aria-level', 'aria-posinset', 'aria-setsize'],
+    menu: ['aria-activedescendant', 'aria-orientation'],
+    menubar: ['aria-activedescendant', 'aria-orientation'],
+    menuitemcheckbox: ['aria-checked'],
+    menuitemradio: ['aria-checked'],
+    meter: ['aria-valuenow', 'aria-valuemin', 'aria-valuemax', 'aria-valuetext'],
+    option: ['aria-selected', 'aria-checked', 'aria-posinset', 'aria-setsize'],
+    progressbar: ['aria-valuenow', 'aria-valuemin', 'aria-valuemax', 'aria-valuetext'],
+    radio: ['aria-checked'],
+    radiogroup: ['aria-readonly', 'aria-required', 'aria-orientation'],
+    row: ['aria-selected', 'aria-level', 'aria-posinset', 'aria-setsize', 'aria-colindex', 'aria-rowindex'],
+    rowheader: ['aria-sort', 'aria-colindex', 'aria-colspan', 'aria-readonly', 'aria-required', 'aria-rowindex', 'aria-rowspan', 'aria-selected'],
+    scrollbar: ['aria-valuenow', 'aria-valuemin', 'aria-valuemax', 'aria-valuetext', 'aria-orientation', 'aria-controls'],
+    searchbox: ['aria-activedescendant', 'aria-autocomplete', 'aria-multiline', 'aria-placeholder', 'aria-readonly', 'aria-required'],
+    separator: ['aria-valuenow', 'aria-valuemin', 'aria-valuemax', 'aria-valuetext', 'aria-orientation'],
+    slider: ['aria-valuenow', 'aria-valuemin', 'aria-valuemax', 'aria-valuetext', 'aria-orientation', 'aria-readonly'],
+    spinbutton: ['aria-valuenow', 'aria-valuemin', 'aria-valuemax', 'aria-valuetext', 'aria-readonly', 'aria-required'],
+    switch: ['aria-checked'],
+    tab: ['aria-selected'],
+    table: ['aria-colcount', 'aria-rowcount'],
+    tablist: ['aria-multiselectable', 'aria-orientation'],
+    textbox: ['aria-activedescendant', 'aria-autocomplete', 'aria-multiline', 'aria-placeholder', 'aria-readonly', 'aria-required'],
+    toolbar: ['aria-activedescendant', 'aria-orientation'],
+    tree: ['aria-multiselectable', 'aria-readonly', 'aria-required', 'aria-orientation'],
+    treegrid: ['aria-multiselectable', 'aria-readonly', 'aria-required', 'aria-orientation', 'aria-colcount', 'aria-rowcount'],
+    treeitem: ['aria-checked', 'aria-selected', 'aria-expanded', 'aria-level', 'aria-posinset', 'aria-setsize']
+  };
+
+  const globalSet = new Set(GLOBAL_ATTRS);
+  const nodes = helpers.queryAllSmart ? helpers.queryAllSmart('[role]', safeRoot) : helpers.queryAll('[role]', safeRoot);
+
+  const occurrences = [];
+  let applicableCount = 0;
+
+  for (const el of nodes) {
+    if (!el || !el.attributes) continue;
+
+    const role = ariaHelpers.getExplicitRole(el);
+    if (!role || !ariaHelpers.isValidConcreteRole(role)) continue; // aria-roles-valid's concern
+
+    // Deliberately scoped: only roles with an explicit supported-attrs
+    // entry are evaluated (see file header — kept narrow to avoid
+    // over-claiming constraints for roles not yet modeled here).
+    const roleSupported = SUPPORTED_ATTRS_BY_ROLE[role];
+    if (!roleSupported) continue;
+    const roleSupportedSet = new Set(roleSupported);
+
+    let disallowed = null;
+    const attrs = el.attributes;
+    for (let i = 0; i < attrs.length; i++) {
+      const name = String(attrs[i].name || '').toLowerCase();
+      if (name.slice(0, 5) !== 'aria-') continue;
+      if (!ariaHelpers.isValidAriaAttrName(name)) continue; // aria-valid-attr's concern
+
+      applicableCount += 1;
+
+      if (globalSet.has(name) || roleSupportedSet.has(name)) continue;
+
+      if (!disallowed) disallowed = [];
+      disallowed.push(name);
+    }
+
+    if (!disallowed || !disallowed.length) continue;
+
+    const stableSelector = helpers.buildSelector ? helpers.buildSelector(el) : 'html';
+    const html = helpers.getOuterHtmlSnippet ? helpers.getOuterHtmlSnippet(el) : (el.outerHTML || '');
+
+    for (const name of disallowed) {
+      occurrences.push({
+        selector: stableSelector,
+        html,
+        summary: 'This ARIA attribute is not permitted for this element’s role.',
+        hint: 'Remove this attribute, or use a role that supports it.',
+        i18n: {
+          summaryKey: 'ariaAllowedAttr_summary_fail',
+          hintKey: 'ariaAllowedAttr_hint_fail',
+          params: { attr: name, role }
+        },
+        data: {
+          details: { reasonCode: 'ARIA_ATTR_NOT_ALLOWED', attr: name, role }
+        }
+      });
+    }
+  }
+
+  if (applicableCount === 0) {
+    return { ruleId: rule.ruleId, outcome: 'notApplicable', severity: 'minor', occurrences: [] };
+  }
+  if (occurrences.length) {
+    return { ruleId: rule.ruleId, outcome: 'fail', severity: rule.defaultSeverity || 'moderate', occurrences };
+  }
+  return { ruleId: rule.ruleId, outcome: 'pass', severity: 'minor', occurrences: [] };
+}
+
+module.exports = { id, meta, runInPage };

package/src/checks/automatic/aria-allowed-role.js

@@ -0,0 +1,102 @@
+'use strict';
+
+/**
+ * @check aria-allowed-role
+ * @atomic true
+ * @summary Explicit role must be permitted by the ARIA-in-HTML spec for its host element
+ * @standard WCAG 2.2
+ * @sc 4.1.2
+ * @applicability
+ *   Applies to elements with an explicit, valid, non-abstract role, where
+ *   the host element/attribute combination has an asserted permitted-roles
+ *   constraint in the ARIA-in-HTML table (src/core/aria-helpers.js
+ *   ALLOWED_ROLES_BY_ELEMENT).
+ * @expectation
+ *   The explicit role is one of the roles the ARIA-in-HTML specification
+ *   permits for that host element.
+ * @implementation-notes
+ * - Deliberately scoped to elements present in ALLOWED_ROLES_BY_ELEMENT;
+ *   elements without an asserted constraint are treated as "no constraint"
+ *   (not flagged) rather than guessed at — see that table's header comment.
+ * - Not gated on isAccTreeEligible: this is a static markup property.
+ */
+
+const id = 'aria-allowed-role';
+
+const meta = {
+  title: 'Explicit role must be permitted for its host element',
+  description: 'Checks that an explicit role="" attribute is one of the roles the ARIA-in-HTML specification permits for the host element (e.g. role="tab" is not permitted on <nav>).',
+  i18n: {
+    titleKey: 'ariaAllowedRole_title',
+    descriptionKey: 'ariaAllowedRole_description'
+  },
+  helpUrl: null,
+  tags: ['wcag2a', 'wcag412', 'aria', 'structure', 'atomic', 'automatic'],
+  wcagSc: ['4.1.2'],
+  normativeMappings: [
+    { standard: 'WCAG', version: '2.2', requirement: '4.1.2', title: 'Name, Role, Value', conformanceLevel: 'A' }
+  ],
+  defaultSeverity: 'moderate',
+  category: 'robust',
+  type: 'automatic',
+  defaultConfidence: 'high',
+  coverage: { facetsBySc: { '4.1.2': ['aria-role-allowed-for-element'] } }
+};
+
+function runInPage(ctx) {
+  const { document, root, helpers, rule } = ctx;
+  const safeRoot = root || document;
+
+  const ariaHelpers = helpers && helpers.aria ? helpers.aria : null;
+  if (!ariaHelpers) {
+    return { ruleId: rule.ruleId, outcome: 'notApplicable', severity: 'minor', occurrences: [] };
+  }
+
+  const nodes = helpers.queryAllSmart ? helpers.queryAllSmart('[role]', safeRoot) : helpers.queryAll('[role]', safeRoot);
+
+  const occurrences = [];
+  let applicableCount = 0;
+
+  for (const el of nodes) {
+    if (!el || !el.getAttribute) continue;
+
+    const role = ariaHelpers.getExplicitRole(el);
+    if (!role || !ariaHelpers.isValidConcreteRole(role)) continue; // aria-roles-valid's concern
+
+    const info = ariaHelpers.isRoleAllowedOnElement(el, role);
+    if (!info.constrained) continue; // no asserted constraint for this element
+
+    applicableCount += 1;
+
+    if (info.allowed) continue;
+
+    const stableSelector = helpers.buildSelector ? helpers.buildSelector(el) : 'html';
+    const html = helpers.getOuterHtmlSnippet ? helpers.getOuterHtmlSnippet(el) : (el.outerHTML || '');
+    const tag = (el.tagName || '').toLowerCase();
+
+    occurrences.push({
+      selector: stableSelector,
+      html,
+      summary: 'This role is not permitted on this element.',
+      hint: 'Use a role permitted for this element, or change the host element.',
+      i18n: {
+        summaryKey: 'ariaAllowedRole_summary_fail',
+        hintKey: 'ariaAllowedRole_hint_fail',
+        params: { role, element: tag }
+      },
+      data: {
+        details: { reasonCode: 'ARIA_ROLE_NOT_ALLOWED_FOR_ELEMENT', role, element: tag }
+      }
+    });
+  }
+
+  if (applicableCount === 0) {
+    return { ruleId: rule.ruleId, outcome: 'notApplicable', severity: 'minor', occurrences: [] };
+  }
+  if (occurrences.length) {
+    return { ruleId: rule.ruleId, outcome: 'fail', severity: rule.defaultSeverity || 'moderate', occurrences };
+  }
+  return { ruleId: rule.ruleId, outcome: 'pass', severity: 'minor', occurrences: [] };
+}
+
+module.exports = { id, meta, runInPage };

package/src/checks/automatic/aria-braille-equivalent.js

@@ -0,0 +1,139 @@
+'use strict';
+
+/**
+ * @check aria-braille-equivalent
+ * @atomic true
+ * @summary aria-braillelabel/aria-brailleroledescription must not be the only naming mechanism
+ * @standard WCAG 2.2
+ * @sc 4.1.2
+ * @applicability
+ *   Elements with a non-empty `aria-braillelabel` and/or non-empty
+ *   `aria-brailleroledescription` attribute.
+ * @expectation
+ *   Per the ARIA specification, `aria-braillelabel` is a Braille-specific
+ *   SUPPLEMENT to (not a replacement for) the element's regular
+ *   accessible name, and `aria-brailleroledescription` is a supplement
+ *   to `aria-roledescription`. An element must therefore also have:
+ *     - a non-empty accessible name from a non-braille mechanism, if it
+ *       declares `aria-braillelabel`;
+ *     - a non-empty `aria-roledescription`, if it declares
+ *       `aria-brailleroledescription`.
+ *   Using either braille-specific attribute as the ONLY naming mechanism
+ *   leaves non-braille assistive technology (most screen readers, voice
+ *   control, etc.) with no accessible name/role description at all.
+ * @implementation-notes
+ * - `aria-braillelabel`/`aria-brailleroledescription` do not participate
+ *   in the standard accessible-name computation, so
+ *   `helpers.getAccessibleNameInfo` already reflects only the "regular"
+ *   (non-braille) name — no special-casing needed there.
+ */
+
+const id = 'aria-braille-equivalent';
+
+const meta = {
+  title: 'aria-braillelabel/aria-brailleroledescription must have a non-braille equivalent',
+  description:
+    'Checks that elements using aria-braillelabel also have a regular accessible name, and elements using aria-brailleroledescription also have aria-roledescription.',
+  i18n: {
+    titleKey: 'ariaBrailleEquivalent_title',
+    descriptionKey: 'ariaBrailleEquivalent_description'
+  },
+  helpUrl: null,
+  tags: ['wcag2a', 'wcag412', 'aria', 'structure', 'atomic', 'automatic'],
+  wcagSc: ['4.1.2'],
+  normativeMappings: [
+    { standard: 'WCAG', version: '2.2', requirement: '4.1.2', title: 'Name, Role, Value', conformanceLevel: 'A' }
+  ],
+  defaultSeverity: 'serious',
+  category: 'robust',
+  type: 'automatic',
+  defaultConfidence: 'high',
+  coverage: { facetsBySc: { '4.1.2': ['aria-braille-equivalent'] } }
+};
+
+function runInPage(ctx) {
+  const { document, root, helpers, rule } = ctx;
+  const safeRoot = root || document;
+
+  function trim(v) { return (v == null ? '' : String(v)).trim(); }
+
+  function getConservativeSubtreeText(container) {
+    // "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
+    // (this replaced a text-node-only TreeWalker that missed the common
+    // "<a><img alt='...'></a>" logo-link / "<button><img alt='...'></button>"
+    // icon-button pattern).
+    if (helpers.getContentNameInfo) {
+      const info = helpers.getContentNameInfo(container, ctx);
+      return info && info.present ? info.value : '';
+    }
+    const t = (container && container.textContent) ? String(container.textContent) : '';
+    return t.replace(/\s+/g, ' ').trim();
+  }
+
+  const nodes = helpers.queryAllSmart
+    ? helpers.queryAllSmart('[aria-braillelabel], [aria-brailleroledescription]', safeRoot)
+    : helpers.queryAll('[aria-braillelabel], [aria-brailleroledescription]', safeRoot);
+
+  const occurrences = [];
+  let applicableCount = 0;
+
+  for (const el of nodes) {
+    if (!el || !el.getAttribute) continue;
+
+    const brailleLabel = trim(el.getAttribute('aria-braillelabel'));
+    const brailleRoleDesc = trim(el.getAttribute('aria-brailleroledescription'));
+    if (!brailleLabel && !brailleRoleDesc) continue;
+
+    applicableCount += 1;
+
+    const missing = [];
+
+    if (brailleLabel) {
+      const nameInfo = helpers.getAccessibleNameInfo ? helpers.getAccessibleNameInfo(el, ctx) : null;
+      const programmaticName = trim(nameInfo && typeof nameInfo.value === 'string' ? nameInfo.value : '');
+      const name = programmaticName || getConservativeSubtreeText(el);
+      if (!name) missing.push({ attr: 'aria-braillelabel', requires: 'an accessible name' });
+    }
+
+    if (brailleRoleDesc) {
+      const roleDesc = trim(el.getAttribute('aria-roledescription'));
+      if (!roleDesc) missing.push({ attr: 'aria-brailleroledescription', requires: 'aria-roledescription' });
+    }
+
+    if (!missing.length) continue;
+
+    const stableSelector = helpers.buildSelector ? helpers.buildSelector(el) : 'html';
+    const html = helpers.getOuterHtmlSnippet ? helpers.getOuterHtmlSnippet(el) : (el.outerHTML || '');
+    const tag = (el.tagName || '').toLowerCase();
+
+    for (const m of missing) {
+      occurrences.push({
+        selector: stableSelector,
+        html,
+        summary: `This element has ${m.attr} but no ${m.requires}, its non-braille equivalent.`,
+        hint: `${m.attr} is a Braille-specific supplement, not a replacement — also provide ${m.requires}.`,
+        i18n: {
+          summaryKey: 'ariaBrailleEquivalent_summary_fail',
+          hintKey: 'ariaBrailleEquivalent_hint_fail',
+          params: { element: tag, attr: m.attr, requires: m.requires }
+        },
+        data: {
+          details: { reasonCode: 'BRAILLE_ATTR_WITHOUT_EQUIVALENT', attr: m.attr, requires: m.requires }
+        }
+      });
+    }
+  }
+
+  if (applicableCount === 0) {
+    return { ruleId: rule.ruleId, outcome: 'notApplicable', severity: 'minor', occurrences: [] };
+  }
+  if (occurrences.length) {
+    return { ruleId: rule.ruleId, outcome: 'fail', severity: rule.defaultSeverity || 'serious', occurrences };
+  }
+  return { ruleId: rule.ruleId, outcome: 'pass', severity: 'minor', occurrences: [] };
+}
+
+module.exports = { id, meta, runInPage };