@surea11y/core 1.0.0

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

@@ -0,0 +1,110 @@
+'use strict';
+
+/**
+ * @check aria-conditional-attr
+ * @atomic true
+ * @summary aria-errormessage is only exposed when aria-invalid is not false/absent
+ * @standard WCAG 2.2
+ * @sc 4.1.2
+ * @applicability
+ *   Elements with a non-empty `aria-errormessage` attribute.
+ * @expectation
+ *   Per the ARIA specification, `aria-errormessage` is only exposed to
+ *   assistive technology when `aria-invalid` is present with a value
+ *   other than `"false"` (i.e. `"true"`, `"grammar"`, or `"spelling"`).
+ *   An element with `aria-errormessage` but `aria-invalid` absent or
+ *   `"false"` silently drops the error message from the accessibility
+ *   tree — authors almost always intend it to be exposed.
+ * @implementation-notes
+ * - This is deliberately narrow: a widely-used reference engine's own
+ *   `aria-conditional-attr` rule covers a broader table of attribute/condition
+ *   pairs. This rule implements only the one pairing (`aria-errormessage` /
+ *   `aria-invalid`) that is unambiguous and explicitly stated in the
+ *   ARIA spec, to keep `fail` high-confidence — matches this repo's
+ *   established pattern (see `aria-required-attr`/`aria-prohibited-attr`
+ *   for the same "narrower than that reference engine, but zero false positives"
+ *   trade-off).
+ * - Does not check whether the `aria-errormessage` ID reference itself
+ *   resolves to an existing element — that is `aria-valid-attr-value`'s
+ *   concern, not this rule's.
+ */
+
+const id = 'aria-conditional-attr';
+
+const meta = {
+  title: 'aria-errormessage requires aria-invalid to be set to a non-false value',
+  description:
+    'Checks that elements with aria-errormessage also have aria-invalid set to "true", "grammar", or "spelling" — otherwise the error message is dropped from the accessibility tree.',
+  i18n: {
+    titleKey: 'ariaConditionalAttr_title',
+    descriptionKey: 'ariaConditionalAttr_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-conditional-attr'] } }
+};
+
+function runInPage(ctx) {
+  const { document, root, helpers, rule } = ctx;
+  const safeRoot = root || document;
+
+  function trim(v) { return (v == null ? '' : String(v)).trim(); }
+
+  const TRUTHY_INVALID_VALUES = new Set(['true', 'grammar', 'spelling']);
+
+  const nodes = helpers.queryAllSmart
+    ? helpers.queryAllSmart('[aria-errormessage]', safeRoot)
+    : helpers.queryAll('[aria-errormessage]', safeRoot);
+
+  const occurrences = [];
+  let applicableCount = 0;
+
+  for (const el of nodes) {
+    if (!el || !el.getAttribute) continue;
+
+    const errorMessageRef = trim(el.getAttribute('aria-errormessage'));
+    if (!errorMessageRef) continue;
+
+    applicableCount += 1;
+
+    const invalidValue = trim(el.getAttribute('aria-invalid')).toLowerCase();
+    if (TRUTHY_INVALID_VALUES.has(invalidValue)) 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 element has aria-errormessage but aria-invalid is missing or "false", so the error message is not exposed.',
+      hint: 'Set aria-invalid to "true" (or "grammar"/"spelling") whenever aria-errormessage should be exposed to assistive technology.',
+      i18n: {
+        summaryKey: 'ariaConditionalAttr_summary_fail',
+        hintKey: 'ariaConditionalAttr_hint_fail',
+        params: { element: tag, ariaInvalid: invalidValue || '(absent)' }
+      },
+      data: {
+        details: { reasonCode: 'ARIA_ERRORMESSAGE_WITHOUT_TRUTHY_INVALID', ariaInvalid: invalidValue }
+      }
+    });
+  }
+
+  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 };

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

@@ -0,0 +1,106 @@
+'use strict';
+
+/**
+ * @check aria-deprecated-role
+ * @atomic true
+ * @summary An explicit role attribute must not use a deprecated or author-prohibited ARIA role
+ * @standard WCAG 2.2
+ * @sc 4.1.2
+ * @applicability
+ *   Applies to any element whose role attribute's first (used) token is a
+ *   valid, non-abstract ARIA role that authors must never explicitly
+ *   declare — either because WAI-ARIA has deprecated it (e.g. "directory",
+ *   superseded by role="list") or because it's reserved for user-agent-
+ *   internal use only, not a spec deprecation but the same "valid token,
+ *   prohibited for authors" shape (role="generic" — verified 2026-07-20
+ *   against both the WAI-ARIA 1.2 spec text and MDN's explicit "It should
+ *   not be used by web authors" guidance).
+ * @expectation
+ *   The role in use is neither deprecated nor author-prohibited. This is a
+ *   distinct, atomic decision from aria-roles-valid (existence/
+ *   abstractness): a role can be perfectly valid and non-abstract while
+ *   still being off-limits for explicit author use.
+ */
+
+const id = 'aria-deprecated-role';
+
+const meta = {
+  title: 'role attribute must not use a deprecated or author-prohibited ARIA role',
+  description: 'Checks that an explicit role="" attribute does not use a role deprecated by the WAI-ARIA specification, or one reserved for user-agent-internal use only (e.g. role="generic").',
+  i18n: {
+    titleKey: 'ariaDeprecatedRole_title',
+    descriptionKey: 'ariaDeprecatedRole_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-not-deprecated'] } }
+};
+
+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) continue;
+
+    // Only applicable to roles that are otherwise valid + concrete;
+    // invalid/abstract usage is aria-roles-valid's concern.
+    if (!ariaHelpers.isValidConcreteRole(role)) continue;
+
+    applicableCount += 1;
+
+    if (!ariaHelpers.isDeprecatedRole(role)) continue;
+
+    const stableSelector = helpers.buildSelector ? helpers.buildSelector(el) : 'html';
+    const html = helpers.getOuterHtmlSnippet ? helpers.getOuterHtmlSnippet(el) : (el.outerHTML || '');
+    const guidance = ariaHelpers.getDeprecatedRoleGuidance
+        ? ariaHelpers.getDeprecatedRoleGuidance(role)
+        : 'Replace the deprecated role with its recommended replacement.';
+
+    occurrences.push({
+      selector: stableSelector,
+      html,
+      summary: `This element uses role="${role}", which authors must not explicitly declare.`,
+      hint: guidance,
+      i18n: {
+        summaryKey: 'ariaDeprecatedRole_summary_fail',
+        hintKey: 'ariaDeprecatedRole_hint_fail',
+        params: { role, guidance }
+      },
+      data: {
+        details: { reasonCode: 'ARIA_ROLE_DEPRECATED', role, guidance }
+      }
+    });
+  }
+
+  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-hidden-body.js

@@ -0,0 +1,87 @@
+'use strict';
+
+/**
+ * @check aria-hidden-body
+ * @atomic true
+ * @summary The document <body> must not have aria-hidden="true"
+ * @standard WCAG 2.2
+ * @sc 1.3.1, 4.1.2
+ * @applicability
+ *   Always applicable to any HTML document with a <body> element,
+ *   independent of contextSelector/root scoping — this is a whole-
+ *   document concern, matching page-title-present's pattern of
+ *   evaluating document.body directly rather than the scoped root.
+ * @expectation
+ *   <body> does not have aria-hidden="true". Hiding the document body
+ *   removes the entire page's content and structure from the
+ *   accessibility tree at once — a widely-used reference engine tags this under both 1.3.1
+ *   (Info and Relationships: the page's structure becomes entirely
+ *   non-determinable) and 4.1.2 (Name, Role, Value: nothing in the
+ *   document exposes a role/name/value any longer).
+ */
+
+const id = 'aria-hidden-body';
+
+const meta = {
+  title: 'The document <body> must not be aria-hidden',
+  description: 'Checks that <body> does not have aria-hidden="true", which would remove the entire page from the accessibility tree.',
+  i18n: {
+    titleKey: 'ariaHiddenBody_title',
+    descriptionKey: 'ariaHiddenBody_description'
+  },
+  helpUrl: null,
+  tags: ['wcag2a', 'wcag131', 'wcag412', 'structure', 'atomic', 'automatic'],
+  wcagSc: ['1.3.1', '4.1.2'],
+  normativeMappings: [
+    { standard: 'WCAG', version: '2.2', requirement: '1.3.1', title: 'Info and Relationships', conformanceLevel: 'A' },
+    { standard: 'WCAG', version: '2.2', requirement: '4.1.2', title: 'Name, Role, Value', conformanceLevel: 'A' }
+  ],
+  defaultSeverity: 'critical',
+  category: 'perceivable',
+  type: 'automatic',
+  defaultConfidence: 'high',
+  coverage: {
+    facetsBySc: {
+      '1.3.1': ['aria-hidden-body-absent'],
+      '4.1.2': ['aria-hidden-body-absent']
+    }
+  }
+};
+
+function runInPage(ctx) {
+  const { document, helpers, rule } = ctx;
+
+  const body = document && document.body ? document.body : null;
+  if (!body) {
+    return { ruleId: rule.ruleId, outcome: 'notApplicable', severity: 'minor', occurrences: [] };
+  }
+
+  const raw = body.getAttribute ? body.getAttribute('aria-hidden') : null;
+  const isHidden = raw != null && String(raw).trim().toLowerCase() === 'true';
+
+  if (!isHidden) {
+    return { ruleId: rule.ruleId, outcome: 'pass', severity: 'minor', occurrences: [] };
+  }
+
+  const stableSelector = helpers.buildSelector ? helpers.buildSelector(body) : 'body';
+  const html = helpers.getOuterHtmlSnippet ? helpers.getOuterHtmlSnippet(body) : (body.outerHTML || '').slice(0, 200);
+
+  const occurrences = [{
+    selector: stableSelector,
+    html,
+    summary: 'The document body has aria-hidden="true", which hides the entire page from assistive technologies.',
+    hint: 'Remove aria-hidden from <body>. Hide specific elements instead, if that was the intent.',
+    i18n: {
+      summaryKey: 'ariaHiddenBody_summary_fail',
+      hintKey: 'ariaHiddenBody_hint_fail',
+      params: {}
+    },
+    data: {
+      details: { reasonCode: 'ARIA_HIDDEN_BODY' }
+    }
+  }];
+
+  return { ruleId: rule.ruleId, outcome: 'fail', severity: rule.defaultSeverity || 'critical', occurrences };
+}
+
+module.exports = { id, meta, runInPage };