@markuplint/ml-spec 5.3.0 → 5.5.0

package/lib/algorithm/aria/accname/helpers.d.ts

@@ -1,16 +1,24 @@
-import type { AccnameElement, AccnameNode, AccnameResolver, AccnameResult, AccnameSource } from './types.js';
+import type { AccnameComputeFn, AccnameElement, AccnameNode, AccnameResolver } from './types.js';
 export { EMBEDDED_CONTROL_ROLES } from '../../../const/index.js';
-export declare function makeResult(name: string, source: AccnameSource | null): AccnameResult;
-export declare function flattenText(text: string): string;
 /**
  * Implements AccName 1.2 §4.3.2 Steps 2F and 2C:
  *
- * - **Step 2F**: "If the current node's role allows name from content [...],
- *   return the accumulated text of the current node's descendant nodes."
- * - **Step 2C (Embedded Controls)**: "If the current node is a descendant of
- *   an `aria-labelledby` or `aria-label` reference AND the current node is
- *   an embedded control, return the embedded control's value." Per spec,
- *   `aria-label` is ignored for embedded controls during this traversal.
+ * **Step 2F**, the name from content:
+ *
+ * > Otherwise, if the current node's role allows name from content, or if the current node is referenced by
+ * > aria-labelledby, aria-describedby, or is a native host language text alternative element (e.g. label in HTML),
+ * > or is a descendant of a native host language text alternative element:
+ *
+ * **Step 2C**, the embedded controls:
+ *
+ * > Otherwise, if the current node is a control embedded within the label (e.g. any element directly referenced by
+ * > aria-labelledby) for another widget, where the user can adjust the embedded control's value, then return the
+ * > embedded control as part of the text alternative in the following manner:
+ *
+ * `aria-label` is ignored for an embedded control during this traversal:
+ *
+ * > If traversal of the current node is due to Name From Content descendant node recursion and the current node is an
+ * > embedded control, ignore aria-label and skip to rule Embedded Control.
  *
  * **Limitation:** CSS-generated content (`::before`/`::after` with the `content`
  * property) is not included. AccName 1.2 §4.3.2 Step 2G specifies that CSS
@@ -18,10 +26,22 @@ export declare function flattenText(text: string): string;
  * performs static HTML analysis without CSS processing, so this content is
  * unavailable at lint time.
  *
- * @see https://www.w3.org/TR/accname-1.2/#computation-steps — AccName 1.2 §4.3.2 Step 2F
- * @see https://www.w3.org/TR/accname-1.2/#comp_embedded_control — AccName 1.2 §4.3.2 Step 2C
+ * @see https://w3c.github.io/accname/#computation-steps — AccName 1.2 §4.3.2 Step 2F
+ * @see https://w3c.github.io/accname/#comp_embedded_control — AccName 1.2 §4.3.2 Step 2C
+ */
+export declare function resolveNameFromContent(el: AccnameElement, resolver: AccnameResolver, visited: ReadonlySet<string>, computeFn: AccnameComputeFn, inLabelledbyTraversal: boolean): string;
+/**
+ * The text an embedded control reached by name-from-content recursion
+ * contributes, in the order of AccName §4.3.2: nothing when it is hidden
+ * (Step 2A), the text of its `aria-labelledby` outside an ongoing
+ * `aria-labelledby` traversal (Step 2B), otherwise its value (Step 2C), as its
+ * `aria-label` is ignored (Step 2D).
+ *
+ * @see https://w3c.github.io/accname/#comp_label
+ *
+ * > If traversal of the current node is due to Name From Content descendant node recursion and the current node is an embedded control, ignore aria-label and skip to rule Embedded Control.
  */
-export declare function resolveNameFromContent(el: AccnameElement, resolver: AccnameResolver, visited: ReadonlySet<string>, computeFn: (el: AccnameElement, resolver: AccnameResolver, inLabelledbyTraversal: boolean, visited: ReadonlySet<string>) => AccnameResult, inLabelledbyTraversal: boolean): string;
+export declare function embeddedControlText(el: AccnameElement, resolver: AccnameResolver, visited: ReadonlySet<string>, computeFn: AccnameComputeFn, inLabelledbyTraversal: boolean): string;
 /**
  * The child nodes to traverse for `el`: what the resolver says it renders,
  * or `el.childNodes` when it says nothing.
@@ -34,10 +54,30 @@ export declare function getChildNodes(el: AccnameElement, resolver: AccnameResol
  */
 export declare function getTextContent(el: AccnameElement, resolver: AccnameResolver): string;
 export declare function findChildByLocalName(el: AccnameElement, localName: string, resolver?: AccnameResolver): AccnameElement | null;
+/**
+ * The closest `label` element among the ancestors of the element, which names the element when it is
+ * its labeled control. The ancestors are those of its own tree, as the HTML Standard defines the
+ * relation between a `label` and its labeled control by ancestors in the tree, so a `label` that
+ * wraps a `template` element does not label a control in its content.
+ *
+ * @see https://html.spec.whatwg.org/multipage/forms.html#labeled-control
+ *
+ * @param el - The element to start from
+ * @returns The closest `label` ancestor, or `null`
+ */
 export declare function findAncestorLabel(el: AccnameElement): AccnameElement | null;
 export declare function resolveLabel(el: AccnameElement, resolver: AccnameResolver): readonly AccnameElement[];
 export declare function getInputType(el: AccnameElement): string;
 export declare function isSvgElement(el: AccnameElement): boolean;
+/**
+ * Whether the element is an SVG `title` or `desc`. They are never rendered,
+ * so their text is not content of the parent: a `title` gives the name only
+ * through Step 2E of its parent (`handleSvgElement`), which an element exposed
+ * as presentational skips.
+ *
+ * @see https://svgwg.org/svg2-draft/render.html#TermNeverRenderedElement
+ */
+export declare function isSvgDescriptiveElement(el: AccnameElement): boolean;
 /**
  * Escapes a string for safe use inside a CSS selector.
  *

package/lib/algorithm/aria/accname/helpers.js

@@ -1,25 +1,27 @@
 /* eslint-disable @typescript-eslint/prefer-readonly-parameter-types -- AccnameElement wraps mutable DOM types */
 import { ELEMENT_NODE, SVG_NAMESPACE, TEXT_NODE, TEXT_LIKE_INPUT_TYPES } from '../../../const/index.js';
+import { getTreeParentElement } from '../../dom/tree-boundary.js';
+import { resolveAriaLabelledby } from './aria-steps.js';
 export { EMBEDDED_CONTROL_ROLES } from '../../../const/index.js';
-export function makeResult(name, source) {
-    const trimmed = flattenText(name);
-    return {
-        name: trimmed,
-        source: trimmed ? source : null,
-    };
-}
-export function flattenText(text) {
-    return text.replaceAll(/\s+/g, ' ').trim();
-}
 /**
  * Implements AccName 1.2 §4.3.2 Steps 2F and 2C:
  *
- * - **Step 2F**: "If the current node's role allows name from content [...],
- *   return the accumulated text of the current node's descendant nodes."
- * - **Step 2C (Embedded Controls)**: "If the current node is a descendant of
- *   an `aria-labelledby` or `aria-label` reference AND the current node is
- *   an embedded control, return the embedded control's value." Per spec,
- *   `aria-label` is ignored for embedded controls during this traversal.
+ * **Step 2F**, the name from content:
+ *
+ * > Otherwise, if the current node's role allows name from content, or if the current node is referenced by
+ * > aria-labelledby, aria-describedby, or is a native host language text alternative element (e.g. label in HTML),
+ * > or is a descendant of a native host language text alternative element:
+ *
+ * **Step 2C**, the embedded controls:
+ *
+ * > Otherwise, if the current node is a control embedded within the label (e.g. any element directly referenced by
+ * > aria-labelledby) for another widget, where the user can adjust the embedded control's value, then return the
+ * > embedded control as part of the text alternative in the following manner:
+ *
+ * `aria-label` is ignored for an embedded control during this traversal:
+ *
+ * > If traversal of the current node is due to Name From Content descendant node recursion and the current node is an
+ * > embedded control, ignore aria-label and skip to rule Embedded Control.
  *
  * **Limitation:** CSS-generated content (`::before`/`::after` with the `content`
  * property) is not included. AccName 1.2 §4.3.2 Step 2G specifies that CSS
@@ -27,8 +29,8 @@ export function flattenText(text) {
  * performs static HTML analysis without CSS processing, so this content is
  * unavailable at lint time.
  *
- * @see https://www.w3.org/TR/accname-1.2/#computation-steps — AccName 1.2 §4.3.2 Step 2F
- * @see https://www.w3.org/TR/accname-1.2/#comp_embedded_control — AccName 1.2 §4.3.2 Step 2C
+ * @see https://w3c.github.io/accname/#computation-steps — AccName 1.2 §4.3.2 Step 2F
+ * @see https://w3c.github.io/accname/#comp_embedded_control — AccName 1.2 §4.3.2 Step 2C
  */
 export function resolveNameFromContent(el, resolver, visited, computeFn, inLabelledbyTraversal) {
     const parts = [];
@@ -38,9 +40,12 @@ export function resolveNameFromContent(el, resolver, visited, computeFn, inLabel
         }
         else if (child.nodeType === ELEMENT_NODE) {
             const childEl = child;
+            if (isSvgDescriptiveElement(childEl)) {
+                continue;
+            }
             if (resolver.isEmbeddedControl(childEl)) {
                 // Step 2C: Embedded controls — use value directly, aria-label is ignored
-                parts.push(getEmbeddedControlValue(childEl, resolver));
+                parts.push(embeddedControlText(childEl, resolver, visited, computeFn, inLabelledbyTraversal));
             }
             else {
                 const result = computeFn(childEl, resolver, inLabelledbyTraversal, visited);
@@ -84,8 +89,11 @@ function collectTextContent(el, resolver, visited, computeFn, inLabelledbyTraver
         }
         else if (child.nodeType === ELEMENT_NODE) {
             const childEl = child;
+            if (isSvgDescriptiveElement(childEl)) {
+                continue;
+            }
             if (resolver.isEmbeddedControl(childEl)) {
-                parts.push(getEmbeddedControlValue(childEl, resolver));
+                parts.push(embeddedControlText(childEl, resolver, visited, computeFn, inLabelledbyTraversal));
             }
             else {
                 const result = computeFn(childEl, resolver, inLabelledbyTraversal, visited);
@@ -100,6 +108,31 @@ function collectTextContent(el, resolver, visited, computeFn, inLabelledbyTraver
     }
     return parts.join(' ');
 }
+/**
+ * The text an embedded control reached by name-from-content recursion
+ * contributes, in the order of AccName §4.3.2: nothing when it is hidden
+ * (Step 2A), the text of its `aria-labelledby` outside an ongoing
+ * `aria-labelledby` traversal (Step 2B), otherwise its value (Step 2C), as its
+ * `aria-label` is ignored (Step 2D).
+ *
+ * @see https://w3c.github.io/accname/#comp_label
+ *
+ * > If traversal of the current node is due to Name From Content descendant node recursion and the current node is an embedded control, ignore aria-label and skip to rule Embedded Control.
+ */
+export function embeddedControlText(el, resolver, visited, computeFn, inLabelledbyTraversal) {
+    const hidden = resolver.isHidden(el);
+    resolver.onVisit?.(el, { hidden, embeddedControl: true, inLabelledbyTraversal });
+    if (hidden) {
+        return '';
+    }
+    if (!inLabelledbyTraversal) {
+        const labelledby = resolveAriaLabelledby(el, resolver, visited, computeFn);
+        if (labelledby) {
+            return labelledby.name;
+        }
+    }
+    return getEmbeddedControlValue(el, resolver);
+}
 /**
  * Implements AccName 1.2 §4.3.2 Step 2C embedded control value resolution:
  * - **Range controls** (slider/spinbutton/input[range]):
@@ -108,7 +141,7 @@ function collectTextContent(el, resolver, visited, computeFn, inLabelledbyTraver
  *   value attr → textContent
  * - **Listbox** (select): selected option text (static analysis approximation)
  *
- * @see https://www.w3.org/TR/accname-1.2/#comp_embedded_control — AccName 1.2 §4.3.2 Step 2C
+ * @see https://w3c.github.io/accname/#comp_embedded_control — AccName 1.2 §4.3.2 Step 2C
  */
 function getEmbeddedControlValue(el, resolver) {
     const role = el.getAttribute('role')?.trim().split(/\s+/)[0];
@@ -254,13 +287,24 @@ export function findChildByLocalName(el, localName, resolver) {
     }
     return null;
 }
+/**
+ * The closest `label` element among the ancestors of the element, which names the element when it is
+ * its labeled control. The ancestors are those of its own tree, as the HTML Standard defines the
+ * relation between a `label` and its labeled control by ancestors in the tree, so a `label` that
+ * wraps a `template` element does not label a control in its content.
+ *
+ * @see https://html.spec.whatwg.org/multipage/forms.html#labeled-control
+ *
+ * @param el - The element to start from
+ * @returns The closest `label` ancestor, or `null`
+ */
 export function findAncestorLabel(el) {
-    let current = el.parentElement;
+    let current = getTreeParentElement(el);
     while (current) {
         if (current.localName === 'label') {
             return current;
         }
-        current = current.parentElement;
+        current = getTreeParentElement(current);
     }
     return null;
 }
@@ -287,6 +331,17 @@ export function getInputType(el) {
 export function isSvgElement(el) {
     return el.namespaceURI === SVG_NAMESPACE;
 }
+/**
+ * Whether the element is an SVG `title` or `desc`. They are never rendered,
+ * so their text is not content of the parent: a `title` gives the name only
+ * through Step 2E of its parent (`handleSvgElement`), which an element exposed
+ * as presentational skips.
+ *
+ * @see https://svgwg.org/svg2-draft/render.html#TermNeverRenderedElement
+ */
+export function isSvgDescriptiveElement(el) {
+    return isSvgElement(el) && (el.localName === 'title' || el.localName === 'desc');
+}
 /**
  * Escapes a string for safe use inside a CSS selector.
  *

package/lib/algorithm/aria/accname/index.d.ts

@@ -1,4 +1,4 @@
-export { computeAccessibleName } from './compute.js';
+export { computeAccessibleName, computeHostLanguageLabel, computeReferencedTextAlternative } from './compute.js';
 export { escapeCSS } from './helpers.js';
 export { hasSvgAccessibleNameSource } from './svg-helpers.js';
-export type { AccnameElement, AccnameNode, AccnameResolver, AccnameResult, AccnameSource } from './types.js';
+export type { AccnameElement, AccnameNode, AccnameResolver, AccnameResult, AccnameSource, AccnameVisit, } from './types.js';

package/lib/algorithm/aria/accname/index.js

@@ -1,3 +1,3 @@
-export { computeAccessibleName } from './compute.js';
+export { computeAccessibleName, computeHostLanguageLabel, computeReferencedTextAlternative } from './compute.js';
 export { escapeCSS } from './helpers.js';
 export { hasSvgAccessibleNameSource } from './svg-helpers.js';

package/lib/algorithm/aria/accname/label-steps.d.ts

@@ -1,9 +1,9 @@
-import type { AccnameElement, AccnameResolver, AccnameResult } from './types.js';
+import type { AccnameComputeFn, AccnameElement, AccnameResolver, AccnameResult } from './types.js';
 /**
  * Part of AccName 1.2 §4.3.2 Step 2E — for labelable elements, the HTML label
  * association is checked before other element-specific rules.
  *
- * @see https://www.w3.org/TR/accname-1.2/#computation-steps — AccName 1.2 §4.3.2 Step 2E
- * @see https://www.w3.org/TR/html-aam-1.0/#el-input-text — HTML-AAM label association
+ * @see https://w3c.github.io/accname/#computation-steps — AccName 1.2 §4.3.2 Step 2E
+ * @see https://www.w3.org/TR/html-aam/#el-input-text — HTML-AAM label association
  */
-export declare function resolveLabelText(el: AccnameElement, resolver: AccnameResolver, visited: ReadonlySet<string>, computeFn: (el: AccnameElement, resolver: AccnameResolver, inLabelledbyTraversal: boolean, visited: ReadonlySet<string>) => AccnameResult, inLabelledbyTraversal: boolean): AccnameResult | null;
+export declare function resolveLabelText(el: AccnameElement, resolver: AccnameResolver, visited: ReadonlySet<string>, computeFn: AccnameComputeFn, inLabelledbyTraversal: boolean): AccnameResult | null;

package/lib/algorithm/aria/accname/label-steps.js

@@ -1,12 +1,13 @@
 /* eslint-disable @typescript-eslint/prefer-readonly-parameter-types -- AccnameElement wraps mutable DOM types */
 import { ELEMENT_NODE, TEXT_NODE } from '../../../const/index.js';
-import { flattenText, getChildNodes, makeResult, resolveLabel } from './helpers.js';
+import { embeddedControlText, getChildNodes, isSvgDescriptiveElement, resolveLabel } from './helpers.js';
+import { flattenText, makeResult } from './result.js';
 /**
  * Part of AccName 1.2 §4.3.2 Step 2E — for labelable elements, the HTML label
  * association is checked before other element-specific rules.
  *
- * @see https://www.w3.org/TR/accname-1.2/#computation-steps — AccName 1.2 §4.3.2 Step 2E
- * @see https://www.w3.org/TR/html-aam-1.0/#el-input-text — HTML-AAM label association
+ * @see https://w3c.github.io/accname/#computation-steps — AccName 1.2 §4.3.2 Step 2E
+ * @see https://www.w3.org/TR/html-aam/#el-input-text — HTML-AAM label association
  */
 export function resolveLabelText(el, resolver, visited, computeFn, inLabelledbyTraversal) {
     const labels = resolveLabel(el, resolver);
@@ -30,6 +31,10 @@ export function resolveLabelText(el, resolver, visited, computeFn, inLabelledbyT
  * Excludes the labeled element itself to prevent circular inclusion. Parts are
  * joined with a space separator, matching the AccName 1.2 concatenation
  * behavior for label text.
+ *
+ * The children are treated as name-from-content recursion treats them
+ * (`resolveNameFromContent`): a hidden one and an SVG `title` or `desc`
+ * contribute nothing, and an embedded control contributes its value.
  */
 function collectLabelText(label, labeledElement, resolver, visited, computeFn, inLabelledbyTraversal) {
     const parts = [];
@@ -39,14 +44,18 @@ function collectLabelText(label, labeledElement, resolver, visited, computeFn, i
         }
         else if (child.nodeType === ELEMENT_NODE) {
             const childEl = child;
-            if (childEl === labeledElement) {
+            if (childEl === labeledElement || isSvgDescriptiveElement(childEl)) {
+                continue;
+            }
+            if (resolver.isEmbeddedControl(childEl)) {
+                parts.push(embeddedControlText(childEl, resolver, visited, computeFn, inLabelledbyTraversal));
                 continue;
             }
             const result = computeFn(childEl, resolver, inLabelledbyTraversal, visited);
             if (result.name) {
                 parts.push(result.name);
             }
-            else {
+            else if (!resolver.isHidden(childEl)) {
                 // Transparent traversal: when the child element has no accessible name
                 // (e.g., <span> with role="generic"), recursively collect its descendant text.
                 // This matches the behavior of resolveNameFromContent's fallback.

package/lib/algorithm/aria/accname/result.d.ts

@@ -0,0 +1,21 @@
+/**
+ * The result builders of the accessible name computation.
+ *
+ * A module of their own, not part of `helpers.ts`: `aria-steps.ts` builds
+ * results, and `helpers.ts` runs Step 2B for an embedded control through
+ * `aria-steps.ts`, so keeping them in `helpers.ts` would make the two import
+ * each other.
+ *
+ * @module
+ */
+import type { AccnameResult, AccnameSource } from './types.js';
+/**
+ * Builds a result from a name, flattened; an empty name has no source.
+ */
+export declare function makeResult(name: string, source: AccnameSource | null): AccnameResult;
+/**
+ * Makes a flat string: whitespace runs become a single space, and the ends are trimmed.
+ *
+ * @see https://w3c.github.io/accname/#terminology
+ */
+export declare function flattenText(text: string): string;

package/lib/algorithm/aria/accname/result.js

@@ -0,0 +1,28 @@
+/**
+ * The result builders of the accessible name computation.
+ *
+ * A module of their own, not part of `helpers.ts`: `aria-steps.ts` builds
+ * results, and `helpers.ts` runs Step 2B for an embedded control through
+ * `aria-steps.ts`, so keeping them in `helpers.ts` would make the two import
+ * each other.
+ *
+ * @module
+ */
+/**
+ * Builds a result from a name, flattened; an empty name has no source.
+ */
+export function makeResult(name, source) {
+    const trimmed = flattenText(name);
+    return {
+        name: trimmed,
+        source: trimmed ? source : null,
+    };
+}
+/**
+ * Makes a flat string: whitespace runs become a single space, and the ends are trimmed.
+ *
+ * @see https://w3c.github.io/accname/#terminology
+ */
+export function flattenText(text) {
+    return text.replaceAll(/\s+/g, ' ').trim();
+}

package/lib/algorithm/aria/accname/svg-helpers.d.ts

@@ -4,7 +4,7 @@ import type { AccnameElement } from './types.js';
  * the full name computation.
  *
  * Used by `get-computed-role.ts` for SVG accessibility tree inclusion decisions
- * per SVG-AAM §5.1.1. This is a lightweight check that avoids the full AccName
+ * per SVG-AAM §4.1.2. This is a lightweight check that avoids the full AccName
  * algorithm, breaking the circular dependency between role computation and
  * name computation.
  *
@@ -19,6 +19,6 @@ import type { AccnameElement } from './types.js';
  *
  * @param el - The SVG element to check for accessible name sources
  * @returns True if the element has aria-label, aria-labelledby, or a title/desc child
- * @see https://www.w3.org/TR/svg-aam-1.0/#include_elements — SVG-AAM §5.1.1
+ * @see https://www.w3.org/TR/svg-aam/#include_elements — SVG-AAM §4.1.2
  */
 export declare function hasSvgAccessibleNameSource(el: AccnameElement): boolean;

package/lib/algorithm/aria/accname/svg-helpers.js

@@ -4,7 +4,7 @@
  * the full name computation.
  *
  * Used by `get-computed-role.ts` for SVG accessibility tree inclusion decisions
- * per SVG-AAM §5.1.1. This is a lightweight check that avoids the full AccName
+ * per SVG-AAM §4.1.2. This is a lightweight check that avoids the full AccName
  * algorithm, breaking the circular dependency between role computation and
  * name computation.
  *
@@ -19,7 +19,7 @@
  *
  * @param el - The SVG element to check for accessible name sources
  * @returns True if the element has aria-label, aria-labelledby, or a title/desc child
- * @see https://www.w3.org/TR/svg-aam-1.0/#include_elements — SVG-AAM §5.1.1
+ * @see https://www.w3.org/TR/svg-aam/#include_elements — SVG-AAM §4.1.2
  */
 export function hasSvgAccessibleNameSource(el) {
     if (el.getAttribute('aria-label')?.trim()) {

package/lib/algorithm/aria/accname/types.d.ts

@@ -20,6 +20,13 @@ export interface AccnameElement extends AccnameNode {
     getAttribute(name: string): string | null;
     hasAttribute(name: string): boolean;
     readonly parentElement: AccnameElement | null;
+    /**
+     * The root of the tree of the element. An element and its parent element are in the same tree,
+     * unless the parent element is only the syntactical parent, as `MLElement#parentElement` is for the
+     * top of the content of a `template` element: see `getTreeParentElement`. An implementation without
+     * it has no tree boundary.
+     */
+    getRootNode?(): unknown;
     readonly children: Iterable<AccnameElement>;
     readonly childNodes: Iterable<AccnameNode>;
 }
@@ -42,6 +49,19 @@ export interface AccnameResolver {
      * in name-from-content computation (textbox, combobox, listbox, spinbutton, slider, searchbox).
      */
     isEmbeddedControl(el: AccnameElement): boolean;
+    /**
+     * Checks if an element is exposed with an explicit `none` or `presentation`
+     * role, so that Step 2E does not use its host language text alternative.
+     * When absent, no element is treated so.
+     */
+    isExposedAsPresentational?(el: AccnameElement): boolean;
+    /**
+     * Called for every element the computation reaches, before Step 2A, so that
+     * a caller can tell which attributes of a descendant took part in a name.
+     * An element that the computation does not reach (the subtree of a hidden
+     * element, or of one named before content) is never reported.
+     */
+    onVisit?(el: AccnameElement, visit: AccnameVisit): void;
     /**
      * Returns a pre-computed name for an element, bypassing the standard algorithm.
      * Used by ml-core for Pretender integration where framework components provide
@@ -53,6 +73,11 @@ export interface AccnameResolver {
      * Used by ml-core for a pretended component: it renders its own elements around
      * the children given at the usage site (`contents` of the pretender), and those
      * can carry the accessible name (`<button><img alt="Save"></button>`).
+     * Also the rendered children, when they are not the syntactical ones: the
+     * child nodes of an attached shadow root, and none for an ordinary
+     * `template` element, whose content is not rendered where it is written.
+     * An element whose shadow root is only maybe attached is given none as
+     * well, because that root is not there to read.
      * Consulted by name-from-content, label text, the legend/caption/SVG `title`
      * lookups, the `<select>` options, and wherever the computation reads an
      * element's text (`getTextContent`): an option, an SVG `title`, the value of
@@ -60,6 +85,32 @@ export interface AccnameResolver {
      */
     getChildNodes?(el: AccnameElement): Iterable<AccnameNode>;
 }
+/**
+ * The recursive entry of the computation (`computeAccessibleNameInternal`),
+ * handed to the steps that compute the text alternative of another node.
+ */
+export type AccnameComputeFn = (el: AccnameElement, resolver: AccnameResolver, inLabelledbyTraversal: boolean, visited: ReadonlySet<string>) => AccnameResult;
+/**
+ * How the computation reached an element (see `AccnameResolver.onVisit`).
+ */
+export interface AccnameVisit {
+    /**
+     * Whether Step 2A found the element hidden, which ends the computation of
+     * it. Step 2A does not apply inside an `aria-labelledby` traversal whose
+     * directly referenced node is hidden, so no element is found hidden there.
+     */
+    readonly hidden: boolean;
+    /**
+     * Whether the element is an embedded control reached by name-from-content
+     * recursion (Step 2C), whose value is used and whose `aria-label` is ignored.
+     */
+    readonly embeddedControl: boolean;
+    /**
+     * Whether the element is part of an ongoing `aria-labelledby` traversal, in
+     * which Step 2B is not applied.
+     */
+    readonly inLabelledbyTraversal: boolean;
+}
 /**
  * Identifies the source of an element's accessible name per HTML-AAM §4.1.
  * Used for diagnostic purposes (e.g., reporting which source provided the name).

package/lib/algorithm/aria/accname-computation.d.ts

@@ -14,6 +14,6 @@ import type { ARIAVersion, MLMLSpec } from '../../types/index.js';
  * @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
+ * @see https://w3c.github.io/accname/#computation-steps — AccName 1.2 §4.3.2
  */
 export declare function getAccname(el: Element, specs: MLMLSpec, version: ARIAVersion): string;

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

@@ -2,6 +2,7 @@ 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';
+import { isExposedAsPresentational } from './is-presentational.js';
 /**
  * [Implementation-specific] Reentrant guard to prevent infinite recursion when
  * getComputedRole evaluates `:aria(has name)` selectors, which call back into getAccname.
@@ -30,7 +31,7 @@ const computingElements = new WeakSet();
  * @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
+ * @see https://w3c.github.io/accname/#computation-steps — AccName 1.2 §4.3.2
  */
 export function getAccname(
 // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
@@ -121,18 +122,23 @@ el, specs, version) {
             // Native HTML embedded controls without explicit role
             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(specs, target, version));
+        },
     };
 }
 /**
- * Walks up the DOM tree to find the root node (Document or DocumentFragment).
+ * Finds the root node (Document or DocumentFragment) of the tree the element is in: for an
+ * element in the content of a `template` element or a shadow root, that content, not the
+ * document. A host that holds the content in the syntax tree under the `template` element (the
+ * markuplint DOM) answers it in `getRootNode()`, as the DOM does.
  */
 function getRootNode(
 // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
 el) {
-    let root = el;
-    while (root.parentNode) {
-        root = root.parentNode;
-    }
+    const root = el.getRootNode();
     if (root.nodeType === 9 || root.nodeType === 11) {
         return root;
     }

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

@@ -89,14 +89,14 @@ function optimizePermittedRoles(permittedRoles, version) {
         return permittedRoles;
     }
     const unique = new Set(permittedRoles);
-    // https://www.w3.org/TR/wai-aria-1.2/#note-regarding-the-aria-1-1-none-role
+    // https://w3c.github.io/aria/#none
     if (unique.has('presentation')) {
         unique.add('none');
     }
     if (unique.has('none')) {
         unique.add('presentation');
     }
-    // https://w3c.github.io/aria/#ref-for-image
+    // https://w3c.github.io/aria/#image
     // In ARIA 1.3, `image` is the primary role name and `img` is a synonym.
     if (version === '1.3') {
         if (unique.has('image')) {