@markuplint/ml-spec 4.10.1 → 5.0.0-alpha.0

package/lib/algorithm/aria/get-non-presentational-ancestor.js

@@ -1,5 +1,17 @@
-import { isPresentational } from './is-presentational.js';
+import { isTransparentForOwnership } from './is-presentational.js';
 import { getComputedRole } from './get-computed-role.js';
+/**
+ * Traverses the parent element chain to find the nearest ancestor with a
+ * non-presentational role, skipping elements that are transparent for
+ * ownership traversal (via `isTransparentForOwnership`).
+ *
+ * In ARIA 1.3, `generic` role elements are additionally transparent.
+ *
+ * @param el - The DOM element whose ancestors to traverse
+ * @param specs - The full markup language specification
+ * @param version - The ARIA specification version to use
+ * @returns The nearest non-presentational ancestor's `ComputedRole`, or `{ el: null, role: null }` if none exists
+ */
 export function getNonPresentationalAncestor(
 // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
 el, specs, version) {
@@ -12,7 +24,7 @@ el, specs, version) {
     const assumeSingleNode = version !== '1.1' && version !== '1.2';
     while (ancestor) {
         const ancestorRole = getComputedRole(specs, ancestor, version, assumeSingleNode);
-        if (!isPresentational(ancestorRole.role?.name)) {
+        if (!isTransparentForOwnership(ancestorRole.role?.name, version)) {
             return ancestorRole;
         }
         ancestor = ancestor.parentElement;

package/lib/algorithm/aria/get-permitted-roles-spec.d.ts

@@ -1,10 +1,14 @@
 import type { ARIAVersion, Matches, MLMLSpec } from '../../types/index.js';
 /**
- * Getting permitted ARIA roles.
+ * Computes the list of permitted ARIA roles for an element at the spec level,
+ * operating on tag name and namespace rather than a DOM element.
  *
- * - If an array, it is role list.
- * - If `true`, this mean is "Any".
- * - If `false`, this mean is "No".
+ * @param specs - The full markup language specification
+ * @param localName - The element's local tag name
+ * @param namespace - The element's namespace URI
+ * @param version - The ARIA specification version to use
+ * @param matches - A function that tests CSS selector matches for conditional role resolution
+ * @returns A list of permitted roles, each with a `name` and optional `deprecated` flag
  */
 export declare function getPermittedRoles(specs: MLMLSpec, localName: string, namespace: string | null, version: ARIAVersion, matches: Matches): readonly {
     readonly name: string;

package/lib/algorithm/aria/get-permitted-roles-spec.js

@@ -4,11 +4,15 @@ import { mergeArray } from '../../utils/merge-array.js';
 import { ariaSpecs } from './aria-specs.js';
 import { getARIA } from './get-aria.js';
 /**
- * Getting permitted ARIA roles.
+ * Computes the list of permitted ARIA roles for an element at the spec level,
+ * operating on tag name and namespace rather than a DOM element.
  *
- * - If an array, it is role list.
- * - If `true`, this mean is "Any".
- * - If `false`, this mean is "No".
+ * @param specs - The full markup language specification
+ * @param localName - The element's local tag name
+ * @param namespace - The element's namespace URI
+ * @param version - The ARIA specification version to use
+ * @param matches - A function that tests CSS selector matches for conditional role resolution
+ * @returns A list of permitted roles, each with a `name` and optional `deprecated` flag
  */
 export function getPermittedRoles(specs, localName, namespace, version, matches) {
     const aria = getARIA(specs, localName, namespace, version, matches);
@@ -16,7 +20,7 @@ export function getPermittedRoles(specs, localName, namespace, version, matches)
         return [];
     }
     const { implicitRole, permittedRoles } = aria;
-    const { roles, graphicsRoles } = ariaSpecs(specs, version);
+    const { roles, graphicsRoles, dpubRoles } = ariaSpecs(specs, version);
     let permittedRoleList = [];
     if (permittedRoles === true) {
         permittedRoleList = mergeArray(permittedRoleList, roles
@@ -24,6 +28,11 @@ export function getPermittedRoles(specs, localName, namespace, version, matches)
             .map(role => ({
             name: role.name,
         })));
+        permittedRoleList = mergeArray(permittedRoleList, dpubRoles
+            .filter(role => !role.isAbstract)
+            .map(role => ({
+            name: role.name,
+        })));
     }
     if (isAAMInfo(permittedRoles)) {
         if (permittedRoles['core-aam']) {
@@ -54,7 +63,11 @@ export function getPermittedRoles(specs, localName, namespace, version, matches)
     if (implicitRole === false) {
         return permittedRoleList;
     }
-    const implicitRoles = implicitRole === 'presentation' || implicitRole === 'none' ? ['none', 'presentation'] : [implicitRole];
+    const implicitRoles = implicitRole === 'presentation' || implicitRole === 'none'
+        ? ['none', 'presentation']
+        : version === '1.3' && (implicitRole === 'img' || implicitRole === 'image')
+            ? ['image', 'img']
+            : [implicitRole];
     return mergeArray(implicitRoles.map(r => ({ name: r })), permittedRoleList);
 }
 function isAAMInfo(permittedRoles) {

package/lib/algorithm/aria/get-permitted-roles.d.ts

@@ -1,4 +1,13 @@
 import type { ARIAVersion, MLMLSpec } from '../../types/index.js';
+/**
+ * Retrieves the list of permitted ARIA roles that may be explicitly assigned
+ * to an element, based on its tag name, namespace, and current attribute state.
+ *
+ * @param el - The DOM element to determine permitted roles for
+ * @param version - The ARIA specification version to use
+ * @param specs - The full markup language specification
+ * @returns The permitted roles specification, which may be a boolean, an array of role names, or an AAM reference
+ */
 export declare function getPermittedRoles(el: Element, version: ARIAVersion, specs: MLMLSpec): readonly {
     readonly name: string;
     readonly deprecated?: boolean;

package/lib/algorithm/aria/get-permitted-roles.js

@@ -1,4 +1,13 @@
 import { getPermittedRoles as _getPermittedRoles } from './get-permitted-roles-spec.js';
+/**
+ * Retrieves the list of permitted ARIA roles that may be explicitly assigned
+ * to an element, based on its tag name, namespace, and current attribute state.
+ *
+ * @param el - The DOM element to determine permitted roles for
+ * @param version - The ARIA specification version to use
+ * @param specs - The full markup language specification
+ * @returns The permitted roles specification, which may be a boolean, an array of role names, or an AAM reference
+ */
 export function getPermittedRoles(
 // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
 el, version, specs) {

package/lib/algorithm/aria/get-role-spec.d.ts

@@ -1,5 +1,16 @@
 import type { ARIAVersion, ARIARoleInSchema, MLMLSpec, ARIARole } from '../../types/index.js';
 import type { NamespaceURI } from '@markuplint/ml-ast';
+/**
+ * Retrieves the full ARIA role specification for a given role name, including
+ * its properties, requirements, and the complete chain of super-class roles.
+ * For SVG namespace elements, also searches graphics ARIA roles.
+ *
+ * @param specs - The full markup language specification
+ * @param roleName - The name of the ARIA role to look up
+ * @param namespace - The namespace URI of the element context
+ * @param version - The ARIA specification version to use
+ * @returns The role specification with super-class roles, or null if the role does not exist
+ */
 export declare function getRoleSpec(specs: MLMLSpec, roleName: string, namespace: NamespaceURI, version: ARIAVersion): (ARIARole & {
     superClassRoles: ARIARoleInSchema[];
 }) | null;

package/lib/algorithm/aria/get-role-spec.js

@@ -1,16 +1,31 @@
 import { ariaSpecs } from './aria-specs.js';
+/**
+ * Retrieves the full ARIA role specification for a given role name, including
+ * its properties, requirements, and the complete chain of super-class roles.
+ * For SVG namespace elements, also searches graphics ARIA roles.
+ *
+ * @param specs - The full markup language specification
+ * @param roleName - The name of the ARIA role to look up
+ * @param namespace - The namespace URI of the element context
+ * @param version - The ARIA specification version to use
+ * @returns The role specification with super-class roles, or null if the role does not exist
+ */
 export function getRoleSpec(specs, roleName, namespace, version) {
     const role = getRoleByName(specs, roleName, namespace, version);
     if (!role) {
         return null;
     }
     const superClassRoles = recursiveTraverseSuperClassRoles(specs, roleName, namespace, version);
+    const requiredAccessibilityParentRole = role.requiredContextRole ?? role.requiredAccessibilityParentRole ?? [];
+    const allowedAccessibilityChildRoles = role.requiredOwnedElements ?? role.allowedAccessibilityChildRoles ?? [];
     return {
         name: role.name,
         isAbstract: !!role.isAbstract,
         deprecated: !!role.deprecated,
-        requiredContextRole: role.requiredContextRole ?? [],
-        requiredOwnedElements: role.requiredOwnedElements ?? [],
+        requiredAccessibilityParentRole,
+        allowedAccessibilityChildRoles,
+        requiredContextRole: requiredAccessibilityParentRole,
+        requiredOwnedElements: allowedAccessibilityChildRoles,
         accessibleNameRequired: !!role.accessibleNameRequired,
         accessibleNameFromAuthor: !!role.accessibleNameFromAuthor,
         accessibleNameFromContent: !!role.accessibleNameFromContent,
@@ -40,10 +55,13 @@ function getSuperClassRoles(specs, roleName, namespace, version) {
         .filter((role) => !!role) ?? null);
 }
 function getRoleByName(specs, roleName, namespace, version) {
-    const { roles, graphicsRoles } = ariaSpecs(specs, version);
+    const { roles, graphicsRoles, dpubRoles } = ariaSpecs(specs, version);
     let role = roles.find(r => r.name === roleName);
     if (!role && namespace === 'http://www.w3.org/2000/svg') {
         role = graphicsRoles.find(r => r.name === roleName);
     }
+    if (!role) {
+        role = dpubRoles.find(r => r.name === roleName);
+    }
     return role;
 }

package/lib/algorithm/aria/has-required-owned-elements.d.ts

@@ -1,3 +1,27 @@
 import type { ARIAVersion, ComputedRole, MLMLSpec } from '../../types/index.js';
+/**
+ * Checks whether an element satisfies the "Allowed Accessibility Child Roles"
+ * constraint (called "Required Owned Elements" in ARIA 1.2)
+ * defined by its computed ARIA role. An element satisfies this constraint if it
+ * has `aria-owns`, or if any of its closest non-presentational descendants match
+ * the required owned element roles.
+ *
+ * @param el - The DOM element to check
+ * @param specs - The full markup language specification
+ * @param version - The ARIA specification version to use
+ * @returns `true` if the element has no required owned elements or the constraint is satisfied, `false` otherwise
+ */
 export declare function hasRequiredOwnedElement(el: Element, specs: MLMLSpec, version: ARIAVersion): boolean;
+/**
+ * Determines whether an element with a given role matches a required owned element query.
+ * The query string may describe a single role or a parent-child relationship using `>` notation
+ * (e.g., `"listitem"` or `"group > listitem"`).
+ *
+ * @param el - The DOM element to test
+ * @param role - The computed role of the element
+ * @param query - The required owned element query string, optionally containing `>` for nested requirements
+ * @param specs - The full markup language specification
+ * @param version - The ARIA specification version to use
+ * @returns `true` if the element and its role match the required owned element query
+ */
 export declare function isRequiredOwnedElement(el: Element, role: ComputedRole['role'], query: string, specs: MLMLSpec, version: ARIAVersion): boolean;

package/lib/algorithm/aria/has-required-owned-elements.js

@@ -1,7 +1,19 @@
-import { isPresentational } from './is-presentational.js';
+import { isTransparentForOwnership } from './is-presentational.js';
 import { getComputedRole } from './get-computed-role.js';
 import { getExplicitRole } from './get-explicit-role.js';
 import { getImplicitRole } from './get-implicit-role.js';
+/**
+ * Checks whether an element satisfies the "Allowed Accessibility Child Roles"
+ * constraint (called "Required Owned Elements" in ARIA 1.2)
+ * defined by its computed ARIA role. An element satisfies this constraint if it
+ * has `aria-owns`, or if any of its closest non-presentational descendants match
+ * the required owned element roles.
+ *
+ * @param el - The DOM element to check
+ * @param specs - The full markup language specification
+ * @param version - The ARIA specification version to use
+ * @returns `true` if the element has no required owned elements or the constraint is satisfied, `false` otherwise
+ */
 export function hasRequiredOwnedElement(
 // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
 el, specs, version) {
@@ -18,10 +30,10 @@ el, specs, version) {
      * Otherwise, traverses descendants to find owned elements.
      */
     const computed = getComputedRole(specs, el, version);
-    if (!computed.role || computed.role.requiredOwnedElements.length === 0) {
+    if (!computed.role || computed.role.allowedAccessibilityChildRoles.length === 0) {
         return true;
     }
-    for (const expectRole of computed.role.requiredOwnedElements) {
+    for (const expectRole of computed.role.allowedAccessibilityChildRoles) {
         for (const owned of getClosestNonPresentationalDescendants(el, specs, version)) {
             if (isRequiredOwnedElement(owned.el, owned.role, expectRole, specs, version)) {
                 return true;
@@ -30,6 +42,18 @@ el, specs, version) {
     }
     return false;
 }
+/**
+ * Determines whether an element with a given role matches a required owned element query.
+ * The query string may describe a single role or a parent-child relationship using `>` notation
+ * (e.g., `"listitem"` or `"group > listitem"`).
+ *
+ * @param el - The DOM element to test
+ * @param role - The computed role of the element
+ * @param query - The required owned element query string, optionally containing `>` for nested requirements
+ * @param specs - The full markup language specification
+ * @param version - The ARIA specification version to use
+ * @returns `true` if the element and its role match the required owned element query
+ */
 export function isRequiredOwnedElement(
 // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
 el, role, query, specs, version) {
@@ -49,18 +73,20 @@ el, role, query, specs, version) {
 }
 /**
  * Gets the list of closest non-presentational descendants.
- * ⚠ THE SPECIFICATION HAS AN ISSUE
- * that has not decided whether the owned element is a child or a descendant.
+ * This corresponds to the "Allowed Accessibility Child Roles" validation
+ * (called "Required Owned Elements" in ARIA 1.2).
  *
- * @see https://github.com/w3c/aria/issues/1033
- * @see https://github.com/w3c/aria/issues/748
- * @see https://github.com/w3c/aria/pull/1162
- * @see https://github.com/w3c/aria/pull/1213
+ * In ARIA 1.1/1.2, the spec had not decided whether the owned element
+ * is a child or a descendant. This implementation interprets that as
+ * A CHILD, but `presentation`/`none` elements are treated as transparent.
  *
- * Currently, this process interprets that as A CHILD
- * because it wants to be near to HTML semantics.
- * However, the presentational role behaves transparently
- * according to the sample code in WAI-ARIA specification.
+ * ARIA 1.3 formally resolves this with the definitions of
+ * "accessibility child" and "accessibility parent", and additionally
+ * makes `generic` elements transparent.
+ *
+ * @see https://w3c.github.io/aria/#mustContain
+ * @see https://github.com/w3c/aria/issues/1033
+ * @see https://github.com/w3c/aria/pull/1454
  */
 function getClosestNonPresentationalDescendants(
 // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
@@ -69,7 +95,7 @@ el, specs, version) {
     for (const child of el.children) {
         const explicitRole = getExplicitRole(specs, child, version);
         const computed = explicitRole.role ? explicitRole : getImplicitRole(specs, child, version);
-        if (isPresentational(computed.role?.name)) {
+        if (isTransparentForOwnership(computed.role?.name, version)) {
             owned.push(...getClosestNonPresentationalDescendants(child, specs, version));
             continue;
         }

package/lib/algorithm/aria/is-exposed.d.ts

@@ -1,11 +1,14 @@
 import type { ARIAVersion, MLMLSpec } from '../../types/index.js';
 /**
- * Detect including/excluding from the Accessibility Tree
+ * Detects whether an element is included in (exposed to) the Accessibility Tree.
+ * Applies WAI-ARIA exclusion/inclusion rules, SVG rendering rules, and
+ * HTML metadata element filtering.
  *
  * @see https://www.w3.org/TR/wai-aria-1.2/#accessibility_tree
  *
- * @param specs
- * @param el
- * @param version
+ * @param el - The DOM element to check for accessibility tree exposure
+ * @param specs - The full markup language specification
+ * @param version - The ARIA specification version to use
+ * @returns `true` if the element should be exposed in the accessibility tree
  */
 export declare function isExposed(el: Element, specs: MLMLSpec, version: ARIAVersion): boolean;

package/lib/algorithm/aria/is-exposed.js

@@ -4,13 +4,16 @@ import { isPresentational } from './is-presentational.js';
 import { resolveNamespace } from '../../utils/resolve-namespace.js';
 import { getComputedRole } from './get-computed-role.js';
 /**
- * Detect including/excluding from the Accessibility Tree
+ * Detects whether an element is included in (exposed to) the Accessibility Tree.
+ * Applies WAI-ARIA exclusion/inclusion rules, SVG rendering rules, and
+ * HTML metadata element filtering.
  *
  * @see https://www.w3.org/TR/wai-aria-1.2/#accessibility_tree
  *
- * @param specs
- * @param el
- * @param version
+ * @param el - The DOM element to check for accessibility tree exposure
+ * @param specs - The full markup language specification
+ * @param version - The ARIA specification version to use
+ * @returns `true` if the element should be exposed in the accessibility tree
  */
 export function isExposed(
 // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types

package/lib/algorithm/aria/is-presentational.d.ts

@@ -1 +1,33 @@
+import type { ARIAVersion } from '../../types/index.js';
+/**
+ * Determines whether a given role name corresponds to a presentational role
+ * (`"presentation"` or `"none"`), which indicates the element should be
+ * excluded from the accessibility tree.
+ *
+ * @param roleName - The ARIA role name to check, or undefined
+ * @returns `true` if the role name is `"presentation"` or `"none"`, `false` otherwise
+ */
 export declare function isPresentational(roleName?: string): boolean;
+/**
+ * Determines whether a given role is transparent for ownership traversal.
+ *
+ * **Version behavior:**
+ * - **ARIA 1.1/1.2:** Only `presentation`/`none` are transparent.
+ *   This matches the pre-existing behavior of `getClosestNonPresentationalDescendants`
+ *   and `getNonPresentationalAncestor`.
+ * - **ARIA 1.3:** `generic` is additionally transparent per the spec:
+ *   "user agents MUST ignore any intervening elements with the role
+ *   `generic` or `none`."
+ *
+ * **Note:** `matchesContextRole` calls this function unconditionally
+ * (without a version gate) so that `presentation`/`none` are always
+ * transparent, consistent with `getNonPresentationalAncestor`.
+ *
+ * @see https://w3c.github.io/aria/#mustContain — "Allowed Accessibility Child Roles" (called "Required Owned Elements" in ARIA 1.2)
+ * @see https://w3c.github.io/aria/#scope — "Required Accessibility Parent Role" (called "Required Context Role" in ARIA 1.2)
+ *
+ * @param roleName - The ARIA role name to check, or undefined
+ * @param version - The ARIA specification version
+ * @returns `true` if the role should be skipped during ownership traversal
+ */
+export declare function isTransparentForOwnership(roleName: string | undefined, version: ARIAVersion): boolean;

package/lib/algorithm/aria/is-presentational.js

@@ -1,6 +1,45 @@
+/**
+ * Determines whether a given role name corresponds to a presentational role
+ * (`"presentation"` or `"none"`), which indicates the element should be
+ * excluded from the accessibility tree.
+ *
+ * @param roleName - The ARIA role name to check, or undefined
+ * @returns `true` if the role name is `"presentation"` or `"none"`, `false` otherwise
+ */
 export function isPresentational(roleName) {
     if (!roleName) {
         return false;
     }
     return ['presentation', 'none'].includes(roleName);
 }
+/**
+ * Determines whether a given role is transparent for ownership traversal.
+ *
+ * **Version behavior:**
+ * - **ARIA 1.1/1.2:** Only `presentation`/`none` are transparent.
+ *   This matches the pre-existing behavior of `getClosestNonPresentationalDescendants`
+ *   and `getNonPresentationalAncestor`.
+ * - **ARIA 1.3:** `generic` is additionally transparent per the spec:
+ *   "user agents MUST ignore any intervening elements with the role
+ *   `generic` or `none`."
+ *
+ * **Note:** `matchesContextRole` calls this function unconditionally
+ * (without a version gate) so that `presentation`/`none` are always
+ * transparent, consistent with `getNonPresentationalAncestor`.
+ *
+ * @see https://w3c.github.io/aria/#mustContain — "Allowed Accessibility Child Roles" (called "Required Owned Elements" in ARIA 1.2)
+ * @see https://w3c.github.io/aria/#scope — "Required Accessibility Parent Role" (called "Required Context Role" in ARIA 1.2)
+ *
+ * @param roleName - The ARIA role name to check, or undefined
+ * @param version - The ARIA specification version
+ * @returns `true` if the role should be skipped during ownership traversal
+ */
+export function isTransparentForOwnership(roleName, version) {
+    if (isPresentational(roleName)) {
+        return true;
+    }
+    if (version === '1.3' && roleName === 'generic') {
+        return true;
+    }
+    return false;
+}

package/lib/algorithm/aria/matches-context-role.d.ts

@@ -1,2 +1,21 @@
 import type { ARIAVersion, MLMLSpec } from '../../types/index.js';
+/**
+ * Checks whether an element's parent hierarchy satisfies the
+ * "Required Accessibility Parent Role" (called "Required Context Role" in ARIA 1.2).
+ * Each condition string may describe a chain of ancestor roles separated by
+ * ` > ` (e.g., `"list > group"`).
+ *
+ * TODO: This function only walks the DOM `parentElement` chain and does not
+ * consider `aria-owns` relationships. An element referenced by `aria-owns` on
+ * a remote ancestor should be treated as if it were an accessibility child of
+ * that ancestor. Implementing this requires a document-wide reverse lookup of
+ * `aria-owns` attributes, which is a separate architectural concern.
+ * See also: `has-required-owned-elements.ts` has a similar limitation.
+ *
+ * @param conditions - An array of required accessibility parent role condition strings to match against
+ * @param ownedEl - The owned DOM element whose parent context is being validated
+ * @param specs - The full markup language specification
+ * @param version - The ARIA specification version to use
+ * @returns `true` if any of the context role conditions are satisfied by the element's ancestors
+ */
 export declare function matchesContextRole(conditions: readonly string[], ownedEl: Element, specs: MLMLSpec, version: ARIAVersion): boolean;

package/lib/algorithm/aria/matches-context-role.js

@@ -1,4 +1,24 @@
+import { isTransparentForOwnership } from './is-presentational.js';
 import { getComputedRole } from './get-computed-role.js';
+/**
+ * Checks whether an element's parent hierarchy satisfies the
+ * "Required Accessibility Parent Role" (called "Required Context Role" in ARIA 1.2).
+ * Each condition string may describe a chain of ancestor roles separated by
+ * ` > ` (e.g., `"list > group"`).
+ *
+ * TODO: This function only walks the DOM `parentElement` chain and does not
+ * consider `aria-owns` relationships. An element referenced by `aria-owns` on
+ * a remote ancestor should be treated as if it were an accessibility child of
+ * that ancestor. Implementing this requires a document-wide reverse lookup of
+ * `aria-owns` attributes, which is a separate architectural concern.
+ * See also: `has-required-owned-elements.ts` has a similar limitation.
+ *
+ * @param conditions - An array of required accessibility parent role condition strings to match against
+ * @param ownedEl - The owned DOM element whose parent context is being validated
+ * @param specs - The full markup language specification
+ * @param version - The ARIA specification version to use
+ * @returns `true` if any of the context role conditions are satisfied by the element's ancestors
+ */
 export function matchesContextRole(conditions, 
 // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
 ownedEl, specs, version) {
@@ -7,13 +27,37 @@ ownedEl, specs, version) {
 function matchesCondition(condition, 
 // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
 parentEl, specs, version) {
-    const conditions = condition.split(/\s+>\s+/).reverse();
+    const conditions = condition.split(/\s+>\s+/).toReversed();
     while (conditions.length > 0) {
         if (!parentEl) {
             return false;
         }
-        const condition = conditions.shift();
         const parentRole = getComputedRole(specs, parentEl, version, true).role;
+        /**
+         * ARIA 1.3 ("Required Accessibility Parent Role"): "To determine
+         * whether an element has a parent with the required role, user agents
+         * MUST ignore any elements with the role `generic` or `none`."
+         *
+         * `presentation`/`none` are transparent in all ARIA versions to stay
+         * consistent with `getNonPresentationalAncestor` (which already skips
+         * them unconditionally). `generic` is additionally transparent in 1.3+
+         * per the spec.
+         *
+         * While the ARIA 1.1/1.2 specification text does not explicitly define
+         * this transparency for the context role check, applying it is a
+         * pragmatic choice: `getNonPresentationalAncestor` and `classifyChildren`
+         * (for owned elements) already skip `presentation`/`none` in all versions.
+         * Treating the context role check differently would create inconsistent
+         * behavior where a structure is valid from the parent's perspective
+         * (owned elements) but invalid from the child's perspective (context role).
+         *
+         * @see https://w3c.github.io/aria/#scope
+         */
+        if (isTransparentForOwnership(parentRole?.name, version)) {
+            parentEl = parentEl.parentElement;
+            continue;
+        }
+        const condition = conditions.shift();
         if (condition !== parentRole?.name) {
             return false;
         }

package/lib/algorithm/html/content-model-category-to-tag-names.d.ts

@@ -1,3 +1,12 @@
 import type { MLMLSpec } from '../../types/index.js';
 import type { Category } from '../../types/permitted-structures.js';
+/**
+ * Converts a content model category (e.g., `#flow`, `#phrasing`) to a sorted,
+ * frozen array of HTML/SVG tag names that belong to that category.
+ * Results are cached for repeated lookups.
+ *
+ * @param contentModel - The content model category identifier
+ * @param def - The specification definitions containing content model mappings
+ * @returns A frozen, sorted array of tag name strings belonging to the category
+ */
 export declare function contentModelCategoryToTagNames(contentModel: Category, def: MLMLSpec['def']): ReadonlyArray<string>;

package/lib/algorithm/html/content-model-category-to-tag-names.js

@@ -1,11 +1,20 @@
 const cache = new Map();
+/**
+ * Converts a content model category (e.g., `#flow`, `#phrasing`) to a sorted,
+ * frozen array of HTML/SVG tag names that belong to that category.
+ * Results are cached for repeated lookups.
+ *
+ * @param contentModel - The content model category identifier
+ * @param def - The specification definitions containing content model mappings
+ * @returns A frozen, sorted array of tag name strings belonging to the category
+ */
 export function contentModelCategoryToTagNames(contentModel, def) {
     const cached = cache.get(contentModel);
     if (cached) {
         return cached;
     }
     const tags = def['#contentModels'][contentModel];
-    const sortedTag = Object.freeze(tags && Array.isArray(tags) ? tags.sort() : []);
+    const sortedTag = Object.freeze(tags && Array.isArray(tags) ? tags.toSorted() : []);
     cache.set(contentModel, sortedTag);
     return sortedTag;
 }

package/lib/algorithm/html/get-content-model.d.ts

@@ -1,4 +1,15 @@
 import type { ElementSpec } from '../../types/index.js';
+import type { PermittedContentPattern } from '../../types/permitted-structures.js';
+import type { ReadonlyDeep } from 'type-fest';
 type Specs = readonly Pick<ElementSpec, 'name' | 'contentModel'>[];
-export declare function getContentModel(el: Element, specs: Specs): boolean | readonly (import("type-fest/source/readonly-deep.js").ReadonlyObjectDeep<import("../../types/permitted-structures.js").PermittedContentRequire> | import("type-fest/source/readonly-deep.js").ReadonlyObjectDeep<import("../../types/permitted-structures.js").PermittedContentOptional> | import("type-fest/source/readonly-deep.js").ReadonlyObjectDeep<import("../../types/permitted-structures.js").PermittedContentOneOrMore> | import("type-fest/source/readonly-deep.js").ReadonlyObjectDeep<import("../../types/permitted-structures.js").PermittedContentZeroOrMore> | import("type-fest/source/readonly-deep.js").ReadonlyObjectDeep<import("../../types/permitted-structures.js").PermittedContentChoice> | import("type-fest/source/readonly-deep.js").ReadonlyObjectDeep<import("../../types/permitted-structures.js").PermittedContentTransparent>)[] | null;
+/**
+ * Retrieves the permitted content model for an element. Evaluates any conditional
+ * content models based on the element's current attributes (e.g., different content
+ * models for `<ol>` vs `<ol reversed>`). Results are cached per element.
+ *
+ * @param el - The DOM element to retrieve the content model for
+ * @param specs - The element specifications containing content model definitions
+ * @returns The permitted content patterns array, a boolean (true for any content, false for no content), or null if no spec exists
+ */
+export declare function getContentModel(el: Element, specs: Specs): ReadonlyDeep<PermittedContentPattern[]> | boolean | null;
 export {};

package/lib/algorithm/html/get-content-model.js

@@ -1,25 +1,33 @@
 import { getSpec } from '../../utils/get-spec.js';
-const cachesBySpecs = new Map();
+const contentModelCache = new WeakMap();
+/**
+ * Retrieves the permitted content model for an element. Evaluates any conditional
+ * content models based on the element's current attributes (e.g., different content
+ * models for `<ol>` vs `<ol reversed>`). Results are cached per element.
+ *
+ * @param el - The DOM element to retrieve the content model for
+ * @param specs - The element specifications containing content model definitions
+ * @returns The permitted content patterns array, a boolean (true for any content, false for no content), or null if no spec exists
+ */
 export function getContentModel(
 // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
 el, specs) {
-    const cacheByEl = cachesBySpecs.get(specs) ?? new Map();
-    const cached = cacheByEl.get(el);
+    const cached = contentModelCache.get(el);
     if (cached !== undefined) {
         return cached;
     }
     const spec = getSpec(el, specs);
     if (!spec) {
-        cacheByEl.set(el, null);
+        contentModelCache.set(el, null);
         return null;
     }
     const conditions = spec.contentModel.conditional ?? [];
     for (const cond of conditions) {
         if (el.matches(cond.condition)) {
-            cacheByEl.set(el, cond.contents);
+            contentModelCache.set(el, cond.contents);
             return cond.contents;
         }
     }
-    cacheByEl.set(el, spec.contentModel.contents);
+    contentModelCache.set(el, spec.contentModel.contents);
     return spec.contentModel.contents;
 }

package/lib/algorithm/html/get-selectors-by-content-model-category.d.ts

@@ -1,3 +1,11 @@
 import type { MLMLSpec } from '../../types/index.js';
 import type { Category } from '../../types/permitted-structures.js';
+/**
+ * Retrieves the CSS selectors associated with a content model category from the spec definitions.
+ * These selectors can be used to match elements that belong to the given category.
+ *
+ * @param specs - The full markup language specification
+ * @param category - The content model category identifier (e.g., `#flow`, `#interactive`)
+ * @returns A readonly array of CSS selector strings for the category, or an empty array if the category is not defined
+ */
 export declare function getSelectorsByContentModelCategory(specs: MLMLSpec, category: Category): ReadonlyArray<string>;