@markuplint/ml-core 5.3.0 → 5.4.0

package/CHANGELOG.md

@@ -3,6 +3,13 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+# [5.4.0](https://github.com/markuplint/markuplint/compare/v5.3.0...v5.4.0) (2026-10-29)
+
+### Features
+
+* **ml-core:** expose what the accessible name computation reaches ([2a29d84](https://github.com/markuplint/markuplint/commit/2a29d84ca196ad1808ede49e75796df7c599d2e8)), closes [#4408](https://github.com/markuplint/markuplint/issues/4408)
+
+
 # [5.3.0](https://github.com/markuplint/markuplint/compare/v5.2.0...v5.3.0) (2026-10-21)
 
 ### Bug Fixes

package/lib/ml-dom/helper/accname.d.ts

@@ -1,3 +1,27 @@
 import type { MLElement } from '../node/element.js';
-import type { ARIAVersion } from '@markuplint/ml-spec';
+import type { AccnameSource, AccnameVisit, ARIAVersion } from '@markuplint/ml-spec';
 export declare function getAccname(el: MLElement<any, any>, version: ARIAVersion): string;
+/**
+ * The elements that the computation of the element's text alternative reaches,
+ * with how it reaches each (see `AccnameResolver.onVisit` of `@markuplint/ml-spec`).
+ * Errors are handled as in {@link getAccname}: the computation is taken to reach
+ * nothing, so a caller that exempts what the computation reads (such as
+ * `no-aria-on-presentational-children`) exempts nothing for that element.
+ *
+ * @param el - The element whose text alternative is computed
+ * @param version - The ARIA version
+ * @param asReferenced - Computes it as a node referenced by `aria-labelledby` or
+ *   `aria-describedby` instead of its accessible name
+ */
+export declare function getAccnameVisits(el: MLElement<any, any>, version: ARIAVersion, asReferenced: boolean): ReadonlyMap<MLElement<any, any>, readonly AccnameVisit[]>;
+/**
+ * The text alternative of the element as a node referenced by `aria-labelledby`
+ * or `aria-describedby`. Errors are handled as in {@link getAccname}.
+ */
+export declare function getReferencedTextAlternative(el: MLElement<any, any>, version: ARIAVersion): string;
+/**
+ * The source of the host language text alternative of the element (AccName
+ * Step 2E), whether or not the element is exposed as presentational. Errors are
+ * handled as in {@link getAccname}: the element is taken to have none.
+ */
+export declare function getHostLanguageLabelSource(el: MLElement<any, any>, version: ARIAVersion): AccnameSource | null;

package/lib/ml-dom/helper/accname.js

@@ -1,4 +1,4 @@
-import { computeAccessibleName, escapeCSS, getComputedRole, EMBEDDED_CONTROL_ROLES, isNativeEmbeddedControl, } from '@markuplint/ml-spec';
+import { computeAccessibleName, computeHostLanguageLabel, computeReferencedTextAlternative, escapeCSS, getComputedRole, EMBEDDED_CONTROL_ROLES, isExposedAsPresentational, isNativeEmbeddedControl, } from '@markuplint/ml-spec';
 import { log } from '../../debug.js';
 const accnameLog = log.extend('accname');
 export function getAccname(
@@ -23,13 +23,89 @@ el, version) {
         return result.name;
     }
     catch (error) {
-        if (accnameLog.enabled) {
-            accnameLog('Raw: %s', el.raw);
-            accnameLog('Error: %O', error);
+        logFailure(el, error);
+        return '';
+    }
+}
+/**
+ * The elements that the computation of the element's text alternative reaches,
+ * with how it reaches each (see `AccnameResolver.onVisit` of `@markuplint/ml-spec`).
+ * Errors are handled as in {@link getAccname}: the computation is taken to reach
+ * nothing, so a caller that exempts what the computation reads (such as
+ * `no-aria-on-presentational-children`) exempts nothing for that element.
+ *
+ * @param el - The element whose text alternative is computed
+ * @param version - The ARIA version
+ * @param asReferenced - Computes it as a node referenced by `aria-labelledby` or
+ *   `aria-describedby` instead of its accessible name
+ */
+export function getAccnameVisits(
+// eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
+el, version, asReferenced) {
+    const visits = new Map();
+    try {
+        const resolver = {
+            ...createMLCoreResolver(el, version),
+            onVisit(target, visit) {
+                // TODO: Remove cast when AccnameResolver is generic (#3178)
+                const targetEl = target;
+                const list = visits.get(targetEl) ?? [];
+                list.push(visit);
+                visits.set(targetEl, list);
+            },
+        };
+        if (asReferenced) {
+            computeReferencedTextAlternative(el, resolver);
+        }
+        else {
+            computeAccessibleName(el, resolver);
         }
+        return visits;
+    }
+    catch (error) {
+        logFailure(el, error);
+        return new Map();
+    }
+}
+/**
+ * The text alternative of the element as a node referenced by `aria-labelledby`
+ * or `aria-describedby`. Errors are handled as in {@link getAccname}.
+ */
+export function getReferencedTextAlternative(
+// eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
+el, version) {
+    try {
+        return computeReferencedTextAlternative(el, createMLCoreResolver(el, version)).name;
+    }
+    catch (error) {
+        logFailure(el, error);
         return '';
     }
 }
+/**
+ * The source of the host language text alternative of the element (AccName
+ * Step 2E), whether or not the element is exposed as presentational. Errors are
+ * handled as in {@link getAccname}: the element is taken to have none.
+ */
+export function getHostLanguageLabelSource(
+// eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
+el, version) {
+    try {
+        return computeHostLanguageLabel(el, createMLCoreResolver(el, version))?.source ?? null;
+    }
+    catch (error) {
+        logFailure(el, error);
+        return null;
+    }
+}
+function logFailure(
+// eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
+el, error) {
+    if (accnameLog.enabled) {
+        accnameLog('Raw: %s', el.raw);
+        accnameLog('Error: %O', error);
+    }
+}
 function createMLCoreResolver(
 // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
 el, version) {
@@ -63,6 +139,11 @@ el, version) {
             return isNativeEmbeddedControl(target);
         },
         // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
+        isExposedAsPresentational(target) {
+            // TODO: Remove cast when getComputedRole accepts AccnameElement (#3178)
+            return isExposedAsPresentational(getComputedRole(doc.specs, target, version));
+        },
+        // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
         getPrecomputedName(target) {
             // TODO: Remove cast when AccnameResolver is generic (#3178)
             const targetEl = target;

package/lib/ml-dom/node/element.d.ts

@@ -5,7 +5,7 @@ import type { MLText } from './text.js';
 import type { ElementNodeType, PretenderContext } from './types.js';
 import type { ElementType, MLASTBlockBehavior, MLASTElement, NamespaceURI } from '@markuplint/ml-ast';
 import type { PlainData, Pretender, RegexSelector, RuleConfigValue, RuleInfo } from '@markuplint/ml-config';
-import type { ARIAVersion } from '@markuplint/ml-spec';
+import type { AccnameSource, AccnameVisit, ARIAVersion } from '@markuplint/ml-spec';
 import type { SelectorMatches } from '@markuplint/selector';
 import { MLAttr } from './attr.js';
 import { MLDomTokenList } from './dom-token-list.js';
@@ -1968,6 +1968,44 @@ export declare class MLElement<T extends RuleConfigValue, O extends PlainData =
      * @returns The computed accessible name string (may be empty)
      */
     getAccessibleName(version: ARIAVersion): string;
+    /**
+     * Returns the elements that the computation of this element's text
+     * alternative reaches, with how it reaches each, memoized per ARIA version
+     * and mode like {@link getAccessibleName}.
+     *
+     * A descendant missing from the map takes no part in the text alternative:
+     * the computation ends before it (a hidden element, a name given before
+     * content, a component that does not render its children). When the
+     * computation fails, the map is empty.
+     *
+     * @implements `@markuplint/ml-core` API: `MLElement`
+     * @param version - The ARIA specification version to use for computation
+     * @param asReferenced - Computes it as a node referenced by `aria-labelledby`
+     *   or `aria-describedby` instead of as this element's accessible name
+     * @returns The reached elements and their visits
+     */
+    getAccessibleNameVisits(version: ARIAVersion, asReferenced?: boolean): ReadonlyMap<MLElement<any, any>, readonly AccnameVisit[]>;
+    /**
+     * Returns the text alternative of this element as a node referenced by
+     * `aria-labelledby` or `aria-describedby` (AccName Step 2B, LabelledBy
+     * Traversal), memoized per ARIA version like {@link getAccessibleName}.
+     *
+     * @implements `@markuplint/ml-core` API: `MLElement`
+     * @param version - The ARIA specification version to use for computation
+     * @returns The text alternative (may be empty)
+     */
+    getReferencedTextAlternative(version: ARIAVersion): string;
+    /**
+     * Returns the source of this element's host language text alternative
+     * (AccName Step 2E), such as `'alt'` or `'svg-title'`, whether or not an
+     * explicit `none` or `presentation` role keeps it out of the name.
+     * Memoized per ARIA version like {@link getAccessibleName}.
+     *
+     * @implements `@markuplint/ml-core` API: `MLElement`
+     * @param version - The ARIA specification version to use for computation
+     * @returns The source, or `null` if the element has no host language text alternative
+     */
+    getHostLanguageLabelSource(version: ARIAVersion): AccnameSource | null;
     /**
      * **IT THROWS AN ERROR WHEN CALLING THIS.**
      *

package/lib/ml-dom/node/element.js

@@ -4,7 +4,7 @@ import { getSpecByTagName, resolveNamespace } from '@markuplint/ml-spec';
 import { pretenderNamespaceToURI } from '@markuplint/ml-config';
 import { getChildNamespace } from '@markuplint/parser-utils';
 import { matchSelector, typeNameMatches } from '@markuplint/selector';
-import { getAccname } from '../helper/accname.js';
+import { getAccname, getAccnameVisits, getHostLanguageLabelSource, getReferencedTextAlternative, } from '../helper/accname.js';
 import { after, before, nextElementSibling, previousElementSibling, remove, replaceWith, } from '../manipulations/child-node-methods.js';
 import { MLAttr } from './attr.js';
 import { MLDomTokenList } from './dom-token-list.js';
@@ -227,6 +227,21 @@ export class MLElement extends MLParentNode {
      * @see {@link getAccessibleName} — the public method that reads/writes this cache
      */
     #accessibleNameCache = new Map();
+    /**
+     * Memoizes {@link getAccessibleNameVisits}, keyed by `${version}:${asReferenced}`.
+     * Safe for the same reason as {@link #accessibleNameCache}.
+     */
+    #accessibleNameVisitsCache = new Map();
+    /**
+     * Memoizes {@link getHostLanguageLabelSource}. Safe for the same reason as
+     * {@link #accessibleNameCache}.
+     */
+    #hostLanguageLabelSourceCache = new Map();
+    /**
+     * Memoizes {@link getReferencedTextAlternative}. Safe for the same reason as
+     * {@link #accessibleNameCache}.
+     */
+    #referencedTextAlternativeCache = new Map();
     #normalizedAttrs = new Map();
     #normalizedString = null;
     ontouchcancel;
@@ -2589,6 +2604,68 @@ export class MLElement extends MLParentNode {
         this.#accessibleNameCache.set(version, name);
         return name;
     }
+    /**
+     * Returns the elements that the computation of this element's text
+     * alternative reaches, with how it reaches each, memoized per ARIA version
+     * and mode like {@link getAccessibleName}.
+     *
+     * A descendant missing from the map takes no part in the text alternative:
+     * the computation ends before it (a hidden element, a name given before
+     * content, a component that does not render its children). When the
+     * computation fails, the map is empty.
+     *
+     * @implements `@markuplint/ml-core` API: `MLElement`
+     * @param version - The ARIA specification version to use for computation
+     * @param asReferenced - Computes it as a node referenced by `aria-labelledby`
+     *   or `aria-describedby` instead of as this element's accessible name
+     * @returns The reached elements and their visits
+     */
+    getAccessibleNameVisits(version, asReferenced = false) {
+        const key = `${version}:${asReferenced}`;
+        const cached = this.#accessibleNameVisitsCache.get(key);
+        if (cached != null) {
+            return cached;
+        }
+        const visits = getAccnameVisits(this, version, asReferenced);
+        this.#accessibleNameVisitsCache.set(key, visits);
+        return visits;
+    }
+    /**
+     * Returns the text alternative of this element as a node referenced by
+     * `aria-labelledby` or `aria-describedby` (AccName Step 2B, LabelledBy
+     * Traversal), memoized per ARIA version like {@link getAccessibleName}.
+     *
+     * @implements `@markuplint/ml-core` API: `MLElement`
+     * @param version - The ARIA specification version to use for computation
+     * @returns The text alternative (may be empty)
+     */
+    getReferencedTextAlternative(version) {
+        const cached = this.#referencedTextAlternativeCache.get(version);
+        if (cached != null) {
+            return cached;
+        }
+        const text = getReferencedTextAlternative(this, version);
+        this.#referencedTextAlternativeCache.set(version, text);
+        return text;
+    }
+    /**
+     * Returns the source of this element's host language text alternative
+     * (AccName Step 2E), such as `'alt'` or `'svg-title'`, whether or not an
+     * explicit `none` or `presentation` role keeps it out of the name.
+     * Memoized per ARIA version like {@link getAccessibleName}.
+     *
+     * @implements `@markuplint/ml-core` API: `MLElement`
+     * @param version - The ARIA specification version to use for computation
+     * @returns The source, or `null` if the element has no host language text alternative
+     */
+    getHostLanguageLabelSource(version) {
+        if (this.#hostLanguageLabelSourceCache.has(version)) {
+            return this.#hostLanguageLabelSourceCache.get(version) ?? null;
+        }
+        const source = getHostLanguageLabelSource(this, version);
+        this.#hostLanguageLabelSourceCache.set(version, source);
+        return source;
+    }
     /**
      * **IT THROWS AN ERROR WHEN CALLING THIS.**
      *

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@markuplint/ml-core",
-	"version": "5.3.0",
+	"version": "5.4.0",
 	"description": "The core module of markuplint",
 	"repository": {
 		"type": "git",
@@ -34,20 +34,20 @@
 		"./lib/configs.js": "./lib/configs.browser.js"
 	},
 	"dependencies": {
-		"@markuplint/config-presets": "5.3.0",
-		"@markuplint/html-parser": "5.3.0",
-		"@markuplint/html-spec": "5.3.0",
+		"@markuplint/config-presets": "5.4.0",
+		"@markuplint/html-parser": "5.4.0",
+		"@markuplint/html-spec": "5.4.0",
 		"@markuplint/i18n": "5.3.0",
 		"@markuplint/ml-ast": "5.3.0",
-		"@markuplint/ml-config": "5.3.0",
-		"@markuplint/ml-spec": "5.3.0",
-		"@markuplint/parser-utils": "5.3.0",
-		"@markuplint/selector": "5.3.0",
-		"@markuplint/shared": "5.3.0",
+		"@markuplint/ml-config": "5.4.0",
+		"@markuplint/ml-spec": "5.4.0",
+		"@markuplint/parser-utils": "5.4.0",
+		"@markuplint/selector": "5.4.0",
+		"@markuplint/shared": "5.4.0",
 		"@types/debug": "^4.1.13",
 		"debug": "^4.4.3",
 		"is-plain-object": "^5.1.0",
 		"type-fest": "^5.10.0"
 	},
-	"gitHead": "f587cf0206c8426e57369a48d6d5fb22306eafde"
+	"gitHead": "647f6fb5d5743f060678599c97e9c84b58970747"
 }