@markuplint/rules 4.12.0 → 5.0.0-alpha.0

package/lib/srcset-sizes-constraint/index.js

@@ -0,0 +1,108 @@
+import { createRule } from '@markuplint/ml-core';
+import meta from './meta.js';
+import { hasSizesAuto, parseSrcset } from './parse-srcset.js';
+/**
+ * Rule that enforces WHATWG constraints between the `srcset`, `sizes`,
+ * and `loading` attributes on `<img>` and `<source>` elements.
+ */
+export default createRule({
+    meta: meta,
+    async verify({ document, report }) {
+        await document.walkOn('Element', el => {
+            const localName = el.localName;
+            // Only check img and source (inside picture) elements
+            if (localName !== 'img' && localName !== 'source') {
+                return;
+            }
+            // source is only relevant inside <picture>
+            if (localName === 'source' && el.parentElement?.localName !== 'picture') {
+                return;
+            }
+            // Skip if element has spread attributes (dynamic props)
+            if (el.hasSpreadAttr) {
+                return;
+            }
+            const srcsetAttr = el.getAttributeNode('srcset');
+            if (!srcsetAttr) {
+                return;
+            }
+            const srcsetIsDynamic = srcsetAttr.isDynamicValue;
+            const sizesAttr = el.getAttributeNode('sizes');
+            const sizesValue = sizesAttr?.value ?? null;
+            const sizesIsDynamic = sizesAttr?.isDynamicValue;
+            // Parse srcset unless dynamic
+            const parsed = srcsetIsDynamic ? null : parseSrcset(srcsetAttr.value);
+            // Check 2: width and density descriptors must not be mixed
+            if (parsed && parsed.hasWidth && (parsed.hasDensity || parsed.hasImplied)) {
+                report({
+                    scope: el,
+                    line: srcsetAttr.valueNode?.startLine,
+                    col: srcsetAttr.valueNode?.startCol,
+                    raw: srcsetAttr.valueNode?.raw,
+                    message: 'The "srcset" attribute must not mix width and pixel density descriptors',
+                });
+            }
+            // Check 1: sizes present → srcset must use width descriptors
+            if (sizesAttr && !sizesIsDynamic && parsed && !parsed.hasWidth) {
+                report({
+                    scope: el,
+                    line: srcsetAttr.valueNode?.startLine,
+                    col: srcsetAttr.valueNode?.startCol,
+                    raw: srcsetAttr.valueNode?.raw,
+                    message: 'The "srcset" attribute requires width descriptors when the "sizes" attribute is present',
+                });
+            }
+            // Check 3: img[sizes=auto] → loading=lazy required
+            if (localName === 'img' && sizesValue != null && !sizesIsDynamic && hasSizesAuto(sizesValue)) {
+                const loading = el.getAttribute('loading');
+                if (loading !== 'lazy') {
+                    report({
+                        scope: el,
+                        line: sizesAttr.valueNode?.startLine,
+                        col: sizesAttr.valueNode?.startCol,
+                        raw: sizesAttr.valueNode?.raw,
+                        message: 'The "sizes" attribute with "auto" requires the "loading" attribute to be "lazy"',
+                    });
+                }
+            }
+            // Check 4: source[sizes=auto] → following sibling img must have loading=lazy
+            if (localName === 'source' && sizesValue != null && !sizesIsDynamic && hasSizesAuto(sizesValue)) {
+                const img = findFollowingImg(el);
+                if (!img || img.getAttribute('loading') !== 'lazy') {
+                    report({
+                        scope: el,
+                        line: sizesAttr.valueNode?.startLine,
+                        col: sizesAttr.valueNode?.startCol,
+                        raw: sizesAttr.valueNode?.raw,
+                        message: 'The "source" element with sizes="auto" requires the following sibling "img" element to have loading="lazy"',
+                    });
+                }
+            }
+            // Check 5: img with w descriptors → sizes required
+            if (localName === 'img' && parsed && parsed.hasWidth && !sizesAttr) {
+                report({
+                    scope: el,
+                    message: 'The "sizes" attribute is required when the "srcset" attribute uses width descriptors',
+                });
+            }
+        });
+    },
+});
+/**
+ * Find the first following sibling `<img>` element.
+ * Per the spec, the img does not have to be the immediately next sibling.
+ *
+ * @param el - The starting element to search from
+ * @returns The first following sibling `<img>` element, or `null` if none found
+ */
+// eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
+function findFollowingImg(el) {
+    let sibling = el.nextElementSibling;
+    while (sibling != null) {
+        if (sibling.localName === 'img') {
+            return sibling;
+        }
+        sibling = sibling.nextElementSibling;
+    }
+    return null;
+}

package/lib/srcset-sizes-constraint/meta.d.ts

@@ -0,0 +1,5 @@
+/** Rule metadata for `srcset-sizes-constraint`: categorized as a validation rule. */
+declare const _default: {
+    readonly category: "validation";
+};
+export default _default;

package/lib/srcset-sizes-constraint/meta.js

@@ -0,0 +1,4 @@
+/** Rule metadata for `srcset-sizes-constraint`: categorized as a validation rule. */
+export default {
+    category: 'validation',
+};

package/lib/srcset-sizes-constraint/parse-srcset.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Descriptor type for an image candidate in a srcset attribute.
+ * - `width`: ends with `w` (e.g., `480w`)
+ * - `density`: ends with `x` (e.g., `2x`)
+ * - `none`: no descriptor (implies `1x`)
+ */
+type DescriptorType = 'width' | 'density' | 'none';
+type SrcsetCandidate = {
+    readonly url: string;
+    readonly descriptorType: DescriptorType;
+};
+type ParseResult = {
+    readonly candidates: readonly SrcsetCandidate[];
+    /** At least one candidate has a width descriptor (`w`). */
+    readonly hasWidth: boolean;
+    /** At least one candidate has a pixel density descriptor (`x`). */
+    readonly hasDensity: boolean;
+    /** At least one candidate has no descriptor (implied `1x`). */
+    readonly hasImplied: boolean;
+};
+/**
+ * Parse a `srcset` attribute value into its image candidates.
+ *
+ * @param value - The raw `srcset` attribute value string
+ * @returns Parsed result with candidates and descriptor flags
+ * @see https://html.spec.whatwg.org/multipage/images.html#srcset-attributes
+ */
+export declare function parseSrcset(value: string): ParseResult;
+/**
+ * Check whether a `sizes` attribute value starts with `auto`.
+ *
+ * Per the spec, `auto` is only valid as the first entry in a sizes list.
+ * Examples: `"auto"`, `"auto, 100vw"`, `"AUTO"`.
+ *
+ * @param value - The raw `sizes` attribute value string
+ * @returns `true` if the value starts with `auto` (case-insensitive)
+ * @see https://html.spec.whatwg.org/multipage/embedded-content.html#the-img-element
+ */
+export declare function hasSizesAuto(value: string): boolean;
+export {};

package/lib/srcset-sizes-constraint/parse-srcset.js

@@ -0,0 +1,56 @@
+/**
+ * Parse a `srcset` attribute value into its image candidates.
+ *
+ * @param value - The raw `srcset` attribute value string
+ * @returns Parsed result with candidates and descriptor flags
+ * @see https://html.spec.whatwg.org/multipage/images.html#srcset-attributes
+ */
+export function parseSrcset(value) {
+    const raw = value.trim();
+    if (raw === '') {
+        return { candidates: [], hasWidth: false, hasDensity: false, hasImplied: false };
+    }
+    const candidates = [];
+    let hasWidth = false;
+    let hasDensity = false;
+    let hasImplied = false;
+    for (const segment of raw.split(',')) {
+        const tokens = segment.trim().split(/\s+/);
+        const url = tokens[0];
+        if (!url) {
+            continue;
+        }
+        const descriptor = tokens[1];
+        let descriptorType = 'none';
+        if (descriptor) {
+            if (/^[1-9]\d*w$/.test(descriptor)) {
+                descriptorType = 'width';
+                hasWidth = true;
+            }
+            else if (/^\d+(?:\.\d+)?x$/.test(descriptor)) {
+                descriptorType = 'density';
+                hasDensity = true;
+            }
+            // Invalid descriptors are ignored here; type validation handles them.
+        }
+        else {
+            hasImplied = true;
+        }
+        candidates.push({ url, descriptorType });
+    }
+    return { candidates, hasWidth, hasDensity, hasImplied };
+}
+/**
+ * Check whether a `sizes` attribute value starts with `auto`.
+ *
+ * Per the spec, `auto` is only valid as the first entry in a sizes list.
+ * Examples: `"auto"`, `"auto, 100vw"`, `"AUTO"`.
+ *
+ * @param value - The raw `sizes` attribute value string
+ * @returns `true` if the value starts with `auto` (case-insensitive)
+ * @see https://html.spec.whatwg.org/multipage/embedded-content.html#the-img-element
+ */
+export function hasSizesAuto(value) {
+    const v = value.trim().toLowerCase();
+    return v === 'auto' || /^auto[\s,]/.test(v);
+}

package/lib/table-row-column-alignment/grid.js

@@ -1,15 +1,3 @@
-var __classPrivateFieldSet = (this && this.__classPrivateFieldSet) || function (receiver, state, value, kind, f) {
-    if (kind === "m") throw new TypeError("Private method is not writable");
-    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a setter");
-    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot write private member to an object whose class did not declare it");
-    return (kind === "a" ? f.call(receiver, value) : f ? f.value = value : state.set(receiver, value)), value;
-};
-var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (receiver, state, kind, f) {
-    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a getter");
-    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot read private member from an object whose class did not declare it");
-    return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
-};
-var _Grid_tbodyRowElements, _Grid_tfootRowElements, _Grid_theadRowElements;
 import { findChildren } from './find-children.js';
 /**
  * Represents a table as a grid model, splitting it into thead, tbody, and tfoot sections.
@@ -19,6 +7,18 @@ import { findChildren } from './find-children.js';
  * rule to detect misaligned rows and overlapping cells.
  */
 export class Grid {
+    /** The grid model for the `<tbody>` section. */
+    tbodyGrid;
+    /** The grid model for the `<tfoot>` section. */
+    tfootGrid;
+    /** The grid model for the `<thead>` section. */
+    theadGrid;
+    /** The `<tr>` elements within `<tbody>`. */
+    #tbodyRowElements;
+    /** The `<tr>` elements within `<tfoot>`. */
+    #tfootRowElements;
+    /** The `<tr>` elements within `<thead>`. */
+    #theadRowElements;
     /**
      * Constructs a grid model from a `<table>` element.
      *
@@ -27,21 +27,15 @@ export class Grid {
     constructor(
     // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
     table) {
-        /** The `<tr>` elements within `<tbody>`. */
-        _Grid_tbodyRowElements.set(this, void 0);
-        /** The `<tr>` elements within `<tfoot>`. */
-        _Grid_tfootRowElements.set(this, void 0);
-        /** The `<tr>` elements within `<thead>`. */
-        _Grid_theadRowElements.set(this, void 0);
         const thead = findChildren(table, 'thead')[0];
         const tbody = findChildren(table, 'tbody')[0];
         const tfoot = findChildren(table, 'tfoot')[0];
-        __classPrivateFieldSet(this, _Grid_theadRowElements, thead ? findChildren(thead, 'tr') : [], "f");
-        __classPrivateFieldSet(this, _Grid_tbodyRowElements, tbody ? findChildren(tbody, 'tr') : [], "f");
-        __classPrivateFieldSet(this, _Grid_tfootRowElements, tfoot ? findChildren(tfoot, 'tr') : [], "f");
-        this.theadGrid = createGrid(__classPrivateFieldGet(this, _Grid_theadRowElements, "f"));
-        this.tbodyGrid = createGrid(__classPrivateFieldGet(this, _Grid_tbodyRowElements, "f"));
-        this.tfootGrid = createGrid(__classPrivateFieldGet(this, _Grid_tfootRowElements, "f"));
+        this.#theadRowElements = thead ? findChildren(thead, 'tr') : [];
+        this.#tbodyRowElements = tbody ? findChildren(tbody, 'tr') : [];
+        this.#tfootRowElements = tfoot ? findChildren(tfoot, 'tr') : [];
+        this.theadGrid = createGrid(this.#theadRowElements);
+        this.tbodyGrid = createGrid(this.#tbodyRowElements);
+        this.tfootGrid = createGrid(this.#tfootRowElements);
     }
     /**
      * Returns all `<tr>` elements across all table sections in document order.
@@ -49,7 +43,7 @@ export class Grid {
      * @returns Combined array of row elements from thead, tbody, and tfoot.
      */
     getAllRowElements() {
-        return [...__classPrivateFieldGet(this, _Grid_theadRowElements, "f"), ...__classPrivateFieldGet(this, _Grid_tbodyRowElements, "f"), ...__classPrivateFieldGet(this, _Grid_tfootRowElements, "f")];
+        return [...this.#theadRowElements, ...this.#tbodyRowElements, ...this.#tfootRowElements];
     }
     /**
      * Returns all grid rows that contain at least one actual cell element.
@@ -88,15 +82,15 @@ export class Grid {
         return [
             {
                 section: this.theadGrid,
-                elements: __classPrivateFieldGet(this, _Grid_theadRowElements, "f"),
+                elements: this.#theadRowElements,
             },
             {
                 section: this.tbodyGrid,
-                elements: __classPrivateFieldGet(this, _Grid_tbodyRowElements, "f"),
+                elements: this.#tbodyRowElements,
             },
             {
                 section: this.tfootGrid,
-                elements: __classPrivateFieldGet(this, _Grid_tfootRowElements, "f"),
+                elements: this.#tfootRowElements,
             },
         ];
     }
@@ -120,7 +114,6 @@ export class Grid {
         console.table(this.tfootGrid);
     }
 }
-_Grid_tbodyRowElements = new WeakMap(), _Grid_tfootRowElements = new WeakMap(), _Grid_theadRowElements = new WeakMap();
 /**
  * Detects a rowspan that extends beyond the available rows in a table section.
  *

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

@@ -1,4 +1,4 @@
-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.
  *
@@ -9,7 +9,10 @@ import { ariaSpecs } from '@markuplint/ml-spec';
  * @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/disallowed-prop.js

@@ -1,4 +1,4 @@
-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.
  *
@@ -20,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-role.js

@@ -1,4 +1,4 @@
-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.
  *
@@ -13,7 +13,10 @@ export const checkingImplicitRole = ({ attr }) => t => {
     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/non-existent-role.d.ts

@@ -6,6 +6,7 @@ import type { AttrChecker } from '@markuplint/ml-core';
  *
  * 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.

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

@@ -1,16 +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;
@@ -20,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.js

@@ -1,4 +1,4 @@
-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.
@@ -10,8 +10,11 @@ import { getPermittedRoles } from '@markuplint/ml-spec';
  * @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.js

@@ -1,4 +1,4 @@
-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.
@@ -58,9 +58,10 @@ export const checkingPresentationalChildren = ({ el }) => t => {
 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,16 +2,17 @@ import type { Options } from '../types.js';
 import type { ElementChecker } from '@markuplint/ml-core';
 import type { ARIARole } from '@markuplint/ml-spec';
 /**
- * Checks whether an element with a role that requires specific owned elements
- * actually contains children with the expected roles.
+ * 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 required owned elements.
- * @param role - The computed ARIA role of the element, which defines required owned elements.
+ * @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, {