@markuplint/ml-spec 5.0.0-rc.2 → 5.0.0-rc.5

package/CHANGELOG.md

@@ -3,6 +3,24 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+# [5.0.0-rc.5](https://github.com/markuplint/markuplint/compare/v5.0.0-rc.4...v5.0.0-rc.5) (2026-08-28)
+
+### Bug Fixes
+
+- **html-spec:** div in dl allows exactly one dt+dd group per HTML LS ([6f344bb](https://github.com/markuplint/markuplint/commit/6f344bbc72bc82dbe2d1ebf05600a5fce9838de1))
+
+### Features
+
+- **ml-spec:** add requiredCondition field to ARIARoleOwnedProperties ([6867215](https://github.com/markuplint/markuplint/commit/686721537b3d9b141dac12666a2796635d320151)), closes [#3682](https://github.com/markuplint/markuplint/issues/3682)
+
+# [5.0.0-rc.4](https://github.com/markuplint/markuplint/compare/v5.0.0-rc.3...v5.0.0-rc.4) (2026-04-19)
+
+**Note:** Version bump only for package @markuplint/ml-spec
+
+# [5.0.0-rc.3](https://github.com/markuplint/markuplint/compare/v5.0.0-rc.2...v5.0.0-rc.3) (2026-04-19)
+
+**Note:** Version bump only for package @markuplint/ml-spec
+
 # [5.0.0-rc.2](https://github.com/markuplint/markuplint/compare/v5.0.0-rc.1...v5.0.0-rc.2) (2026-04-15)
 
 ### Bug Fixes

package/README.md

@@ -126,14 +126,6 @@ yarn add @markuplint/ml-spec
 - "HTML Schema" and "Specs" are used interchangeably in markuplint to mean the JSON Schema that
   describes HTML element specs (attributes, ARIA, content models, etc) and their TypeScript types.
 
-### Contributing
-
-For schema editing workflows, generation commands, common recipes, dependency management, and troubleshooting, see the [Maintenance Guide](docs/maintenance.md).
-
-For schema merging and spec extension details, see [Spec Resolution](docs/spec-resolution.md).
-
-For content model categories and pattern format, see [HTML Algorithms](docs/html-algorithms.md).
-
 ### License
 
 MIT

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

@@ -1,25 +1,10 @@
 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
@@ -29,23 +14,14 @@ import type { AccnameElement, AccnameResolver, AccnameResult } from './types.js'
  * 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

@@ -1,26 +1,11 @@
 /* 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
@@ -30,11 +15,6 @@ import { flattenText, makeResult } from './helpers.js';
  * 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) {
@@ -84,14 +64,10 @@ export function resolveAriaLabelledby(el, resolver, visited, computeFn) {
     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) {

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

@@ -33,19 +33,9 @@ import type { AccnameElement, AccnameResolver, AccnameResult } from './types.js'
  */
 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

@@ -39,19 +39,9 @@ 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) {

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

@@ -1,7 +1,5 @@
 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.
@@ -9,27 +7,6 @@ import type { AccnameElement, AccnameResolver, AccnameResult } from './types.js'
  * 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
  */

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

@@ -3,8 +3,6 @@ import { DEFAULT_IMAGE_LABEL, DEFAULT_RESET_LABEL, DEFAULT_SUBMIT_LABEL, TEXT_IN
 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.
@@ -12,27 +10,6 @@ import { resolveLabelText } from './label-steps.js';
  * 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
  */

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

@@ -1,40 +1,16 @@
 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.
+ *   an embedded control, return the embedded control's value." Per spec,
+ *   `aria-label` is ignored for embedded controls during this traversal.
  *
  * **Limitation:** CSS-generated content (`::before`/`::after` with the `content`
  * property) is not included. AccName 1.2 §4.3.2 Step 2G specifies that CSS
@@ -42,52 +18,14 @@ export declare function flattenText(text: string): string;
  * 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.

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

@@ -1,13 +1,6 @@
 /* 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 {
@@ -15,35 +8,18 @@ export function makeResult(name, source) {
         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.
+ *   an embedded control, return the embedded control's value." Per spec,
+ *   `aria-label` is ignored for embedded controls during this traversal.
  *
  * **Limitation:** CSS-generated content (`::before`/`::after` with the `content`
  * property) is not included. AccName 1.2 §4.3.2 Step 2G specifies that CSS
@@ -51,12 +27,6 @@ export function flattenText(text) {
  * 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
  */
@@ -131,8 +101,6 @@ function collectTextContent(el, resolver, visited, computeFn, inLabelledbyTraver
     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
@@ -214,9 +182,6 @@ function getSelectedOptionText(el) {
     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
@@ -240,19 +205,9 @@ function collectOptions(el) {
     }
     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) {
@@ -261,12 +216,6 @@ export function findChildByLocalName(el, localName) {
     }
     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) {
@@ -277,13 +226,6 @@ export function findAncestorLabel(el) {
     }
     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) {
@@ -298,24 +240,12 @@ export function resolveLabel(el, resolver) {
     }
     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;
 }

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

@@ -1,24 +1,8 @@
 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, the HTML label
+ * association is checked before other element-specific rules.
  *
- * 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
  */

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

@@ -2,25 +2,9 @@
 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, the HTML label
+ * association is checked before other element-specific rules.
  *
- * 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
  */
@@ -43,9 +27,9 @@ export function resolveLabelText(el, resolver, visited, computeFn, inLabelledbyT
     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.
+ * 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.
  */
 function collectLabelText(label, labeledElement, resolver, visited, computeFn, inLabelledbyTraversal) {
     const parts = [];

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

@@ -61,9 +61,6 @@ 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/get-explicit-role.d.ts

@@ -1,14 +1,7 @@
 import type { ARIAVersion, ComputedRole, MLMLSpec } from '../../types/index.js';
 /**
- * Resolves the ARIA role from the `role` attribute value, implementing the
- * WAI-ARIA "Handling Author Errors" algorithm. Iterates through whitespace-separated
- * role tokens and returns the first one that passes all validation checks
- * (exists, non-abstract, permitted, valid landmark).
+ * Implements the WAI-ARIA "Handling Author Errors" algorithm.
  *
  * @see https://w3c.github.io/aria/#document-handling_author-errors
- * @param specs - The full markup language specification
- * @param el - The DOM element to resolve the explicit role for
- * @param version - The ARIA specification version to use
- * @returns The first valid role found as a `ComputedRole`, or `role: null` with the last encountered error type
  */
 export declare function getExplicitRole(specs: MLMLSpec, el: Element, version: ARIAVersion): ComputedRole;

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

@@ -2,16 +2,9 @@ import { getRoleSpec } from './get-role-spec.js';
 import { resolveNamespace } from '../../utils/resolve-namespace.js';
 import { getPermittedRoles } from './get-permitted-roles.js';
 /**
- * Resolves the ARIA role from the `role` attribute value, implementing the
- * WAI-ARIA "Handling Author Errors" algorithm. Iterates through whitespace-separated
- * role tokens and returns the first one that passes all validation checks
- * (exists, non-abstract, permitted, valid landmark).
+ * Implements the WAI-ARIA "Handling Author Errors" algorithm.
  *
  * @see https://w3c.github.io/aria/#document-handling_author-errors
- * @param specs - The full markup language specification
- * @param el - The DOM element to resolve the explicit role for
- * @param version - The ARIA specification version to use
- * @returns The first valid role found as a `ComputedRole`, or `role: null` with the last encountered error type
  */
 export function getExplicitRole(specs, 
 // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types

package/lib/algorithm/aria/get-non-presentational-ancestor.d.ts

@@ -1,15 +1,7 @@
 import type { ARIAVersion, MLMLSpec } from '../../types/index.js';
 /**
- * Traverses the parent element chain to find the nearest ancestor with a
- * non-presentational role, skipping elements that are transparent for
- * ownership traversal (via `isTransparentForOwnership`).
- *
- * In ARIA 1.3, `generic` role elements are additionally transparent.
- *
- * @param el - The DOM element whose ancestors to traverse
- * @param specs - The full markup language specification
- * @param version - The ARIA specification version to use
- * @returns The nearest non-presentational ancestor's `ComputedRole`, or `{ el: null, role: null }` if none exists
+ * In ARIA 1.3, `generic` role elements are additionally transparent for
+ * ownership traversal.
  */
 export declare function getNonPresentationalAncestor(el: Element, specs: MLMLSpec, version: ARIAVersion): import("../../types/index.js").ComputedRole | {
     el: null;