@markuplint/ml-spec 4.10.2 → 5.0.0-alpha.1

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

@@ -0,0 +1,330 @@
+/* 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';
+export { EMBEDDED_CONTROL_ROLES } from '../../../const/index.js';
+/**
+ * Creates an AccnameResult with a trimmed, whitespace-collapsed name.
+ *
+ * @param name - The raw name string to normalize
+ * @param source - The source that provided the name, or null if the name is empty
+ * @returns A result with the collapsed name and its source (source is null when name is empty)
+ */
+export function makeResult(name, source) {
+    const trimmed = flattenText(name);
+    return {
+        name: trimmed,
+        source: trimmed ? source : null,
+    };
+}
+/**
+ * Collapses internal whitespace and trims a string.
+ *
+ * @param text - The string to normalize
+ * @returns The string with collapsed whitespace and trimmed
+ */
+export function flattenText(text) {
+    return text.replaceAll(/\s+/g, ' ').trim();
+}
+/**
+ * Collects text content from child nodes recursively for name-from-content computation.
+ *
+ * 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."
+ *
+ * Control flow for each child node:
+ * 1. **Text node** → contribute text directly.
+ * 2. **Embedded control** (textbox, combobox, listbox, slider, spinbutton, searchbox)
+ *    → use value via `getEmbeddedControlValue`. Per spec, `aria-label` is ignored
+ *    for embedded controls during name-from-content traversal.
+ * 3. **Other element** → first try its full accessible name (Steps 2B–2I via `computeFn`).
+ *    If no name, fall through to `collectTextContent` for transparent traversal.
+ *
+ * Parts are joined with a space separator per AccName 1.2 §4.3.2 Step 2C.
+ *
+ * **Limitation:** CSS-generated content (`::before`/`::after` with the `content`
+ * property) is not included. AccName 1.2 §4.3.2 Step 2G specifies that CSS
+ * generated textual content should be part of the accumulated text, but markuplint
+ * performs static HTML analysis without CSS processing, so this content is
+ * unavailable at lint time.
+ *
+ * @param el - The element whose child nodes to collect text from
+ * @param resolver - Environment-dependent resolver for DOM traversal and role queries
+ * @param visited - Set of element IDs already visited (cycle prevention)
+ * @param computeFn - The recursive accessible name computation function
+ * @param inLabelledbyTraversal - Whether this computation is part of an aria-labelledby traversal
+ * @returns The concatenated text content from child nodes
+ * @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
+ */
+export function resolveNameFromContent(el, resolver, visited, computeFn, inLabelledbyTraversal) {
+    const parts = [];
+    for (const child of el.childNodes) {
+        if (child.nodeType === TEXT_NODE) {
+            parts.push(child.textContent ?? '');
+        }
+        else if (child.nodeType === ELEMENT_NODE) {
+            const childEl = child;
+            if (resolver.isEmbeddedControl(childEl)) {
+                // Step 2C: Embedded controls — use value directly, aria-label is ignored
+                parts.push(getEmbeddedControlValue(childEl));
+            }
+            else {
+                const result = computeFn(childEl, resolver, inLabelledbyTraversal, visited);
+                if (result.name) {
+                    parts.push(result.name);
+                }
+                else {
+                    // When name-from-content traversal reaches an element with no accessible name,
+                    // recursively collect its text content (transparent traversal)
+                    parts.push(collectTextContent(childEl, resolver, visited, computeFn, inLabelledbyTraversal));
+                }
+            }
+        }
+    }
+    return parts.join(' ');
+}
+/**
+ * [Implementation-specific extension] Recursively collects text content
+ * from an element and its descendants during name-from-content traversal.
+ *
+ * The AccName spec (§4.3.2 Step 2F) only formally defines name-from-content
+ * for elements whose role's `nameFrom` includes `"content"`. However,
+ * intermediate wrapper elements (e.g., `<span>` inside `<button>`) may
+ * have roles that do NOT include `nameFrom: ["content"]`, yet their text
+ * must still be collected for the parent's name computation to work.
+ *
+ * This function provides that "transparent traversal": when `computeFn`
+ * returns no name for a child element, this function recursively collects
+ * the child's text content regardless of its role settings.
+ *
+ * Hidden elements (per `resolver.isHidden`) are excluded.
+ */
+function collectTextContent(el, resolver, visited, computeFn, inLabelledbyTraversal) {
+    if (resolver.isHidden(el)) {
+        return '';
+    }
+    const parts = [];
+    for (const child of el.childNodes) {
+        if (child.nodeType === TEXT_NODE) {
+            parts.push(child.textContent ?? '');
+        }
+        else if (child.nodeType === ELEMENT_NODE) {
+            const childEl = child;
+            if (resolver.isEmbeddedControl(childEl)) {
+                parts.push(getEmbeddedControlValue(childEl));
+            }
+            else {
+                const result = computeFn(childEl, resolver, inLabelledbyTraversal, visited);
+                if (result.name) {
+                    parts.push(result.name);
+                }
+                else {
+                    parts.push(collectTextContent(childEl, resolver, visited, computeFn, inLabelledbyTraversal));
+                }
+            }
+        }
+    }
+    return parts.join(' ');
+}
+/**
+ * Gets the value of an embedded control for name-from-content computation.
+ *
+ * Implements AccName 1.2 §4.3.2 Step 2C embedded control value resolution:
+ * - **Range controls** (slider/spinbutton/input[range]):
+ *   aria-valuetext → aria-valuenow → value attr → textContent
+ * - **Textbox/combobox/searchbox** (input[text-like]/textarea):
+ *   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
+ */
+function getEmbeddedControlValue(el) {
+    const role = el.getAttribute('role')?.trim().split(/\s+/)[0];
+    // Range controls: slider, spinbutton, input[type=range]
+    if (role === 'slider' || role === 'spinbutton' || (el.localName === 'input' && getInputType(el) === 'range')) {
+        const valuetext = el.getAttribute('aria-valuetext');
+        if (valuetext?.trim()) {
+            return valuetext;
+        }
+        const valuenow = el.getAttribute('aria-valuenow');
+        if (valuenow?.trim()) {
+            return valuenow;
+        }
+        const value = el.getAttribute('value');
+        if (value?.trim()) {
+            return value;
+        }
+        return el.textContent ?? '';
+    }
+    // Textbox/combobox: value attr -> textContent
+    if (role === 'textbox' ||
+        role === 'combobox' ||
+        role === 'searchbox' ||
+        el.localName === 'textarea' ||
+        (el.localName === 'input' && isTextLikeInput(el))) {
+        const value = el.getAttribute('value');
+        if (value != null) {
+            return value;
+        }
+        return el.textContent ?? '';
+    }
+    // Listbox/select: selected option text
+    if (el.localName === 'select') {
+        return getSelectedOptionText(el);
+    }
+    return el.textContent ?? '';
+}
+/**
+ * Gets the text content of the selected `<option>` elements within a `<select>`.
+ *
+ * AccName 1.2 §4.3.2 Step 2C specifies that a listbox should return the
+ * text of the **selected** option(s). Since this is static analysis, we
+ * approximate by checking the `selected` attribute on `<option>` elements.
+ * If no option has `selected`, the first non-disabled option is used
+ * (matching the HTML spec's default selection behavior for non-`multiple` selects).
+ *
+ * For `<select multiple>` with multiple `selected` options, texts are
+ * joined with a space separator.
+ *
+ * **Future work (#2069 — customizable `<select>` / `<selectedcontent>`):**
+ *
+ * When customizable `<select>` is supported:
+ * 1. `collectOptions` must skip non-`<option>` children that the new content
+ *    model allows (e.g., `<button>`, `<datalist>`, `<selectedcontent>`, `<div>`).
+ * 2. Consider whether `<selectedcontent>` (which clones the selected option's
+ *    content into the button area) affects name computation, or whether we
+ *    should continue to resolve from `<option>` elements directly.
+ * 3. Parse5 must support the new `<select>` content model first.
+ *
+ * @see https://github.com/markuplint/markuplint/issues/2069 — `<select>` and `<selectedcontent>` support
+ */
+function getSelectedOptionText(el) {
+    const options = collectOptions(el);
+    const selected = options.filter(opt => opt.hasAttribute('selected'));
+    if (selected.length > 0) {
+        return selected.map(opt => opt.textContent?.trim() ?? '').join(' ');
+    }
+    // No explicit selected attr: HTML spec says first non-disabled option is selected
+    // (only for non-multiple selects, but we approximate for all)
+    const first = options.find(opt => !opt.hasAttribute('disabled'));
+    return first?.textContent?.trim() ?? '';
+}
+/**
+ * Collects all `<option>` descendant elements from a `<select>`,
+ * traversing through `<optgroup>` containers.
+ *
+ * **Note (#2069):** Customizable `<select>` allows non-option children
+ * (e.g., `<button>`, `<datalist>`, `<div>`). This function currently only
+ * recognizes `<option>` and `<optgroup>` — it will need updating when the
+ * new content model is supported.
+ *
+ * @see https://github.com/markuplint/markuplint/issues/2069
+ */
+function collectOptions(el) {
+    const result = [];
+    for (const child of el.children) {
+        if (child.localName === 'option') {
+            result.push(child);
+        }
+        else if (child.localName === 'optgroup') {
+            for (const grandchild of child.children) {
+                if (grandchild.localName === 'option') {
+                    result.push(grandchild);
+                }
+            }
+        }
+    }
+    return result;
+}
+/**
+ * Checks if an input element is a text-like type (text, search, tel, url, email, etc.).
+ */
+function isTextLikeInput(el) {
+    return TEXT_LIKE_INPUT_TYPES.has(getInputType(el));
+}
+/**
+ * Finds the first child element with a matching localName.
+ *
+ * @param el - The parent element to search within
+ * @param localName - The local tag name to match
+ * @returns The first matching child element, or null if none found
+ */
+export function findChildByLocalName(el, localName) {
+    for (const child of el.children) {
+        if (child.localName === localName) {
+            return child;
+        }
+    }
+    return null;
+}
+/**
+ * Finds the nearest ancestor label element (implicit label association).
+ *
+ * @param el - The element to search from
+ * @returns The nearest ancestor label element, or null if none found
+ */
+export function findAncestorLabel(el) {
+    let current = el.parentElement;
+    while (current) {
+        if (current.localName === 'label') {
+            return current;
+        }
+        current = current.parentElement;
+    }
+    return null;
+}
+/**
+ * Resolves a label for an element via explicit (for=id) or implicit (ancestor) association.
+ *
+ * @param el - The element to find labels for
+ * @param resolver - Environment-dependent resolver for label lookups
+ * @returns An array of label elements associated with the element
+ */
+export function resolveLabel(el, resolver) {
+    const id = el.id;
+    if (id) {
+        const explicitLabels = resolver.getLabelsForId(id);
+        if (explicitLabels.length > 0) {
+            return explicitLabels;
+        }
+    }
+    const implicitLabel = findAncestorLabel(el);
+    if (implicitLabel) {
+        return [implicitLabel];
+    }
+    return [];
+}
+/**
+ * Gets the input type, defaulting to 'text' for inputs without a type attribute.
+ *
+ * @param el - The element to get the input type for
+ * @returns The lowercase input type, or an empty string if not an input element
+ */
+export function getInputType(el) {
+    if (el.localName !== 'input') {
+        return '';
+    }
+    return (el.getAttribute('type') ?? 'text').toLowerCase();
+}
+/**
+ * Checks if an element is in the SVG namespace.
+ *
+ * @param el - The element to check
+ * @returns True if the element is in the SVG namespace
+ */
+export function isSvgElement(el) {
+    return el.namespaceURI === SVG_NAMESPACE;
+}
+/**
+ * Escapes a string for safe use inside a CSS selector.
+ *
+ * @param value - The raw string value (typically an element ID)
+ * @returns The escaped string with CSS special characters backslash-escaped
+ */
+export function escapeCSS(value) {
+    return value.replaceAll(/([!"#$%&'()*+,./:;<=>?@[\\\]^`{|}~])/g, '\\$1');
+}

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

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

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

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

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

@@ -0,0 +1,25 @@
+import type { AccnameElement, AccnameResolver, AccnameResult } from './types.js';
+/**
+ * Resolves accessible name from `<label>` element association.
+ *
+ * Part of AccName 1.2 §4.3.2 Step 2E — for labelable elements, checks
+ * the HTML label association before other element-specific rules.
+ *
+ * Control flow:
+ * 1. Find labels via `resolveLabel`: explicit `<label for="id">` first,
+ *    then implicit ancestor `<label>`.
+ * 2. For each label, collect its text content via `collectLabelText`,
+ *    which walks the label's children but **excludes** the labeled
+ *    element itself (prevents circular inclusion).
+ * 3. Join all label texts with a space separator and flatten whitespace.
+ *
+ * @param el - The labelable element to resolve label text for
+ * @param resolver - Environment-dependent resolver for label lookups
+ * @param visited - Set of element IDs already visited (cycle prevention)
+ * @param computeFn - The recursive accessible name computation function
+ * @param inLabelledbyTraversal - Whether this computation is part of an aria-labelledby traversal
+ * @returns The resolved name result, or null if no label provides a name
+ * @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
+ */
+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;

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

@@ -0,0 +1,74 @@
+/* eslint-disable @typescript-eslint/prefer-readonly-parameter-types -- AccnameElement wraps mutable DOM types */
+import { ELEMENT_NODE, TEXT_NODE } from '../../../const/index.js';
+import { flattenText, makeResult, resolveLabel } from './helpers.js';
+/**
+ * Resolves accessible name from `<label>` element association.
+ *
+ * Part of AccName 1.2 §4.3.2 Step 2E — for labelable elements, checks
+ * the HTML label association before other element-specific rules.
+ *
+ * Control flow:
+ * 1. Find labels via `resolveLabel`: explicit `<label for="id">` first,
+ *    then implicit ancestor `<label>`.
+ * 2. For each label, collect its text content via `collectLabelText`,
+ *    which walks the label's children but **excludes** the labeled
+ *    element itself (prevents circular inclusion).
+ * 3. Join all label texts with a space separator and flatten whitespace.
+ *
+ * @param el - The labelable element to resolve label text for
+ * @param resolver - Environment-dependent resolver for label lookups
+ * @param visited - Set of element IDs already visited (cycle prevention)
+ * @param computeFn - The recursive accessible name computation function
+ * @param inLabelledbyTraversal - Whether this computation is part of an aria-labelledby traversal
+ * @returns The resolved name result, or null if no label provides a name
+ * @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
+ */
+export function resolveLabelText(el, resolver, visited, computeFn, inLabelledbyTraversal) {
+    const labels = resolveLabel(el, resolver);
+    if (labels.length === 0) {
+        return null;
+    }
+    const parts = [];
+    for (const label of labels) {
+        const text = collectLabelText(label, el, resolver, visited, computeFn, inLabelledbyTraversal);
+        if (text) {
+            parts.push(text);
+        }
+    }
+    const name = flattenText(parts.join(' '));
+    if (name) {
+        return makeResult(name, 'label');
+    }
+    return null;
+}
+/**
+ * Collects text from a label element, excluding the labeled element itself.
+ * Parts are joined with a space separator, matching the AccName 1.2
+ * concatenation behavior for label text.
+ */
+function collectLabelText(label, labeledElement, resolver, visited, computeFn, inLabelledbyTraversal) {
+    const parts = [];
+    for (const child of label.childNodes) {
+        if (child.nodeType === TEXT_NODE) {
+            parts.push(child.textContent ?? '');
+        }
+        else if (child.nodeType === ELEMENT_NODE) {
+            const childEl = child;
+            if (childEl === labeledElement) {
+                continue;
+            }
+            const result = computeFn(childEl, resolver, inLabelledbyTraversal, visited);
+            if (result.name) {
+                parts.push(result.name);
+            }
+            else {
+                // 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.
+                parts.push(collectLabelText(childEl, labeledElement, resolver, visited, computeFn, inLabelledbyTraversal));
+            }
+        }
+    }
+    return parts.join(' ');
+}

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

@@ -0,0 +1,17 @@
+import type { AccnameElement } from './types.js';
+/**
+ * Checks whether an SVG element has any accessible name source, without performing
+ * 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
+ * algorithm, breaking the circular dependency between role computation and
+ * name computation.
+ *
+ * Checks (in order): `aria-label`, `aria-labelledby`, `<title>` child, `<desc>` child.
+ *
+ * @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
+ */
+export declare function hasSvgAccessibleNameSource(el: AccnameElement): boolean;

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

@@ -0,0 +1,30 @@
+/* eslint-disable @typescript-eslint/prefer-readonly-parameter-types -- AccnameElement wraps mutable DOM types */
+/**
+ * Checks whether an SVG element has any accessible name source, without performing
+ * 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
+ * algorithm, breaking the circular dependency between role computation and
+ * name computation.
+ *
+ * Checks (in order): `aria-label`, `aria-labelledby`, `<title>` child, `<desc>` child.
+ *
+ * @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
+ */
+export function hasSvgAccessibleNameSource(el) {
+    if (el.getAttribute('aria-label')?.trim()) {
+        return true;
+    }
+    if (el.getAttribute('aria-labelledby')?.trim()) {
+        return true;
+    }
+    for (const child of el.children) {
+        if ((child.localName === 'title' || child.localName === 'desc') && child.textContent?.trim()) {
+            return true;
+        }
+    }
+    return false;
+}

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

@@ -0,0 +1,70 @@
+/**
+ * Minimal node interface for accessible name computation.
+ * Structurally compatible with both DOM `Element` and `MLElement`,
+ * enabling the AccName algorithm to run in both JSDOM (tests, accname-computation.ts)
+ * and ml-core (MLElement-based lint rules) environments without adaptation.
+ */
+export interface AccnameNode {
+    readonly nodeType: number;
+    readonly textContent: string | null;
+}
+/**
+ * Minimal element interface for accessible name computation.
+ * MLElement satisfies this interface via structural typing (no adapter needed).
+ */
+export interface AccnameElement extends AccnameNode {
+    readonly nodeType: number;
+    readonly localName: string;
+    readonly id: string;
+    readonly namespaceURI: string | null;
+    getAttribute(name: string): string | null;
+    hasAttribute(name: string): boolean;
+    readonly parentElement: AccnameElement | null;
+    readonly children: Iterable<AccnameElement>;
+    readonly childNodes: Iterable<AccnameNode>;
+}
+/**
+ * Environment-dependent resolver for accessible name computation.
+ *
+ * Decouples the pure AccName algorithm (accname/) from DOM traversal
+ * and role resolution. Two implementations exist:
+ * - **accname-computation.ts**: DOM-based resolver using `document.getElementById`,
+ *   `querySelectorAll`, and `getComputedRole` for JSDOM/browser environments.
+ * - **ml-core**: MLElement-based resolver using the parsed MLDOM tree.
+ */
+export interface AccnameResolver {
+    getElementById(id: string): AccnameElement | null;
+    getLabelsForId(id: string): readonly AccnameElement[];
+    allowsNameFromContent(el: AccnameElement): boolean;
+    isHidden(el: AccnameElement): boolean;
+    /**
+     * Checks if an element is an embedded control whose value should be used
+     * in name-from-content computation (textbox, combobox, listbox, spinbutton, slider, searchbox).
+     */
+    isEmbeddedControl(el: AccnameElement): boolean;
+    /**
+     * Returns a pre-computed name for an element, bypassing the standard algorithm.
+     * Used by ml-core for Pretender integration where framework components provide
+     * accessible names through configuration.
+     */
+    getPrecomputedName?(el: AccnameElement): string | null;
+}
+/**
+ * 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).
+ */
+export type AccnameSource = 'aria-labelledby' | 'aria-label' | 'label' | 'alt' | 'content' | 'title' | 'placeholder' | 'value' | 'legend' | 'caption' | 'svg-title' | 'default';
+/**
+ * Result of accessible name computation, including the name string and its source.
+ */
+export interface AccnameResult {
+    readonly name: string;
+    readonly source: AccnameSource | null;
+}
+/**
+ * Internal options passed through recursive calls.
+ */
+export interface AccnameOptions {
+    readonly inLabelledbyTraversal?: boolean;
+    readonly visited?: ReadonlySet<string>;
+}

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

@@ -0,0 +1,2 @@
+/* eslint-disable @typescript-eslint/prefer-readonly-parameter-types -- AccnameElement wraps mutable DOM types */
+export {};

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

@@ -1,8 +1,19 @@
+import type { ARIAVersion, MLMLSpec } from '../../types/index.js';
 /**
- * Computes the accessible name for an element using the WAI-ARIA accessible name computation algorithm.
- * Falls back to the placeholder attribute value for input elements when no accessible name is found.
+ * 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 declare function getAccname(el: Element): string;
+export declare function getAccname(el: Element, specs: MLMLSpec, version: ARIAVersion): string;