@markuplint/rules 5.0.0-rc.4 → 5.0.0-rc.6

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

@@ -1,82 +1,138 @@
 import type { CellType } from './types.js';
 import type { Element } from '@markuplint/ml-core';
+/** A `<th>` / `<td>` anchored to a slot, together with the slots it covers. */
+export type Anchor = {
+    /** The cell element. */
+    readonly cell: Element<boolean>;
+    /** The slot column the cell is anchored to (spec: xcurrent when the cell was placed). */
+    readonly x: number;
+    /** The slot row the cell is anchored to, counted within the owning row group (spec: ycurrent). */
+    readonly y: number;
+    /** The clamped `colspan`. */
+    readonly colspan: number;
+    /** The clamped `rowspan`, or the distance to the end of the row group for a downward-growing cell. */
+    readonly rowspan: number;
+    /** Whether `rowspan="0"` made the cell grow downward to the end of its row group (spec Step 10). */
+    readonly growsDownward: boolean;
+};
+/** A contiguous slot column range together with the element that established it. */
+export type ColumnRange = {
+    /**
+     * The element the range is attributed to: a `<col>` / `<colgroup>` for column markup,
+     * or the `<th>` / `<td>` whose `colspan` stretched the table to cover the range.
+     */
+    readonly source: Element<boolean>;
+    /** The leftmost column that is part of the range. */
+    readonly left: number;
+    /** The first column to the right that is not part of the range. */
+    readonly right: number;
+};
+/** One row of slots, paired with the `<tr>` that established it. */
+export type Row = {
+    /** The `<tr>` element. */
+    readonly element: Element<boolean>;
+    /**
+     * The slots the row occupies. Its length is the row's width, which mirrors
+     * nu-validator's insertion point at the end of the row: the cells anchored in
+     * the row plus the run of slots that spans from earlier rows continue into.
+     */
+    readonly slots: readonly CellType[];
+    /** How many cells are anchored in this row (spec Step 20 counts rows by this). */
+    readonly anchorCount: number;
+};
+/** One row group — `<thead>`, `<tbody>`, `<tfoot>`, or the implicit group parse5 inserts. */
+export type RowGroup = {
+    /** The tag name of the element that established the group, lowercased. */
+    readonly tagName: string;
+    /** The rows of the group, in document order. */
+    readonly rows: readonly Row[];
+    /** Every cell anchored within the group, in document order. */
+    readonly anchors: readonly Anchor[];
+    /**
+     * Anchors whose `rowspan` reaches past the last row of the group. HTML LS
+     * §4.9.12 forbids this ("A cell cannot cover slots that are from two or more
+     * row groups."), and the *ending a row group* algorithm clips the cell instead.
+     */
+    readonly overflows: readonly Anchor[];
+    /** Whether any slot of the group is covered twice (spec Step 14). */
+    readonly hasOverlap: boolean;
+};
 /**
- * Represents a table as a grid model, splitting it into thead, tbody, and tfoot sections.
+ * Models a `<table>` as the slot grid of HTML LS
+ * [§4.9.12.1 *Forming a table*](https://html.spec.whatwg.org/multipage/tables.html#forming-a-table).
+ *
+ * Shared by `no-table-cell-overlap`, `no-table-span-overflow`, `no-empty-table-track`, and
+ * `consistent-table-row-length` — the four rules split out of the former
+ * `table-row-column-alignment` rule, one per table model error / diagnostic this class models.
+ *
+ * The algorithm is followed rather than approximated because every table model error those rules
+ * report is defined in terms of it: Step 6 decides which slot a cell is anchored to (a `colspan`
+ * after a `rowspan` continuation does *not* start at the cell's ordinal position), Steps 7 and 11
+ * decide how wide the table becomes, Step 14 defines cell overlap, and Step 20 defines rows and
+ * columns that no cell is anchored to.
  *
- * 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.
+ * Two things the spec has no name for are tracked alongside:
+ *
+ * - **Row width** ({@link Row.slots} length). Rows narrower or wider than the rest of the
+ *   table are not a table model error — nu-validator reports them as warnings unless column
+ *   markup fixes the width — but they are `consistent-table-row-length`'s diagnostic and predate
+ *   the spec-level checks.
+ * - **Row group boundaries**. The spec's *ending a row group* algorithm clips a cell to its
+ *   row group, so slots are covered per group; {@link RowGroup.overflows} keeps the cells that
+ *   were clipped so `no-table-span-overflow` can report them.
  */
 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>>;
+    /** Column ranges established by `<col>` / `<colgroup>`, in document order. */
+    readonly columnMarkup: readonly ColumnRange[];
+    /** The row groups of the table, in document order. */
+    readonly rowGroups: readonly RowGroup[];
+    /** The number of slot columns in the table (spec: xwidth). */
+    readonly xwidth: number;
     /**
      * Constructs a grid model from a `<table>` element.
      *
      * @param table - The table element to model.
      */
     constructor(table: Element<boolean>);
+    /** @returns Every cell anchored in the table, in document order. */
+    getAnchors(): Anchor[];
     /**
-     * Returns all `<tr>` elements across all table sections in document order.
+     * Determines the expected (base) column count that rows are compared against.
      *
-     * @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.
+     * Rows decide it, preferring `<thead>` then `<tfoot>` since a heading or footing
+     * row is the more deliberate declaration. Column markup is deliberately *not*
+     * consulted: HTML LS §4.9.12.1 Step 7 grows xwidth to fit a row that is wider
+     * than the `<col>` markup, so such a row is not an error (tracked as a
+     * nu-validator over-detection in `tests/external/snapshots/excluded-ids.json`).
+     * A row narrower than the column markup is caught by the Step 20 column scan
+     * instead, which reports the `<col>` that no cell ever starts in.
      *
      * @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).
+     * Collects the columns that no cell is anchored to (spec Step 20), merging
+     * neighbouring columns that the same element established into one range so a
+     * `colspan` overshooting by four columns is reported once, not four times.
      *
-     * @returns An array of objects, each containing the section grid and its row elements.
+     * @returns The offending ranges, in column order.
      */
-    getSections(): {
-        section: readonly (readonly CellType[])[];
-        elements: readonly Element<boolean, undefined>[];
-    }[];
+    getColumnsWithoutAnchor(): ColumnRange[];
+    /** @returns Every row of the table, in document order. */
+    getRows(): Row[];
     /**
-     * Checks whether any cell in the table grid has been marked as overlapping.
+     * Checks whether any slot of the table is covered by more than one cell.
      *
-     * @returns `true` if any cell has the overlap marker `'x'`.
+     * @returns `true` if the table has a Step 14 cell overlap.
      */
     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.
+ * Maps each slot of a row to the index of the `<th>` / `<td>` anchored to it
+ * (counted among the row's own cells), or `null` for a slot the row does not anchor a cell to.
  *
- * @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.
+ * @param slots - The slots of a single row.
+ * @returns An array of cell indices or `null` values, one per slot.
  */
-export declare function getIndexes(row: readonly CellType[]): (number | null)[];
+export declare function getIndexes(slots: readonly CellType[]): (number | null)[];