@markuplint/rules 4.11.2 → 4.12.0

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;

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

@@ -1,13 +1,36 @@
 import type { Options } from '../types.js';
 import type { AttrChecker } from '@markuplint/ml-core';
 import type { ARIAProperty, ARIARole } from '@markuplint/ml-spec';
+/**
+ * Checks whether the value of an ARIA property or state conforms to its expected type.
+ *
+ * ARIA properties have specific value types (token, token list, true/false, tristate,
+ * integer, number, string, ID reference, etc.). This checker validates the attribute
+ * value against the property's expected type and allowed enum values.
+ * Role-specific conditional value types are also considered.
+ *
+ * @param attr - The ARIA attribute node to inspect.
+ * @param role - The computed ARIA role, used to resolve conditional value types.
+ * @param propSpecs - The list of ARIA property specifications for value type lookup.
+ * @param booleanish - Whether the document supports booleanish attribute values (e.g., JSX).
+ * @returns A violation if the attribute value does not match the expected type.
+ */
 export declare const checkingValue: AttrChecker<boolean, Options, {
     role?: ARIARole | null;
     propSpecs: readonly ARIAProperty[];
     booleanish?: boolean;
 }>;
 /**
+ * Validates a raw ARIA value against the expected value type defined in the specification.
+ *
+ * Supports token, token list, string, ID reference, true/false, tristate,
+ * true/false/undefined, integer, and number value types.
  *
  * @see https://www.w3.org/TR/wai-aria-1.2/#propcharacteristic_value
+ * @param type - The ARIA value type (e.g., `"token"`, `"true/false"`, `"integer"`).
+ * @param value - The raw attribute value to validate.
+ * @param tokenEnum - The list of allowed token values for token-based types.
+ * @param booleanish - Whether empty string is accepted as a boolean `true` value.
+ * @returns `true` if the value is valid for the given type, `false` otherwise.
  */
 export declare function checkAriaValue(type: string, value: string, tokenEnum: readonly string[], booleanish?: boolean): boolean;

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

@@ -1,3 +1,17 @@
+/**
+ * Checks whether the value of an ARIA property or state conforms to its expected type.
+ *
+ * ARIA properties have specific value types (token, token list, true/false, tristate,
+ * integer, number, string, ID reference, etc.). This checker validates the attribute
+ * value against the property's expected type and allowed enum values.
+ * Role-specific conditional value types are also considered.
+ *
+ * @param attr - The ARIA attribute node to inspect.
+ * @param role - The computed ARIA role, used to resolve conditional value types.
+ * @param propSpecs - The list of ARIA property specifications for value type lookup.
+ * @param booleanish - Whether the document supports booleanish attribute values (e.g., JSX).
+ * @returns A violation if the attribute value does not match the expected type.
+ */
 export const checkingValue = ({ attr, role, propSpecs, booleanish }) => t => {
     if (attr.isDynamicValue) {
         return;
@@ -15,6 +29,15 @@ export const checkingValue = ({ attr, role, propSpecs, booleanish }) => t => {
                 : ''),
     };
 };
+/**
+ * Validates an ARIA property value against its specification, considering role-specific conditional types.
+ *
+ * @param propSpec - The ARIA property specification, or `undefined` if the property is unknown.
+ * @param currentValue - The current attribute value to validate.
+ * @param role - The name of the computed role, used to resolve conditional value types.
+ * @param booleanish - Whether booleanish values (empty string as `true`) are accepted.
+ * @returns An object containing the validation result and, for enum types, the allowed values.
+ */
 function checkAria(propSpec, currentValue, role, booleanish) {
     if (!propSpec) {
         return {
@@ -40,8 +63,17 @@ function checkAria(propSpec, currentValue, role, booleanish) {
     };
 }
 /**
+ * Validates a raw ARIA value against the expected value type defined in the specification.
+ *
+ * Supports token, token list, string, ID reference, true/false, tristate,
+ * true/false/undefined, integer, and number value types.
  *
  * @see https://www.w3.org/TR/wai-aria-1.2/#propcharacteristic_value
+ * @param type - The ARIA value type (e.g., `"token"`, `"true/false"`, `"integer"`).
+ * @param value - The raw attribute value to validate.
+ * @param tokenEnum - The list of allowed token values for token-based types.
+ * @param booleanish - Whether empty string is accepted as a boolean `true` value.
+ * @returns `true` if the value is valid for the given type, `false` otherwise.
  */
 export function checkAriaValue(type, value, tokenEnum, booleanish) {
     switch (type) {

package/lib/wai-aria/index.d.ts

@@ -1,3 +1,13 @@
 import type { Options } from './types.js';
+/**
+ * WAI-ARIA rule for markuplint.
+ *
+ * Validates the correct usage of WAI-ARIA roles, states, and properties
+ * on HTML elements. This rule performs a comprehensive set of checks including
+ * role validity, property values, required owned elements, and conformance
+ * with the ARIA in HTML specification.
+ *
+ * Individual checks can be toggled on or off via the rule's options.
+ */
 declare const _default: Readonly<import("@markuplint/ml-core").RuleSeed<boolean, Options>>;
 export default _default;

package/lib/wai-aria/index.js

@@ -17,6 +17,16 @@ import { checkingRequiredOwnedElements } from './checkings/required-owned-elemen
 import { checkingRequiredProp } from './checkings/required-prop.js';
 import { checkingValue } from './checkings/value.js';
 import meta from './meta.js';
+/**
+ * WAI-ARIA rule for markuplint.
+ *
+ * Validates the correct usage of WAI-ARIA roles, states, and properties
+ * on HTML elements. This rule performs a comprehensive set of checks including
+ * role validity, property values, required owned elements, and conformance
+ * with the ARIA in HTML specification.
+ *
+ * Individual checks can be toggled on or off via the rule's options.
+ */
 export default createRule({
     meta: meta,
     defaultOptions: {

package/lib/wai-aria/meta.d.ts

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

package/lib/wai-aria/meta.js

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

package/lib/wai-aria/types.d.ts

@@ -1,14 +1,31 @@
 import type { ARIAVersion } from '@markuplint/ml-spec';
+/**
+ * Configuration options for the `wai-aria` rule.
+ *
+ * Each boolean flag enables or disables a specific WAI-ARIA validation check.
+ * The `version` field determines which ARIA specification version to validate against.
+ */
 export type Options = {
+    /** Whether to validate ARIA property and state values against their expected types. */
     checkingValue: boolean;
+    /** Whether to report usage of deprecated ARIA properties and states. */
     checkingDeprecatedProps: boolean;
+    /** Whether to report usage of deprecated ARIA roles. */
     checkingDeprecatedRole: boolean;
+    /** Whether to enforce the list of permitted ARIA roles for each element. */
     permittedAriaRoles: boolean;
+    /** Whether to verify that roles requiring specific owned elements contain them. */
     checkingRequiredOwnedElements: boolean;
+    /** Whether to warn when ARIA attributes are set on descendants of presentational-children roles. */
     checkingPresentationalChildren: boolean;
+    /** Whether to warn about focusable interactive elements hidden via `aria-hidden`. */
     checkingInteractionInHidden: boolean;
+    /** Whether to disallow explicitly setting a role that matches the element's implicit role. */
     disallowSetImplicitRole: boolean;
+    /** Whether to disallow explicitly setting ARIA properties that duplicate the element's native semantics. */
     disallowSetImplicitProps: boolean;
+    /** Whether to disallow explicitly setting an ARIA property to its default value. */
     disallowDefaultValue: boolean;
+    /** The WAI-ARIA specification version to validate against. */
     version: ARIAVersion;
 };