@markuplint/rules 4.11.2 → 4.18.0

package/lib/table-row-column-alignment/types.d.ts

@@ -1,2 +1,12 @@
+/** A grid cell coordinate key in "row:column" format. */
 export type Key = `${number}:${number}`;
+/**
+ * Represents the type of a cell in the table grid model.
+ *
+ * - `'●'` - A regular cell (single-span).
+ * - `'◎'` - The origin cell of a colspan or rowspan.
+ * - `'↓'` - A cell occupied by a rowspan from a row above.
+ * - `'→'` - A cell occupied by a colspan from a column to the left.
+ * - `'x'` - An overlapping cell caused by conflicting spans.
+ */
 export type CellType = '●' | '◎' | '↓' | '→' | 'x';

package/lib/use-list/index.d.ts

@@ -1,10 +1,26 @@
+/** An array of characters recognized as bullet-like symbols indicating list items. */
 type Bullets = readonly string[];
+/**
+ * Configuration options for the use-list rule.
+ */
 type Options = {
+    /** Bullet characters that require a space after them to be considered list items. */
     spaceNeededBullets?: string[];
+    /** Whether to report text nodes with no preceding sibling. */
     noPrev?: boolean;
+    /** Whether to report text nodes preceded by an element node. */
     prevElement?: boolean;
+    /** Whether to report text nodes preceded by a comment node. */
     prevComment?: boolean;
+    /** Whether to report text nodes preceded by a preprocessor block. */
     prevCodeBlock?: boolean;
 };
+/**
+ * Rule that suggests using `<li>` elements instead of text with bullet characters.
+ *
+ * Detects text nodes that start with bullet-like characters (Unicode bullets,
+ * markdown-style dashes/asterisks, etc.) and recommends converting them into
+ * proper list markup using `<li>` elements.
+ */
 declare const _default: Readonly<import("@markuplint/ml-core").RuleSeed<Bullets, Options>>;
 export default _default;

package/lib/use-list/index.js

@@ -1,6 +1,13 @@
 import { createRule } from '@markuplint/ml-core';
 import { decodeEntities } from '@markuplint/shared';
 import meta from './meta.js';
+/**
+ * Rule that suggests using `<li>` elements instead of text with bullet characters.
+ *
+ * Detects text nodes that start with bullet-like characters (Unicode bullets,
+ * markdown-style dashes/asterisks, etc.) and recommends converting them into
+ * proper list markup using `<li>` elements.
+ */
 export default createRule({
     meta: meta,
     defaultValue: [
@@ -94,6 +101,19 @@ export default createRule({
         });
     },
 });
+/**
+ * Determines whether a text string appears to be a list item based on its first character.
+ *
+ * Checks if the text starts with a recognized bullet character. For bullets
+ * that require a trailing space (e.g., `-`, `*`, `+`), also verifies that the
+ * second character is whitespace. Consecutive identical characters are not
+ * treated as bullets (e.g., `--` is not a list item).
+ *
+ * @param text - The text content to evaluate.
+ * @param bullets - Characters recognized as bullet symbols.
+ * @param spaceNeededBullets - Bullet characters that require a following space.
+ * @returns `true` if the text appears to be a list item.
+ */
 function isMayListItem(text, bullets, spaceNeededBullets) {
     const textArray = [...text];
     const firstLetter = textArray[0] ?? '';

package/lib/use-list/meta.d.ts

@@ -1,3 +1,4 @@
+/** Rule metadata for the `use-list` rule, categorized as accessibility. */
 declare const _default: {
     readonly category: "a11y";
 };

package/lib/use-list/meta.js

@@ -1,3 +1,4 @@
+/** Rule metadata for the `use-list` rule, categorized as accessibility. */
 export default {
     category: 'a11y',
 };

package/lib/wai-aria/checkings/abstract-role.d.ts

@@ -1,3 +1,12 @@
 import type { Options } from '../types.js';
 import type { AttrChecker } from '@markuplint/ml-core';
+/**
+ * Checks whether the `role` attribute value refers to an abstract WAI-ARIA role.
+ *
+ * Abstract roles (e.g., `widget`, `landmark`) are used for ontological purposes
+ * in the ARIA taxonomy and must not be used directly in content.
+ *
+ * @param attr - The `role` attribute node to inspect.
+ * @returns A violation if any token in the role attribute is an abstract role.
+ */
 export declare const checkingAbstractRole: AttrChecker<boolean, Options>;

package/lib/wai-aria/checkings/abstract-role.js

@@ -1,4 +1,13 @@
 import { ariaSpecs } from '@markuplint/ml-spec';
+/**
+ * Checks whether the `role` attribute value refers to an abstract WAI-ARIA role.
+ *
+ * Abstract roles (e.g., `widget`, `landmark`) are used for ontological purposes
+ * in the ARIA taxonomy and must not be used directly in content.
+ *
+ * @param attr - The `role` attribute node to inspect.
+ * @returns A violation if any token in the role attribute is an abstract role.
+ */
 export const checkingAbstractRole = ({ attr }) => t => {
     const { roles } = ariaSpecs(attr.ownerMLDocument.specs, attr.rule.options.version);
     const tokens = attr.tokenList?.allTokens();

package/lib/wai-aria/checkings/default-value.d.ts

@@ -1,6 +1,17 @@
 import type { Options } from '../types.js';
 import type { AttrChecker } from '@markuplint/ml-core';
 import type { ARIAProperty } from '@markuplint/ml-spec';
+/**
+ * Checks whether an ARIA property is explicitly set to its spec-defined default value.
+ *
+ * Setting an ARIA property to its default value is redundant and may indicate
+ * a misunderstanding of the property's behavior. This checker reports such cases
+ * when the `disallowDefaultValue` option is enabled.
+ *
+ * @param attr - The ARIA attribute node to inspect.
+ * @param propSpecs - The list of ARIA property specifications for value lookup.
+ * @returns A violation if the attribute value matches the property's default value.
+ */
 export declare const checkingDefaultValue: AttrChecker<boolean, Options, {
     propSpecs: readonly ARIAProperty[];
 }>;

package/lib/wai-aria/checkings/default-value.js

@@ -1,3 +1,14 @@
+/**
+ * Checks whether an ARIA property is explicitly set to its spec-defined default value.
+ *
+ * Setting an ARIA property to its default value is redundant and may indicate
+ * a misunderstanding of the property's behavior. This checker reports such cases
+ * when the `disallowDefaultValue` option is enabled.
+ *
+ * @param attr - The ARIA attribute node to inspect.
+ * @param propSpecs - The list of ARIA property specifications for value lookup.
+ * @returns A violation if the attribute value matches the property's default value.
+ */
 export const checkingDefaultValue = ({ attr, propSpecs }) => t => {
     if (attr.isDynamicValue) {
         return;

package/lib/wai-aria/checkings/deprecated-props.d.ts

@@ -1,6 +1,17 @@
 import type { Options } from '../types.js';
 import type { AttrChecker } from '@markuplint/ml-core';
 import type { ARIAProperty, ARIARole } from '@markuplint/ml-spec';
+/**
+ * Checks whether an ARIA property or state is deprecated for the element's computed role.
+ *
+ * Some ARIA properties become deprecated on specific roles across ARIA versions.
+ * This checker reports usage of such deprecated properties.
+ *
+ * @param attr - The ARIA attribute node to inspect.
+ * @param role - The computed ARIA role of the element.
+ * @param propSpecs - The list of ARIA property specifications for type lookup.
+ * @returns A violation if the property is deprecated on the given role.
+ */
 export declare const checkingDeprecatedProps: AttrChecker<boolean, Options, {
     role: ARIARole | null;
     propSpecs: readonly ARIAProperty[];

package/lib/wai-aria/checkings/deprecated-props.js

@@ -1,3 +1,14 @@
+/**
+ * Checks whether an ARIA property or state is deprecated for the element's computed role.
+ *
+ * Some ARIA properties become deprecated on specific roles across ARIA versions.
+ * This checker reports usage of such deprecated properties.
+ *
+ * @param attr - The ARIA attribute node to inspect.
+ * @param role - The computed ARIA role of the element.
+ * @param propSpecs - The list of ARIA property specifications for type lookup.
+ * @returns A violation if the property is deprecated on the given role.
+ */
 export const checkingDeprecatedProps = ({ attr, role, propSpecs }) => t => {
     if (!role) {
         return;

package/lib/wai-aria/checkings/deprecated-role.d.ts

@@ -1,6 +1,16 @@
 import type { Options } from '../types.js';
 import type { AttrChecker } from '@markuplint/ml-core';
 import type { ARIARole } from '@markuplint/ml-spec';
+/**
+ * Checks whether the element's computed ARIA role is deprecated in the specified ARIA version.
+ *
+ * Deprecated roles should be avoided as they may be removed in future ARIA versions
+ * and assistive technologies may not support them reliably.
+ *
+ * @param attr - The `role` attribute node to inspect.
+ * @param role - The computed ARIA role of the element.
+ * @returns A violation if the role is marked as deprecated.
+ */
 export declare const checkingDeprecatedRole: AttrChecker<boolean, Options, {
     role: ARIARole | null;
 }>;

package/lib/wai-aria/checkings/deprecated-role.js

@@ -1,3 +1,13 @@
+/**
+ * Checks whether the element's computed ARIA role is deprecated in the specified ARIA version.
+ *
+ * Deprecated roles should be avoided as they may be removed in future ARIA versions
+ * and assistive technologies may not support them reliably.
+ *
+ * @param attr - The `role` attribute node to inspect.
+ * @param role - The computed ARIA role of the element.
+ * @returns A violation if the role is marked as deprecated.
+ */
 export const checkingDeprecatedRole = ({ attr, role }) => t => {
     if (!role) {
         return;

package/lib/wai-aria/checkings/disallowed-prop.d.ts

@@ -1,6 +1,20 @@
 import type { Options } from '../types.js';
 import type { AttrChecker } from '@markuplint/ml-core';
 import type { ARIAProperty, ARIARole } from '@markuplint/ml-spec';
+/**
+ * Checks whether an ARIA property or state is disallowed on the element's computed role.
+ *
+ * Each ARIA role defines a set of supported states and properties. This checker reports
+ * usage of ARIA attributes that are not in that set. It also considers element-specific
+ * restrictions from the ARIA in HTML specification (e.g., properties that should not
+ * be used on certain native HTML elements).
+ *
+ * @param attr - The ARIA attribute node to inspect.
+ * @param role - The computed ARIA role of the element.
+ * @param propSpecs - The list of ARIA property specifications for type lookup.
+ * @param disallowSetImplicitProps - Whether to also enforce element-specific restrictions.
+ * @returns A violation if the property is not allowed on the given role or element.
+ */
 export declare const checkingDisallowedProp: AttrChecker<boolean, Options, {
     role: ARIARole | null;
     propSpecs: readonly ARIAProperty[];

package/lib/wai-aria/checkings/disallowed-prop.js

@@ -1,4 +1,18 @@
 import { getARIA } from '@markuplint/ml-spec';
+/**
+ * Checks whether an ARIA property or state is disallowed on the element's computed role.
+ *
+ * Each ARIA role defines a set of supported states and properties. This checker reports
+ * usage of ARIA attributes that are not in that set. It also considers element-specific
+ * restrictions from the ARIA in HTML specification (e.g., properties that should not
+ * be used on certain native HTML elements).
+ *
+ * @param attr - The ARIA attribute node to inspect.
+ * @param role - The computed ARIA role of the element.
+ * @param propSpecs - The list of ARIA property specifications for type lookup.
+ * @param disallowSetImplicitProps - Whether to also enforce element-specific restrictions.
+ * @returns A violation if the property is not allowed on the given role or element.
+ */
 export const checkingDisallowedProp = ({ attr, role, propSpecs, disallowSetImplicitProps }) => t => {
     if (!role) {
         return;

package/lib/wai-aria/checkings/implicit-props.d.ts

@@ -1,6 +1,19 @@
 import type { Options } from '../types.js';
 import type { AttrChecker } from '@markuplint/ml-core';
 import type { ARIAProperty, Attribute } from '@markuplint/ml-spec';
+/**
+ * Checks whether an ARIA property duplicates or contradicts semantics already
+ * provided by an equivalent native HTML attribute.
+ *
+ * Many ARIA properties have equivalent HTML attributes (e.g., `aria-required` and `required`).
+ * This checker reports when an ARIA property is redundant because the native attribute
+ * already conveys the same semantics, or when the ARIA value contradicts the native attribute.
+ *
+ * @param attr - The ARIA attribute node to inspect.
+ * @param propSpecs - The list of ARIA property specifications for equivalence lookup.
+ * @param attrSpecs - The HTML attribute specifications for the element.
+ * @returns A violation if the ARIA property duplicates or contradicts an equivalent HTML attribute.
+ */
 export declare const checkingImplicitProps: AttrChecker<boolean, Options, {
     propSpecs: readonly ARIAProperty[];
     attrSpecs: readonly Attribute[] | null;

package/lib/wai-aria/checkings/implicit-props.js

@@ -1,4 +1,17 @@
 import { isValidAttr } from '../../helpers.js';
+/**
+ * Checks whether an ARIA property duplicates or contradicts semantics already
+ * provided by an equivalent native HTML attribute.
+ *
+ * Many ARIA properties have equivalent HTML attributes (e.g., `aria-required` and `required`).
+ * This checker reports when an ARIA property is redundant because the native attribute
+ * already conveys the same semantics, or when the ARIA value contradicts the native attribute.
+ *
+ * @param attr - The ARIA attribute node to inspect.
+ * @param propSpecs - The list of ARIA property specifications for equivalence lookup.
+ * @param attrSpecs - The HTML attribute specifications for the element.
+ * @returns A violation if the ARIA property duplicates or contradicts an equivalent HTML attribute.
+ */
 export const checkingImplicitProps = ({ attr, propSpecs, attrSpecs }) => t => {
     if (!attrSpecs) {
         return;

package/lib/wai-aria/checkings/implicit-role.d.ts

@@ -1,3 +1,12 @@
 import type { Options } from '../types.js';
 import type { AttrChecker } from '@markuplint/ml-core';
+/**
+ * Checks whether the explicit `role` attribute duplicates the element's implicit (native) role.
+ *
+ * HTML elements have implicit ARIA roles (e.g., `<nav>` has an implicit role of `navigation`).
+ * Explicitly setting the same role is redundant and should be avoided.
+ *
+ * @param attr - The `role` attribute node to inspect.
+ * @returns A violation if any token in the role attribute matches the element's implicit role.
+ */
 export declare const checkingImplicitRole: AttrChecker<boolean, Options>;

package/lib/wai-aria/checkings/implicit-role.js

@@ -1,4 +1,13 @@
 import { getImplicitRoleName } from '@markuplint/ml-spec';
+/**
+ * Checks whether the explicit `role` attribute duplicates the element's implicit (native) role.
+ *
+ * HTML elements have implicit ARIA roles (e.g., `<nav>` has an implicit role of `navigation`).
+ * Explicitly setting the same role is redundant and should be avoided.
+ *
+ * @param attr - The `role` attribute node to inspect.
+ * @returns A violation if any token in the role attribute matches the element's implicit role.
+ */
 export const checkingImplicitRole = ({ attr }) => t => {
     const tokens = attr.tokenList?.allTokens();
     if (!tokens) {

package/lib/wai-aria/checkings/interaction-in-hidden.d.ts

@@ -1,11 +1,20 @@
 import type { Options } from '../types.js';
 import type { ElementChecker } from '@markuplint/ml-core';
 /**
+ * Checks whether a focusable interactive element is inside an `aria-hidden=true` subtree.
+ *
  * Including Elements in the Accessibility Tree
  *
  * @see https://w3c.github.io/aria/#tree_inclusion
  * > Elements that are not hidden and may fire an accessibility API event, including:
  * > - Elements that are currently focused, even if the element or one of its ancestor elements has its aria-hidden attribute set to true.
  * > - Elements that are a valid target of an aria-activedescendant attribute.
+ *
+ * When a focused element exists within an `aria-hidden=true` ancestor, it is still
+ * exposed to the accessibility tree. This situation is almost always unintentional --
+ * while not strictly invalid per spec, it requires careful attention from the developer.
+ *
+ * @param el - The element node to inspect for focusability within a hidden context.
+ * @returns A violation if the element is focusable and has `aria-hidden=true` on itself or an ancestor.
  */
 export declare const checkingInteractionInHidden: ElementChecker<boolean, Options>;

package/lib/wai-aria/checkings/interaction-in-hidden.js

@@ -1,16 +1,21 @@
 import { mayBeFocusable } from '@markuplint/ml-spec';
 /**
+ * Checks whether a focusable interactive element is inside an `aria-hidden=true` subtree.
+ *
  * Including Elements in the Accessibility Tree
  *
  * @see https://w3c.github.io/aria/#tree_inclusion
  * > Elements that are not hidden and may fire an accessibility API event, including:
  * > - Elements that are currently focused, even if the element or one of its ancestor elements has its aria-hidden attribute set to true.
  * > - Elements that are a valid target of an aria-activedescendant attribute.
+ *
+ * When a focused element exists within an `aria-hidden=true` ancestor, it is still
+ * exposed to the accessibility tree. This situation is almost always unintentional --
+ * while not strictly invalid per spec, it requires careful attention from the developer.
+ *
+ * @param el - The element node to inspect for focusability within a hidden context.
+ * @returns A violation if the element is focusable and has `aria-hidden=true` on itself or an ancestor.
  */
-// フォーカスがあたっている場合に限り、先祖がaria-hidden=trueでもアクセシビリティツリーに提示される
-// なので、aria-hidden=trueの子孫要素で且つインタラクティブ要素である場合、
-// それは開発者にとってはほとんどの場合、意図しないことが多いはずなので、
-// 仕様上不正にはならないが、十分に注意しなければならない状態である。
 export const checkingInteractionInHidden = ({ el }) => t => {
     if (!mayBeFocusable(el, el.ownerMLDocument.specs)) {
         return;
@@ -30,6 +35,12 @@ export const checkingInteractionInHidden = ({ el }) => t => {
         message: t('It may be focusable in spite of it has the ancestor that has aria-hidden=true'),
     };
 };
+/**
+ * Traverses the element's ancestor chain to find the closest element with `aria-hidden="true"`.
+ *
+ * @param el - The element to start searching from (inclusive).
+ * @returns The `aria-hidden` attribute node if found, or `null` if no ancestor is hidden.
+ */
 function getClosestAriaHidden(
 // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
 el) {

package/lib/wai-aria/checkings/no-global-prop.d.ts

@@ -1,6 +1,16 @@
 import type { Options } from '../types.js';
 import type { AttrChecker } from '@markuplint/ml-core';
 import type { ARIAProperty } from '@markuplint/ml-spec';
+/**
+ * Checks whether a non-global ARIA property is used on an element without an explicit role.
+ *
+ * When no role is computed for an element, only global ARIA properties (e.g., `aria-label`,
+ * `aria-hidden`) are allowed. This checker reports non-global properties used in that context.
+ *
+ * @param attr - The ARIA attribute node to inspect.
+ * @param propSpecs - The list of ARIA property specifications for global status lookup.
+ * @returns A violation if the property is not a global ARIA property.
+ */
 export declare const checkingNoGlobalProp: AttrChecker<boolean, Options, {
     propSpecs: readonly ARIAProperty[];
 }>;

package/lib/wai-aria/checkings/no-global-prop.js

@@ -1,3 +1,13 @@
+/**
+ * Checks whether a non-global ARIA property is used on an element without an explicit role.
+ *
+ * When no role is computed for an element, only global ARIA properties (e.g., `aria-label`,
+ * `aria-hidden`) are allowed. This checker reports non-global properties used in that context.
+ *
+ * @param attr - The ARIA attribute node to inspect.
+ * @param propSpecs - The list of ARIA property specifications for global status lookup.
+ * @returns A violation if the property is not a global ARIA property.
+ */
 export const checkingNoGlobalProp = ({ attr, propSpecs }) => t => {
     const propSpec = propSpecs.find(prop => prop.name === attr.name);
     if (propSpec && !propSpec.isGlobal) {

package/lib/wai-aria/checkings/non-existent-role.d.ts

@@ -1,3 +1,13 @@
 import type { Options } from '../types.js';
 import type { AttrChecker } from '@markuplint/ml-core';
+/**
+ * Checks whether the `role` attribute value refers to a role that does not exist
+ * in the WAI-ARIA specification.
+ *
+ * Validates each token in the role attribute against the known ARIA roles list.
+ * For SVG elements, the WAI-ARIA Graphics Module roles are also accepted.
+ *
+ * @param attr - The `role` attribute node to inspect.
+ * @returns A violation if any token does not correspond to a defined ARIA role.
+ */
 export declare const checkingNonExistentRole: AttrChecker<boolean, Options>;

package/lib/wai-aria/checkings/non-existent-role.js

@@ -1,4 +1,14 @@
 import { ariaSpecs } from '@markuplint/ml-spec';
+/**
+ * Checks whether the `role` attribute value refers to a role that does not exist
+ * in the WAI-ARIA specification.
+ *
+ * Validates each token in the role attribute against the known ARIA roles list.
+ * For SVG elements, the WAI-ARIA Graphics Module roles are also accepted.
+ *
+ * @param attr - The `role` attribute node to inspect.
+ * @returns A violation if any token does not correspond to a defined ARIA role.
+ */
 export const checkingNonExistentRole = ({ attr }) => t => {
     const { roles, graphicsRoles } = ariaSpecs(attr.ownerMLDocument.specs, attr.rule.options.version);
     const tokens = attr.tokenList?.allTokens();

package/lib/wai-aria/checkings/permitted-roles.d.ts

@@ -1,3 +1,13 @@
 import type { Options } from '../types.js';
 import type { AttrChecker } from '@markuplint/ml-core';
+/**
+ * Checks whether the explicit `role` attribute value is permitted on the element
+ * according to the ARIA in HTML specification.
+ *
+ * Each HTML element defines a set of roles that may be assigned to it. Some elements
+ * (e.g., `<meta>`) do not allow any role overrides. This checker enforces those constraints.
+ *
+ * @param attr - The `role` attribute node to inspect.
+ * @returns A violation if the role is not in the element's list of permitted roles.
+ */
 export declare const checkingPermittedRoles: AttrChecker<boolean, Options>;

package/lib/wai-aria/checkings/permitted-roles.js

@@ -1,4 +1,14 @@
 import { getPermittedRoles } from '@markuplint/ml-spec';
+/**
+ * Checks whether the explicit `role` attribute value is permitted on the element
+ * according to the ARIA in HTML specification.
+ *
+ * Each HTML element defines a set of roles that may be assigned to it. Some elements
+ * (e.g., `<meta>`) do not allow any role overrides. This checker enforces those constraints.
+ *
+ * @param attr - The `role` attribute node to inspect.
+ * @returns A violation if the role is not in the element's list of permitted roles.
+ */
 export const checkingPermittedRoles = ({ attr }) => t => {
     const el = attr.ownerElement;
     const permittedRoles = getPermittedRoles(el, el.rule.options.version, attr.ownerMLDocument.specs);

package/lib/wai-aria/checkings/presentational-children.d.ts

@@ -1,6 +1,9 @@
 import type { Options } from '../types.js';
 import type { ElementChecker } from '@markuplint/ml-core';
 /**
+ * Checks whether ARIA attributes are applied to descendants of an element whose
+ * role has the `childrenArePresentational` characteristic.
+ *
  * Presentational Children
  *
  * @see https://www.w3.org/TR/wai-aria/#childrenArePresentational
@@ -22,8 +25,11 @@ import type { ElementChecker } from '@markuplint/ml-core';
  *
  * @see https://w3c.github.io/aria/#tree_inclusion
  *
- *  > Text equivalents for hidden referenced objects
+ * > Text equivalents for hidden referenced objects
  * > may still be used in the name and description computation
  * > even when not included in the accessibility tree.
+ *
+ * @param el - The element node to inspect for presentational ancestor context.
+ * @returns A violation if the element has ARIA attributes and an ancestor with presentational children.
  */
 export declare const checkingPresentationalChildren: ElementChecker<boolean, Options>;

package/lib/wai-aria/checkings/presentational-children.js

@@ -1,5 +1,8 @@
 import { getComputedRole } from '@markuplint/ml-spec';
 /**
+ * Checks whether ARIA attributes are applied to descendants of an element whose
+ * role has the `childrenArePresentational` characteristic.
+ *
  * Presentational Children
  *
  * @see https://www.w3.org/TR/wai-aria/#childrenArePresentational
@@ -21,9 +24,12 @@ import { getComputedRole } from '@markuplint/ml-spec';
  *
  * @see https://w3c.github.io/aria/#tree_inclusion
  *
- *  > Text equivalents for hidden referenced objects
+ * > Text equivalents for hidden referenced objects
  * > may still be used in the name and description computation
  * > even when not included in the accessibility tree.
+ *
+ * @param el - The element node to inspect for presentational ancestor context.
+ * @returns A violation if the element has ARIA attributes and an ancestor with presentational children.
  */
 export const checkingPresentationalChildren = ({ el }) => t => {
     const ancestor = getAncestorHasPresentationalChildren(el);
@@ -42,6 +48,13 @@ export const checkingPresentationalChildren = ({ el }) => t => {
         message: t('it may be ineffective because {0}', t("it has {0} as an ancestor that doesn't expose its descendants to the accessibility tree", t('the "{0*}" {1}', ancestor.role.name, 'role'))),
     };
 };
+/**
+ * Traverses the element's ancestor chain to find one whose computed role
+ * has the `childrenArePresentational` characteristic.
+ *
+ * @param el - The element to start searching from (exclusive, starts from parent).
+ * @returns The computed role of the ancestor with presentational children, or `null` if none found.
+ */
 function getAncestorHasPresentationalChildren(
 // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
 el) {

package/lib/wai-aria/checkings/required-owned-elements.d.ts

@@ -2,9 +2,17 @@ import type { Options } from '../types.js';
 import type { ElementChecker } from '@markuplint/ml-core';
 import type { ARIARole } from '@markuplint/ml-spec';
 /**
- * Required Owned Elements
+ * Checks whether an element with a role that requires specific owned elements
+ * actually contains children with the expected roles.
+ *
+ * For example, a `list` role must own at least one element with the `listitem` role.
+ * This checker respects `aria-busy="true"` (which signals that content is still loading),
+ * preprocessor blocks, and mutable children from template engines.
  *
  * @see https://w3c.github.io/aria/#mustContain
+ * @param el - The element node to inspect for required owned elements.
+ * @param role - The computed ARIA role of the element, which defines required owned elements.
+ * @returns A violation if the role requires owned elements and none are found.
  */
 export declare const checkingRequiredOwnedElements: ElementChecker<boolean, Options, {
     role?: ARIARole | null;

package/lib/wai-aria/checkings/required-owned-elements.js

@@ -1,8 +1,16 @@
 import { getComputedRole, isRequiredOwnedElement } from '@markuplint/ml-spec';
 /**
- * Required Owned Elements
+ * Checks whether an element with a role that requires specific owned elements
+ * actually contains children with the expected roles.
+ *
+ * For example, a `list` role must own at least one element with the `listitem` role.
+ * This checker respects `aria-busy="true"` (which signals that content is still loading),
+ * preprocessor blocks, and mutable children from template engines.
  *
  * @see https://w3c.github.io/aria/#mustContain
+ * @param el - The element node to inspect for required owned elements.
+ * @param role - The computed ARIA role of the element, which defines required owned elements.
+ * @returns A violation if the role requires owned elements and none are found.
  */
 export const checkingRequiredOwnedElements = ({ el, role }) => t => {
     if (!role) {
@@ -87,6 +95,13 @@ export const checkingRequiredOwnedElements = ({ el, role }) => t => {
             : t('the {0}', 'roles') + `: ${t(role.requiredOwnedElements)}`),
     };
 };
+/**
+ * Determines whether the element's children may not yet exist (e.g., empty or
+ * containing only `<script>` / `<template>` elements that could dynamically create content).
+ *
+ * @param el - The element to inspect.
+ * @returns `true` if the element is empty or only contains script/template children.
+ */
 function mayBeBeforeCreated(
 // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
 el) {

package/lib/wai-aria/checkings/required-prop.d.ts

@@ -1,6 +1,19 @@
 import type { Options } from '../types.js';
 import type { ElementChecker } from '@markuplint/ml-core';
 import { type ARIAProperty, type ARIARole } from '@markuplint/ml-spec';
+/**
+ * Checks whether all required ARIA properties for the element's computed role are present.
+ *
+ * Each ARIA role may define required states and properties (e.g., `slider` requires
+ * `aria-valuenow`). This checker verifies that explicitly-set roles have their required
+ * properties. Implicit roles are skipped since the browser provides default semantics.
+ * Alternative native HTML attributes that satisfy the requirement are also considered.
+ *
+ * @param el - The element node to inspect for required properties.
+ * @param role - The computed ARIA role (with an optional `isImplicit` flag).
+ * @param propSpecs - The list of ARIA property specifications for type lookup.
+ * @returns A violation if a required property is missing and no native alternative is present.
+ */
 export declare const checkingRequiredProp: ElementChecker<boolean, Options, {
     role?: (ARIARole & {
         isImplicit?: boolean;

package/lib/wai-aria/checkings/required-prop.js

@@ -1,4 +1,17 @@
 import { getARIA } from '@markuplint/ml-spec';
+/**
+ * Checks whether all required ARIA properties for the element's computed role are present.
+ *
+ * Each ARIA role may define required states and properties (e.g., `slider` requires
+ * `aria-valuenow`). This checker verifies that explicitly-set roles have their required
+ * properties. Implicit roles are skipped since the browser provides default semantics.
+ * Alternative native HTML attributes that satisfy the requirement are also considered.
+ *
+ * @param el - The element node to inspect for required properties.
+ * @param role - The computed ARIA role (with an optional `isImplicit` flag).
+ * @param propSpecs - The list of ARIA property specifications for type lookup.
+ * @returns A violation if a required property is missing and no native alternative is present.
+ */
 export const checkingRequiredProp = ({ el, role, propSpecs }) => t => {
     if (!role) {
         return;