@markuplint/rules 4.11.2 → 5.0.0-alpha.0

package/lib/srcset-sizes-constraint/index.js

@@ -0,0 +1,108 @@
+import { createRule } from '@markuplint/ml-core';
+import meta from './meta.js';
+import { hasSizesAuto, parseSrcset } from './parse-srcset.js';
+/**
+ * Rule that enforces WHATWG constraints between the `srcset`, `sizes`,
+ * and `loading` attributes on `<img>` and `<source>` elements.
+ */
+export default createRule({
+    meta: meta,
+    async verify({ document, report }) {
+        await document.walkOn('Element', el => {
+            const localName = el.localName;
+            // Only check img and source (inside picture) elements
+            if (localName !== 'img' && localName !== 'source') {
+                return;
+            }
+            // source is only relevant inside <picture>
+            if (localName === 'source' && el.parentElement?.localName !== 'picture') {
+                return;
+            }
+            // Skip if element has spread attributes (dynamic props)
+            if (el.hasSpreadAttr) {
+                return;
+            }
+            const srcsetAttr = el.getAttributeNode('srcset');
+            if (!srcsetAttr) {
+                return;
+            }
+            const srcsetIsDynamic = srcsetAttr.isDynamicValue;
+            const sizesAttr = el.getAttributeNode('sizes');
+            const sizesValue = sizesAttr?.value ?? null;
+            const sizesIsDynamic = sizesAttr?.isDynamicValue;
+            // Parse srcset unless dynamic
+            const parsed = srcsetIsDynamic ? null : parseSrcset(srcsetAttr.value);
+            // Check 2: width and density descriptors must not be mixed
+            if (parsed && parsed.hasWidth && (parsed.hasDensity || parsed.hasImplied)) {
+                report({
+                    scope: el,
+                    line: srcsetAttr.valueNode?.startLine,
+                    col: srcsetAttr.valueNode?.startCol,
+                    raw: srcsetAttr.valueNode?.raw,
+                    message: 'The "srcset" attribute must not mix width and pixel density descriptors',
+                });
+            }
+            // Check 1: sizes present → srcset must use width descriptors
+            if (sizesAttr && !sizesIsDynamic && parsed && !parsed.hasWidth) {
+                report({
+                    scope: el,
+                    line: srcsetAttr.valueNode?.startLine,
+                    col: srcsetAttr.valueNode?.startCol,
+                    raw: srcsetAttr.valueNode?.raw,
+                    message: 'The "srcset" attribute requires width descriptors when the "sizes" attribute is present',
+                });
+            }
+            // Check 3: img[sizes=auto] → loading=lazy required
+            if (localName === 'img' && sizesValue != null && !sizesIsDynamic && hasSizesAuto(sizesValue)) {
+                const loading = el.getAttribute('loading');
+                if (loading !== 'lazy') {
+                    report({
+                        scope: el,
+                        line: sizesAttr.valueNode?.startLine,
+                        col: sizesAttr.valueNode?.startCol,
+                        raw: sizesAttr.valueNode?.raw,
+                        message: 'The "sizes" attribute with "auto" requires the "loading" attribute to be "lazy"',
+                    });
+                }
+            }
+            // Check 4: source[sizes=auto] → following sibling img must have loading=lazy
+            if (localName === 'source' && sizesValue != null && !sizesIsDynamic && hasSizesAuto(sizesValue)) {
+                const img = findFollowingImg(el);
+                if (!img || img.getAttribute('loading') !== 'lazy') {
+                    report({
+                        scope: el,
+                        line: sizesAttr.valueNode?.startLine,
+                        col: sizesAttr.valueNode?.startCol,
+                        raw: sizesAttr.valueNode?.raw,
+                        message: 'The "source" element with sizes="auto" requires the following sibling "img" element to have loading="lazy"',
+                    });
+                }
+            }
+            // Check 5: img with w descriptors → sizes required
+            if (localName === 'img' && parsed && parsed.hasWidth && !sizesAttr) {
+                report({
+                    scope: el,
+                    message: 'The "sizes" attribute is required when the "srcset" attribute uses width descriptors',
+                });
+            }
+        });
+    },
+});
+/**
+ * Find the first following sibling `<img>` element.
+ * Per the spec, the img does not have to be the immediately next sibling.
+ *
+ * @param el - The starting element to search from
+ * @returns The first following sibling `<img>` element, or `null` if none found
+ */
+// eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
+function findFollowingImg(el) {
+    let sibling = el.nextElementSibling;
+    while (sibling != null) {
+        if (sibling.localName === 'img') {
+            return sibling;
+        }
+        sibling = sibling.nextElementSibling;
+    }
+    return null;
+}

package/lib/srcset-sizes-constraint/meta.d.ts

@@ -0,0 +1,5 @@
+/** Rule metadata for `srcset-sizes-constraint`: categorized as a validation rule. */
+declare const _default: {
+    readonly category: "validation";
+};
+export default _default;

package/lib/srcset-sizes-constraint/meta.js

@@ -0,0 +1,4 @@
+/** Rule metadata for `srcset-sizes-constraint`: categorized as a validation rule. */
+export default {
+    category: 'validation',
+};

package/lib/srcset-sizes-constraint/parse-srcset.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Descriptor type for an image candidate in a srcset attribute.
+ * - `width`: ends with `w` (e.g., `480w`)
+ * - `density`: ends with `x` (e.g., `2x`)
+ * - `none`: no descriptor (implies `1x`)
+ */
+type DescriptorType = 'width' | 'density' | 'none';
+type SrcsetCandidate = {
+    readonly url: string;
+    readonly descriptorType: DescriptorType;
+};
+type ParseResult = {
+    readonly candidates: readonly SrcsetCandidate[];
+    /** At least one candidate has a width descriptor (`w`). */
+    readonly hasWidth: boolean;
+    /** At least one candidate has a pixel density descriptor (`x`). */
+    readonly hasDensity: boolean;
+    /** At least one candidate has no descriptor (implied `1x`). */
+    readonly hasImplied: boolean;
+};
+/**
+ * Parse a `srcset` attribute value into its image candidates.
+ *
+ * @param value - The raw `srcset` attribute value string
+ * @returns Parsed result with candidates and descriptor flags
+ * @see https://html.spec.whatwg.org/multipage/images.html#srcset-attributes
+ */
+export declare function parseSrcset(value: string): ParseResult;
+/**
+ * Check whether a `sizes` attribute value starts with `auto`.
+ *
+ * Per the spec, `auto` is only valid as the first entry in a sizes list.
+ * Examples: `"auto"`, `"auto, 100vw"`, `"AUTO"`.
+ *
+ * @param value - The raw `sizes` attribute value string
+ * @returns `true` if the value starts with `auto` (case-insensitive)
+ * @see https://html.spec.whatwg.org/multipage/embedded-content.html#the-img-element
+ */
+export declare function hasSizesAuto(value: string): boolean;
+export {};

package/lib/srcset-sizes-constraint/parse-srcset.js

@@ -0,0 +1,56 @@
+/**
+ * Parse a `srcset` attribute value into its image candidates.
+ *
+ * @param value - The raw `srcset` attribute value string
+ * @returns Parsed result with candidates and descriptor flags
+ * @see https://html.spec.whatwg.org/multipage/images.html#srcset-attributes
+ */
+export function parseSrcset(value) {
+    const raw = value.trim();
+    if (raw === '') {
+        return { candidates: [], hasWidth: false, hasDensity: false, hasImplied: false };
+    }
+    const candidates = [];
+    let hasWidth = false;
+    let hasDensity = false;
+    let hasImplied = false;
+    for (const segment of raw.split(',')) {
+        const tokens = segment.trim().split(/\s+/);
+        const url = tokens[0];
+        if (!url) {
+            continue;
+        }
+        const descriptor = tokens[1];
+        let descriptorType = 'none';
+        if (descriptor) {
+            if (/^[1-9]\d*w$/.test(descriptor)) {
+                descriptorType = 'width';
+                hasWidth = true;
+            }
+            else if (/^\d+(?:\.\d+)?x$/.test(descriptor)) {
+                descriptorType = 'density';
+                hasDensity = true;
+            }
+            // Invalid descriptors are ignored here; type validation handles them.
+        }
+        else {
+            hasImplied = true;
+        }
+        candidates.push({ url, descriptorType });
+    }
+    return { candidates, hasWidth, hasDensity, hasImplied };
+}
+/**
+ * Check whether a `sizes` attribute value starts with `auto`.
+ *
+ * Per the spec, `auto` is only valid as the first entry in a sizes list.
+ * Examples: `"auto"`, `"auto, 100vw"`, `"AUTO"`.
+ *
+ * @param value - The raw `sizes` attribute value string
+ * @returns `true` if the value starts with `auto` (case-insensitive)
+ * @see https://html.spec.whatwg.org/multipage/embedded-content.html#the-img-element
+ */
+export function hasSizesAuto(value) {
+    const v = value.trim().toLowerCase();
+    return v === 'auto' || /^auto[\s,]/.test(v);
+}

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

@@ -1,36 +1,55 @@
-var __classPrivateFieldSet = (this && this.__classPrivateFieldSet) || function (receiver, state, value, kind, f) {
-    if (kind === "m") throw new TypeError("Private method is not writable");
-    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a setter");
-    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot write private member to an object whose class did not declare it");
-    return (kind === "a" ? f.call(receiver, value) : f ? f.value = value : state.set(receiver, value)), value;
-};
-var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (receiver, state, kind, f) {
-    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a getter");
-    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot read private member from an object whose class did not declare it");
-    return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
-};
-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 {
+    /** The grid model for the `<tbody>` section. */
+    tbodyGrid;
+    /** The grid model for the `<tfoot>` section. */
+    tfootGrid;
+    /** The grid model for the `<thead>` section. */
+    theadGrid;
+    /** The `<tr>` elements within `<tbody>`. */
+    #tbodyRowElements;
+    /** The `<tr>` elements within `<tfoot>`. */
+    #tfootRowElements;
+    /** The `<tr>` elements within `<thead>`. */
+    #theadRowElements;
+    /**
+     * 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) {
-        _Grid_tbodyRowElements.set(this, void 0);
-        _Grid_tfootRowElements.set(this, void 0);
-        _Grid_theadRowElements.set(this, void 0);
         const thead = findChildren(table, 'thead')[0];
         const tbody = findChildren(table, 'tbody')[0];
         const tfoot = findChildren(table, 'tfoot')[0];
-        __classPrivateFieldSet(this, _Grid_theadRowElements, thead ? findChildren(thead, 'tr') : [], "f");
-        __classPrivateFieldSet(this, _Grid_tbodyRowElements, tbody ? findChildren(tbody, 'tr') : [], "f");
-        __classPrivateFieldSet(this, _Grid_tfootRowElements, tfoot ? findChildren(tfoot, 'tr') : [], "f");
-        this.theadGrid = createGrid(__classPrivateFieldGet(this, _Grid_theadRowElements, "f"));
-        this.tbodyGrid = createGrid(__classPrivateFieldGet(this, _Grid_tbodyRowElements, "f"));
-        this.tfootGrid = createGrid(__classPrivateFieldGet(this, _Grid_tfootRowElements, "f"));
+        this.#theadRowElements = thead ? findChildren(thead, 'tr') : [];
+        this.#tbodyRowElements = tbody ? findChildren(tbody, 'tr') : [];
+        this.#tfootRowElements = tfoot ? findChildren(tfoot, 'tr') : [];
+        this.theadGrid = createGrid(this.#theadRowElements);
+        this.tbodyGrid = createGrid(this.#tbodyRowElements);
+        this.tfootGrid = createGrid(this.#tfootRowElements);
     }
+    /**
+     * 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")];
+        return [...this.#theadRowElements, ...this.#tbodyRowElements, ...this.#tfootRowElements];
     }
+    /**
+     * 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 +57,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,27 +73,38 @@ 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 [
             {
                 section: this.theadGrid,
-                elements: __classPrivateFieldGet(this, _Grid_theadRowElements, "f"),
+                elements: this.#theadRowElements,
             },
             {
                 section: this.tbodyGrid,
-                elements: __classPrivateFieldGet(this, _Grid_tbodyRowElements, "f"),
+                elements: this.#tbodyRowElements,
             },
             {
                 section: this.tfootGrid,
-                elements: __classPrivateFieldGet(this, _Grid_tfootRowElements, "f"),
+                elements: this.#tfootRowElements,
             },
         ];
     }
+    /**
+     * 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);
@@ -77,7 +114,16 @@ export class Grid {
         console.table(this.tfootGrid);
     }
 }
-_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 +160,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 +198,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 +253,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',
 };