@markuplint/ml-spec 5.0.0 → 5.1.0

package/CHANGELOG.md

@@ -3,6 +3,21 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+# [5.1.0](https://github.com/markuplint/markuplint/compare/v5.0.1...v5.1.0) (2026-10-08)
+
+### Bug Fixes
+
+- **ml-spec:** read option, SVG title and control text through the accname resolver ([4c66d1f](https://github.com/markuplint/markuplint/commit/4c66d1fb960e746dc9f3c6cec0c8b3c9284a657e))
+- **ml-spec:** read the SVG title and select options through the accname resolver ([0a7c162](https://github.com/markuplint/markuplint/commit/0a7c162a83a553d7872388184ea0020735def6fb)), closes [#4067](https://github.com/markuplint/markuplint/issues/4067)
+
+### Features
+
+- **ml-spec:** let the accname resolver supply the child nodes to traverse ([caa8263](https://github.com/markuplint/markuplint/commit/caa82633dcecb604b32e8e9438b1096c116f059c)), closes [#4056](https://github.com/markuplint/markuplint/issues/4056)
+
+## [5.0.1](https://github.com/markuplint/markuplint/compare/v5.0.0...v5.0.1) (2026-09-22)
+
+**Note:** Version bump only for package @markuplint/ml-spec
+
 # [5.0.0](https://github.com/markuplint/markuplint/compare/v5.0.0-rc.7...v5.0.0) (2026-09-11)
 
 **Note:** Version bump only for package @markuplint/ml-spec

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

@@ -1,6 +1,6 @@
 /* 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 { findChildByLocalName, getInputType, getTextContent, isSvgElement, makeResult, resolveNameFromContent, } from './helpers.js';
 import { resolveLabelText } from './label-steps.js';
 /**
  * Implements AccName 1.2 §4.3.2 Step 2E: for elements that have a native
@@ -15,7 +15,7 @@ import { resolveLabelText } from './label-steps.js';
  */
 export function getElementSpecificName(el, resolver, visited, computeFn, inLabelledbyTraversal) {
     if (isSvgElement(el)) {
-        return handleSvgElement(el);
+        return handleSvgElement(el, resolver);
     }
     const { localName } = el;
     switch (localName) {
@@ -185,7 +185,7 @@ function handleButton(el, resolver, visited, computeFn, inLabelledbyTraversal) {
  * @see https://www.w3.org/TR/html-aam-1.0/#el-fieldset
  */
 function handleFieldset(el, resolver, visited, computeFn, inLabelledbyTraversal) {
-    const legend = findChildByLocalName(el, 'legend');
+    const legend = findChildByLocalName(el, 'legend', resolver);
     if (legend) {
         const content = resolveNameFromContent(legend, resolver, visited, computeFn, inLabelledbyTraversal);
         if (content.trim()) {
@@ -204,7 +204,7 @@ function handleFieldset(el, resolver, visited, computeFn, inLabelledbyTraversal)
  * @see https://www.w3.org/TR/html-aam-1.0/#el-table
  */
 function handleTable(el, resolver, visited, computeFn, inLabelledbyTraversal) {
-    const caption = findChildByLocalName(el, 'caption');
+    const caption = findChildByLocalName(el, 'caption', resolver);
     if (caption) {
         const content = resolveNameFromContent(caption, resolver, visited, computeFn, inLabelledbyTraversal);
         if (content.trim()) {
@@ -310,10 +310,11 @@ function handleTitleOnly(el) {
  * 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');
+function handleSvgElement(el, resolver) {
+    const titleEl = findChildByLocalName(el, 'title', resolver);
+    const title = titleEl ? getTextContent(titleEl, resolver) : '';
+    if (title.trim()) {
+        return makeResult(title, 'svg-title');
     }
     return null;
 }

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

@@ -1,4 +1,4 @@
-import type { AccnameElement, AccnameResolver, AccnameResult, AccnameSource } from './types.js';
+import type { AccnameElement, AccnameNode, AccnameResolver, AccnameResult, AccnameSource } 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;
@@ -22,7 +22,18 @@ export declare function flattenText(text: string): string;
  * @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;
-export declare function findChildByLocalName(el: AccnameElement, localName: string): AccnameElement | null;
+/**
+ * The child nodes to traverse for `el`: what the resolver says it renders,
+ * or `el.childNodes` when it says nothing.
+ */
+export declare function getChildNodes(el: AccnameElement, resolver: AccnameResolver): Iterable<AccnameNode>;
+/**
+ * `el.textContent` as the resolver sees the element: the text of the nodes it
+ * says the element renders, at any depth. Text written inside a pretended
+ * component that never renders its children is not among them.
+ */
+export declare function getTextContent(el: AccnameElement, resolver: AccnameResolver): string;
+export declare function findChildByLocalName(el: AccnameElement, localName: string, resolver?: AccnameResolver): AccnameElement | 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;

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

@@ -32,7 +32,7 @@ export function flattenText(text) {
  */
 export function resolveNameFromContent(el, resolver, visited, computeFn, inLabelledbyTraversal) {
     const parts = [];
-    for (const child of el.childNodes) {
+    for (const child of getChildNodes(el, resolver)) {
         if (child.nodeType === TEXT_NODE) {
             parts.push(child.textContent ?? '');
         }
@@ -40,7 +40,7 @@ export function resolveNameFromContent(el, resolver, visited, computeFn, inLabel
             const childEl = child;
             if (resolver.isEmbeddedControl(childEl)) {
                 // Step 2C: Embedded controls — use value directly, aria-label is ignored
-                parts.push(getEmbeddedControlValue(childEl));
+                parts.push(getEmbeddedControlValue(childEl, resolver));
             }
             else {
                 const result = computeFn(childEl, resolver, inLabelledbyTraversal, visited);
@@ -78,14 +78,14 @@ function collectTextContent(el, resolver, visited, computeFn, inLabelledbyTraver
         return '';
     }
     const parts = [];
-    for (const child of el.childNodes) {
+    for (const child of getChildNodes(el, resolver)) {
         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));
+                parts.push(getEmbeddedControlValue(childEl, resolver));
             }
             else {
                 const result = computeFn(childEl, resolver, inLabelledbyTraversal, visited);
@@ -110,7 +110,7 @@ function collectTextContent(el, resolver, visited, computeFn, inLabelledbyTraver
  *
  * @see https://www.w3.org/TR/accname-1.2/#comp_embedded_control — AccName 1.2 §4.3.2 Step 2C
  */
-function getEmbeddedControlValue(el) {
+function getEmbeddedControlValue(el, resolver) {
     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')) {
@@ -126,7 +126,7 @@ function getEmbeddedControlValue(el) {
         if (value?.trim()) {
             return value;
         }
-        return el.textContent ?? '';
+        return getTextContent(el, resolver);
     }
     // Textbox/combobox: value attr -> textContent
     if (role === 'textbox' ||
@@ -138,13 +138,13 @@ function getEmbeddedControlValue(el) {
         if (value != null) {
             return value;
         }
-        return el.textContent ?? '';
+        return getTextContent(el, resolver);
     }
     // Listbox/select: selected option text
     if (el.localName === 'select') {
-        return getSelectedOptionText(el);
+        return getSelectedOptionText(el, resolver);
     }
-    return el.textContent ?? '';
+    return getTextContent(el, resolver);
 }
 /**
  * Gets the text content of the selected `<option>` elements within a `<select>`.
@@ -170,16 +170,16 @@ function getEmbeddedControlValue(el) {
  *
  * @see https://github.com/markuplint/markuplint/issues/2069 — `<select>` and `<selectedcontent>` support
  */
-function getSelectedOptionText(el) {
-    const options = collectOptions(el);
+function getSelectedOptionText(el, resolver) {
+    const options = collectOptions(el, resolver);
     const selected = options.filter(opt => opt.hasAttribute('selected'));
     if (selected.length > 0) {
-        return selected.map(opt => opt.textContent?.trim() ?? '').join(' ');
+        return selected.map(opt => getTextContent(opt, resolver).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() ?? '';
+    return first ? getTextContent(first, resolver).trim() : '';
 }
 /**
  * **Note (#2069):** Customizable `<select>` allows non-option children
@@ -189,14 +189,14 @@ function getSelectedOptionText(el) {
  *
  * @see https://github.com/markuplint/markuplint/issues/2069
  */
-function collectOptions(el) {
+function collectOptions(el, resolver) {
     const result = [];
-    for (const child of el.children) {
+    for (const child of getChildElements(el, resolver)) {
         if (child.localName === 'option') {
             result.push(child);
         }
         else if (child.localName === 'optgroup') {
-            for (const grandchild of child.children) {
+            for (const grandchild of getChildElements(child, resolver)) {
                 if (grandchild.localName === 'option') {
                     result.push(grandchild);
                 }
@@ -208,9 +208,47 @@ function collectOptions(el) {
 function isTextLikeInput(el) {
     return TEXT_LIKE_INPUT_TYPES.has(getInputType(el));
 }
-export function findChildByLocalName(el, localName) {
-    for (const child of el.children) {
-        if (child.localName === localName) {
+/**
+ * The child nodes to traverse for `el`: what the resolver says it renders,
+ * or `el.childNodes` when it says nothing.
+ */
+export function getChildNodes(el, resolver) {
+    return resolver.getChildNodes?.(el) ?? el.childNodes;
+}
+/**
+ * `el.textContent` as the resolver sees the element: the text of the nodes it
+ * says the element renders, at any depth. Text written inside a pretended
+ * component that never renders its children is not among them.
+ */
+export function getTextContent(el, resolver) {
+    if (!resolver.getChildNodes) {
+        return el.textContent ?? '';
+    }
+    let text = '';
+    for (const child of resolver.getChildNodes(el)) {
+        if (child.nodeType === TEXT_NODE) {
+            text += child.textContent ?? '';
+        }
+        else if (child.nodeType === ELEMENT_NODE) {
+            text += getTextContent(child, resolver);
+        }
+    }
+    return text;
+}
+function getChildElements(el, resolver) {
+    return [...getChildNodes(el, resolver)].filter((child) => child.nodeType === ELEMENT_NODE);
+}
+export function findChildByLocalName(el, localName, resolver) {
+    if (!resolver?.getChildNodes) {
+        for (const child of el.children) {
+            if (child.localName === localName) {
+                return child;
+            }
+        }
+        return null;
+    }
+    for (const child of resolver.getChildNodes(el)) {
+        if (child.nodeType === ELEMENT_NODE && child.localName === localName) {
             return child;
         }
     }

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

@@ -1,6 +1,6 @@
 /* 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';
+import { flattenText, getChildNodes, makeResult, resolveLabel } from './helpers.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.
@@ -33,7 +33,7 @@ export function resolveLabelText(el, resolver, visited, computeFn, inLabelledbyT
  */
 function collectLabelText(label, labeledElement, resolver, visited, computeFn, inLabelledbyTraversal) {
     const parts = [];
-    for (const child of label.childNodes) {
+    for (const child of getChildNodes(label, resolver)) {
         if (child.nodeType === TEXT_NODE) {
             parts.push(child.textContent ?? '');
         }

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

@@ -10,6 +10,13 @@ import type { AccnameElement } from './types.js';
  *
  * Checks (in order): `aria-label`, `aria-labelledby`, `<title>` child, `<desc>` child.
  *
+ * Known limitation: this reads `el.children`, not `AccnameResolver.getChildNodes`,
+ * because `getComputedRole` has no resolver to pass. For a pretended component it
+ * therefore answers from the children written at the usage site, while the name
+ * computation reads the ones the component renders. A `<title>` that comes only
+ * from the `contents` of a pretender names nothing in either: those entries are
+ * childless, so it has no text.
+ *
  * @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

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

@@ -10,6 +10,13 @@
  *
  * Checks (in order): `aria-label`, `aria-labelledby`, `<title>` child, `<desc>` child.
  *
+ * Known limitation: this reads `el.children`, not `AccnameResolver.getChildNodes`,
+ * because `getComputedRole` has no resolver to pass. For a pretended component it
+ * therefore answers from the children written at the usage site, while the name
+ * computation reads the ones the component renders. A `<title>` that comes only
+ * from the `contents` of a pretender names nothing in either: those entries are
+ * childless, so it has no text.
+ *
  * @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

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

@@ -48,6 +48,17 @@ export interface AccnameResolver {
      * accessible names through configuration.
      */
     getPrecomputedName?(el: AccnameElement): string | null;
+    /**
+     * Returns the child nodes to traverse for `el`, in place of `el.childNodes`.
+     * 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>`).
+     * 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
+     * an embedded control. `hasSvgAccessibleNameSource` is the exception.
+     */
+    getChildNodes?(el: AccnameElement): Iterable<AccnameNode>;
 }
 /**
  * Identifies the source of an element's accessible name per HTML-AAM §4.1.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@markuplint/ml-spec",
-	"version": "5.0.0",
+	"version": "5.1.0",
 	"description": "Types and schema that specs of the Markup languages for markuplint",
 	"repository": {
 		"type": "git",
@@ -36,14 +36,14 @@
 		"schema:aria": "npx json2ts ./schemas/aria.schema.json --cwd ./schemas > ./src/types/aria.ts"
 	},
 	"dependencies": {
-		"@markuplint/ml-ast": "5.0.0",
-		"@markuplint/types": "5.0.0",
+		"@markuplint/ml-ast": "5.1.0",
+		"@markuplint/types": "5.1.0",
 		"is-plain-object": "5.0.0",
 		"type-fest": "5.6.0"
 	},
 	"devDependencies": {
-		"@markuplint/test-tools": "5.0.0",
+		"@markuplint/test-tools": "5.1.0",
 		"json-schema-to-typescript": "15.0.4"
 	},
-	"gitHead": "c99706fda4c186aeb87b521eaabc5208ac144bbd"
+	"gitHead": "3a061784a8211034ad0c1cbd64798c0213414f65"
 }