@markuplint/rules 4.11.2 → 5.0.0-alpha.0

package/lib/wai-aria/checkings/abstract-role.d.ts

@@ -1,3 +1,12 @@
 import type { Options } from '../types.js';
 import type { AttrChecker } from '@markuplint/ml-core';
+/**
+ * Checks whether the `role` attribute value refers to an abstract WAI-ARIA role.
+ *
+ * Abstract roles (e.g., `widget`, `landmark`) are used for ontological purposes
+ * in the ARIA taxonomy and must not be used directly in content.
+ *
+ * @param attr - The `role` attribute node to inspect.
+ * @returns A violation if any token in the role attribute is an abstract role.
+ */
 export declare const checkingAbstractRole: AttrChecker<boolean, Options>;

package/lib/wai-aria/checkings/abstract-role.js

@@ -1,6 +1,18 @@
-import { ariaSpecs } from '@markuplint/ml-spec';
+import { ARIA_RECOMMENDED_VERSION, ariaSpecs } from '@markuplint/ml-spec';
+/**
+ * Checks whether the `role` attribute value refers to an abstract WAI-ARIA role.
+ *
+ * Abstract roles (e.g., `widget`, `landmark`) are used for ontological purposes
+ * in the ARIA taxonomy and must not be used directly in content.
+ *
+ * @param attr - The `role` attribute node to inspect.
+ * @returns A violation if any token in the role attribute is an abstract role.
+ */
 export const checkingAbstractRole = ({ attr }) => t => {
-    const { roles } = ariaSpecs(attr.ownerMLDocument.specs, attr.rule.options.version);
+    const ariaVersion = attr.rule.options?.version ??
+        attr.ownerMLDocument.ruleCommonSettings?.ariaVersion ??
+        ARIA_RECOMMENDED_VERSION;
+    const { roles } = ariaSpecs(attr.ownerMLDocument.specs, ariaVersion);
     const tokens = attr.tokenList?.allTokens();
     if (!tokens) {
         return;

package/lib/wai-aria/checkings/default-value.d.ts

@@ -1,6 +1,17 @@
 import type { Options } from '../types.js';
 import type { AttrChecker } from '@markuplint/ml-core';
 import type { ARIAProperty } from '@markuplint/ml-spec';
+/**
+ * Checks whether an ARIA property is explicitly set to its spec-defined default value.
+ *
+ * Setting an ARIA property to its default value is redundant and may indicate
+ * a misunderstanding of the property's behavior. This checker reports such cases
+ * when the `disallowDefaultValue` option is enabled.
+ *
+ * @param attr - The ARIA attribute node to inspect.
+ * @param propSpecs - The list of ARIA property specifications for value lookup.
+ * @returns A violation if the attribute value matches the property's default value.
+ */
 export declare const checkingDefaultValue: AttrChecker<boolean, Options, {
     propSpecs: readonly ARIAProperty[];
 }>;

package/lib/wai-aria/checkings/default-value.js

@@ -1,3 +1,14 @@
+/**
+ * Checks whether an ARIA property is explicitly set to its spec-defined default value.
+ *
+ * Setting an ARIA property to its default value is redundant and may indicate
+ * a misunderstanding of the property's behavior. This checker reports such cases
+ * when the `disallowDefaultValue` option is enabled.
+ *
+ * @param attr - The ARIA attribute node to inspect.
+ * @param propSpecs - The list of ARIA property specifications for value lookup.
+ * @returns A violation if the attribute value matches the property's default value.
+ */
 export const checkingDefaultValue = ({ attr, propSpecs }) => t => {
     if (attr.isDynamicValue) {
         return;

package/lib/wai-aria/checkings/deprecated-props.d.ts

@@ -1,6 +1,17 @@
 import type { Options } from '../types.js';
 import type { AttrChecker } from '@markuplint/ml-core';
 import type { ARIAProperty, ARIARole } from '@markuplint/ml-spec';
+/**
+ * Checks whether an ARIA property or state is deprecated for the element's computed role.
+ *
+ * Some ARIA properties become deprecated on specific roles across ARIA versions.
+ * This checker reports usage of such deprecated properties.
+ *
+ * @param attr - The ARIA attribute node to inspect.
+ * @param role - The computed ARIA role of the element.
+ * @param propSpecs - The list of ARIA property specifications for type lookup.
+ * @returns A violation if the property is deprecated on the given role.
+ */
 export declare const checkingDeprecatedProps: AttrChecker<boolean, Options, {
     role: ARIARole | null;
     propSpecs: readonly ARIAProperty[];

package/lib/wai-aria/checkings/deprecated-props.js

@@ -1,3 +1,14 @@
+/**
+ * Checks whether an ARIA property or state is deprecated for the element's computed role.
+ *
+ * Some ARIA properties become deprecated on specific roles across ARIA versions.
+ * This checker reports usage of such deprecated properties.
+ *
+ * @param attr - The ARIA attribute node to inspect.
+ * @param role - The computed ARIA role of the element.
+ * @param propSpecs - The list of ARIA property specifications for type lookup.
+ * @returns A violation if the property is deprecated on the given role.
+ */
 export const checkingDeprecatedProps = ({ attr, role, propSpecs }) => t => {
     if (!role) {
         return;

package/lib/wai-aria/checkings/deprecated-role.d.ts

@@ -1,6 +1,16 @@
 import type { Options } from '../types.js';
 import type { AttrChecker } from '@markuplint/ml-core';
 import type { ARIARole } from '@markuplint/ml-spec';
+/**
+ * Checks whether the element's computed ARIA role is deprecated in the specified ARIA version.
+ *
+ * Deprecated roles should be avoided as they may be removed in future ARIA versions
+ * and assistive technologies may not support them reliably.
+ *
+ * @param attr - The `role` attribute node to inspect.
+ * @param role - The computed ARIA role of the element.
+ * @returns A violation if the role is marked as deprecated.
+ */
 export declare const checkingDeprecatedRole: AttrChecker<boolean, Options, {
     role: ARIARole | null;
 }>;

package/lib/wai-aria/checkings/deprecated-role.js

@@ -1,3 +1,13 @@
+/**
+ * Checks whether the element's computed ARIA role is deprecated in the specified ARIA version.
+ *
+ * Deprecated roles should be avoided as they may be removed in future ARIA versions
+ * and assistive technologies may not support them reliably.
+ *
+ * @param attr - The `role` attribute node to inspect.
+ * @param role - The computed ARIA role of the element.
+ * @returns A violation if the role is marked as deprecated.
+ */
 export const checkingDeprecatedRole = ({ attr, role }) => t => {
     if (!role) {
         return;

package/lib/wai-aria/checkings/disallowed-prop.d.ts

@@ -1,6 +1,20 @@
 import type { Options } from '../types.js';
 import type { AttrChecker } from '@markuplint/ml-core';
 import type { ARIAProperty, ARIARole } from '@markuplint/ml-spec';
+/**
+ * Checks whether an ARIA property or state is disallowed on the element's computed role.
+ *
+ * Each ARIA role defines a set of supported states and properties. This checker reports
+ * usage of ARIA attributes that are not in that set. It also considers element-specific
+ * restrictions from the ARIA in HTML specification (e.g., properties that should not
+ * be used on certain native HTML elements).
+ *
+ * @param attr - The ARIA attribute node to inspect.
+ * @param role - The computed ARIA role of the element.
+ * @param propSpecs - The list of ARIA property specifications for type lookup.
+ * @param disallowSetImplicitProps - Whether to also enforce element-specific restrictions.
+ * @returns A violation if the property is not allowed on the given role or element.
+ */
 export declare const checkingDisallowedProp: AttrChecker<boolean, Options, {
     role: ARIARole | null;
     propSpecs: readonly ARIAProperty[];

package/lib/wai-aria/checkings/disallowed-prop.js

@@ -1,4 +1,18 @@
-import { getARIA } from '@markuplint/ml-spec';
+import { ARIA_RECOMMENDED_VERSION, getARIA } from '@markuplint/ml-spec';
+/**
+ * Checks whether an ARIA property or state is disallowed on the element's computed role.
+ *
+ * Each ARIA role defines a set of supported states and properties. This checker reports
+ * usage of ARIA attributes that are not in that set. It also considers element-specific
+ * restrictions from the ARIA in HTML specification (e.g., properties that should not
+ * be used on certain native HTML elements).
+ *
+ * @param attr - The ARIA attribute node to inspect.
+ * @param role - The computed ARIA role of the element.
+ * @param propSpecs - The list of ARIA property specifications for type lookup.
+ * @param disallowSetImplicitProps - Whether to also enforce element-specific restrictions.
+ * @returns A violation if the property is not allowed on the given role or element.
+ */
 export const checkingDisallowedProp = ({ attr, role, propSpecs, disallowSetImplicitProps }) => t => {
     if (!role) {
         return;
@@ -6,9 +20,12 @@ export const checkingDisallowedProp = ({ attr, role, propSpecs, disallowSetImpli
     if (!/^aria-/i.test(attr.name)) {
         return;
     }
+    const ariaVersion = attr.rule.options?.version ??
+        attr.ownerMLDocument.ruleCommonSettings?.ariaVersion ??
+        ARIA_RECOMMENDED_VERSION;
     const statesAndProp = role.ownedProperties.find(p => p.name === attr.name);
     const propSpec = propSpecs.find(p => p.name === attr.name);
-    const elAriaSpec = getARIA(attr.ownerMLDocument.specs, attr.ownerElement.localName, attr.ownerElement.namespaceURI, attr.rule.options.version, attr.ownerElement.matches.bind(attr.ownerElement));
+    const elAriaSpec = getARIA(attr.ownerMLDocument.specs, attr.ownerElement.localName, attr.ownerElement.namespaceURI, ariaVersion, attr.ownerElement.matches.bind(attr.ownerElement));
     if (disallowSetImplicitProps && elAriaSpec?.properties !== false && elAriaSpec?.properties?.without) {
         for (const ignore of elAriaSpec.properties.without) {
             if (ignore.name === attr.name) {

package/lib/wai-aria/checkings/implicit-props.d.ts

@@ -1,6 +1,19 @@
 import type { Options } from '../types.js';
 import type { AttrChecker } from '@markuplint/ml-core';
 import type { ARIAProperty, Attribute } from '@markuplint/ml-spec';
+/**
+ * Checks whether an ARIA property duplicates or contradicts semantics already
+ * provided by an equivalent native HTML attribute.
+ *
+ * Many ARIA properties have equivalent HTML attributes (e.g., `aria-required` and `required`).
+ * This checker reports when an ARIA property is redundant because the native attribute
+ * already conveys the same semantics, or when the ARIA value contradicts the native attribute.
+ *
+ * @param attr - The ARIA attribute node to inspect.
+ * @param propSpecs - The list of ARIA property specifications for equivalence lookup.
+ * @param attrSpecs - The HTML attribute specifications for the element.
+ * @returns A violation if the ARIA property duplicates or contradicts an equivalent HTML attribute.
+ */
 export declare const checkingImplicitProps: AttrChecker<boolean, Options, {
     propSpecs: readonly ARIAProperty[];
     attrSpecs: readonly Attribute[] | null;

package/lib/wai-aria/checkings/implicit-props.js

@@ -1,4 +1,17 @@
 import { isValidAttr } from '../../helpers.js';
+/**
+ * Checks whether an ARIA property duplicates or contradicts semantics already
+ * provided by an equivalent native HTML attribute.
+ *
+ * Many ARIA properties have equivalent HTML attributes (e.g., `aria-required` and `required`).
+ * This checker reports when an ARIA property is redundant because the native attribute
+ * already conveys the same semantics, or when the ARIA value contradicts the native attribute.
+ *
+ * @param attr - The ARIA attribute node to inspect.
+ * @param propSpecs - The list of ARIA property specifications for equivalence lookup.
+ * @param attrSpecs - The HTML attribute specifications for the element.
+ * @returns A violation if the ARIA property duplicates or contradicts an equivalent HTML attribute.
+ */
 export const checkingImplicitProps = ({ attr, propSpecs, attrSpecs }) => t => {
     if (!attrSpecs) {
         return;

package/lib/wai-aria/checkings/implicit-role.d.ts

@@ -1,3 +1,12 @@
 import type { Options } from '../types.js';
 import type { AttrChecker } from '@markuplint/ml-core';
+/**
+ * Checks whether the explicit `role` attribute duplicates the element's implicit (native) role.
+ *
+ * HTML elements have implicit ARIA roles (e.g., `<nav>` has an implicit role of `navigation`).
+ * Explicitly setting the same role is redundant and should be avoided.
+ *
+ * @param attr - The `role` attribute node to inspect.
+ * @returns A violation if any token in the role attribute matches the element's implicit role.
+ */
 export declare const checkingImplicitRole: AttrChecker<boolean, Options>;

package/lib/wai-aria/checkings/implicit-role.js

@@ -1,10 +1,22 @@
-import { getImplicitRoleName } from '@markuplint/ml-spec';
+import { ARIA_RECOMMENDED_VERSION, getImplicitRoleName } from '@markuplint/ml-spec';
+/**
+ * Checks whether the explicit `role` attribute duplicates the element's implicit (native) role.
+ *
+ * HTML elements have implicit ARIA roles (e.g., `<nav>` has an implicit role of `navigation`).
+ * Explicitly setting the same role is redundant and should be avoided.
+ *
+ * @param attr - The `role` attribute node to inspect.
+ * @returns A violation if any token in the role attribute matches the element's implicit role.
+ */
 export const checkingImplicitRole = ({ attr }) => t => {
     const tokens = attr.tokenList?.allTokens();
     if (!tokens) {
         return;
     }
-    const implicitRole = getImplicitRoleName(attr.ownerElement, attr.rule.options.version, attr.ownerMLDocument.specs);
+    const ariaVersion = attr.rule.options?.version ??
+        attr.ownerMLDocument.ruleCommonSettings?.ariaVersion ??
+        ARIA_RECOMMENDED_VERSION;
+    const implicitRole = getImplicitRoleName(attr.ownerElement, ariaVersion, attr.ownerMLDocument.specs);
     for (const token of tokens) {
         if (implicitRole === token.raw) {
             return {

package/lib/wai-aria/checkings/interaction-in-hidden.d.ts

@@ -1,11 +1,20 @@
 import type { Options } from '../types.js';
 import type { ElementChecker } from '@markuplint/ml-core';
 /**
+ * Checks whether a focusable interactive element is inside an `aria-hidden=true` subtree.
+ *
  * Including Elements in the Accessibility Tree
  *
  * @see https://w3c.github.io/aria/#tree_inclusion
  * > Elements that are not hidden and may fire an accessibility API event, including:
  * > - Elements that are currently focused, even if the element or one of its ancestor elements has its aria-hidden attribute set to true.
  * > - Elements that are a valid target of an aria-activedescendant attribute.
+ *
+ * When a focused element exists within an `aria-hidden=true` ancestor, it is still
+ * exposed to the accessibility tree. This situation is almost always unintentional --
+ * while not strictly invalid per spec, it requires careful attention from the developer.
+ *
+ * @param el - The element node to inspect for focusability within a hidden context.
+ * @returns A violation if the element is focusable and has `aria-hidden=true` on itself or an ancestor.
  */
 export declare const checkingInteractionInHidden: ElementChecker<boolean, Options>;

package/lib/wai-aria/checkings/interaction-in-hidden.js

@@ -1,16 +1,21 @@
 import { mayBeFocusable } from '@markuplint/ml-spec';
 /**
+ * Checks whether a focusable interactive element is inside an `aria-hidden=true` subtree.
+ *
  * Including Elements in the Accessibility Tree
  *
  * @see https://w3c.github.io/aria/#tree_inclusion
  * > Elements that are not hidden and may fire an accessibility API event, including:
  * > - Elements that are currently focused, even if the element or one of its ancestor elements has its aria-hidden attribute set to true.
  * > - Elements that are a valid target of an aria-activedescendant attribute.
+ *
+ * When a focused element exists within an `aria-hidden=true` ancestor, it is still
+ * exposed to the accessibility tree. This situation is almost always unintentional --
+ * while not strictly invalid per spec, it requires careful attention from the developer.
+ *
+ * @param el - The element node to inspect for focusability within a hidden context.
+ * @returns A violation if the element is focusable and has `aria-hidden=true` on itself or an ancestor.
  */
-// フォーカスがあたっている場合に限り、先祖がaria-hidden=trueでもアクセシビリティツリーに提示される
-// なので、aria-hidden=trueの子孫要素で且つインタラクティブ要素である場合、
-// それは開発者にとってはほとんどの場合、意図しないことが多いはずなので、
-// 仕様上不正にはならないが、十分に注意しなければならない状態である。
 export const checkingInteractionInHidden = ({ el }) => t => {
     if (!mayBeFocusable(el, el.ownerMLDocument.specs)) {
         return;
@@ -30,6 +35,12 @@ export const checkingInteractionInHidden = ({ el }) => t => {
         message: t('It may be focusable in spite of it has the ancestor that has aria-hidden=true'),
     };
 };
+/**
+ * Traverses the element's ancestor chain to find the closest element with `aria-hidden="true"`.
+ *
+ * @param el - The element to start searching from (inclusive).
+ * @returns The `aria-hidden` attribute node if found, or `null` if no ancestor is hidden.
+ */
 function getClosestAriaHidden(
 // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
 el) {

package/lib/wai-aria/checkings/no-global-prop.d.ts

@@ -1,6 +1,16 @@
 import type { Options } from '../types.js';
 import type { AttrChecker } from '@markuplint/ml-core';
 import type { ARIAProperty } from '@markuplint/ml-spec';
+/**
+ * Checks whether a non-global ARIA property is used on an element without an explicit role.
+ *
+ * When no role is computed for an element, only global ARIA properties (e.g., `aria-label`,
+ * `aria-hidden`) are allowed. This checker reports non-global properties used in that context.
+ *
+ * @param attr - The ARIA attribute node to inspect.
+ * @param propSpecs - The list of ARIA property specifications for global status lookup.
+ * @returns A violation if the property is not a global ARIA property.
+ */
 export declare const checkingNoGlobalProp: AttrChecker<boolean, Options, {
     propSpecs: readonly ARIAProperty[];
 }>;

package/lib/wai-aria/checkings/no-global-prop.js

@@ -1,3 +1,13 @@
+/**
+ * Checks whether a non-global ARIA property is used on an element without an explicit role.
+ *
+ * When no role is computed for an element, only global ARIA properties (e.g., `aria-label`,
+ * `aria-hidden`) are allowed. This checker reports non-global properties used in that context.
+ *
+ * @param attr - The ARIA attribute node to inspect.
+ * @param propSpecs - The list of ARIA property specifications for global status lookup.
+ * @returns A violation if the property is not a global ARIA property.
+ */
 export const checkingNoGlobalProp = ({ attr, propSpecs }) => t => {
     const propSpec = propSpecs.find(prop => prop.name === attr.name);
     if (propSpec && !propSpec.isGlobal) {

package/lib/wai-aria/checkings/non-existent-role.d.ts

@@ -1,3 +1,14 @@
 import type { Options } from '../types.js';
 import type { AttrChecker } from '@markuplint/ml-core';
+/**
+ * Checks whether the `role` attribute value refers to a role that does not exist
+ * in the WAI-ARIA specification.
+ *
+ * Validates each token in the role attribute against the known ARIA roles list.
+ * For SVG elements, the WAI-ARIA Graphics Module roles are also accepted.
+ * DPub ARIA roles (Digital Publishing WAI-ARIA Module) are accepted for all elements.
+ *
+ * @param attr - The `role` attribute node to inspect.
+ * @returns A violation if any token does not correspond to a defined ARIA role.
+ */
 export declare const checkingNonExistentRole: AttrChecker<boolean, Options>;

package/lib/wai-aria/checkings/non-existent-role.js

@@ -1,6 +1,20 @@
-import { ariaSpecs } from '@markuplint/ml-spec';
+import { ARIA_RECOMMENDED_VERSION, ariaSpecs } from '@markuplint/ml-spec';
+/**
+ * Checks whether the `role` attribute value refers to a role that does not exist
+ * in the WAI-ARIA specification.
+ *
+ * Validates each token in the role attribute against the known ARIA roles list.
+ * For SVG elements, the WAI-ARIA Graphics Module roles are also accepted.
+ * DPub ARIA roles (Digital Publishing WAI-ARIA Module) are accepted for all elements.
+ *
+ * @param attr - The `role` attribute node to inspect.
+ * @returns A violation if any token does not correspond to a defined ARIA role.
+ */
 export const checkingNonExistentRole = ({ attr }) => t => {
-    const { roles, graphicsRoles } = ariaSpecs(attr.ownerMLDocument.specs, attr.rule.options.version);
+    const ariaVersion = attr.rule.options?.version ??
+        attr.ownerMLDocument.ruleCommonSettings?.ariaVersion ??
+        ARIA_RECOMMENDED_VERSION;
+    const { roles, graphicsRoles, dpubRoles } = ariaSpecs(attr.ownerMLDocument.specs, ariaVersion);
     const tokens = attr.tokenList?.allTokens();
     if (!tokens) {
         return;
@@ -10,6 +24,9 @@ export const checkingNonExistentRole = ({ attr }) => t => {
         if (!role && attr.ownerElement.namespaceURI === 'http://www.w3.org/2000/svg') {
             role = graphicsRoles.find(r => r.name === token.raw);
         }
+        if (!role) {
+            role = dpubRoles.find(r => r.name === token.raw);
+        }
         if (!role) {
             return {
                 scope: token,

package/lib/wai-aria/checkings/permitted-roles.d.ts

@@ -1,3 +1,13 @@
 import type { Options } from '../types.js';
 import type { AttrChecker } from '@markuplint/ml-core';
+/**
+ * Checks whether the explicit `role` attribute value is permitted on the element
+ * according to the ARIA in HTML specification.
+ *
+ * Each HTML element defines a set of roles that may be assigned to it. Some elements
+ * (e.g., `<meta>`) do not allow any role overrides. This checker enforces those constraints.
+ *
+ * @param attr - The `role` attribute node to inspect.
+ * @returns A violation if the role is not in the element's list of permitted roles.
+ */
 export declare const checkingPermittedRoles: AttrChecker<boolean, Options>;

package/lib/wai-aria/checkings/permitted-roles.js

@@ -1,7 +1,20 @@
-import { getPermittedRoles } from '@markuplint/ml-spec';
+import { ARIA_RECOMMENDED_VERSION, getPermittedRoles } from '@markuplint/ml-spec';
+/**
+ * Checks whether the explicit `role` attribute value is permitted on the element
+ * according to the ARIA in HTML specification.
+ *
+ * Each HTML element defines a set of roles that may be assigned to it. Some elements
+ * (e.g., `<meta>`) do not allow any role overrides. This checker enforces those constraints.
+ *
+ * @param attr - The `role` attribute node to inspect.
+ * @returns A violation if the role is not in the element's list of permitted roles.
+ */
 export const checkingPermittedRoles = ({ attr }) => t => {
+    const ariaVersion = attr.rule.options?.version ??
+        attr.ownerMLDocument.ruleCommonSettings?.ariaVersion ??
+        ARIA_RECOMMENDED_VERSION;
     const el = attr.ownerElement;
-    const permittedRoles = getPermittedRoles(el, el.rule.options.version, attr.ownerMLDocument.specs);
+    const permittedRoles = getPermittedRoles(el, ariaVersion, attr.ownerMLDocument.specs);
     if (permittedRoles.length === 0) {
         return {
             scope: attr,

package/lib/wai-aria/checkings/presentational-children.d.ts

@@ -1,6 +1,9 @@
 import type { Options } from '../types.js';
 import type { ElementChecker } from '@markuplint/ml-core';
 /**
+ * Checks whether ARIA attributes are applied to descendants of an element whose
+ * role has the `childrenArePresentational` characteristic.
+ *
  * Presentational Children
  *
  * @see https://www.w3.org/TR/wai-aria/#childrenArePresentational
@@ -22,8 +25,11 @@ import type { ElementChecker } from '@markuplint/ml-core';
  *
  * @see https://w3c.github.io/aria/#tree_inclusion
  *
- *  > Text equivalents for hidden referenced objects
+ * > Text equivalents for hidden referenced objects
  * > may still be used in the name and description computation
  * > even when not included in the accessibility tree.
+ *
+ * @param el - The element node to inspect for presentational ancestor context.
+ * @returns A violation if the element has ARIA attributes and an ancestor with presentational children.
  */
 export declare const checkingPresentationalChildren: ElementChecker<boolean, Options>;

package/lib/wai-aria/checkings/presentational-children.js

@@ -1,5 +1,8 @@
-import { getComputedRole } from '@markuplint/ml-spec';
+import { ARIA_RECOMMENDED_VERSION, getComputedRole } from '@markuplint/ml-spec';
 /**
+ * Checks whether ARIA attributes are applied to descendants of an element whose
+ * role has the `childrenArePresentational` characteristic.
+ *
  * Presentational Children
  *
  * @see https://www.w3.org/TR/wai-aria/#childrenArePresentational
@@ -21,9 +24,12 @@ import { getComputedRole } from '@markuplint/ml-spec';
  *
  * @see https://w3c.github.io/aria/#tree_inclusion
  *
- *  > Text equivalents for hidden referenced objects
+ * > Text equivalents for hidden referenced objects
  * > may still be used in the name and description computation
  * > even when not included in the accessibility tree.
+ *
+ * @param el - The element node to inspect for presentational ancestor context.
+ * @returns A violation if the element has ARIA attributes and an ancestor with presentational children.
  */
 export const checkingPresentationalChildren = ({ el }) => t => {
     const ancestor = getAncestorHasPresentationalChildren(el);
@@ -42,12 +48,20 @@ export const checkingPresentationalChildren = ({ el }) => t => {
         message: t('it may be ineffective because {0}', t("it has {0} as an ancestor that doesn't expose its descendants to the accessibility tree", t('the "{0*}" {1}', ancestor.role.name, 'role'))),
     };
 };
+/**
+ * Traverses the element's ancestor chain to find one whose computed role
+ * has the `childrenArePresentational` characteristic.
+ *
+ * @param el - The element to start searching from (exclusive, starts from parent).
+ * @returns The computed role of the ancestor with presentational children, or `null` if none found.
+ */
 function getAncestorHasPresentationalChildren(
 // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
 el) {
+    const ariaVersion = el.rule.options?.version ?? el.ownerMLDocument.ruleCommonSettings?.ariaVersion ?? ARIA_RECOMMENDED_VERSION;
     let current = el.parentElement;
     while (current) {
-        const computed = getComputedRole(el.ownerMLDocument.specs, current, el.rule.options.version);
+        const computed = getComputedRole(el.ownerMLDocument.specs, current, ariaVersion);
         if (computed.role?.childrenPresentational) {
             return computed;
         }

package/lib/wai-aria/checkings/required-accessibility-parent-role.d.ts

@@ -0,0 +1,25 @@
+import type { Options } from '../types.js';
+import type { ElementChecker } from '@markuplint/ml-core';
+import type { ComputedRole } from '@markuplint/ml-spec';
+/**
+ * Checks whether an element with an explicit role satisfies its
+ * "Required Accessibility Parent Role" (called "Required Context Role" in ARIA 1.2).
+ *
+ * When `getComputedRole()` detects that the parent hierarchy does not include
+ * one of the required context roles, it sets `errorType` to
+ * `'INVALID_REQUIRED_CONTEXT_ROLE'` (mismatch) or `'NO_OWNER'`
+ * (no non-transparent ancestor found) and resets `role` to `null`.
+ * This checker translates either result into a user-facing violation.
+ *
+ * Only explicit roles (set via the `role` attribute) are checked;
+ * implicit roles are skipped because native HTML parent-child semantics
+ * are already guaranteed by the HTML specification.
+ *
+ * @see https://w3c.github.io/aria/#scope
+ * @param el - The element to inspect.
+ * @param computed - The computed role result from `getComputedRole()`.
+ * @returns A violation if the role's required context is not satisfied.
+ */
+export declare const checkingRequiredAccessibilityParentRole: ElementChecker<boolean, Options, {
+    computed?: ComputedRole;
+}>;

package/lib/wai-aria/checkings/required-accessibility-parent-role.js

@@ -0,0 +1,56 @@
+import { ARIA_RECOMMENDED_VERSION, ariaSpecs } from '@markuplint/ml-spec';
+/**
+ * Checks whether an element with an explicit role satisfies its
+ * "Required Accessibility Parent Role" (called "Required Context Role" in ARIA 1.2).
+ *
+ * When `getComputedRole()` detects that the parent hierarchy does not include
+ * one of the required context roles, it sets `errorType` to
+ * `'INVALID_REQUIRED_CONTEXT_ROLE'` (mismatch) or `'NO_OWNER'`
+ * (no non-transparent ancestor found) and resets `role` to `null`.
+ * This checker translates either result into a user-facing violation.
+ *
+ * Only explicit roles (set via the `role` attribute) are checked;
+ * implicit roles are skipped because native HTML parent-child semantics
+ * are already guaranteed by the HTML specification.
+ *
+ * @see https://w3c.github.io/aria/#scope
+ * @param el - The element to inspect.
+ * @param computed - The computed role result from `getComputedRole()`.
+ * @returns A violation if the role's required context is not satisfied.
+ */
+export const checkingRequiredAccessibilityParentRole = ({ el, computed }) => t => {
+    if (!computed ||
+        (computed.errorType !== 'INVALID_REQUIRED_CONTEXT_ROLE' &&
+            // NO_OWNER with role: null means all ancestors were transparent
+            // and no valid context could be found. NO_OWNER with role kept
+            // (parentElement === null) is a root fragment — skip.
+            !(computed.errorType === 'NO_OWNER' && !computed.role))) {
+        return;
+    }
+    const roleAttr = el.getAttributeNode('role');
+    if (!roleAttr) {
+        return;
+    }
+    const ariaVersion = el.rule.options?.version ?? el.ownerMLDocument.ruleCommonSettings?.ariaVersion ?? ARIA_RECOMMENDED_VERSION;
+    const { roles } = ariaSpecs(el.ownerMLDocument.specs, ariaVersion);
+    for (const token of roleAttr.tokenList?.allTokens() ?? []) {
+        const roleSpec = roles.find(r => r.name === token.raw);
+        if (!roleSpec) {
+            continue;
+        }
+        // `ariaSpecs().roles` returns raw spec data where the field is always
+        // `requiredContextRole` for all versions. The fallback to
+        // `requiredAccessibilityParentRole` is a defensive guard in case
+        // the spec-generator changes the field name in the future.
+        const parentRoles = roleSpec.requiredContextRole ?? roleSpec.requiredAccessibilityParentRole;
+        if (parentRoles && parentRoles.length > 0) {
+            return {
+                scope: token,
+                message: t('{0} requires {1}', t('the "{0*}" {1}', roleSpec.name, 'role'), parentRoles.length === 1 && parentRoles[0]
+                    ? t('an accessibility parent with the "{0*}" {1}', parentRoles[0], 'role')
+                    : t('an accessibility parent with one of the {0}', 'roles') +
+                        `: ${t(parentRoles)}`),
+            };
+        }
+    }
+};

package/lib/wai-aria/checkings/required-owned-elements.d.ts

@@ -2,9 +2,18 @@ import type { Options } from '../types.js';
 import type { ElementChecker } from '@markuplint/ml-core';
 import type { ARIARole } from '@markuplint/ml-spec';
 /**
- * Required Owned Elements
+ * Checks whether an element with a role that has "Allowed Accessibility Child Roles"
+ * (called "Required Owned Elements" in ARIA 1.2) actually contains children
+ * with the expected roles.
+ *
+ * For example, a `list` role must own at least one element with the `listitem` role.
+ * This checker respects `aria-busy="true"` (which signals that content is still loading),
+ * preprocessor blocks, and mutable children from template engines.
  *
  * @see https://w3c.github.io/aria/#mustContain
+ * @param el - The element node to inspect for allowed accessibility child roles.
+ * @param role - The computed ARIA role of the element, which defines allowed accessibility child roles.
+ * @returns A violation if the role requires owned elements and none are found.
  */
 export declare const checkingRequiredOwnedElements: ElementChecker<boolean, Options, {
     role?: ARIARole | null;