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

package/lib/algorithm/aria/accname/element-names.js

@@ -0,0 +1,342 @@
+/* eslint-disable @typescript-eslint/prefer-readonly-parameter-types -- AccnameElement wraps mutable DOM types */
+import { DEFAULT_IMAGE_LABEL, DEFAULT_RESET_LABEL, DEFAULT_SUBMIT_LABEL, TEXT_INPUT_TYPES, } from '../../../const/index.js';
+import { findChildByLocalName, getInputType, isSvgElement, makeResult, resolveNameFromContent } from './helpers.js';
+import { resolveLabelText } from './label-steps.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 function getElementSpecificName(el, resolver, visited, computeFn, inLabelledbyTraversal) {
+    if (isSvgElement(el)) {
+        return handleSvgElement(el);
+    }
+    const { localName } = el;
+    switch (localName) {
+        case 'input': {
+            return handleInput(el, resolver, visited, computeFn, inLabelledbyTraversal);
+        }
+        case 'textarea':
+        case 'select':
+        case 'meter':
+        case 'progress':
+        case 'output': {
+            return handleLabelableWithTitle(el, resolver, visited, computeFn, inLabelledbyTraversal);
+        }
+        case 'button': {
+            return handleButton(el, resolver, visited, computeFn, inLabelledbyTraversal);
+        }
+        case 'fieldset': {
+            return handleFieldset(el, resolver, visited, computeFn, inLabelledbyTraversal);
+        }
+        case 'table': {
+            return handleTable(el, resolver, visited, computeFn, inLabelledbyTraversal);
+        }
+        case 'img': {
+            return handleImg(el);
+        }
+        case 'area': {
+            return handleArea(el);
+        }
+        case 'figure': {
+            return handleFigure(el);
+        }
+        case 'summary': {
+            return handleSummary(el, resolver, visited, computeFn, inLabelledbyTraversal);
+        }
+        case 'a': {
+            if (el.hasAttribute('href')) {
+                return handleAnchor(el, resolver, visited, computeFn, inLabelledbyTraversal);
+            }
+            return null;
+        }
+        case 'iframe': {
+            return handleTitleOnly(el);
+        }
+        default: {
+            // All other elements (tr, td, th, section, div, span, p, h1-h6, etc.)
+            // only get name from title (handled by caller's title fallback)
+            return null;
+        }
+    }
+}
+/**
+ * HTML-AAM §4.1 (input[text-like], textarea, select, meter, progress, output).
+ * Name sources: label → title → placeholder.
+ * @see https://www.w3.org/TR/html-aam-1.0/#el-input-text
+ */
+function handleLabelableWithTitle(el, resolver, visited, computeFn, inLabelledbyTraversal) {
+    const labelResult = resolveLabelText(el, resolver, visited, computeFn, inLabelledbyTraversal);
+    if (labelResult) {
+        return labelResult;
+    }
+    const title = el.getAttribute('title');
+    if (title?.trim()) {
+        return makeResult(title, 'title');
+    }
+    const placeholder = el.getAttribute('placeholder');
+    if (placeholder?.trim()) {
+        return makeResult(placeholder, 'placeholder');
+    }
+    return null;
+}
+/**
+ * HTML-AAM §4.1 (input — dispatches by type).
+ * Text-like types: label → title → placeholder.
+ * Button/submit/reset: label → value → default label.
+ * Image: label → alt → title → default label.
+ * Hidden: always empty.
+ * Checkbox/radio: label → title.
+ * @see https://www.w3.org/TR/html-aam-1.0/#el-input-text
+ */
+function handleInput(el, resolver, visited, computeFn, inLabelledbyTraversal) {
+    const type = getInputType(el);
+    if (TEXT_INPUT_TYPES.has(type)) {
+        return handleLabelableWithTitle(el, resolver, visited, computeFn, inLabelledbyTraversal);
+    }
+    if (type === 'button' || type === 'submit' || type === 'reset') {
+        return handleInputButton(el, type, resolver, visited, computeFn, inLabelledbyTraversal);
+    }
+    if (type === 'image') {
+        return handleInputImage(el, resolver, visited, computeFn, inLabelledbyTraversal);
+    }
+    if (type === 'hidden') {
+        return makeResult('', null);
+    }
+    // checkbox, radio: label -> title
+    return handleLabelableWithTitle(el, resolver, visited, computeFn, inLabelledbyTraversal);
+}
+/**
+ * HTML-AAM §4.1 (input[type=button/submit/reset]).
+ * Name sources: label → value → title → default label (submit="Submit", reset="Reset").
+ * @see https://www.w3.org/TR/html-aam-1.0/#el-input-button
+ */
+function handleInputButton(el, type, resolver, visited, computeFn, inLabelledbyTraversal) {
+    const labelResult = resolveLabelText(el, resolver, visited, computeFn, inLabelledbyTraversal);
+    if (labelResult) {
+        return labelResult;
+    }
+    const value = el.getAttribute('value');
+    if (value?.trim()) {
+        return makeResult(value, 'value');
+    }
+    const title = el.getAttribute('title');
+    if (title?.trim()) {
+        return makeResult(title, 'title');
+    }
+    // Default label for submit/reset buttons
+    if (type === 'submit') {
+        return makeResult(DEFAULT_SUBMIT_LABEL, 'default');
+    }
+    if (type === 'reset') {
+        return makeResult(DEFAULT_RESET_LABEL, 'default');
+    }
+    return null;
+}
+/**
+ * HTML-AAM §4.1 (input[type=image]).
+ * Name sources: label → alt → title → default ("Submit Query").
+ * @see https://www.w3.org/TR/html-aam-1.0/#el-input-image
+ */
+function handleInputImage(el, resolver, visited, computeFn, inLabelledbyTraversal) {
+    const labelResult = resolveLabelText(el, resolver, visited, computeFn, inLabelledbyTraversal);
+    if (labelResult) {
+        return labelResult;
+    }
+    const alt = el.getAttribute('alt');
+    if (alt?.trim()) {
+        return makeResult(alt, 'alt');
+    }
+    const title = el.getAttribute('title');
+    if (title?.trim()) {
+        return makeResult(title, 'title');
+    }
+    return makeResult(DEFAULT_IMAGE_LABEL, 'default');
+}
+/**
+ * HTML-AAM §4.1 (button).
+ * Name sources: label → content → title.
+ * @see https://www.w3.org/TR/html-aam-1.0/#el-button
+ */
+function handleButton(el, resolver, visited, computeFn, inLabelledbyTraversal) {
+    const labelResult = resolveLabelText(el, resolver, visited, computeFn, inLabelledbyTraversal);
+    if (labelResult) {
+        return labelResult;
+    }
+    const content = resolveNameFromContent(el, resolver, visited, computeFn, inLabelledbyTraversal);
+    if (content.trim()) {
+        return makeResult(content, 'content');
+    }
+    const title = el.getAttribute('title');
+    if (title?.trim()) {
+        return makeResult(title, 'title');
+    }
+    return null;
+}
+/**
+ * HTML-AAM §4.1 (fieldset).
+ * Name sources: legend (content) → title.
+ * @see https://www.w3.org/TR/html-aam-1.0/#el-fieldset
+ */
+function handleFieldset(el, resolver, visited, computeFn, inLabelledbyTraversal) {
+    const legend = findChildByLocalName(el, 'legend');
+    if (legend) {
+        const content = resolveNameFromContent(legend, resolver, visited, computeFn, inLabelledbyTraversal);
+        if (content.trim()) {
+            return makeResult(content, 'legend');
+        }
+    }
+    const title = el.getAttribute('title');
+    if (title?.trim()) {
+        return makeResult(title, 'title');
+    }
+    return null;
+}
+/**
+ * HTML-AAM §4.1 (table).
+ * Name sources: caption (content) → title.
+ * @see https://www.w3.org/TR/html-aam-1.0/#el-table
+ */
+function handleTable(el, resolver, visited, computeFn, inLabelledbyTraversal) {
+    const caption = findChildByLocalName(el, 'caption');
+    if (caption) {
+        const content = resolveNameFromContent(caption, resolver, visited, computeFn, inLabelledbyTraversal);
+        if (content.trim()) {
+            return makeResult(content, 'caption');
+        }
+    }
+    const title = el.getAttribute('title');
+    if (title?.trim()) {
+        return makeResult(title, 'title');
+    }
+    return null;
+}
+/**
+ * HTML-AAM §4.1 (img).
+ * Name sources: alt → title (only when alt is not specified).
+ * When alt="" (empty), returns empty name with null source (decorative image).
+ * @see https://www.w3.org/TR/html-aam-1.0/#el-img
+ */
+function handleImg(el) {
+    if (el.hasAttribute('alt')) {
+        const alt = el.getAttribute('alt') ?? '';
+        return makeResult(alt, alt.trim() ? 'alt' : null);
+    }
+    const title = el.getAttribute('title');
+    if (title?.trim()) {
+        return makeResult(title, 'title');
+    }
+    return null;
+}
+/**
+ * HTML-AAM §4.1 (area).
+ * Name sources: alt → title.
+ * @see https://www.w3.org/TR/html-aam-1.0/#el-area
+ */
+function handleArea(el) {
+    const alt = el.getAttribute('alt');
+    if (alt?.trim()) {
+        return makeResult(alt, 'alt');
+    }
+    const title = el.getAttribute('title');
+    if (title?.trim()) {
+        return makeResult(title, 'title');
+    }
+    return null;
+}
+/**
+ * HTML-AAM §4.1 (figure).
+ * Name sources: title only. Note: figcaption provides the accessible
+ * *description*, not the name, per HTML-AAM.
+ * @see https://www.w3.org/TR/html-aam-1.0/#el-figure
+ */
+function handleFigure(el) {
+    const title = el.getAttribute('title');
+    if (title?.trim()) {
+        return makeResult(title, 'title');
+    }
+    return null;
+}
+/**
+ * HTML-AAM §4.1 (summary).
+ * Name sources: content → title.
+ * @see https://www.w3.org/TR/html-aam-1.0/#el-summary
+ */
+function handleSummary(el, resolver, visited, computeFn, inLabelledbyTraversal) {
+    const content = resolveNameFromContent(el, resolver, visited, computeFn, inLabelledbyTraversal);
+    if (content.trim()) {
+        return makeResult(content, 'content');
+    }
+    const title = el.getAttribute('title');
+    if (title?.trim()) {
+        return makeResult(title, 'title');
+    }
+    return null;
+}
+/**
+ * HTML-AAM §4.1 (a[href]).
+ * Name sources: content → title.
+ * @see https://www.w3.org/TR/html-aam-1.0/#el-a
+ */
+function handleAnchor(el, resolver, visited, computeFn, inLabelledbyTraversal) {
+    const content = resolveNameFromContent(el, resolver, visited, computeFn, inLabelledbyTraversal);
+    if (content.trim()) {
+        return makeResult(content, 'content');
+    }
+    const title = el.getAttribute('title');
+    if (title?.trim()) {
+        return makeResult(title, 'title');
+    }
+    return null;
+}
+/**
+ * HTML-AAM §4.1 (iframe) — name from title attribute only.
+ * @see https://www.w3.org/TR/html-aam-1.0/#el-iframe
+ */
+function handleTitleOnly(el) {
+    const title = el.getAttribute('title');
+    if (title?.trim()) {
+        return makeResult(title, 'title');
+    }
+    return null;
+}
+/**
+ * SVG-AAM: SVG elements get name from `<title>` child element.
+ * @see https://www.w3.org/TR/svg-aam-1.0/#mapping_additional_nd — SVG-AAM §8.1
+ */
+function handleSvgElement(el) {
+    const titleEl = findChildByLocalName(el, 'title');
+    if (titleEl?.textContent?.trim()) {
+        return makeResult(titleEl.textContent, 'svg-title');
+    }
+    return null;
+}

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

@@ -0,0 +1,98 @@
+import type { AccnameElement, AccnameResolver, AccnameResult, AccnameSource } from './types.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 declare function makeResult(name: string, source: AccnameSource | null): AccnameResult;
+/**
+ * Collapses internal whitespace and trims a string.
+ *
+ * @param text - The string to normalize
+ * @returns The string with collapsed whitespace and trimmed
+ */
+export declare function flattenText(text: string): string;
+/**
+ * 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 declare function resolveNameFromContent(el: AccnameElement, resolver: AccnameResolver, visited: ReadonlySet<string>, computeFn: (el: AccnameElement, resolver: AccnameResolver, inLabelledbyTraversal: boolean, visited: ReadonlySet<string>) => AccnameResult, inLabelledbyTraversal: boolean): string;
+/**
+ * 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 declare function findChildByLocalName(el: AccnameElement, localName: string): AccnameElement | 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 declare function findAncestorLabel(el: AccnameElement): AccnameElement | 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 declare function resolveLabel(el: AccnameElement, resolver: AccnameResolver): readonly AccnameElement[];
+/**
+ * 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 declare function getInputType(el: AccnameElement): string;
+/**
+ * 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 declare function isSvgElement(el: AccnameElement): boolean;
+/**
+ * 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 declare function escapeCSS(value: string): string;