@markuplint/ml-spec 4.10.1 → 4.10.2

package/lib/algorithm/aria/get-computed-aria-props.js

@@ -1,5 +1,15 @@
 import { ariaSpecs as _ariaSpecs } from './aria-specs.js';
 import { getComputedRole } from './get-computed-role.js';
+/**
+ * Computes the resolved ARIA properties for an element based on its computed role.
+ * Resolves property values by checking explicit `aria-*` attributes first,
+ * then equivalent HTML attributes, and finally falling back to spec-defined defaults.
+ *
+ * @param specs - The full markup language specification
+ * @param el - The DOM element to compute ARIA properties for
+ * @param version - The ARIA specification version to use
+ * @returns A record of ARIA property names to their computed property details, or an empty record if the element has no computed role
+ */
 export function getComputedAriaProps(specs, 
 // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
 el, version) {

package/lib/algorithm/aria/get-computed-role.d.ts

@@ -1,2 +1,14 @@
 import type { ARIAVersion, ComputedRole, MLMLSpec } from '../../types/index.js';
+/**
+ * Computes the final ARIA role for an element according to the WAI-ARIA specification,
+ * applying the Presentational Roles Conflict Resolution algorithm. This considers
+ * the explicit role, implicit role, required context roles, focusability,
+ * global ARIA properties, and SVG accessibility tree inclusion rules.
+ *
+ * @param specs - The full markup language specification
+ * @param el - The DOM element to compute the role for
+ * @param version - The ARIA specification version to use
+ * @param assumeSingleNode - When true, skips parent context validation and assumes the element is a standalone fragment
+ * @returns The computed role result including the resolved role spec (or null) and any error type
+ */
 export declare function getComputedRole(specs: MLMLSpec, el: Element, version: ARIAVersion, assumeSingleNode?: boolean): ComputedRole;

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

@@ -8,6 +8,18 @@ import { getNonPresentationalAncestor } from './get-non-presentational-ancestor.
 import { isRequiredOwnedElement } from './has-required-owned-elements.js';
 import { matchesContextRole } from './matches-context-role.js';
 import { mayBeFocusable } from '../html/may-be-focusable.js';
+/**
+ * Computes the final ARIA role for an element according to the WAI-ARIA specification,
+ * applying the Presentational Roles Conflict Resolution algorithm. This considers
+ * the explicit role, implicit role, required context roles, focusability,
+ * global ARIA properties, and SVG accessibility tree inclusion rules.
+ *
+ * @param specs - The full markup language specification
+ * @param el - The DOM element to compute the role for
+ * @param version - The ARIA specification version to use
+ * @param assumeSingleNode - When true, skips parent context validation and assumes the element is a standalone fragment
+ * @returns The computed role result including the resolved role spec (or null) and any error type
+ */
 export function getComputedRole(specs, 
 // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
 el, version, assumeSingleNode = false) {

package/lib/algorithm/aria/get-implicit-role.d.ts

@@ -1,4 +1,22 @@
 import type { ImplicitRole } from '../../types/aria.js';
 import type { ARIAVersion, ComputedRole, MLMLSpec } from '../../types/index.js';
+/**
+ * Determines the implicit (native) ARIA role for an element based on its tag name,
+ * namespace, and any matching conditions defined in the HTML-ARIA spec.
+ *
+ * @param specs - The full markup language specification
+ * @param el - The DOM element to determine the implicit role for
+ * @param version - The ARIA specification version to use
+ * @returns The computed role result containing the implicit role spec, or null if no corresponding role exists
+ */
 export declare function getImplicitRole(specs: MLMLSpec, el: Element, version: ARIAVersion): ComputedRole;
+/**
+ * Retrieves the implicit role name string for an element without resolving
+ * the full role specification. Returns `false` when no corresponding role exists.
+ *
+ * @param el - The DOM element to look up the implicit role name for
+ * @param version - The ARIA specification version to use
+ * @param specs - The full markup language specification
+ * @returns The implicit role name string, or `false` if the element has no corresponding role
+ */
 export declare function getImplicitRoleName(el: Element, version: ARIAVersion, specs: MLMLSpec): ImplicitRole;

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

@@ -1,6 +1,15 @@
 import { getImplicitRole as _getImplicitRole } from './get-implicit-role-spec.js';
 import { getRoleSpec } from './get-role-spec.js';
 import { resolveNamespace } from '../../utils/resolve-namespace.js';
+/**
+ * Determines the implicit (native) ARIA role for an element based on its tag name,
+ * namespace, and any matching conditions defined in the HTML-ARIA spec.
+ *
+ * @param specs - The full markup language specification
+ * @param el - The DOM element to determine the implicit role for
+ * @param version - The ARIA specification version to use
+ * @returns The computed role result containing the implicit role spec, or null if no corresponding role exists
+ */
 export function getImplicitRole(specs, 
 // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
 el, version) {
@@ -29,6 +38,15 @@ el, version) {
         },
     };
 }
+/**
+ * Retrieves the implicit role name string for an element without resolving
+ * the full role specification. Returns `false` when no corresponding role exists.
+ *
+ * @param el - The DOM element to look up the implicit role name for
+ * @param version - The ARIA specification version to use
+ * @param specs - The full markup language specification
+ * @returns The implicit role name string, or `false` if the element has no corresponding role
+ */
 export function getImplicitRoleName(
 // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
 el, version, specs) {

package/lib/algorithm/aria/get-permitted-roles.d.ts

@@ -1,4 +1,13 @@
 import type { ARIAVersion, MLMLSpec } from '../../types/index.js';
+/**
+ * Retrieves the list of permitted ARIA roles that may be explicitly assigned
+ * to an element, based on its tag name, namespace, and current attribute state.
+ *
+ * @param el - The DOM element to determine permitted roles for
+ * @param version - The ARIA specification version to use
+ * @param specs - The full markup language specification
+ * @returns The permitted roles specification, which may be a boolean, an array of role names, or an AAM reference
+ */
 export declare function getPermittedRoles(el: Element, version: ARIAVersion, specs: MLMLSpec): readonly {
     readonly name: string;
     readonly deprecated?: boolean;

package/lib/algorithm/aria/get-permitted-roles.js

@@ -1,4 +1,13 @@
 import { getPermittedRoles as _getPermittedRoles } from './get-permitted-roles-spec.js';
+/**
+ * Retrieves the list of permitted ARIA roles that may be explicitly assigned
+ * to an element, based on its tag name, namespace, and current attribute state.
+ *
+ * @param el - The DOM element to determine permitted roles for
+ * @param version - The ARIA specification version to use
+ * @param specs - The full markup language specification
+ * @returns The permitted roles specification, which may be a boolean, an array of role names, or an AAM reference
+ */
 export function getPermittedRoles(
 // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
 el, version, specs) {

package/lib/algorithm/aria/get-role-spec.d.ts

@@ -1,5 +1,16 @@
 import type { ARIAVersion, ARIARoleInSchema, MLMLSpec, ARIARole } from '../../types/index.js';
 import type { NamespaceURI } from '@markuplint/ml-ast';
+/**
+ * Retrieves the full ARIA role specification for a given role name, including
+ * its properties, requirements, and the complete chain of super-class roles.
+ * For SVG namespace elements, also searches graphics ARIA roles.
+ *
+ * @param specs - The full markup language specification
+ * @param roleName - The name of the ARIA role to look up
+ * @param namespace - The namespace URI of the element context
+ * @param version - The ARIA specification version to use
+ * @returns The role specification with super-class roles, or null if the role does not exist
+ */
 export declare function getRoleSpec(specs: MLMLSpec, roleName: string, namespace: NamespaceURI, version: ARIAVersion): (ARIARole & {
     superClassRoles: ARIARoleInSchema[];
 }) | null;

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

@@ -1,4 +1,15 @@
 import { ariaSpecs } from './aria-specs.js';
+/**
+ * Retrieves the full ARIA role specification for a given role name, including
+ * its properties, requirements, and the complete chain of super-class roles.
+ * For SVG namespace elements, also searches graphics ARIA roles.
+ *
+ * @param specs - The full markup language specification
+ * @param roleName - The name of the ARIA role to look up
+ * @param namespace - The namespace URI of the element context
+ * @param version - The ARIA specification version to use
+ * @returns The role specification with super-class roles, or null if the role does not exist
+ */
 export function getRoleSpec(specs, roleName, namespace, version) {
     const role = getRoleByName(specs, roleName, namespace, version);
     if (!role) {

package/lib/algorithm/aria/has-required-owned-elements.d.ts

@@ -1,3 +1,26 @@
 import type { ARIAVersion, ComputedRole, MLMLSpec } from '../../types/index.js';
+/**
+ * Checks whether an element satisfies the "Required Owned Elements" constraint
+ * defined by its computed ARIA role. An element satisfies this constraint if it
+ * has `aria-owns`, or if any of its closest non-presentational descendants match
+ * the required owned element roles.
+ *
+ * @param el - The DOM element to check
+ * @param specs - The full markup language specification
+ * @param version - The ARIA specification version to use
+ * @returns `true` if the element has no required owned elements or the constraint is satisfied, `false` otherwise
+ */
 export declare function hasRequiredOwnedElement(el: Element, specs: MLMLSpec, version: ARIAVersion): boolean;
+/**
+ * Determines whether an element with a given role matches a required owned element query.
+ * The query string may describe a single role or a parent-child relationship using `>` notation
+ * (e.g., `"listitem"` or `"group > listitem"`).
+ *
+ * @param el - The DOM element to test
+ * @param role - The computed role of the element
+ * @param query - The required owned element query string, optionally containing `>` for nested requirements
+ * @param specs - The full markup language specification
+ * @param version - The ARIA specification version to use
+ * @returns `true` if the element and its role match the required owned element query
+ */
 export declare function isRequiredOwnedElement(el: Element, role: ComputedRole['role'], query: string, specs: MLMLSpec, version: ARIAVersion): boolean;

package/lib/algorithm/aria/has-required-owned-elements.js

@@ -2,6 +2,17 @@ import { isPresentational } from './is-presentational.js';
 import { getComputedRole } from './get-computed-role.js';
 import { getExplicitRole } from './get-explicit-role.js';
 import { getImplicitRole } from './get-implicit-role.js';
+/**
+ * Checks whether an element satisfies the "Required Owned Elements" constraint
+ * defined by its computed ARIA role. An element satisfies this constraint if it
+ * has `aria-owns`, or if any of its closest non-presentational descendants match
+ * the required owned element roles.
+ *
+ * @param el - The DOM element to check
+ * @param specs - The full markup language specification
+ * @param version - The ARIA specification version to use
+ * @returns `true` if the element has no required owned elements or the constraint is satisfied, `false` otherwise
+ */
 export function hasRequiredOwnedElement(
 // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
 el, specs, version) {
@@ -30,6 +41,18 @@ el, specs, version) {
     }
     return false;
 }
+/**
+ * Determines whether an element with a given role matches a required owned element query.
+ * The query string may describe a single role or a parent-child relationship using `>` notation
+ * (e.g., `"listitem"` or `"group > listitem"`).
+ *
+ * @param el - The DOM element to test
+ * @param role - The computed role of the element
+ * @param query - The required owned element query string, optionally containing `>` for nested requirements
+ * @param specs - The full markup language specification
+ * @param version - The ARIA specification version to use
+ * @returns `true` if the element and its role match the required owned element query
+ */
 export function isRequiredOwnedElement(
 // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
 el, role, query, specs, version) {

package/lib/algorithm/aria/is-exposed.d.ts

@@ -1,11 +1,14 @@
 import type { ARIAVersion, MLMLSpec } from '../../types/index.js';
 /**
- * Detect including/excluding from the Accessibility Tree
+ * Detects whether an element is included in (exposed to) the Accessibility Tree.
+ * Applies WAI-ARIA exclusion/inclusion rules, SVG rendering rules, and
+ * HTML metadata element filtering.
  *
  * @see https://www.w3.org/TR/wai-aria-1.2/#accessibility_tree
  *
- * @param specs
- * @param el
- * @param version
+ * @param el - The DOM element to check for accessibility tree exposure
+ * @param specs - The full markup language specification
+ * @param version - The ARIA specification version to use
+ * @returns `true` if the element should be exposed in the accessibility tree
  */
 export declare function isExposed(el: Element, specs: MLMLSpec, version: ARIAVersion): boolean;

package/lib/algorithm/aria/is-exposed.js

@@ -4,13 +4,16 @@ import { isPresentational } from './is-presentational.js';
 import { resolveNamespace } from '../../utils/resolve-namespace.js';
 import { getComputedRole } from './get-computed-role.js';
 /**
- * Detect including/excluding from the Accessibility Tree
+ * Detects whether an element is included in (exposed to) the Accessibility Tree.
+ * Applies WAI-ARIA exclusion/inclusion rules, SVG rendering rules, and
+ * HTML metadata element filtering.
  *
  * @see https://www.w3.org/TR/wai-aria-1.2/#accessibility_tree
  *
- * @param specs
- * @param el
- * @param version
+ * @param el - The DOM element to check for accessibility tree exposure
+ * @param specs - The full markup language specification
+ * @param version - The ARIA specification version to use
+ * @returns `true` if the element should be exposed in the accessibility tree
  */
 export function isExposed(
 // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types

package/lib/algorithm/aria/is-presentational.d.ts

@@ -1 +1,9 @@
+/**
+ * Determines whether a given role name corresponds to a presentational role
+ * (`"presentation"` or `"none"`), which indicates the element should be
+ * excluded from the accessibility tree.
+ *
+ * @param roleName - The ARIA role name to check, or undefined
+ * @returns `true` if the role name is `"presentation"` or `"none"`, `false` otherwise
+ */
 export declare function isPresentational(roleName?: string): boolean;

package/lib/algorithm/aria/is-presentational.js

@@ -1,3 +1,11 @@
+/**
+ * Determines whether a given role name corresponds to a presentational role
+ * (`"presentation"` or `"none"`), which indicates the element should be
+ * excluded from the accessibility tree.
+ *
+ * @param roleName - The ARIA role name to check, or undefined
+ * @returns `true` if the role name is `"presentation"` or `"none"`, `false` otherwise
+ */
 export function isPresentational(roleName) {
     if (!roleName) {
         return false;

package/lib/algorithm/aria/matches-context-role.d.ts

@@ -1,2 +1,13 @@
 import type { ARIAVersion, MLMLSpec } from '../../types/index.js';
+/**
+ * Checks whether an element's parent hierarchy satisfies at least one of the
+ * required context role conditions. Each condition string may describe a chain
+ * of ancestor roles separated by ` > ` (e.g., `"list > group"`).
+ *
+ * @param conditions - An array of required context role condition strings to match against
+ * @param ownedEl - The owned DOM element whose parent context is being validated
+ * @param specs - The full markup language specification
+ * @param version - The ARIA specification version to use
+ * @returns `true` if any of the context role conditions are satisfied by the element's ancestors
+ */
 export declare function matchesContextRole(conditions: readonly string[], ownedEl: Element, specs: MLMLSpec, version: ARIAVersion): boolean;

package/lib/algorithm/aria/matches-context-role.js

@@ -1,4 +1,15 @@
 import { getComputedRole } from './get-computed-role.js';
+/**
+ * Checks whether an element's parent hierarchy satisfies at least one of the
+ * required context role conditions. Each condition string may describe a chain
+ * of ancestor roles separated by ` > ` (e.g., `"list > group"`).
+ *
+ * @param conditions - An array of required context role condition strings to match against
+ * @param ownedEl - The owned DOM element whose parent context is being validated
+ * @param specs - The full markup language specification
+ * @param version - The ARIA specification version to use
+ * @returns `true` if any of the context role conditions are satisfied by the element's ancestors
+ */
 export function matchesContextRole(conditions, 
 // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
 ownedEl, specs, version) {

package/lib/algorithm/html/content-model-category-to-tag-names.d.ts

@@ -1,3 +1,12 @@
 import type { MLMLSpec } from '../../types/index.js';
 import type { Category } from '../../types/permitted-structures.js';
+/**
+ * Converts a content model category (e.g., `#flow`, `#phrasing`) to a sorted,
+ * frozen array of HTML/SVG tag names that belong to that category.
+ * Results are cached for repeated lookups.
+ *
+ * @param contentModel - The content model category identifier
+ * @param def - The specification definitions containing content model mappings
+ * @returns A frozen, sorted array of tag name strings belonging to the category
+ */
 export declare function contentModelCategoryToTagNames(contentModel: Category, def: MLMLSpec['def']): ReadonlyArray<string>;

package/lib/algorithm/html/content-model-category-to-tag-names.js

@@ -1,4 +1,13 @@
 const cache = new Map();
+/**
+ * Converts a content model category (e.g., `#flow`, `#phrasing`) to a sorted,
+ * frozen array of HTML/SVG tag names that belong to that category.
+ * Results are cached for repeated lookups.
+ *
+ * @param contentModel - The content model category identifier
+ * @param def - The specification definitions containing content model mappings
+ * @returns A frozen, sorted array of tag name strings belonging to the category
+ */
 export function contentModelCategoryToTagNames(contentModel, def) {
     const cached = cache.get(contentModel);
     if (cached) {

package/lib/algorithm/html/get-content-model.d.ts

@@ -1,4 +1,13 @@
 import type { ElementSpec } from '../../types/index.js';
 type Specs = readonly Pick<ElementSpec, 'name' | 'contentModel'>[];
+/**
+ * Retrieves the permitted content model for an element. Evaluates any conditional
+ * content models based on the element's current attributes (e.g., different content
+ * models for `<ol>` vs `<ol reversed>`). Results are cached per element and spec set.
+ *
+ * @param el - The DOM element to retrieve the content model for
+ * @param specs - The element specifications containing content model definitions
+ * @returns The permitted content patterns array, a boolean (true for any content, false for no content), or null if no spec exists
+ */
 export declare function getContentModel(el: Element, specs: Specs): boolean | readonly (import("type-fest/source/readonly-deep.js").ReadonlyObjectDeep<import("../../types/permitted-structures.js").PermittedContentRequire> | import("type-fest/source/readonly-deep.js").ReadonlyObjectDeep<import("../../types/permitted-structures.js").PermittedContentOptional> | import("type-fest/source/readonly-deep.js").ReadonlyObjectDeep<import("../../types/permitted-structures.js").PermittedContentOneOrMore> | import("type-fest/source/readonly-deep.js").ReadonlyObjectDeep<import("../../types/permitted-structures.js").PermittedContentZeroOrMore> | import("type-fest/source/readonly-deep.js").ReadonlyObjectDeep<import("../../types/permitted-structures.js").PermittedContentChoice> | import("type-fest/source/readonly-deep.js").ReadonlyObjectDeep<import("../../types/permitted-structures.js").PermittedContentTransparent>)[] | null;
 export {};

package/lib/algorithm/html/get-content-model.js

@@ -1,5 +1,14 @@
 import { getSpec } from '../../utils/get-spec.js';
 const cachesBySpecs = new Map();
+/**
+ * Retrieves the permitted content model for an element. Evaluates any conditional
+ * content models based on the element's current attributes (e.g., different content
+ * models for `<ol>` vs `<ol reversed>`). Results are cached per element and spec set.
+ *
+ * @param el - The DOM element to retrieve the content model for
+ * @param specs - The element specifications containing content model definitions
+ * @returns The permitted content patterns array, a boolean (true for any content, false for no content), or null if no spec exists
+ */
 export function getContentModel(
 // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
 el, specs) {

package/lib/algorithm/html/get-selectors-by-content-model-category.d.ts

@@ -1,3 +1,11 @@
 import type { MLMLSpec } from '../../types/index.js';
 import type { Category } from '../../types/permitted-structures.js';
+/**
+ * Retrieves the CSS selectors associated with a content model category from the spec definitions.
+ * These selectors can be used to match elements that belong to the given category.
+ *
+ * @param specs - The full markup language specification
+ * @param category - The content model category identifier (e.g., `#flow`, `#interactive`)
+ * @returns A readonly array of CSS selector strings for the category, or an empty array if the category is not defined
+ */
 export declare function getSelectorsByContentModelCategory(specs: MLMLSpec, category: Category): ReadonlyArray<string>;

package/lib/algorithm/html/get-selectors-by-content-model-category.js

@@ -1,3 +1,11 @@
+/**
+ * Retrieves the CSS selectors associated with a content model category from the spec definitions.
+ * These selectors can be used to match elements that belong to the given category.
+ *
+ * @param specs - The full markup language specification
+ * @param category - The content model category identifier (e.g., `#flow`, `#interactive`)
+ * @returns A readonly array of CSS selector strings for the category, or an empty array if the category is not defined
+ */
 export function getSelectorsByContentModelCategory(specs, category) {
     const selectors = specs.def['#contentModels'][category];
     return selectors ?? [];

package/lib/algorithm/html/is-nothing-content-model.d.ts

@@ -1,5 +1,12 @@
 /**
+ * Determines whether an element uses the "nothing" content model, meaning it
+ * must not contain any content. This includes void elements as well as
+ * `<iframe>` and `<template>` elements.
+ *
  * @see https://html.spec.whatwg.org/multipage/dom.html#the-nothing-content-model
  * @see https://html.spec.whatwg.org/multipage/indices.html#elements-3
+ *
+ * @param el - The DOM element to check
+ * @returns `true` if the element has the "nothing" content model
  */
 export declare function isNothingContentModel(el: Element): boolean;

package/lib/algorithm/html/is-nothing-content-model.js

@@ -1,7 +1,14 @@
 import { isVoidElement } from './is-void-element.js';
 /**
+ * Determines whether an element uses the "nothing" content model, meaning it
+ * must not contain any content. This includes void elements as well as
+ * `<iframe>` and `<template>` elements.
+ *
  * @see https://html.spec.whatwg.org/multipage/dom.html#the-nothing-content-model
  * @see https://html.spec.whatwg.org/multipage/indices.html#elements-3
+ *
+ * @param el - The DOM element to check
+ * @returns `true` if the element has the "nothing" content model
  */
 export function isNothingContentModel(
 // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types

package/lib/algorithm/html/is-palpable-elements.d.ts

@@ -1,4 +1,17 @@
 import type { MLMLSpec } from '../../types/index.js';
+/**
+ * Determines whether an element is considered palpable content. Palpable elements
+ * are those that render something visible or meaningful to the user. Optionally
+ * extends the check to include SVG renderable elements and other exposable elements
+ * that do not belong to any standard content model category.
+ *
+ * @param el - The DOM element to check
+ * @param specs - The full markup language specification
+ * @param options - Optional flags to extend the palpable check
+ * @param options.extendsSvg - Whether to include SVG renderable elements (defaults to true)
+ * @param options.extendsExposableElements - Whether to include additional exposable elements like `<li>`, `<td>`, etc. (defaults to false)
+ * @returns `true` if the element is considered palpable content
+ */
 export declare function isPalpableElement(el: Element, specs: MLMLSpec, options?: {
     readonly extendsSvg?: boolean;
     readonly extendsExposableElements?: boolean;

package/lib/algorithm/html/is-palpable-elements.js

@@ -28,6 +28,19 @@ const exposableElementsThatAreNoBelongingAModel = [
     'thead',
     'tr',
 ];
+/**
+ * Determines whether an element is considered palpable content. Palpable elements
+ * are those that render something visible or meaningful to the user. Optionally
+ * extends the check to include SVG renderable elements and other exposable elements
+ * that do not belong to any standard content model category.
+ *
+ * @param el - The DOM element to check
+ * @param specs - The full markup language specification
+ * @param options - Optional flags to extend the palpable check
+ * @param options.extendsSvg - Whether to include SVG renderable elements (defaults to true)
+ * @param options.extendsExposableElements - Whether to include additional exposable elements like `<li>`, `<td>`, etc. (defaults to false)
+ * @returns `true` if the element is considered palpable content
+ */
 export function isPalpableElement(
 // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
 el, specs, options) {

package/lib/algorithm/html/is-void-element.d.ts

@@ -1,3 +1,12 @@
+/**
+ * Determines whether an element is a void element as defined by the HTML specification.
+ * Void elements cannot have any contents (e.g., `<br>`, `<img>`, `<input>`).
+ *
+ * @see https://html.spec.whatwg.org/multipage/syntax.html#void-elements
+ *
+ * @param el - An object with a `localName` property representing the element's tag name
+ * @returns `true` if the element is a void element
+ */
 export declare function isVoidElement(el: {
     readonly localName: string;
 }): boolean;

package/lib/algorithm/html/is-void-element.js

@@ -16,6 +16,15 @@ const voidElements = new Set([
     'track',
     'wbr',
 ]);
+/**
+ * Determines whether an element is a void element as defined by the HTML specification.
+ * Void elements cannot have any contents (e.g., `<br>`, `<img>`, `<input>`).
+ *
+ * @see https://html.spec.whatwg.org/multipage/syntax.html#void-elements
+ *
+ * @param el - An object with a `localName` property representing the element's tag name
+ * @returns `true` if the element is a void element
+ */
 export function isVoidElement(el) {
     return voidElements.has(el.localName);
 }

package/lib/algorithm/html/may-be-focusable.d.ts

@@ -1,2 +1,12 @@
 import type { MLMLSpec } from '../../types/index.js';
+/**
+ * Determines whether an element may potentially be focusable, based on whether it matches
+ * interactive content selectors, has a `tabindex` attribute, or has a `contenteditable`
+ * attribute. This is a heuristic check that does not account for runtime state such as
+ * `disabled` or `inert` attributes.
+ *
+ * @param el - The DOM element to check
+ * @param specs - The full markup language specification containing interactive content definitions
+ * @returns `true` if the element may be focusable
+ */
 export declare function mayBeFocusable(el: Element, specs: MLMLSpec): boolean;

package/lib/algorithm/html/may-be-focusable.js

@@ -1,4 +1,14 @@
 import { getSelectorsByContentModelCategory } from './get-selectors-by-content-model-category.js';
+/**
+ * Determines whether an element may potentially be focusable, based on whether it matches
+ * interactive content selectors, has a `tabindex` attribute, or has a `contenteditable`
+ * attribute. This is a heuristic check that does not account for runtime state such as
+ * `disabled` or `inert` attributes.
+ *
+ * @param el - The DOM element to check
+ * @param specs - The full markup language specification containing interactive content definitions
+ * @returns `true` if the element may be focusable
+ */
 export function mayBeFocusable(
 // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
 el, specs) {