@surea11y/core 1.0.0

package/src/checks/automatic/aria-prohibited-children.js

@@ -0,0 +1,265 @@
+'use strict';
+
+/**
+ * @check aria-prohibited-children
+ * @atomic true
+ * @summary Container roles must not own an accessible-tree child with a disallowed role
+ * @standard WCAG 2.2
+ * @sc 4.1.2
+ * @applicability
+ *   Applies to elements with an explicit, valid role that is one of the
+ *   container roles with a documented "required owned elements" entry
+ *   (the same REQUIRED_OWNED_ROLES table aria-required-children
+ *   uses — see src/core/aria-helpers.js).
+ * @expectation
+ *   Every accessible-tree-owned descendant of the container (after
+ *   pruning role="none"/"presentation" elements and any "group"/
+ *   "rowgroup" wrapper whose role is itself one of the required roles —
+ *   both are structurally transparent, same as WAI-ARIA's own
+ *   accessibility-tree construction) has a role from that same required-
+ *   owned set. Nothing else is a structurally valid direct child of a
+ *   composite/container role.
+ * @implementation-notes
+ * - A distinct atomic decision from aria-required-children (see
+ *   that rule): "does at least one required child exist" vs "is every
+ *   owned child one of the allowed roles." A widely-used reference engine
+ *   bundles both under one check (`aria-required-children`); this repo's
+ *   "one rule = one normative decision" principle splits them, matching
+ *   the established pattern elsewhere of surea11y rules mapping
+ *   many-to-one against a single check in that reference engine.
+ * - The "allowed owned roles" set is exactly REQUIRED_OWNED_ROLES — not
+ *   a separately authored, broader list. Verified directly against a
+ *   widely-used reference engine's own ariaRequiredChildren/getOwnedRoles
+ *   algorithm: an owned element is only considered allowed if its role is
+ *   literally in the container's required set; that engine does not
+ *   define a superset "allowed but not required" list for this purpose.
+ *   Found and verified via a real page (Red Cross's homepage: a
+ *   <nav role="region"> nested inside a <ul role="menubar"> through a
+ *   role="none" <li> wrapper — a real violation that reference engine
+ *   caught that aria-required-children's own scope (documented
+ *   there as "can only under-report, never over-report") does not).
+ * - Widened 2026-07-21 to also flag a ROLELESS descendant that has any
+ *   global WAI-ARIA attribute or is focusable, matching a widely-used
+ *   reference engine's own `getOwnedRoles` exactly (verified directly
+ *   against its source: `hasGlobalAriaOrFocusable =
+ *   !!globalAriaAttr || _isFocusable(vNode)` — such a descendant is
+ *   pushed as an owned entry with `role: null`, which can never match a
+ *   container's required-owned-roles set, so it's always "unallowed").
+ *   Previously left out as riskier to replicate — re-evaluated given
+ *   direct access to that engine's exact algorithm (not a guess) plus this
+ *   engine's own already-existing, shared `helpers.getFocusableInfo` for
+ *   the focusability half. Both signals (global-attribute presence,
+ *   focusability) are static, declarative markup facts with no live-DOM/
+ *   hydration risk, unlike e.g. `aria-checked-state-mismatch`'s DOM-
+ *   property comparison.
+ * - Recursion stops at the first non-transparent role boundary, same as
+ *   that reference engine: a nested container with its own real role (e.g. a
+ *   <div role="listbox"> inside a menubar) is evaluated as ITS OWN
+ *   owned-role entry against the outer container (and, separately, gets
+ *   its own applicability pass as a container in the same rule run) —
+ *   its descendants are never misattributed to the outer container.
+ * - Gated on isAccTreeEligible for the container itself, matching the fix
+ *   applied to aria-required-children (see that rule's header): the
+ *   original "not gated" note here just cited that rule's reasoning
+ *   without re-deriving it, and that reasoning turned out not to hold —
+ *   a closed dialog/flyout menu populated on open is a real false-positive
+ *   shape. In this rule specifically the descendant-level eligibility gate
+ *   already made the container-level gate redundant for correctness (an
+ *   ineligible container has no eligible descendants either, so `owned`
+ *   ends up empty and nothing fails) — but skipping the container up front
+ *   reports `notApplicable` instead of a vacuous `pass`, which is the more
+ *   accurate outcome for a container that isn't currently exposed at all,
+ *   and avoids walking a subtree whose result is already known.
+ * - No aria-busy exemption here (unlike aria-required-children): the
+ *   WAI-ARIA spec's aria-busy escape hatch is specifically about a
+ *   container missing its required owned elements while loading, not
+ *   about a container that already has extra/disallowed owned elements —
+ *   that scenario isn't this rule's concern.
+ */
+
+const id = 'aria-prohibited-children';
+
+const meta = {
+  title: 'Container roles must not own a child with a disallowed role',
+  description: 'Checks that every accessible-tree-owned child of a container role (list, listbox, menu, menubar, radiogroup, rowgroup, table, grid, treegrid, tablist, tree, row) has one of that role\'s allowed owned roles — the same set as its required owned roles.',
+  i18n: {
+    titleKey: 'ariaProhibitedChildren_title',
+    descriptionKey: 'ariaProhibitedChildren_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-role-owned-children-allowed'] } }
+};
+
+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: [] };
+  }
+
+  function isEligibleAcc(el) {
+    const fn = helpers && typeof helpers.isAccTreeEligible === 'function' ? helpers.isAccTreeEligible : null;
+    if (!fn) return true;
+    try {
+      const r = fn(el, ctx);
+      if (typeof r === 'boolean') return r;
+      return !!(r && r.eligible);
+    } catch {
+      return true;
+    }
+  }
+
+  // The WAI-ARIA "Global States and Properties" set (same list as
+  // aria-allowed-attr.js's GLOBAL_ATTRS — duplicated, not imported, since
+  // runInPage must be self-contained per scripts/build-core.js). A
+  // roleless descendant carrying any of these is a real accessible-tree
+  // node a widely-used reference engine's getOwnedRoles also flags, not a transparent wrapper.
+  const GLOBAL_ARIA_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'
+  ];
+
+  function getGlobalAriaAttr(el) {
+    for (const attr of GLOBAL_ARIA_ATTRS) {
+      const v = el.getAttribute ? el.getAttribute(attr) : null;
+      if (v != null) return attr;
+    }
+    return null;
+  }
+
+  const MAX_DEPTH = 40;
+
+  // Collects this container's owned-role entries, pruning role="none"/
+  // "presentation" and required-matching "group"/"rowgroup" wrappers as
+  // transparent (recursing through them), and stopping at the first
+  // non-transparent role boundary otherwise — see header comment. A
+  // roleless descendant is ALSO a non-transparent boundary (an owned
+  // entry with role: null, which can never satisfy a required-role set)
+  // when it carries a global aria-* attribute or is focusable — matches
+  // a widely-used reference engine's own getOwnedRoles exactly (see header comment).
+  function collectOwnedRoles(el, requiredSet, out, depth) {
+    if (depth > MAX_DEPTH) return;
+    const kids = el.children ? Array.prototype.slice.call(el.children) : [];
+    for (const kid of kids) {
+      if (!kid || kid.nodeType !== 1) continue;
+      if (!isEligibleAcc(kid)) continue;
+
+      const kidRole = ariaHelpers.getExplicitRole(kid);
+      const isPresentational = kidRole === 'presentation' || kidRole === 'none';
+      const isTransparentGroup = (kidRole === 'group' || kidRole === 'rowgroup') && requiredSet.has(kidRole);
+
+      if (!kidRole && !isPresentational) {
+        const globalAttr = getGlobalAriaAttr(kid);
+        let focusable = false;
+        try {
+          const fi = helpers && typeof helpers.getFocusableInfo === 'function' ? helpers.getFocusableInfo(kid, ctx) : null;
+          focusable = !!(fi && fi.focusable);
+        } catch {
+          focusable = false;
+        }
+        if (globalAttr || focusable) {
+          out.push({ el: kid, role: null, attr: globalAttr || 'tabindex' });
+          continue; // real accessible-tree node: stop here, do not recurse further
+        }
+      }
+
+      if (!kidRole || isPresentational || isTransparentGroup) {
+        collectOwnedRoles(kid, requiredSet, out, depth + 1);
+        continue;
+      }
+
+      if (!ariaHelpers.isValidConcreteRole(kidRole)) continue; // aria-roles-valid's concern
+
+      out.push({ el: kid, role: kidRole });
+      // Stop here: a real, non-transparent role is its own semantic unit.
+    }
+  }
+
+  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;
+
+    const requiredOwned = ariaHelpers.getRequiredOwnedRoles(role);
+    if (!requiredOwned || !requiredOwned.length) continue;
+
+    if (!isEligibleAcc(el)) continue; // not currently exposed to the accessibility tree
+
+    applicableCount += 1;
+
+    const requiredSet = new Set(requiredOwned);
+    const owned = [];
+    collectOwnedRoles(el, requiredSet, owned, 0);
+
+    for (const entry of owned) {
+      if (entry.role && requiredSet.has(entry.role)) continue;
+
+      const stableSelector = helpers.buildSelector ? helpers.buildSelector(entry.el) : 'html';
+      const html = helpers.getOuterHtmlSnippet ? helpers.getOuterHtmlSnippet(entry.el) : (entry.el.outerHTML || '');
+      const containerSelector = helpers.buildSelector ? helpers.buildSelector(el) : 'html';
+
+      const isRoleless = !entry.role;
+      const summary = isRoleless
+        ? `This element has no explicit role but carries ${entry.attr}, making it a real accessible-tree node that is not an allowed owned child of the enclosing role="${role}" container.`
+        : `This element has role="${entry.role}", which is not an allowed owned child of the enclosing role="${role}" container.`;
+      const hint = isRoleless
+        ? `Remove ${entry.attr} (or the role="${role}" container ownership), or give this element role="presentation"/"none" if it isn't meant to be its own accessible-tree node.`
+        : `Remove or change this role so it matches one of the container's allowed owned roles (${requiredOwned.join(', ')}), or move this element outside the ${role} container.`;
+
+      occurrences.push({
+        selector: stableSelector,
+        html,
+        summary,
+        hint,
+        i18n: {
+          summaryKey: isRoleless ? 'ariaProhibitedChildren_summary_fail_roleless' : 'ariaProhibitedChildren_summary_fail',
+          hintKey: isRoleless ? 'ariaProhibitedChildren_hint_fail_roleless' : 'ariaProhibitedChildren_hint_fail',
+          params: isRoleless
+            ? { attr: entry.attr, containerRole: role }
+            : { childRole: entry.role, containerRole: role, allowedRoles: requiredOwned.join(', ') }
+        },
+        data: {
+          details: {
+            reasonCode: isRoleless ? 'ARIA_PROHIBITED_CHILD_ROLELESS' : 'ARIA_PROHIBITED_CHILD',
+            childRole: entry.role,
+            attr: entry.attr,
+            containerRole: role,
+            containerSelector,
+            allowedOwnedRoles: requiredOwned
+          }
+        }
+      });
+    }
+  }
+
+  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-required-attr.js

@@ -0,0 +1,154 @@
+'use strict';
+
+/**
+ * @check aria-required-attr
+ * @atomic true
+ * @summary Roles with an unambiguous required state/property must carry it
+ * @standard WCAG 2.2
+ * @sc 4.1.2
+ * @applicability
+ *   Applies to elements with an explicit, valid, non-abstract role that is
+ *   also one of the small set of roles with a documented, context-
+ *   independent required state/property (checkbox, combobox, heading,
+ *   menuitemcheckbox, menuitemradio, meter, radio, scrollbar, slider,
+ *   switch).
+ * @expectation
+ *   Every required aria-* attribute for that role is present (and non-empty).
+ * @implementation-notes
+ * - Deliberately scoped to REQUIRED_PROPS_BY_ROLE in src/core/aria-helpers.js,
+ *   which only lists a required property when the spec is unambiguous and
+ *   context-independent — see that file's header for the rationale.
+ * - Widened 2026-07-21 to add `meter` (`aria-valuenow`), verified against
+ *   a widely-used reference engine's own `requiredAttrs` table. Deliberately
+ *   did NOT add two other entries from that same table: `progressbar`'s
+ *   `aria-valuenow` (a legitimately indeterminate progressbar omits it —
+ *   that engine itself excludes progressbar from its own table for this reason)
+ *   and `combobox`'s `aria-controls` (confirmed via MDN's combobox role
+ *   page to be conditional — only required once the popup is actually
+ *   displayed, not unconditionally). See src/core/aria-helpers.js's
+ *   REQUIRED_PROPS_BY_ROLE comment for the full reasoning.
+ * - Gated on isAccTreeEligible for the element itself: unlike a syntax-
+ *   level check (attribute name/value validity), "does this element
+ *   currently carry its required state attribute" is not fixed once
+ *   written — checkbox/switch/radio's aria-checked and slider/scrollbar's
+ *   aria-valuenow are exactly the kind of live-widget-state attribute
+ *   component libraries set during hydration/mount, at the same moment
+ *   the element becomes exposed. Same false-positive shape as
+ *   aria-required-children; an element that isn't currently exposed to
+ *   the accessibility tree is skipped (notApplicable), not failed.
+ * - Also treats aria-busy="true" as an exemption, same as
+ *   aria-required-children. Note this is an extension by analogy, not a
+ *   literal reading of the spec: WAI-ARIA's aria-busy carve-out text names
+ *   "required owned elements" specifically, not required state attributes.
+ *   The underlying rationale (a widget mid-initialization shouldn't be
+ *   flagged for not yet reflecting state the same initialization step is
+ *   about to set) applies equally here, so the exemption is extended by
+ *   analogy rather than by explicit spec text.
+ */
+
+const id = 'aria-required-attr';
+
+const meta = {
+  title: 'Roles with a required ARIA state/property must carry it',
+  description: 'Checks that elements with an explicit role carry every unambiguous, context-independent required aria-* state/property for that role (e.g. role="checkbox" must have aria-checked).',
+  i18n: {
+    titleKey: 'ariaRequiredAttr_title',
+    descriptionKey: 'ariaRequiredAttr_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-attr-required-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: [] };
+  }
+
+  function isEligibleAcc(el) {
+    const fn = helpers && typeof helpers.isAccTreeEligible === 'function' ? helpers.isAccTreeEligible : null;
+    if (!fn) return true;
+    try {
+      const r = fn(el, ctx);
+      if (typeof r === 'boolean') return r;
+      return !!(r && r.eligible);
+    } catch {
+      return true;
+    }
+  }
+
+  function isMarkedBusy(el) {
+    const v = el.getAttribute('aria-busy');
+    return v != null && String(v).trim().toLowerCase() === 'true';
+  }
+
+  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 required = ariaHelpers.getRequiredAttrsForRole(role);
+    if (!required.length) continue;
+
+    if (!isEligibleAcc(el)) continue; // not currently exposed to the accessibility tree
+    if (isMarkedBusy(el)) continue; // author has signaled transient incompleteness per WAI-ARIA
+
+    applicableCount += 1;
+
+    const missing = [];
+    for (const attr of required) {
+      const v = el.getAttribute(attr);
+      if (v == null || String(v).trim() === '') missing.push(attr);
+    }
+
+    if (!missing.length) continue;
+
+    const stableSelector = helpers.buildSelector ? helpers.buildSelector(el) : 'html';
+    const html = helpers.getOuterHtmlSnippet ? helpers.getOuterHtmlSnippet(el) : (el.outerHTML || '');
+
+    for (const attr of missing) {
+      occurrences.push({
+        selector: stableSelector,
+        html,
+        summary: 'This attribute is required for this element’s role, but is missing.',
+        hint: 'Add this attribute with a valid value for this role.',
+        i18n: {
+          summaryKey: 'ariaRequiredAttr_summary_fail',
+          hintKey: 'ariaRequiredAttr_hint_fail',
+          params: { attr, role }
+        },
+        data: {
+          details: { reasonCode: 'ARIA_ATTR_REQUIRED_MISSING', attr, 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 || 'serious', occurrences };
+  }
+  return { ruleId: rule.ruleId, outcome: 'pass', severity: 'minor', occurrences: [] };
+}
+
+module.exports = { id, meta, runInPage };