@surea11y/core 1.0.0

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

@@ -0,0 +1,274 @@
+'use strict';
+
+/**
+ * @check aria-required-children
+ * @atomic true
+ * @summary Container roles that require specific owned elements must contain at least one
+ * @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 container roles with a documented "required owned
+ *   elements" entry (list, listbox, menu, menubar, radiogroup, rowgroup,
+ *   table, grid, treegrid, tablist, tree, row).
+ * @expectation
+ *   At least one descendant, or one aria-owns-referenced element, has one
+ *   of the acceptable owned roles for that container role.
+ * @implementation-notes
+ * - Deliberately scoped to REQUIRED_OWNED_ROLES in src/core/aria-helpers.js
+ *   (see that file's header for the conservative-scope rationale).
+ * - Owned-role matching uses ariaHelpers.getContainmentRole, which combines
+ *   explicit role="" attributes with a small, curated native-HTML-tag
+ *   mapping (li, option, tr, td, th, ...). This avoids false positives on
+ *   plain native markup under an explicitly-asserted container role, e.g.
+ *   <ul role="list"><li>...</li></ul> (a common CSS-reset workaround where
+ *   only the container gets an explicit role).
+ * - Only one qualifying descendant/owned element is required (per
+ *   WAI-ARIA "required owned elements": any one acceptable role satisfies
+ *   the requirement); the full subtree is scanned without excluding nested
+ *   containers with their own differing role, favoring simplicity — this
+ *   can only under-report (recall), never over-report (fail integrity).
+ * - Gated on isAccTreeEligible for the container itself: unlike this
+ *   file's sibling attribute/role-validity checks (e.g. aria-roles-valid),
+ *   "does this container currently have a required child" is not a fact
+ *   that stays fixed once written — it is routinely filled in by the same
+ *   script/interaction that reveals the container (a closed flyout menu
+ *   or <dialog> populated on open). Flagging it while the container isn't
+ *   currently exposed to the accessibility tree is a false positive; such
+ *   a container is skipped entirely (does not count toward applicability),
+ *   matching the pattern already used by this engine's accessible-name
+ *   rules (svg-text-alternative-present, iframe-name-present, ...).
+ * - Also honors the WAI-ARIA spec's own explicit escape hatch: "When a
+ *   widget is missing required owned elements due to script execution or
+ *   loading, authors MUST mark a containing element with aria-busy equal
+ *   to true." A container carrying aria-busy="true" is skipped the same
+ *   way — only the exact string "true" counts (absent/"false" do not),
+ *   matching a widely-used reference engine's own aria-required-children
+ *   behavior.
+ * - Descendant search tries a fast native querySelectorAll(CANDIDATE_
+ *   SELECTOR) first (covers the light-DOM-only common case with no added
+ *   cost); only when that finds nothing AND the container has a <slot>
+ *   anywhere in its subtree does it fall back to a composed-tree walk that
+ *   expands <slot> elements via assignedElements({flatten:true}) — plain
+ *   querySelectorAll only sees a <slot>'s unrendered fallback content, never
+ *   what's actually distributed into it. Deliberately scoped to slot
+ *   expansion only, not a general "also descend into any nested custom
+ *   element's own shadow root" walk — no confirmed real-world case needs
+ *   that yet.
+ */
+
+const id = 'aria-required-children';
+
+const meta = {
+  title: 'Container roles must own at least one required child role',
+  description: 'Checks that container roles with a documented "required owned elements" entry (list, listbox, menu, radiogroup, table, grid, tablist, tree, row, ...) contain at least one descendant or aria-owns-referenced element with an acceptable owned role.',
+  i18n: {
+    titleKey: 'ariaRequiredChildren_title',
+    descriptionKey: 'ariaRequiredChildren_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-required-owned-children'] } }
+};
+
+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';
+  }
+
+  // Candidate selector for descendant scanning: explicit role attributes,
+  // plus every native tag ariaHelpers.getContainmentRole() recognizes
+  // (kept in sync with aria-helpers.js NATIVE_CONTAINMENT_ROLE_BY_ELEMENT).
+  // Declared inside runInPage — see scripts/build-core.js header
+  // ("runInPage MUST be self-contained").
+  const CANDIDATE_SELECTOR = '[role], li, option, tr, td, th, thead, tbody, tfoot, ul, ol, table, select, input[type="radio"]';
+
+  const nodes = helpers.queryAllSmart ? helpers.queryAllSmart('[role]', safeRoot) : helpers.queryAll('[role]', safeRoot);
+
+  const occurrences = [];
+  let applicableCount = 0;
+
+  // Composed-tree descendant walk: el.querySelectorAll only sees the raw
+  // light-DOM subtree, so a container whose real owned children are
+  // distributed via <slot> (e.g. a shadow-DOM role="list" wrapping
+  // <slot></slot>, with the actual role="listitem" elements living in the
+  // light DOM and projected in) would never find them there — same class
+  // of bug as aria-required-parent's ancestor search, just in the opposite
+  // (descendant) direction. Found via Adobe Spectrum Web Components'
+  // sp-sidenav-item: its shadow root's role="list" div owns its listitems
+  // only through slot projection.
+  //
+  // Deliberately scoped to slot expansion only — does NOT separately
+  // descend into an unrelated nested custom element's own shadow root
+  // (e.g. a <my-widget> child with no <slot> involvement at all). That's a
+  // qualitatively different question (does an arbitrary component's own
+  // internal structure count as this container's "owned children"?) with
+  // no confirmed real-world case driving it yet; slot projection is the
+  // shape actually observed.
+  function collectComposedDescendants(node, out, seen, limit) {
+    if (!node || !node.children) return;
+    for (const child of Array.from(node.children)) {
+      if (out.length >= limit) return;
+      if (seen.has(child)) continue;
+
+      if ((child.tagName || '').toLowerCase() === 'slot' && typeof child.assignedElements === 'function') {
+        let assigned = [];
+        try {
+          assigned = child.assignedElements({ flatten: true }) || [];
+        } catch {
+          assigned = [];
+        }
+        for (const a of assigned) {
+          if (seen.has(a)) continue;
+          seen.add(a);
+          out.push(a);
+          if (out.length >= limit) return;
+          collectComposedDescendants(a, out, seen, limit);
+          if (out.length >= limit) return;
+        }
+        continue; // a <slot>'s own childNodes are unrendered fallback content once something is assigned
+      }
+
+      seen.add(child);
+      out.push(child);
+      collectComposedDescendants(child, out, seen, limit);
+    }
+  }
+
+  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 requiredOwned = ariaHelpers.getRequiredOwnedRoles(role);
+    if (!requiredOwned || !requiredOwned.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 ownedSet = new Set(requiredOwned);
+    let found = false;
+
+    // Fast path first: native querySelectorAll over the curated candidate
+    // selector, exactly as before this fix — covers the overwhelming
+    // majority of containers (no shadow DOM involved at all) with zero
+    // added cost.
+    let descendants = [];
+    try {
+      descendants = el.querySelectorAll(CANDIDATE_SELECTOR);
+    } catch {
+      descendants = [];
+    }
+    for (const cand of descendants) {
+      const candRole = ariaHelpers.getContainmentRole(cand);
+      if (candRole && ownedSet.has(candRole)) {
+        found = true;
+        break;
+      }
+    }
+
+    // Slow path only when the fast path found nothing AND there's an actual
+    // <slot> somewhere in the subtree to expand — bounds the extra cost to
+    // exactly the containers that could possibly need it.
+    if (!found) {
+      let hasSlot = false;
+      try {
+        hasSlot = !!el.querySelector('slot');
+      } catch {
+        hasSlot = false;
+      }
+      if (hasSlot) {
+        const composed = [];
+        try {
+          collectComposedDescendants(el, composed, new Set(), 5000);
+        } catch {
+          // fall through with whatever was collected before the error
+        }
+        for (const cand of composed) {
+          if (!cand || !cand.getAttribute) continue;
+          const candRole = ariaHelpers.getContainmentRole(cand);
+          if (candRole && ownedSet.has(candRole)) {
+            found = true;
+            break;
+          }
+        }
+      }
+    }
+
+    if (!found) {
+      const ownsAttr = el.getAttribute('aria-owns');
+      if (ownsAttr && helpers.resolveIdRefs) {
+        const resolved = helpers.resolveIdRefs(ownsAttr, ctx, { maxRefs: 50 });
+        for (const ownedEl of resolved.refs || []) {
+          const candRole = ariaHelpers.getContainmentRole(ownedEl);
+          if (candRole && ownedSet.has(candRole)) {
+            found = true;
+            break;
+          }
+        }
+      }
+    }
+
+    if (found) continue;
+
+    const stableSelector = helpers.buildSelector ? helpers.buildSelector(el) : 'html';
+    const html = helpers.getOuterHtmlSnippet ? helpers.getOuterHtmlSnippet(el) : (el.outerHTML || '');
+
+    occurrences.push({
+      selector: stableSelector,
+      html,
+      summary: 'This container role has no owned child with a required role.',
+      hint: 'Add a descendant (or aria-owns-referenced element) with one of the required owned roles.',
+      i18n: {
+        summaryKey: 'ariaRequiredChildren_summary_fail',
+        hintKey: 'ariaRequiredChildren_hint_fail',
+        params: { role, requiredRoles: requiredOwned.join(', ') }
+      },
+      data: {
+        details: { reasonCode: 'ARIA_REQUIRED_CHILD_MISSING', role, requiredOwnedRoles: 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-parent.js

@@ -0,0 +1,222 @@
+'use strict';
+
+/**
+ * @check aria-required-parent
+ * @atomic true
+ * @summary Roles that require a specific ancestor/owner context role must have one
+ * @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 roles with a documented, non-empty "required context
+ *   role" entry (listitem, option, menuitem, menuitemcheckbox,
+ *   menuitemradio, tab, treeitem, row, cell, gridcell, columnheader,
+ *   rowheader, rowgroup).
+ * @expectation
+ *   The element has an ancestor (DOM containment) or owner (via that
+ *   ancestor/owner's aria-owns) whose effective role is one of the
+ *   acceptable context roles for this element's role.
+ * @implementation-notes
+ * - Deliberately scoped to REQUIRED_CONTEXT_ROLE in src/core/aria-helpers.js
+ *   (see that file's header for the conservative-scope rationale); roles
+ *   with an explicitly empty entry (e.g. tabpanel) are left unconstrained.
+ * - Context-role matching uses ariaHelpers.getContainmentRole, which
+ *   combines explicit role="" attributes with a small, curated native-HTML-
+ *   tag mapping, so a native ancestor (e.g. <table>/<tr>/<select>) without
+ *   an explicit role still satisfies the requirement.
+ * - Ancestor search walks the flat/composed tree (helpers.composedParent:
+ *   assignedSlot, then parentNode, then shadow host), not raw parentElement,
+ *   so a slotted element's real rendered ancestor context (e.g. a shadow-
+ *   tree role="list" wrapper around its <slot>) is found even though it's
+ *   invisible to plain DOM containment; aria-owns is checked as a second,
+ *   independent path via a reverse lookup over the search root.
+ * - Gated on isAccTreeEligible for the element itself. The ancestor-role
+ *   walk itself doesn't care about visibility (a hidden ancestor's role is
+ *   still found by plain DOM/composed-tree containment, so a genuinely
+ *   correctly-nested-but-hidden widget was never at risk here) — the
+ *   remaining false-positive shape is an element whose required ancestor
+ *   context doesn't exist YET because it (and its wrapping context) are
+ *   assembled together at reveal time (e.g. a portal-rendered item staged
+ *   outside the live menu until opened). Same category of fix as
+ *   aria-required-children/aria-prohibited-children, applied for
+ *   consistency; an element that isn't currently exposed to the
+ *   accessibility tree is skipped (notApplicable), not failed.
+ */
+
+const id = 'aria-required-parent';
+
+const meta = {
+  title: 'Roles requiring a specific context role must be in that context',
+  description: 'Checks that roles with a documented "required context role" entry (listitem, option, tab, treeitem, row, cell, ...) have an ancestor or aria-owns owner with an acceptable context role.',
+  i18n: {
+    titleKey: 'ariaRequiredParent_title',
+    descriptionKey: 'ariaRequiredParent_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-required-context-parent'] } }
+};
+
+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;
+    }
+  }
+
+  // Roles that may host a nested listitem/treeitem group without breaking
+  // the required-context chain (verified against a widely-used reference
+  // engine's own getMissingContext, which special-cases exactly these two
+  // roles via its ownGroupRoles option).
+  const GROUP_TRANSPARENT_FOR_ROLES = new Set(['listitem', 'treeitem']);
+
+  // A real ancestor role — not "no role at all" and not the two roles that
+  // strip an element from the accessibility tree's parent/child chain
+  // entirely (presentation/none) — stops the search, matching that reference
+  // engine's getMissingContext. This is stricter than "any ancestor with the right
+  // role anywhere up the tree": the required-context relationship is about
+  // the accessibility tree's actual PARENT, so an intervening ancestor with
+  // its OWN distinct real role (e.g. a plain <li>'s native "listitem" role)
+  // blocks the search even if a further-up ancestor has the correct role.
+  // Found via a real page — Le Monde's review-carousel tablist, where each
+  // <button role="tab"> sits inside a plain <li> (native listitem) inside
+  // <ul role="tablist">: that reference engine correctly fails this (the tablist is never the
+  // tab's accessible-tree parent, listitem is), which the old "walk every
+  // ancestor" version here missed entirely.
+  function getRealContextRole(el) {
+    const role = ariaHelpers.getContainmentRole(el);
+    if (!role || role === 'presentation' || role === 'none') return '';
+    return role;
+  }
+
+  // Flat-tree ancestor walk (ctx.helpers.composedParent — assignedSlot wins
+  // over parentNode, then shadow host). A slotted light-DOM element's real
+  // rendered ancestor is whatever the shadow tree wraps its <slot> in (e.g.
+  // a role="list" container), not its own light-DOM parentElement — found
+  // via Adobe Spectrum Web Components' <sp-sidenav-item role="listitem">,
+  // distributed via slot="descendant" into its parent's shadow root, which
+  // wraps that slot in a <div role="list">. composedParent can return a
+  // non-Element node (a ShadowRoot, nodeType 11) when climbing out of a
+  // shadow tree that has no further light-DOM parent — skip those and keep
+  // climbing rather than treating them as a (roleless) context.
+  const getComposedParent = helpers && typeof helpers.composedParent === 'function'
+    ? helpers.composedParent
+    : function (n) { return n && n.parentElement ? n.parentElement : null; };
+
+  function hasAcceptableAncestorContext(el, acceptableRoles, ownRole) {
+    const allowsGroup = acceptableRoles.has('group');
+    let cur = getComposedParent(el);
+    let guard = 0;
+    while (cur && guard++ < 200) {
+      if (cur.nodeType !== 1) {
+        cur = getComposedParent(cur);
+        continue;
+      }
+      const role = getRealContextRole(cur);
+      if (!role) {
+        cur = getComposedParent(cur);
+        continue;
+      }
+      if (role === 'group' && allowsGroup && GROUP_TRANSPARENT_FOR_ROLES.has(ownRole)) {
+        cur = getComposedParent(cur);
+        continue;
+      }
+      return acceptableRoles.has(role);
+    }
+    return false;
+  }
+
+  function hasAcceptableOwnerContext(el, acceptableRoles) {
+    const elId = el.getAttribute('id');
+    const idTok = elId && String(elId).trim();
+    if (!idTok) return false;
+
+    const owners = helpers.queryAllSmart ? helpers.queryAllSmart('[aria-owns]', safeRoot) : helpers.queryAll('[aria-owns]', safeRoot);
+    for (const owner of owners) {
+      if (!owner || !owner.getAttribute) continue;
+      const ownsAttr = owner.getAttribute('aria-owns') || '';
+      const tokens = ownsAttr.split(/\s+/).filter(Boolean);
+      if (tokens.indexOf(idTok) === -1) continue;
+
+      const role = ariaHelpers.getContainmentRole(owner);
+      if (role && acceptableRoles.has(role)) return true;
+    }
+    return false;
+  }
+
+  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 requiredContext = ariaHelpers.getRequiredContextRoles(role);
+    if (!requiredContext || !requiredContext.length) continue; // no entry, or explicitly unconstrained
+
+    if (!isEligibleAcc(el)) continue; // not currently exposed to the accessibility tree
+
+    applicableCount += 1;
+
+    const acceptableRoles = new Set(requiredContext);
+    const hasContext =
+      hasAcceptableAncestorContext(el, acceptableRoles, role) ||
+      hasAcceptableOwnerContext(el, acceptableRoles);
+
+    if (hasContext) continue;
+
+    const stableSelector = helpers.buildSelector ? helpers.buildSelector(el) : 'html';
+    const html = helpers.getOuterHtmlSnippet ? helpers.getOuterHtmlSnippet(el) : (el.outerHTML || '');
+
+    occurrences.push({
+      selector: stableSelector,
+      html,
+      summary: 'This role requires a specific ancestor/owner context role, which was not found.',
+      hint: 'Place this element inside (or aria-owns-reference it from) an element with an acceptable context role.',
+      i18n: {
+        summaryKey: 'ariaRequiredParent_summary_fail',
+        hintKey: 'ariaRequiredParent_hint_fail',
+        params: { role, requiredRoles: requiredContext.join(', ') }
+      },
+      data: {
+        details: { reasonCode: 'ARIA_REQUIRED_PARENT_MISSING', role, requiredContextRoles: requiredContext }
+      }
+    });
+  }
+
+  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 };