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

package/lib/algorithm/aria/accname-computation.js

@@ -1,11 +1,141 @@
-// @ts-ignore
-import { computeAccessibleName } from 'dom-accessibility-api';
+import { computeAccessibleName } from './accname/compute.js';
+import { EMBEDDED_CONTROL_ROLES, escapeCSS } from './accname/helpers.js';
+import { isNativeEmbeddedControl } from '../../const/index.js';
+import { getComputedRole } from './get-computed-role.js';
+/**
+ * [Implementation-specific] Reentrant guard to prevent infinite recursion when
+ * getComputedRole evaluates `:aria(has name)` selectors, which call back into getAccname.
+ *
+ * This breaks the cycle: `getAccname → createDomResolver → allowsNameFromContent
+ * → getComputedRole → getARIA → matches(":aria(has name)") → getAccname`.
+ *
+ * Module-level state is intentional: the guard must span the entire call stack
+ * within a single synchronous computation. `WeakSet` ensures no memory leaks
+ * (entries are GC'd with their Element), and `try/finally` in `getAccname`
+ * guarantees cleanup even on exceptions.
+ */
+const computingElements = new WeakSet();
+/**
+ * Computes the accessible name for a DOM `Element` using the AccName 1.2 algorithm.
+ *
+ * This is the public facade that bridges the pure AccName algorithm (in `accname/compute.ts`)
+ * with the DOM environment. It creates a DOM-based `AccnameResolver` and delegates to
+ * `computeAccessibleName`.
+ *
+ * **Reentrant guard**: Uses a `WeakSet<Element>` to detect and short-circuit
+ * recursive calls caused by the `:aria(has name)` pseudo-class selector in
+ * `getComputedRole` → `getARIA` → `matches` chain.
+ *
+ * @param el - The DOM element to compute the accessible name for
+ * @param specs - The ML specification data for role resolution
+ * @param version - The ARIA version to use for role computation
+ * @returns The computed accessible name string, or an empty string if none is found
+ * @see https://www.w3.org/TR/accname-1.2/#computation-steps — AccName 1.2 §4.3.2
+ */
 export function getAccname(
 // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
+el, specs, version) {
+    if (computingElements.has(el)) {
+        return '';
+    }
+    computingElements.add(el);
+    const resolver = createDomResolver(el, specs, version);
+    // try/finally ensures the reentrant guard (WeakSet) is cleaned up even
+    // when computeAccessibleName throws. This is NOT a try/catch — exceptions
+    // propagate to the caller (ml-core's getAccname catches them).
+    try {
+        const result = computeAccessibleName(el, resolver);
+        return result.name;
+    }
+    finally {
+        computingElements.delete(el);
+    }
+}
+/**
+ * Creates an `AccnameResolver` from a DOM Element's owner document.
+ *
+ * [Implementation-specific] This resolver bridges the pure AccName algorithm
+ * with the DOM API. It uses `getComputedRole` for spec-driven role resolution
+ * (determining `allowsNameFromContent` and `isEmbeddedControl`) instead of
+ * hardcoded role lists, ensuring accuracy across ARIA versions.
+ */
+function createDomResolver(
+// eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
+el, specs, version) {
+    const root = getRootNode(el);
+    return {
+        getElementById(id) {
+            if ('getElementById' in root && typeof root.getElementById === 'function') {
+                return root.getElementById(id);
+            }
+            return root.querySelector(`[id="${escapeCSS(id)}"]`) ?? null;
+        },
+        getLabelsForId(id) {
+            const labels = root.querySelectorAll(`label[for="${escapeCSS(id)}"]`);
+            return [...labels];
+        },
+        // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
+        allowsNameFromContent(target) {
+            // TODO: Remove cast when getComputedRole accepts AccnameElement (#3178)
+            const role = getComputedRole(specs, target, version);
+            return !!role.role?.accessibleNameFromContent;
+        },
+        // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
+        isHidden(target) {
+            if (target.getAttribute('aria-hidden') === 'true') {
+                return true;
+            }
+            if (target.hasAttribute('hidden')) {
+                return true;
+            }
+            // Best-effort CSS visibility check (available in browser/JSDOM).
+            // getComputedStyle may throw on:
+            //   - SecurityError: cross-origin iframes
+            //   - TypeError: detached nodes not connected to a document
+            // These are expected operational failures. On error, fall through
+            // to return false (treat as visible). Attribute-based checks above
+            // (aria-hidden, hidden) are the primary detection for static analysis.
+            if (typeof getComputedStyle === 'function') {
+                try {
+                    // TODO: Remove cast when getComputedStyle dependency is decoupled (#3178)
+                    const style = getComputedStyle(target);
+                    if (style.display === 'none' || style.visibility === 'hidden') {
+                        return true;
+                    }
+                }
+                catch {
+                    // Swallowed intentionally: SecurityError or TypeError from
+                    // getComputedStyle is non-fatal. CSS hidden detection is
+                    // supplementary; attribute checks above cover static analysis.
+                }
+            }
+            return false;
+        },
+        // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
+        isEmbeddedControl(target) {
+            // TODO: Remove cast when getComputedRole accepts AccnameElement (#3178)
+            const role = getComputedRole(specs, target, version);
+            if (role.role?.name && EMBEDDED_CONTROL_ROLES.has(role.role.name)) {
+                return true;
+            }
+            // Native HTML embedded controls without explicit role
+            return isNativeEmbeddedControl(target);
+        },
+    };
+}
+/**
+ * Walks up the DOM tree to find the root node (Document or DocumentFragment).
+ */
+function getRootNode(
+// eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
 el) {
-    const name = computeAccessibleName(el);
-    if (!name.trim() && el.nodeName === 'INPUT') {
-        return el.getAttribute('placeholder')?.trim() ?? '';
+    let root = el;
+    while (root.parentNode) {
+        root = root.parentNode;
+    }
+    if (root.nodeType === 9 || root.nodeType === 11) {
+        return root;
     }
-    return name;
+    // Fallback: if we reach a disconnected element, use ownerDocument
+    return el.ownerDocument;
 }

package/lib/algorithm/aria/aria-specs.d.ts

@@ -1,6 +1,14 @@
 import type { ARIAVersion, MLMLSpec } from '../../types/index.js';
+/**
+ * Retrieves the ARIA specification data for a given ARIA version from the markup language spec.
+ *
+ * @param specs - The full markup language specification containing ARIA definitions
+ * @param version - The ARIA specification version to retrieve (e.g., '1.1', '1.2', '1.3')
+ * @returns The ARIA specification data including roles, properties, and graphics roles for the requested version
+ */
 export declare function ariaSpecs(specs: MLMLSpec, version: ARIAVersion): {
     readonly roles: readonly import("../../types/index.js").ARIARoleInSchema[];
     readonly graphicsRoles: readonly import("../../types/index.js").ARIARoleInSchema[];
+    readonly dpubRoles: readonly import("../../types/index.js").ARIARoleInSchema[];
     readonly props: readonly import("../../types/index.js").ARIAProperty[];
 };

package/lib/algorithm/aria/aria-specs.js

@@ -1,3 +1,10 @@
+/**
+ * Retrieves the ARIA specification data for a given ARIA version from the markup language spec.
+ *
+ * @param specs - The full markup language specification containing ARIA definitions
+ * @param version - The ARIA specification version to retrieve (e.g., '1.1', '1.2', '1.3')
+ * @returns The ARIA specification data including roles, properties, and graphics roles for the requested version
+ */
 export function ariaSpecs(specs, version) {
     const aria = specs.def['#aria'];
     return aria[version];

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

@@ -1,4 +1,16 @@
 import type { ARIA } from '../../types/aria.js';
 import type { ARIAVersion, Matches, MLMLSpec } from '../../types/index.js';
 import type { ReadonlyDeep } from 'type-fest';
+/**
+ * Retrieves the resolved ARIA specification for an element, taking into account
+ * ARIA version differences and conditional overrides based on the element's
+ * current attribute state (e.g., `input[type=checkbox]` vs `input[type=text]`).
+ *
+ * @param specs - The full markup language specification
+ * @param localName - The local tag name of the element
+ * @param namespace - The namespace URI of the element, or null
+ * @param version - The ARIA specification version to use
+ * @param matches - A function that tests whether the element matches a CSS selector
+ * @returns The resolved ARIA specification for the element, or null if no spec exists
+ */
 export declare function getARIA(specs: MLMLSpec, localName: string, namespace: string | null, version: ARIAVersion, matches: Matches): Omit<ReadonlyDeep<ARIA>, ARIAVersion | 'conditions'> | null;

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

@@ -1,6 +1,18 @@
 import { getSpecByTagName } from '../../utils/get-spec-by-tag-name.js';
 import { resolveVersion } from '../../utils/resolve-version.js';
 const cache = new Map();
+/**
+ * Retrieves the resolved ARIA specification for an element, taking into account
+ * ARIA version differences and conditional overrides based on the element's
+ * current attribute state (e.g., `input[type=checkbox]` vs `input[type=text]`).
+ *
+ * @param specs - The full markup language specification
+ * @param localName - The local tag name of the element
+ * @param namespace - The namespace URI of the element, or null
+ * @param version - The ARIA specification version to use
+ * @param matches - A function that tests whether the element matches a CSS selector
+ * @returns The resolved ARIA specification for the element, or null if no spec exists
+ */
 export function getARIA(specs, localName, namespace, version, matches) {
     const aria = getVersionResolvedARIA(specs, localName, namespace, version);
     if (!aria) {
@@ -13,7 +25,23 @@ export function getARIA(specs, localName, namespace, version, matches) {
     const conditionKeys = Object.keys(conditions);
     let { implicitRole, permittedRoles, implicitProperties, properties, namingProhibited } = aria;
     for (const cond of conditionKeys) {
-        if (!matches(cond)) {
+        let matched;
+        try {
+            matched = matches(cond);
+        }
+        catch (error) {
+            // Native Element.prototype.matches() cannot evaluate :aria()
+            // pseudo-class. When called from getImplicitRoleName() or
+            // getPermittedRoles() via accname-computation, native matches
+            // is used, which throws a DOMException (name: "SyntaxError").
+            // Note: JSDOM's DOMException is context-local, so instanceof
+            // checks against the global DOMException/SyntaxError fail.
+            if (error instanceof Error && error.name === 'SyntaxError') {
+                continue;
+            }
+            throw error;
+        }
+        if (!matched) {
             continue;
         }
         const condARIA = conditions[cond];
@@ -49,13 +77,13 @@ function getVersionResolvedARIA(specs, localName, namespace, version) {
     if (aria.permittedRoles !== false) {
         aria = {
             ...aria,
-            permittedRoles: optimizePermittedRoles(aria.permittedRoles),
+            permittedRoles: optimizePermittedRoles(aria.permittedRoles, version),
         };
     }
     cache.set(key, aria);
     return aria;
 }
-function optimizePermittedRoles(permittedRoles) {
+function optimizePermittedRoles(permittedRoles, version) {
     if (!Array.isArray(permittedRoles)) {
         return permittedRoles;
     }
@@ -67,5 +95,15 @@ function optimizePermittedRoles(permittedRoles) {
     if (unique.has('none')) {
         unique.add('presentation');
     }
-    return [...unique].sort();
+    // https://w3c.github.io/aria/#ref-for-image
+    // In ARIA 1.3, `image` is the primary role name and `img` is a synonym.
+    if (version === '1.3') {
+        if (unique.has('image')) {
+            unique.add('img');
+        }
+        if (unique.has('img')) {
+            unique.add('image');
+        }
+    }
+    return [...unique].toSorted();
 }

package/lib/algorithm/aria/get-computed-aria-props.d.ts

@@ -1,5 +1,11 @@
 import type { ARIAVersion, MLMLSpec } from '../../types/index.js';
+/**
+ * A record mapping ARIA property names to their computed property details.
+ */
 type ARIAProps = Record<string, ARIAProp>;
+/**
+ * Represents a single computed ARIA property with its resolved value and metadata.
+ */
 type ARIAProp = {
     name: string;
     value: string | undefined;
@@ -7,6 +13,22 @@ type ARIAProp = {
     deprecated: boolean;
     from: ARIAPropReferenceType;
 };
+/**
+ * Indicates the source from which an ARIA property value was derived:
+ * - `'default'`: The property's default value from the ARIA spec
+ * - `'html-attr'`: A value mapped from an equivalent HTML attribute
+ * - `'aria-attr'`: A value explicitly set via an `aria-*` attribute
+ */
 type ARIAPropReferenceType = 'default' | 'html-attr' | 'aria-attr';
+/**
+ * Computes the resolved ARIA properties for an element based on its computed role.
+ * Resolves property values by checking explicit `aria-*` attributes first,
+ * then equivalent HTML attributes, and finally falling back to spec-defined defaults.
+ *
+ * @param specs - The full markup language specification
+ * @param el - The DOM element to compute ARIA properties for
+ * @param version - The ARIA specification version to use
+ * @returns A record of ARIA property names to their computed property details, or an empty record if the element has no computed role
+ */
 export declare function getComputedAriaProps(specs: MLMLSpec, el: Element, version: ARIAVersion): ARIAProps;
 export {};

package/lib/algorithm/aria/get-computed-aria-props.js

@@ -1,5 +1,15 @@
 import { ariaSpecs as _ariaSpecs } from './aria-specs.js';
 import { getComputedRole } from './get-computed-role.js';
+/**
+ * Computes the resolved ARIA properties for an element based on its computed role.
+ * Resolves property values by checking explicit `aria-*` attributes first,
+ * then equivalent HTML attributes, and finally falling back to spec-defined defaults.
+ *
+ * @param specs - The full markup language specification
+ * @param el - The DOM element to compute ARIA properties for
+ * @param version - The ARIA specification version to use
+ * @returns A record of ARIA property names to their computed property details, or an empty record if the element has no computed role
+ */
 export function getComputedAriaProps(specs, 
 // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
 el, version) {

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

@@ -1,2 +1,14 @@
 import type { ARIAVersion, ComputedRole, MLMLSpec } from '../../types/index.js';
+/**
+ * Computes the final ARIA role for an element according to the WAI-ARIA specification,
+ * applying the Presentational Roles Conflict Resolution algorithm. This considers
+ * the explicit role, implicit role, required context roles, focusability,
+ * global ARIA properties, and SVG accessibility tree inclusion rules.
+ *
+ * @param specs - The full markup language specification
+ * @param el - The DOM element to compute the role for
+ * @param version - The ARIA specification version to use
+ * @param assumeSingleNode - When true, skips parent context validation and assumes the element is a standalone fragment
+ * @returns The computed role result including the resolved role spec (or null) and any error type
+ */
 export declare function getComputedRole(specs: MLMLSpec, el: Element, version: ARIAVersion, assumeSingleNode?: boolean): ComputedRole;

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

@@ -1,6 +1,7 @@
 import { ariaSpecs } from './aria-specs.js';
 import { isPresentational } from './is-presentational.js';
-import { getAccname } from './accname-computation.js';
+import { SVG_NAMESPACE } from '../../const/index.js';
+import { hasSvgAccessibleNameSource } from './accname/svg-helpers.js';
 import { getAttrSpecs } from '../../utils/get-attr-specs.js';
 import { getExplicitRole } from './get-explicit-role.js';
 import { getImplicitRole } from './get-implicit-role.js';
@@ -8,9 +9,58 @@ import { getNonPresentationalAncestor } from './get-non-presentational-ancestor.
 import { isRequiredOwnedElement } from './has-required-owned-elements.js';
 import { matchesContextRole } from './matches-context-role.js';
 import { mayBeFocusable } from '../html/may-be-focusable.js';
+/**
+ * Module-level cache for computed role results.
+ *
+ * Uses WeakMap so entries are automatically garbage-collected
+ * when the Element is released. Cache key format: `${version}:${assumeSingleNode}`.
+ *
+ * Invariants:
+ * - `specs` is always the same `MLMLSpec` instance within a document traversal,
+ *   so it is not included in the cache key.
+ * - Recursive calls from `computeRole` (via `getNonPresentationalAncestor`,
+ *   `matchesContextRole`, `isNativeContextIntact`) always traverse upward
+ *   in the DOM tree, so circular references cannot occur.
+ * - Cache entries become stale if an element's attributes are mutated after
+ *   computation. This is acceptable because markuplint operates on a static
+ *   document snapshot. External consumers that use the algorithm on a live
+ *   DOM with dynamic attribute mutations should be aware of this limitation.
+ */
+const computedRoleCache = new WeakMap();
+/**
+ * Computes the final ARIA role for an element according to the WAI-ARIA specification,
+ * applying the Presentational Roles Conflict Resolution algorithm. This considers
+ * the explicit role, implicit role, required context roles, focusability,
+ * global ARIA properties, and SVG accessibility tree inclusion rules.
+ *
+ * @param specs - The full markup language specification
+ * @param el - The DOM element to compute the role for
+ * @param version - The ARIA specification version to use
+ * @param assumeSingleNode - When true, skips parent context validation and assumes the element is a standalone fragment
+ * @returns The computed role result including the resolved role spec (or null) and any error type
+ */
 export function getComputedRole(specs, 
 // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
 el, version, assumeSingleNode = false) {
+    const cacheKey = `${version}:${assumeSingleNode}`;
+    const elCache = computedRoleCache.get(el);
+    if (elCache) {
+        const cached = elCache.get(cacheKey);
+        if (cached) {
+            return cached;
+        }
+    }
+    const result = computeRole(specs, el, version, assumeSingleNode);
+    const cache = elCache ?? new Map();
+    cache.set(cacheKey, result);
+    if (!elCache) {
+        computedRoleCache.set(el, cache);
+    }
+    return result;
+}
+function computeRole(specs, 
+// eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
+el, version, assumeSingleNode) {
     let lazyImplicitRole;
     const explicitRole = getExplicitRole(specs, el, version);
     const computedRole = explicitRole.role
@@ -36,24 +86,36 @@ el, version, assumeSingleNode = false) {
      * > causes the accessibility tree to be malformed,
      * > the expected results are undefined.
      *
-     * Determines whether the context is valid.
-     * ⚠ THE SPECIFICATION HAS AN ISSUE
-     * that has not decided whether the context is a parent or an ancestor.
+     * Determines whether the "Required Accessibility Parent Role" is valid
+     * (called "Required Context Role" 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 context
+     * is a parent or an ancestor. This implementation interprets that
+     * as A PARENT, but `presentation`/`none` elements are treated as
+     * transparent by `getNonPresentationalAncestor`.
+     *
+     * ARIA 1.3 formally resolves this with the definitions of
+     * "accessibility child" and "accessibility parent", and
+     * `matchesContextRole` additionally skips `generic` elements.
      *
-     * Currently, this process interprets that as A PARENT
-     * because it wants to be near to HTML semantics.
-     * However, the presentational role behaves transparently
-     * according to the sample code in WAI-ARIA specification.
+     * @see https://w3c.github.io/aria/#scope
+     * @see https://github.com/w3c/aria/issues/1033
+     * @see https://github.com/w3c/aria/pull/1454
      */
-    if (computedRole.role && computedRole.role.requiredContextRole.length > 0) {
+    if (computedRole.role &&
+        computedRole.role.requiredAccessibilityParentRole.length > 0 &&
+        // For implicit roles in native HTML contexts, skip the context role check
+        // when the direct parent retains its native semantics (no explicit role override
+        // and its own computed role is non-null). This handles spec data mismatches
+        // such as <option> inside <select>, where the ARIA spec requires "listbox"
+        // context but the HTML-ARIA mapping gives <select> the "combobox" role.
+        // When the parent HAS an explicit role or its computed role is null (cascaded
+        // from an ancestor override like <table role="none">), the check proceeds
+        // normally so that role nullification cascades correctly.
+        !isNativeContextIntact(computedRole, el, specs, version)) {
         /**
          * An element fragment that serves as the root without a parent element
-         * cannot satisfy the "Required Context Role" condition.
+         * cannot satisfy the "Required Accessibility Parent Role" condition.
          * Therefore, under normal circumstances, the `role` will disappear.
          * However, in this specific case, it will fall back to both explicit
          * and implicit roles. Note that the explicit role takes precedence.
@@ -72,7 +134,7 @@ el, version, assumeSingleNode = false) {
                 errorType: 'NO_OWNER',
             };
         }
-        if (!matchesContextRole(computedRole.role.requiredContextRole, el, specs, version)) {
+        if (!matchesContextRole(computedRole.role.requiredAccessibilityParentRole, el, specs, version)) {
             return {
                 el,
                 role: null,
@@ -114,15 +176,12 @@ el, version, assumeSingleNode = false) {
     // It doesn't been specified a valid explicit role.
     (explicitRole.role === null || explicitRole.errorType != null) &&
         // It is an SVG element.
-        el.namespaceURI === 'http://www.w3.org/2000/svg') {
-        const accname = getAccname(el).trim() ||
-            [...el.children].find(child => ['title', 'desc'].includes(child.localName))?.textContent?.trim();
-        if (!accname) {
-            return {
-                el,
-                role: null,
-            };
-        }
+        el.namespaceURI === SVG_NAMESPACE &&
+        !hasSvgAccessibleNameSource(el)) {
+        return {
+            el,
+            role: null,
+        };
     }
     if (computedRole.role && !isPresentational(computedRole.role.name)) {
         return computedRole;
@@ -181,8 +240,8 @@ el, version, assumeSingleNode = false) {
     if (explicitRole.role) {
         const nonPresentationalAncestor = getNonPresentationalAncestor(el, specs, version);
         if (nonPresentationalAncestor.role &&
-            nonPresentationalAncestor.role?.requiredOwnedElements.length > 0 &&
-            nonPresentationalAncestor.role.requiredOwnedElements.some(expected => {
+            nonPresentationalAncestor.role?.allowedAccessibilityChildRoles.length > 0 &&
+            nonPresentationalAncestor.role.allowedAccessibilityChildRoles.some(expected => {
                 // const ancestor = nonPresentationalAncestor.el;
                 // const ancestorImplicitRole = getImplicitRole(specs, ancestor, version);
                 // console.log({ nonPresentationalAncestor, ancestorImplicitRole });
@@ -240,3 +299,36 @@ el, predicate) {
     }
     return list.some(predicate);
 }
+/**
+ * Checks whether an element with an implicit role is in its native HTML
+ * context — i.e., the direct parent has no explicit role override and
+ * its own computed role is non-null.
+ *
+ * When this returns `true`, the context role check can be safely skipped
+ * because the native HTML parent-child relationship is intact, even if
+ * the ARIA spec data has a mismatch (e.g., `<option>` requires "listbox"
+ * but `<select>` maps to "combobox").
+ *
+ * When the parent has an explicit role (e.g., `<table role="none">`) or
+ * its computed role is `null` (cascaded from an ancestor override), the
+ * context is NOT considered intact and the check should proceed.
+ */
+function isNativeContextIntact(
+// eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
+computedRole, 
+// eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
+el, specs, version) {
+    if (!computedRole.role?.isImplicit) {
+        return false;
+    }
+    const parent = el.parentElement;
+    if (!parent) {
+        return false;
+    }
+    const parentExplicit = getExplicitRole(specs, parent, version);
+    if (parentExplicit.role) {
+        return false;
+    }
+    const parentComputed = getComputedRole(specs, parent, version);
+    return parentComputed.role !== null;
+}

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

@@ -1,2 +1,14 @@
 import type { ARIAVersion, ComputedRole, MLMLSpec } from '../../types/index.js';
+/**
+ * Resolves the ARIA role from the `role` attribute value, implementing the
+ * WAI-ARIA "Handling Author Errors" algorithm. Iterates through whitespace-separated
+ * role tokens and returns the first one that passes all validation checks
+ * (exists, non-abstract, permitted, valid landmark).
+ *
+ * @see https://w3c.github.io/aria/#document-handling_author-errors
+ * @param specs - The full markup language specification
+ * @param el - The DOM element to resolve the explicit role for
+ * @param version - The ARIA specification version to use
+ * @returns The first valid role found as a `ComputedRole`, or `role: null` with the last encountered error type
+ */
 export declare function getExplicitRole(specs: MLMLSpec, el: Element, version: ARIAVersion): ComputedRole;

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

@@ -1,6 +1,18 @@
 import { getRoleSpec } from './get-role-spec.js';
 import { resolveNamespace } from '../../utils/resolve-namespace.js';
 import { getPermittedRoles } from './get-permitted-roles.js';
+/**
+ * Resolves the ARIA role from the `role` attribute value, implementing the
+ * WAI-ARIA "Handling Author Errors" algorithm. Iterates through whitespace-separated
+ * role tokens and returns the first one that passes all validation checks
+ * (exists, non-abstract, permitted, valid landmark).
+ *
+ * @see https://w3c.github.io/aria/#document-handling_author-errors
+ * @param specs - The full markup language specification
+ * @param el - The DOM element to resolve the explicit role for
+ * @param version - The ARIA specification version to use
+ * @returns The first valid role found as a `ComputedRole`, or `role: null` with the last encountered error type
+ */
 export function getExplicitRole(specs, 
 // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
 el, version) {

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

@@ -1,4 +1,22 @@
 import type { ImplicitRole } from '../../types/aria.js';
 import type { ARIAVersion, ComputedRole, MLMLSpec } from '../../types/index.js';
+/**
+ * Determines the implicit (native) ARIA role for an element based on its tag name,
+ * namespace, and any matching conditions defined in the HTML-ARIA spec.
+ *
+ * @param specs - The full markup language specification
+ * @param el - The DOM element to determine the implicit role for
+ * @param version - The ARIA specification version to use
+ * @returns The computed role result containing the implicit role spec, or null if no corresponding role exists
+ */
 export declare function getImplicitRole(specs: MLMLSpec, el: Element, version: ARIAVersion): ComputedRole;
+/**
+ * Retrieves the implicit role name string for an element without resolving
+ * the full role specification. Returns `false` when no corresponding role exists.
+ *
+ * @param el - The DOM element to look up the implicit role name for
+ * @param version - The ARIA specification version to use
+ * @param specs - The full markup language specification
+ * @returns The implicit role name string, or `false` if the element has no corresponding role
+ */
 export declare function getImplicitRoleName(el: Element, version: ARIAVersion, specs: MLMLSpec): ImplicitRole;

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

@@ -1,6 +1,15 @@
 import { getImplicitRole as _getImplicitRole } from './get-implicit-role-spec.js';
 import { getRoleSpec } from './get-role-spec.js';
 import { resolveNamespace } from '../../utils/resolve-namespace.js';
+/**
+ * Determines the implicit (native) ARIA role for an element based on its tag name,
+ * namespace, and any matching conditions defined in the HTML-ARIA spec.
+ *
+ * @param specs - The full markup language specification
+ * @param el - The DOM element to determine the implicit role for
+ * @param version - The ARIA specification version to use
+ * @returns The computed role result containing the implicit role spec, or null if no corresponding role exists
+ */
 export function getImplicitRole(specs, 
 // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
 el, version) {
@@ -29,6 +38,15 @@ el, version) {
         },
     };
 }
+/**
+ * Retrieves the implicit role name string for an element without resolving
+ * the full role specification. Returns `false` when no corresponding role exists.
+ *
+ * @param el - The DOM element to look up the implicit role name for
+ * @param version - The ARIA specification version to use
+ * @param specs - The full markup language specification
+ * @returns The implicit role name string, or `false` if the element has no corresponding role
+ */
 export function getImplicitRoleName(
 // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
 el, version, specs) {

package/lib/algorithm/aria/get-non-presentational-ancestor.d.ts

@@ -1,4 +1,16 @@
 import type { ARIAVersion, MLMLSpec } from '../../types/index.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 declare function getNonPresentationalAncestor(el: Element, specs: MLMLSpec, version: ARIAVersion): import("../../types/index.js").ComputedRole | {
     el: null;
     role: null;