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

package/lib/algorithm/aria/accname/__tests__/test-helpers.js

@@ -0,0 +1,120 @@
+/* eslint-disable @typescript-eslint/prefer-readonly-parameter-types -- AccnameElement wraps mutable DOM types */
+import { ELEMENT_NODE, TEXT_NODE, XHTML_NAMESPACE, EMBEDDED_CONTROL_ROLES, isNativeEmbeddedControl, } from '../../../../const/index.js';
+/**
+ * Creates a test AccnameElement (plain object).
+ *
+ * **Note:** `textContent` is computed eagerly at creation time from the initial
+ * `children`. Adding children after creation will NOT update `textContent`.
+ * Build the full child tree before calling this function.
+ *
+ * @param localName - The local tag name of the element
+ * @param options - Configuration for attributes, children, parent, and namespace
+ * @returns A plain object implementing the AccnameElement interface
+ */
+export function element(localName, options = {}) {
+    const attrs = options.attrs ?? {};
+    const childNodes = options.children ?? [];
+    const elementChildren = [];
+    for (const child of childNodes) {
+        if (child.nodeType === ELEMENT_NODE) {
+            elementChildren.push(child);
+        }
+    }
+    const el = {
+        nodeType: ELEMENT_NODE,
+        localName,
+        id: attrs['id'] ?? '',
+        namespaceURI: options.namespaceURI ?? XHTML_NAMESPACE,
+        textContent: computeTextContent(childNodes),
+        parentElement: options.parentElement ?? null,
+        children: elementChildren,
+        childNodes,
+        getAttribute(name) {
+            return attrs[name] ?? null;
+        },
+        hasAttribute(name) {
+            return name in attrs;
+        },
+    };
+    return el;
+}
+/**
+ * Creates a test text node.
+ *
+ * @param text - The text content of the node
+ * @returns A plain object implementing the AccnameNode interface
+ */
+export function textNode(text) {
+    return {
+        nodeType: TEXT_NODE,
+        textContent: text,
+    };
+}
+function computeTextContent(childNodes) {
+    return childNodes
+        .map(child => {
+        if (child.nodeType === TEXT_NODE) {
+            return child.textContent ?? '';
+        }
+        if (child.nodeType === ELEMENT_NODE) {
+            return child.textContent ?? '';
+        }
+        return '';
+    })
+        .join('');
+}
+/**
+ * Creates a test AccnameResolver.
+ *
+ * @param options - Configuration for element lookups, label associations, and behavior overrides
+ * @returns A resolver implementing the AccnameResolver interface for testing
+ */
+export function createTestResolver(options = {}) {
+    const elements = options.elements ?? new Map();
+    const labels = options.labels ?? new Map();
+    const nameFromContent = options.nameFromContent ?? new Set();
+    const hiddenIds = options.hiddenIds ?? new Set();
+    const embeddedControlRoles = options.embeddedControlRoles ?? EMBEDDED_CONTROL_ROLES;
+    return {
+        getElementById(id) {
+            return elements.get(id) ?? null;
+        },
+        getLabelsForId(id) {
+            return labels.get(id) ?? [];
+        },
+        allowsNameFromContent(el) {
+            if (options.allowsNameFromContentFn) {
+                return options.allowsNameFromContentFn(el);
+            }
+            return nameFromContent.has(el.localName);
+        },
+        isHidden(el) {
+            if (options.isHiddenFn) {
+                return options.isHiddenFn(el);
+            }
+            if (hiddenIds.has(el.id)) {
+                return true;
+            }
+            if (el.getAttribute('aria-hidden') === 'true') {
+                return true;
+            }
+            if (el.hasAttribute('hidden')) {
+                return true;
+            }
+            return false;
+        },
+        isEmbeddedControl(el) {
+            if (options.isEmbeddedControlFn) {
+                return options.isEmbeddedControlFn(el);
+            }
+            // Check explicit role
+            const role = el.getAttribute('role')?.trim().split(/\s+/)[0];
+            if (role && embeddedControlRoles.has(role)) {
+                return true;
+            }
+            // Check native HTML elements
+            return isNativeEmbeddedControl(el);
+        },
+        ...(options.getPrecomputedNameFn ? { getPrecomputedName: options.getPrecomputedNameFn } : {}),
+    };
+}

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

@@ -0,0 +1,51 @@
+import type { AccnameElement, AccnameResolver, AccnameResult } from './types.js';
+/**
+ * Resolves accessible name via `aria-labelledby` attribute.
+ *
+ * Implements AccName 1.2 §4.3.2 Step 2B:
+ * "If the current node has an `aria-labelledby` attribute that contains
+ * at least one valid IDREF, and the current node is not already part of
+ * an ongoing `aria-labelledby` traversal, process its IDREFs [...]"
+ *
+ * Control flow:
+ * 1. Read `aria-labelledby` attribute; return null if absent or empty.
+ * 2. Split the attribute value by whitespace into IDREF tokens.
+ * 3. Mark the current element's ID as visited (cycle prevention for A→B→A).
+ * 4. For each IDREF:
+ *    a. Skip if already visited — **except** self-references (see below).
+ *    b. Resolve the referenced element via `resolver.getElementById`.
+ *    c. Recursively compute the referenced element's name with
+ *       `inLabelledbyTraversal=true` (prevents Step 2B re-entry in `compute.ts`).
+ *    d. Each IDREF branch gets its own copy of the visited set so that
+ *       one branch's traversal does not block later branches.
+ * 5. Join all resolved parts with a space separator and flatten whitespace.
+ *
+ * **Self-reference handling** (spec-defined, not a custom extension):
+ * An element may reference its own ID in `aria-labelledby` to include its
+ * own content alongside other referenced elements. This is explicitly
+ * permitted by the spec (AccName 1.2 §4.3.2 Example 2):
+ *   `<h2 id="h" aria-labelledby="h foo">Meeting</h2>`
+ * Infinite recursion is prevented by `inLabelledbyTraversal`, not by the
+ * visited set — `computeFn` is called with `inLabelledbyTraversal=true`,
+ * which causes `compute.ts` to skip Step 2B on the referenced element.
+ *
+ * @param el - The element with a potential aria-labelledby attribute
+ * @param resolver - Environment-dependent resolver for element lookups
+ * @param visited - Set of element IDs already visited (cycle prevention)
+ * @param computeFn - The recursive accessible name computation function
+ * @returns The resolved name result, or null if aria-labelledby is not present or yields no name
+ * @see https://www.w3.org/TR/accname-1.2/#comp_labelledby_traversal — AccName 1.2 §4.3.2 Step 2B
+ */
+export declare function resolveAriaLabelledby(el: AccnameElement, resolver: AccnameResolver, visited: ReadonlySet<string>, computeFn: (el: AccnameElement, resolver: AccnameResolver, inLabelledbyTraversal: boolean, visited: ReadonlySet<string>) => AccnameResult): AccnameResult | null;
+/**
+ * Resolves accessible name via `aria-label` attribute.
+ *
+ * Implements AccName 1.2 §4.3.2 Step 2D:
+ * "If the current node has an `aria-label` attribute whose value is
+ * not undefined, not the empty string, and not a string of whitespace [...]"
+ *
+ * @param el - The element with a potential aria-label attribute
+ * @returns The resolved name result, or null if aria-label is not present or empty
+ * @see https://www.w3.org/TR/accname-1.2/#computation-steps — AccName 1.2 §4.3.2 Step 2D
+ */
+export declare function resolveAriaLabel(el: AccnameElement): AccnameResult | null;

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

@@ -0,0 +1,104 @@
+/* eslint-disable @typescript-eslint/prefer-readonly-parameter-types -- AccnameElement wraps mutable DOM types */
+import { flattenText, makeResult } from './helpers.js';
+/**
+ * Resolves accessible name via `aria-labelledby` attribute.
+ *
+ * Implements AccName 1.2 §4.3.2 Step 2B:
+ * "If the current node has an `aria-labelledby` attribute that contains
+ * at least one valid IDREF, and the current node is not already part of
+ * an ongoing `aria-labelledby` traversal, process its IDREFs [...]"
+ *
+ * Control flow:
+ * 1. Read `aria-labelledby` attribute; return null if absent or empty.
+ * 2. Split the attribute value by whitespace into IDREF tokens.
+ * 3. Mark the current element's ID as visited (cycle prevention for A→B→A).
+ * 4. For each IDREF:
+ *    a. Skip if already visited — **except** self-references (see below).
+ *    b. Resolve the referenced element via `resolver.getElementById`.
+ *    c. Recursively compute the referenced element's name with
+ *       `inLabelledbyTraversal=true` (prevents Step 2B re-entry in `compute.ts`).
+ *    d. Each IDREF branch gets its own copy of the visited set so that
+ *       one branch's traversal does not block later branches.
+ * 5. Join all resolved parts with a space separator and flatten whitespace.
+ *
+ * **Self-reference handling** (spec-defined, not a custom extension):
+ * An element may reference its own ID in `aria-labelledby` to include its
+ * own content alongside other referenced elements. This is explicitly
+ * permitted by the spec (AccName 1.2 §4.3.2 Example 2):
+ *   `<h2 id="h" aria-labelledby="h foo">Meeting</h2>`
+ * Infinite recursion is prevented by `inLabelledbyTraversal`, not by the
+ * visited set — `computeFn` is called with `inLabelledbyTraversal=true`,
+ * which causes `compute.ts` to skip Step 2B on the referenced element.
+ *
+ * @param el - The element with a potential aria-labelledby attribute
+ * @param resolver - Environment-dependent resolver for element lookups
+ * @param visited - Set of element IDs already visited (cycle prevention)
+ * @param computeFn - The recursive accessible name computation function
+ * @returns The resolved name result, or null if aria-labelledby is not present or yields no name
+ * @see https://www.w3.org/TR/accname-1.2/#comp_labelledby_traversal — AccName 1.2 §4.3.2 Step 2B
+ */
+export function resolveAriaLabelledby(el, resolver, visited, computeFn) {
+    const labelledbyAttr = el.getAttribute('aria-labelledby');
+    if (!labelledbyAttr?.trim()) {
+        return null;
+    }
+    const ids = labelledbyAttr.trim().split(/\s+/);
+    const parts = [];
+    const newVisited = new Set(visited);
+    // Mark the current element as visited to prevent other elements from
+    // circling back to it (e.g., A → B → A).
+    if (el.id) {
+        newVisited.add(el.id);
+    }
+    for (const id of ids) {
+        // Skip IDs already visited — but allow self-references (id === el.id).
+        // The spec requires that an element CAN reference itself in
+        // aria-labelledby to include its own content alongside other IDs.
+        // Example (AccName 1.2 §4.3.2 Example 2):
+        //   <h2 id="h" aria-labelledby="h foo">Meeting</h2>
+        // Here "h" references itself, contributing "Meeting" to the result.
+        //
+        // Infinite recursion is prevented not by the visited set, but by
+        // inLabelledbyTraversal: computeFn is called with true below,
+        // which causes compute.ts to skip Step 2B (aria-labelledby) on
+        // the referenced element, so it never re-enters this function.
+        if (newVisited.has(id) && id !== el.id) {
+            continue;
+        }
+        const referenced = resolver.getElementById(id);
+        if (!referenced) {
+            continue;
+        }
+        // Each branch gets its own visited set so that one IDREF's
+        // traversal doesn't block resolution of a later IDREF.
+        const innerVisited = new Set(newVisited);
+        innerVisited.add(id);
+        const result = computeFn(referenced, resolver, true, innerVisited);
+        if (result.name) {
+            parts.push(result.name);
+        }
+    }
+    const name = flattenText(parts.join(' '));
+    if (name) {
+        return makeResult(name, 'aria-labelledby');
+    }
+    return null;
+}
+/**
+ * Resolves accessible name via `aria-label` attribute.
+ *
+ * Implements AccName 1.2 §4.3.2 Step 2D:
+ * "If the current node has an `aria-label` attribute whose value is
+ * not undefined, not the empty string, and not a string of whitespace [...]"
+ *
+ * @param el - The element with a potential aria-label attribute
+ * @returns The resolved name result, or null if aria-label is not present or empty
+ * @see https://www.w3.org/TR/accname-1.2/#computation-steps — AccName 1.2 §4.3.2 Step 2D
+ */
+export function resolveAriaLabel(el) {
+    const label = el.getAttribute('aria-label');
+    if (label?.trim()) {
+        return makeResult(label, 'aria-label');
+    }
+    return null;
+}

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

@@ -0,0 +1,51 @@
+import type { AccnameElement, AccnameResolver, AccnameResult } from './types.js';
+/**
+ * Computes the accessible name for an element.
+ *
+ * Implements the Accessible Name and Description Computation algorithm
+ * per AccName 1.2 §4.3.2 ("Computation Steps") and HTML-AAM §4.1
+ * ("Accessible Name and Description Computation").
+ *
+ * Control flow (Steps map to AccName 1.2 §4.3.2):
+ *
+ * 1. **Step 2A — Hidden check** — If the element is hidden (per `isHidden`) and NOT
+ *    referenced by `aria-labelledby`, return empty immediately.
+ * 2. **Pre-computed name** — (Implementation-specific extension) If the
+ *    resolver provides `getPrecomputedName`, check it before standard steps.
+ *    Used by ml-core's Pretender integration for framework components.
+ * 3. **Step 2B — `aria-labelledby`** — Resolve referenced elements and
+ *    recursively compute their names. Skipped when already inside a
+ *    labelledby traversal (`inLabelledbyTraversal`) to prevent re-entry.
+ * 4. **Step 2D — `aria-label`** — Use the `aria-label` attribute value.
+ * 5. **Step 2E — Element-specific name** — Dispatch to HTML-AAM §4.1
+ *    element-specific rules (label association, alt, value, legend, caption, SVG title).
+ * 6. **Step 2F — Name from content** — If the element's role allows
+ *    `nameFrom: ["content"]`, or the element is referenced by `aria-labelledby`
+ *    (`inLabelledbyTraversal`), recursively collect child text (including
+ *    embedded control values per Step 2C).
+ * 7. **Step 2I — Title fallback** — Use the `title` attribute value.
+ *
+ * @param el - The element to compute the accessible name for
+ * @param resolver - Environment-dependent resolver for DOM traversal and role queries
+ * @returns The computed name and its source
+ * @see https://www.w3.org/TR/accname-1.2/#computation-steps — AccName 1.2 §4.3.2
+ * @see https://www.w3.org/TR/html-aam-1.0/#accessible-name-and-description-computation — HTML-AAM §4.1
+ */
+export declare function computeAccessibleName(el: AccnameElement, resolver: AccnameResolver): AccnameResult;
+/**
+ * Internal recursive entry point for accessible name computation.
+ *
+ * This function is the recursive core called by `resolveAriaLabelledby` (Step 2B),
+ * `resolveLabelText` (Step 2E), and `resolveNameFromContent` (Step 2F) when they
+ * need to compute a child or referenced element's name.
+ *
+ * @param el - The element to compute the accessible name for
+ * @param resolver - Environment-dependent resolver for DOM traversal and role queries
+ * @param inLabelledbyTraversal - When true, Step 2B is skipped to prevent re-entry
+ *   into `resolveAriaLabelledby`, and Step 2F name-from-content is enabled regardless
+ *   of role. This is set by Step 2B when processing each IDREF.
+ * @param visited - Set of element IDs already visited (cycle prevention for aria-labelledby)
+ * @returns The computed name and its source
+ * @see https://www.w3.org/TR/accname-1.2/#computation-steps — AccName 1.2 §4.3.2
+ */
+export declare function computeAccessibleNameInternal(el: AccnameElement, resolver: AccnameResolver, inLabelledbyTraversal: boolean, visited: ReadonlySet<string>): AccnameResult;

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

@@ -0,0 +1,101 @@
+/* eslint-disable @typescript-eslint/prefer-readonly-parameter-types -- AccnameElement wraps mutable DOM types */
+import { resolveAriaLabel, resolveAriaLabelledby } from './aria-steps.js';
+import { getElementSpecificName } from './element-names.js';
+import { makeResult, resolveNameFromContent } from './helpers.js';
+const EMPTY_RESULT = { name: '', source: null };
+/**
+ * Computes the accessible name for an element.
+ *
+ * Implements the Accessible Name and Description Computation algorithm
+ * per AccName 1.2 §4.3.2 ("Computation Steps") and HTML-AAM §4.1
+ * ("Accessible Name and Description Computation").
+ *
+ * Control flow (Steps map to AccName 1.2 §4.3.2):
+ *
+ * 1. **Step 2A — Hidden check** — If the element is hidden (per `isHidden`) and NOT
+ *    referenced by `aria-labelledby`, return empty immediately.
+ * 2. **Pre-computed name** — (Implementation-specific extension) If the
+ *    resolver provides `getPrecomputedName`, check it before standard steps.
+ *    Used by ml-core's Pretender integration for framework components.
+ * 3. **Step 2B — `aria-labelledby`** — Resolve referenced elements and
+ *    recursively compute their names. Skipped when already inside a
+ *    labelledby traversal (`inLabelledbyTraversal`) to prevent re-entry.
+ * 4. **Step 2D — `aria-label`** — Use the `aria-label` attribute value.
+ * 5. **Step 2E — Element-specific name** — Dispatch to HTML-AAM §4.1
+ *    element-specific rules (label association, alt, value, legend, caption, SVG title).
+ * 6. **Step 2F — Name from content** — If the element's role allows
+ *    `nameFrom: ["content"]`, or the element is referenced by `aria-labelledby`
+ *    (`inLabelledbyTraversal`), recursively collect child text (including
+ *    embedded control values per Step 2C).
+ * 7. **Step 2I — Title fallback** — Use the `title` attribute value.
+ *
+ * @param el - The element to compute the accessible name for
+ * @param resolver - Environment-dependent resolver for DOM traversal and role queries
+ * @returns The computed name and its source
+ * @see https://www.w3.org/TR/accname-1.2/#computation-steps — AccName 1.2 §4.3.2
+ * @see https://www.w3.org/TR/html-aam-1.0/#accessible-name-and-description-computation — HTML-AAM §4.1
+ */
+export function computeAccessibleName(el, resolver) {
+    return computeAccessibleNameInternal(el, resolver, false, new Set());
+}
+/**
+ * Internal recursive entry point for accessible name computation.
+ *
+ * This function is the recursive core called by `resolveAriaLabelledby` (Step 2B),
+ * `resolveLabelText` (Step 2E), and `resolveNameFromContent` (Step 2F) when they
+ * need to compute a child or referenced element's name.
+ *
+ * @param el - The element to compute the accessible name for
+ * @param resolver - Environment-dependent resolver for DOM traversal and role queries
+ * @param inLabelledbyTraversal - When true, Step 2B is skipped to prevent re-entry
+ *   into `resolveAriaLabelledby`, and Step 2F name-from-content is enabled regardless
+ *   of role. This is set by Step 2B when processing each IDREF.
+ * @param visited - Set of element IDs already visited (cycle prevention for aria-labelledby)
+ * @returns The computed name and its source
+ * @see https://www.w3.org/TR/accname-1.2/#computation-steps — AccName 1.2 §4.3.2
+ */
+export function computeAccessibleNameInternal(el, resolver, inLabelledbyTraversal, visited) {
+    // AccName 1.2 §4.3.2 Step 2A: Hidden elements return empty unless referenced by aria-labelledby
+    if (!inLabelledbyTraversal && resolver.isHidden(el)) {
+        return EMPTY_RESULT;
+    }
+    // [Implementation-specific] Pre-computed name (e.g., Pretender integration) — checked after hidden check
+    if (resolver.getPrecomputedName) {
+        const precomputed = resolver.getPrecomputedName(el);
+        if (precomputed != null) {
+            return makeResult(precomputed, 'content');
+        }
+    }
+    // AccName 1.2 §4.3.2 Step 2B: aria-labelledby (skipped when inside labelledby traversal)
+    if (!inLabelledbyTraversal) {
+        const labelledbyResult = resolveAriaLabelledby(el, resolver, visited, computeAccessibleNameInternal);
+        if (labelledbyResult) {
+            return labelledbyResult;
+        }
+    }
+    // AccName 1.2 §4.3.2 Step 2D: aria-label
+    const ariaLabelResult = resolveAriaLabel(el);
+    if (ariaLabelResult) {
+        return ariaLabelResult;
+    }
+    // AccName 1.2 §4.3.2 Step 2E: Element-specific name (HTML-AAM §4.1)
+    const elementResult = getElementSpecificName(el, resolver, visited, computeAccessibleNameInternal, inLabelledbyTraversal);
+    if (elementResult) {
+        return elementResult;
+    }
+    // AccName 1.2 §4.3.2 Step 2F/2C: Name from content
+    // Applies when the role allows nameFrom: ["content"] OR when the element is
+    // directly referenced by aria-labelledby (inLabelledbyTraversal).
+    if (resolver.allowsNameFromContent(el) || inLabelledbyTraversal) {
+        const content = resolveNameFromContent(el, resolver, visited, computeAccessibleNameInternal, inLabelledbyTraversal);
+        if (content.trim()) {
+            return makeResult(content, 'content');
+        }
+    }
+    // AccName 1.2 §4.3.2 Step 2I: Title attribute fallback
+    const title = el.getAttribute('title');
+    if (title?.trim()) {
+        return makeResult(title, 'title');
+    }
+    return EMPTY_RESULT;
+}

package/lib/algorithm/aria/accname/element-names.d.ts

@@ -0,0 +1,36 @@
+import type { AccnameElement, AccnameResolver, AccnameResult } from './types.js';
+/**
+ * Computes element-specific accessible name per HTML-AAM §4.1.
+ *
+ * Implements AccName 1.2 §4.3.2 Step 2E: for elements that have a native
+ * host language text alternative, use that alternative. The specific rules
+ * for each HTML element are defined in HTML-AAM §4.1.
+ *
+ * Returns null if no element-specific rule applies, letting the caller
+ * fall through to name-from-content (Step 2F) or title fallback (Step 2I).
+ *
+ * Control flow (dispatches by `localName`):
+ * - SVG elements → `handleSvgElement` (SVG-AAM: `<title>` child)
+ * - `<input>` → `handleInput` (branches by type: text-like, button, image, hidden)
+ * - `<textarea>`, `<select>`, `<meter>`, `<progress>`, `<output>` → `handleLabelableWithTitle`
+ * - `<button>` → `handleButton` (label → content → title)
+ * - `<fieldset>` → `handleFieldset` (legend → title)
+ * - `<table>` → `handleTable` (caption → title)
+ * - `<img>` → `handleImg` (alt → title)
+ * - `<area>` → `handleArea` (alt → title)
+ * - `<figure>` → `handleFigure` (title only)
+ * - `<summary>` → `handleSummary` (content → title)
+ * - `<a href>` → `handleAnchor` (content → title)
+ * - `<iframe>` → `handleTitleOnly` (title only)
+ * - All others → null (rely on caller's generic Steps 2F/2I)
+ *
+ * @param el - The element to compute the name for
+ * @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 computed name result, or null if no element-specific rule applies
+ * @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/#accessible-name-and-description-computation — HTML-AAM §4.1
+ */
+export declare function getElementSpecificName(el: AccnameElement, resolver: AccnameResolver, visited: ReadonlySet<string>, computeFn: (el: AccnameElement, resolver: AccnameResolver, inLabelledbyTraversal: boolean, visited: ReadonlySet<string>) => AccnameResult, inLabelledbyTraversal: boolean): AccnameResult | null;