@markuplint/rules 4.11.2 → 4.12.0

package/lib/required-attr/index.d.ts

@@ -1,7 +1,20 @@
+/** The rule value: either a single attribute name or an array of required attribute descriptors. */
 type RequiredAttributes = string | (string | Attr)[];
+/**
+ * Descriptor for a required attribute with an optional set of allowed values.
+ */
 type Attr = {
+    /** The attribute name that is required. */
     name: string;
+    /** One or more allowed values for the attribute, if constrained. */
     value?: string | string[];
 };
+/**
+ * Rule that validates elements have all required attributes.
+ *
+ * Checks both HTML-spec-defined required attributes and custom required attributes
+ * specified in the rule configuration. Also validates that required attribute values
+ * match expected patterns when value constraints are provided.
+ */
 declare const _default: Readonly<import("@markuplint/ml-core").RuleSeed<RequiredAttributes, undefined>>;
 export default _default;

package/lib/required-attr/index.js

@@ -1,6 +1,13 @@
 import { createRule, getAttrSpecs } from '@markuplint/ml-core';
 import { attrMatches, match } from '../helpers.js';
 import meta from './meta.js';
+/**
+ * Rule that validates elements have all required attributes.
+ *
+ * Checks both HTML-spec-defined required attributes and custom required attributes
+ * specified in the rule configuration. Also validates that required attribute values
+ * match expected patterns when value constraints are provided.
+ */
 export default createRule({
     meta: meta,
     defaultValue: [],

package/lib/required-attr/meta.d.ts

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

package/lib/required-attr/meta.js

@@ -1,3 +1,4 @@
+/** Rule metadata for the `required-attr` rule, categorized as validation. */
 export default {
     category: 'validation',
 };

package/lib/required-element/index.d.ts

@@ -1,5 +1,19 @@
+/**
+ * Configuration options for the required-element rule.
+ */
 type Options = {
+    /** Whether to skip validation for elements that contain mutable (dynamic) content. */
     ignoreHasMutableContents: boolean;
+    /** Whether to ignore omitted (ghost) elements that are implicitly created by the HTML parser. */
+    ignoreOmittedElements: boolean;
 };
+/**
+ * Rule that validates required child elements are present.
+ *
+ * Accepts an array of CSS selectors as the rule value. For the document level,
+ * reports if any matching element is missing from the entire document. For
+ * element-level overrides, checks that the specified child elements exist
+ * among the element's direct children.
+ */
 declare const _default: Readonly<import("@markuplint/ml-core").RuleSeed<string[], Options>>;
 export default _default;

package/lib/required-element/index.js

@@ -1,16 +1,28 @@
 import { createRule } from '@markuplint/ml-core';
 import meta from './meta.js';
+/**
+ * Rule that validates required child elements are present.
+ *
+ * Accepts an array of CSS selectors as the rule value. For the document level,
+ * reports if any matching element is missing from the entire document. For
+ * element-level overrides, checks that the specified child elements exist
+ * among the element's direct children.
+ */
 export default createRule({
     meta: meta,
     defaultValue: [],
     defaultOptions: {
         ignoreHasMutableContents: true,
+        ignoreOmittedElements: false,
     },
     async verify({ document, report, t }) {
         const hasMutableContent = document.nodeList.some(n => n.is(n.ELEMENT_NODE) && n.hasMutableChildren());
         if (!hasMutableContent) {
             for (const query of document.rule.value) {
-                const exists = document.querySelectorAll(query);
+                const matched = document.querySelectorAll(query);
+                const exists = document.rule.options.ignoreOmittedElements
+                    ? [...matched].filter(el => !el.isOmitted)
+                    : [...matched];
                 if (exists.length === 0) {
                     const message = t('Require {0}', t('the "{0*}" {1}', query, 'element'));
                     report({
@@ -30,7 +42,7 @@ export default createRule({
                 return;
             }
             for (const query of el.rule.value) {
-                const exists = [...el.children].find(child => child.matches(query));
+                const exists = [...el.children].find(child => !(el.rule.options.ignoreOmittedElements && child.isOmitted) && child.matches(query));
                 if (!exists) {
                     const message = t('Require {0}', t('the "{0*}" {1}', query, 'element'));
                     report({

package/lib/required-element/meta.d.ts

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

package/lib/required-element/meta.js

@@ -1,3 +1,4 @@
+/** Rule metadata for the `required-element` rule, categorized as validation. */
 export default {
     category: 'validation',
 };

package/lib/required-h1/index.d.ts

@@ -1,6 +1,18 @@
+/**
+ * Configuration options for the required-h1 rule.
+ */
 export interface Options {
+    /** Whether to report a violation when more than one `<h1>` element is found. */
     'expected-once': boolean;
+    /** Whether to apply this rule in document fragments (components, partials). */
     'in-document-fragment': boolean;
 }
+/**
+ * Rule that requires exactly one `<h1>` element in the document.
+ *
+ * Reports a violation when no `<h1>` is present. Optionally reports when
+ * multiple `<h1>` elements exist (controlled by `expected-once`). Can be
+ * configured to skip document fragments via the `in-document-fragment` option.
+ */
 declare const _default: Readonly<import("@markuplint/ml-core").RuleSeed<boolean, Options>>;
 export default _default;

package/lib/required-h1/index.js

@@ -1,5 +1,12 @@
 import { createRule } from '@markuplint/ml-core';
 import meta from './meta.js';
+/**
+ * Rule that requires exactly one `<h1>` element in the document.
+ *
+ * Reports a violation when no `<h1>` is present. Optionally reports when
+ * multiple `<h1>` elements exist (controlled by `expected-once`). Can be
+ * configured to skip document fragments via the `in-document-fragment` option.
+ */
 export default createRule({
     meta: meta,
     defaultOptions: {

package/lib/required-h1/meta.d.ts

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

package/lib/required-h1/meta.js

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

package/lib/table-row-column-alignment/find-children.d.ts

@@ -1,2 +1,12 @@
 import type { Element } from '@markuplint/ml-core';
+/**
+ * Finds direct children of an element matching the given CSS selector, with caching.
+ *
+ * Results are cached by element UUID and selector to avoid redundant DOM traversals
+ * when the same element/selector combination is queried multiple times.
+ *
+ * @param el - The parent element to search within.
+ * @param selector - The CSS selector to match children against.
+ * @returns An array of matching child elements.
+ */
 export declare function findChildren(el: Element<boolean>, selector: string): Element<boolean, undefined>[];

package/lib/table-row-column-alignment/find-children.js

@@ -1,4 +1,15 @@
+/** Cache for `findChildren` results, keyed by element UUID and selector. */
 const findCache = {};
+/**
+ * Finds direct children of an element matching the given CSS selector, with caching.
+ *
+ * Results are cached by element UUID and selector to avoid redundant DOM traversals
+ * when the same element/selector combination is queried multiple times.
+ *
+ * @param el - The parent element to search within.
+ * @param selector - The CSS selector to match children against.
+ * @returns An array of matching child elements.
+ */
 export function findChildren(
 // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
 el, selector) {

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

@@ -1,22 +1,82 @@
 import type { CellType } from './types.js';
 import type { Element } from '@markuplint/ml-core';
+/**
+ * Represents a table as a grid model, splitting it into thead, tbody, and tfoot sections.
+ *
+ * Each section is modeled as a 2D array of `CellType` values that account for
+ * `colspan` and `rowspan` attributes. Used by the `table-row-column-alignment`
+ * rule to detect misaligned rows and overlapping cells.
+ */
 export declare class Grid {
     #private;
+    /** The grid model for the `<tbody>` section. */
     readonly tbodyGrid: ReadonlyArray<ReadonlyArray<CellType>>;
+    /** The grid model for the `<tfoot>` section. */
     readonly tfootGrid: ReadonlyArray<ReadonlyArray<CellType>>;
+    /** The grid model for the `<thead>` section. */
     readonly theadGrid: ReadonlyArray<ReadonlyArray<CellType>>;
+    /**
+     * Constructs a grid model from a `<table>` element.
+     *
+     * @param table - The table element to model.
+     */
     constructor(table: Element<boolean>);
+    /**
+     * Returns all `<tr>` elements across all table sections in document order.
+     *
+     * @returns Combined array of row elements from thead, tbody, and tfoot.
+     */
     getAllRowElements(): Element<boolean, undefined>[];
+    /**
+     * Returns all grid rows that contain at least one actual cell element.
+     *
+     * @returns Combined array of grid rows from thead, tbody, and tfoot, filtered to rows with real cells.
+     */
     getAllRows(): (readonly CellType[])[];
+    /**
+     * Determines the expected (base) column count for the table.
+     *
+     * Prefers the thead section if available, then tfoot, then tbody.
+     *
+     * @returns The base number of columns that rows should have.
+     */
     getBaseColLength(): number;
+    /**
+     * Returns the grid and row elements for each table section (thead, tbody, tfoot).
+     *
+     * @returns An array of objects, each containing the section grid and its row elements.
+     */
     getSections(): {
         section: readonly (readonly CellType[])[];
         elements: readonly Element<boolean, undefined>[];
     }[];
+    /**
+     * Checks whether any cell in the table grid has been marked as overlapping.
+     *
+     * @returns `true` if any cell has the overlap marker `'x'`.
+     */
     hasOverlapped(): boolean;
+    /** Logs the grid data for all three table sections to the console (for debugging). */
     log(): void;
 }
+/**
+ * Detects a rowspan that extends beyond the available rows in a table section.
+ *
+ * When a grid row exists without a corresponding row element, it indicates
+ * a rowspan overflow. Returns the offending `rowspan` attribute node if found.
+ *
+ * @param rows - The grid rows for a single table section.
+ * @param rowElements - The `<tr>` elements for the section.
+ * @returns An object containing the overflowing `rowSpan` attribute, or `null`.
+ */
 export declare function getOverflowRowSpan(rows: ReadonlyArray<ReadonlyArray<CellType>>, rowElements: ReadonlyArray<Element<boolean>>): {
     rowSpan: import("@markuplint/ml-core").Attr<boolean, undefined>;
 } | null;
+/**
+ * Maps each cell in a grid row to its source cell index (for cells that correspond
+ * to actual `<td>`/`<th>` elements), or `null` for spanned cells.
+ *
+ * @param row - A single row of cell types from the grid model.
+ * @returns An array of cell indices or `null` values, one per grid column.
+ */
 export declare function getIndexes(row: readonly CellType[]): (number | null)[];

package/lib/table-row-column-alignment/grid.js

@@ -11,12 +11,27 @@ var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (
 };
 var _Grid_tbodyRowElements, _Grid_tfootRowElements, _Grid_theadRowElements;
 import { findChildren } from './find-children.js';
+/**
+ * Represents a table as a grid model, splitting it into thead, tbody, and tfoot sections.
+ *
+ * Each section is modeled as a 2D array of `CellType` values that account for
+ * `colspan` and `rowspan` attributes. Used by the `table-row-column-alignment`
+ * rule to detect misaligned rows and overlapping cells.
+ */
 export class Grid {
+    /**
+     * Constructs a grid model from a `<table>` element.
+     *
+     * @param table - The table element to model.
+     */
     constructor(
     // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
     table) {
+        /** The `<tr>` elements within `<tbody>`. */
         _Grid_tbodyRowElements.set(this, void 0);
+        /** The `<tr>` elements within `<tfoot>`. */
         _Grid_tfootRowElements.set(this, void 0);
+        /** The `<tr>` elements within `<thead>`. */
         _Grid_theadRowElements.set(this, void 0);
         const thead = findChildren(table, 'thead')[0];
         const tbody = findChildren(table, 'tbody')[0];
@@ -28,9 +43,19 @@ export class Grid {
         this.tbodyGrid = createGrid(__classPrivateFieldGet(this, _Grid_tbodyRowElements, "f"));
         this.tfootGrid = createGrid(__classPrivateFieldGet(this, _Grid_tfootRowElements, "f"));
     }
+    /**
+     * Returns all `<tr>` elements across all table sections in document order.
+     *
+     * @returns Combined array of row elements from thead, tbody, and tfoot.
+     */
     getAllRowElements() {
         return [...__classPrivateFieldGet(this, _Grid_theadRowElements, "f"), ...__classPrivateFieldGet(this, _Grid_tbodyRowElements, "f"), ...__classPrivateFieldGet(this, _Grid_tfootRowElements, "f")];
     }
+    /**
+     * Returns all grid rows that contain at least one actual cell element.
+     *
+     * @returns Combined array of grid rows from thead, tbody, and tfoot, filtered to rows with real cells.
+     */
     getAllRows() {
         return [
             ...this.theadGrid.filter(hasElementFilter),
@@ -38,6 +63,13 @@ export class Grid {
             ...this.tfootGrid.filter(hasElementFilter),
         ];
     }
+    /**
+     * Determines the expected (base) column count for the table.
+     *
+     * Prefers the thead section if available, then tfoot, then tbody.
+     *
+     * @returns The base number of columns that rows should have.
+     */
     getBaseColLength() {
         if (this.theadGrid.length > 0) {
             return getBaseColLength(this.theadGrid);
@@ -47,6 +79,11 @@ export class Grid {
         }
         return getBaseColLength(this.tbodyGrid);
     }
+    /**
+     * Returns the grid and row elements for each table section (thead, tbody, tfoot).
+     *
+     * @returns An array of objects, each containing the section grid and its row elements.
+     */
     getSections() {
         return [
             {
@@ -63,11 +100,17 @@ export class Grid {
             },
         ];
     }
+    /**
+     * Checks whether any cell in the table grid has been marked as overlapping.
+     *
+     * @returns `true` if any cell has the overlap marker `'x'`.
+     */
     hasOverlapped() {
         return (this.tbodyGrid.some(row => row.includes('x')) ||
             this.tfootGrid.some(row => row.includes('x')) ||
             this.theadGrid.some(row => row.includes('x')));
     }
+    /** Logs the grid data for all three table sections to the console (for debugging). */
     log() {
         // eslint-disable-next-line no-console
         console.table(this.theadGrid);
@@ -78,6 +121,16 @@ export class Grid {
     }
 }
 _Grid_tbodyRowElements = new WeakMap(), _Grid_tfootRowElements = new WeakMap(), _Grid_theadRowElements = new WeakMap();
+/**
+ * Detects a rowspan that extends beyond the available rows in a table section.
+ *
+ * When a grid row exists without a corresponding row element, it indicates
+ * a rowspan overflow. Returns the offending `rowspan` attribute node if found.
+ *
+ * @param rows - The grid rows for a single table section.
+ * @param rowElements - The `<tr>` elements for the section.
+ * @returns An object containing the overflowing `rowSpan` attribute, or `null`.
+ */
 export function getOverflowRowSpan(rows, 
 // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
 rowElements) {
@@ -114,10 +167,26 @@ rowElements) {
     }
     return null;
 }
+/**
+ * Maps each cell in a grid row to its source cell index (for cells that correspond
+ * to actual `<td>`/`<th>` elements), or `null` for spanned cells.
+ *
+ * @param row - A single row of cell types from the grid model.
+ * @returns An array of cell indices or `null` values, one per grid column.
+ */
 export function getIndexes(row) {
     let indexCounter = 0;
     return row.map(col => (col === '●' || col === '◎' ? indexCounter++ : null));
 }
+/**
+ * Calculates the base (expected) column count from a section grid.
+ *
+ * For grids with 3 or more rows, uses the row length closest to the
+ * average to handle minor variations from spans. Otherwise uses the first row.
+ *
+ * @param grid - The 2D grid for a table section.
+ * @returns The base number of columns.
+ */
 function getBaseColLength(grid) {
     let baseColLength;
     if (grid.length >= 3) {
@@ -136,6 +205,16 @@ function getBaseColLength(grid) {
     }
     return baseColLength;
 }
+/**
+ * Builds a 2D grid model from an array of `<tr>` elements.
+ *
+ * Processes each row's `<th>` and `<td>` cells, expanding `colspan` and `rowspan`
+ * attributes into the grid. Marks cells with appropriate cell types including
+ * span origins, continuations, and overlaps.
+ *
+ * @param rows - The `<tr>` elements to convert into a grid.
+ * @returns A 2D array of cell types representing the table section layout.
+ */
 function createGrid(
 // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
 rows) {
@@ -181,6 +260,12 @@ rows) {
     }
     return matrix;
 }
+/**
+ * Filter predicate that returns `true` if a grid row contains at least one actual cell element.
+ *
+ * @param row - A single row of cell types.
+ * @returns `true` if the row has a regular or span-origin cell.
+ */
 function hasElementFilter(row) {
     return row.some(cell => cell === '●' || cell === '◎');
 }

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

@@ -1,2 +1,10 @@
+/**
+ * Rule that validates table row and column alignment.
+ *
+ * Builds a grid model of each `<table>` and checks that all rows have a
+ * consistent number of columns, that `colspan`/`rowspan` attributes do not
+ * cause cell overlap, and that `rowspan` values do not exceed the available
+ * rows in their table section.
+ */
 declare const _default: Readonly<import("@markuplint/ml-core").RuleSeed<boolean, undefined>>;
 export default _default;

package/lib/table-row-column-alignment/index.js

@@ -2,6 +2,14 @@ import { createRule } from '@markuplint/ml-core';
 import { findChildren } from './find-children.js';
 import { Grid, getIndexes, getOverflowRowSpan } from './grid.js';
 import meta from './meta.js';
+/**
+ * Rule that validates table row and column alignment.
+ *
+ * Builds a grid model of each `<table>` and checks that all rows have a
+ * consistent number of columns, that `colspan`/`rowspan` attributes do not
+ * cause cell overlap, and that `rowspan` values do not exceed the available
+ * rows in their table section.
+ */
 export default createRule({
     meta,
     defaultSeverity: 'warning',

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

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

package/lib/table-row-column-alignment/meta.js

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

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[];