@beyondwork/docx-react-component 1.0.37 → 1.0.39

package/src/core/commands/table-grid.ts

@@ -0,0 +1,431 @@
+/**
+ * Logical grid topology helper for merge-aware table structural operations.
+ *
+ * A `TableNode` carries cells in row-major order, but horizontal (`gridSpan`)
+ * and vertical (`verticalMerge`) merges mean cell index and logical column
+ * index are not the same. Every structural command that has to reason about
+ * "the cell at logical column C in row R" reads through this module.
+ *
+ * The core type is `LogicalGrid`: a rectangular 2D array where each entry
+ * describes either the origin of a spanning region or a covered slot that
+ * points back to its origin.
+ */
+import type {
+  TableCellNode,
+  TableNode,
+  TableRowNode,
+} from "../../model/canonical-document.ts";
+
+export interface GridOriginSlot {
+  kind: "origin";
+  /** Row index of this origin slot in the table. */
+  rowIndex: number;
+  /** Logical column index of the left edge of the spanning region. */
+  columnIndex: number;
+  /** Index of the cell within its row's `cells` array. */
+  cellIndex: number;
+  /** Horizontal span in logical columns (== gridSpan, default 1). */
+  columnSpan: number;
+  /** Vertical span in rows, resolved from verticalMerge chains. */
+  rowSpan: number;
+  /** The cell this origin points to. */
+  cell: TableCellNode;
+}
+
+export interface GridCoveredSlot {
+  kind: "covered";
+  /** The origin this slot is covered by. */
+  origin: GridOriginSlot;
+}
+
+export type GridSlot = GridOriginSlot | GridCoveredSlot;
+
+export interface LogicalGrid {
+  table: TableNode;
+  rowCount: number;
+  columnCount: number;
+  /** 2D matrix [rowIndex][logicalColumnIndex] → slot. */
+  slots: GridSlot[][];
+  /**
+   * Rows carried over via gridBefore/gridAfter spacers. Each entry lists
+   * the logical columns that were marked as "before" or "after" padding
+   * rather than cell content. Used by commands that must preserve ragged
+   * row geometry.
+   */
+  rowPadding: Array<{ beforeColumns: number[]; afterColumns: number[] }>;
+  /** Invariant violations discovered while building the grid. */
+  warnings: GridWarning[];
+}
+
+export interface GridWarning {
+  kind:
+    | "row-span-mismatch"
+    | "vmerge-continue-without-restart"
+    | "column-span-zero";
+  rowIndex: number;
+  columnIndex?: number;
+  message: string;
+}
+
+/**
+ * Build the logical grid for a canonical table.
+ *
+ * The result is tolerant: malformed inputs (e.g. a `verticalMerge: "continue"`
+ * with no matching restart above) produce `warnings` rather than throwing,
+ * so callers can still make best-effort structural decisions on imported
+ * documents. The grid is always rectangular — covered slots are filled in
+ * to match the widest effective row width.
+ */
+export function buildLogicalGrid(table: TableNode): LogicalGrid {
+  const rowCount = table.rows.length;
+  const columnCount = computeLogicalColumnCount(table);
+  const slots: GridSlot[][] = Array.from({ length: rowCount }, () =>
+    Array.from({ length: columnCount }) as GridSlot[],
+  );
+  const rowPadding: LogicalGrid["rowPadding"] = [];
+  const warnings: GridWarning[] = [];
+
+  // Track active vMerge chains keyed by their logical start column. Each
+  // entry holds the origin and the trailing column covered by the chain.
+  const activeVMerges = new Map<number, GridOriginSlot>();
+
+  for (let rowIndex = 0; rowIndex < rowCount; rowIndex += 1) {
+    const row = table.rows[rowIndex]!;
+    const gridBefore = Math.max(0, row.gridBefore ?? 0);
+    const gridAfter = Math.max(0, row.gridAfter ?? 0);
+    const beforeColumns: number[] = [];
+    const afterColumns: number[] = [];
+    const endColumn = columnCount - gridAfter;
+
+    // Mark gridBefore columns as padding (they don't participate in the
+    // cell grid but we still need to know they're reserved so column
+    // counts stay accurate for subsequent vMerge math).
+    for (let padIndex = 0; padIndex < gridBefore && padIndex < columnCount; padIndex += 1) {
+      beforeColumns.push(padIndex);
+    }
+
+    let columnCursor = gridBefore;
+
+    for (let cellIndex = 0; cellIndex < row.cells.length; cellIndex += 1) {
+      const cell = row.cells[cellIndex]!;
+      const rawSpan = cell.gridSpan ?? 1;
+      if (rawSpan <= 0) {
+        warnings.push({
+          kind: "column-span-zero",
+          rowIndex,
+          columnIndex: columnCursor,
+          message: `Cell ${cellIndex} has non-positive gridSpan; treating as 1`,
+        });
+      }
+      const columnSpan = Math.max(1, rawSpan);
+
+      if (cell.verticalMerge === "continue") {
+        const owner = findVMergeOwner(activeVMerges, columnCursor, columnSpan);
+        if (owner) {
+          // Extend the owner's rowspan to cover this row.
+          owner.rowSpan += 1;
+          const covered: GridCoveredSlot = { kind: "covered", origin: owner };
+          for (let offset = 0; offset < columnSpan; offset += 1) {
+            const column = columnCursor + offset;
+            if (column < columnCount) {
+              slots[rowIndex]![column] = covered;
+            }
+          }
+          // Note: a vMerge:continue cell can still break the chain later;
+          // we keep the owner entry keyed by its original column so
+          // subsequent rows can extend it.
+          columnCursor += columnSpan;
+          continue;
+        }
+
+        warnings.push({
+          kind: "vmerge-continue-without-restart",
+          rowIndex,
+          columnIndex: columnCursor,
+          message: `Cell ${cellIndex} has verticalMerge=continue but no matching restart above`,
+        });
+        // Fall through and treat as a regular cell origin.
+      }
+
+      const origin: GridOriginSlot = {
+        kind: "origin",
+        rowIndex,
+        columnIndex: columnCursor,
+        cellIndex,
+        columnSpan,
+        rowSpan: 1,
+        cell,
+      };
+
+      for (let offset = 0; offset < columnSpan; offset += 1) {
+        const column = columnCursor + offset;
+        if (column >= columnCount) break;
+        if (offset === 0) {
+          slots[rowIndex]![column] = origin;
+        } else {
+          slots[rowIndex]![column] = { kind: "covered", origin };
+        }
+      }
+
+      if (cell.verticalMerge === "restart") {
+        // Close out any prior chain starting at this column (stale).
+        activeVMerges.set(columnCursor, origin);
+      } else {
+        // Any non-merge origin breaks prior chains crossing this column.
+        clearChainsBetween(activeVMerges, columnCursor, columnCursor + columnSpan);
+      }
+
+      columnCursor += columnSpan;
+    }
+
+    // Any columns the cells did not cover fall into gridAfter padding. If
+    // the row was too short to reach endColumn, record the trailing gap so
+    // downstream code knows the row is ragged rather than broken.
+    if (columnCursor < endColumn) {
+      warnings.push({
+        kind: "row-span-mismatch",
+        rowIndex,
+        message:
+          `Row cells reached column ${columnCursor}, expected ${endColumn}` +
+          ` (gridBefore=${gridBefore}, gridAfter=${gridAfter})`,
+      });
+      for (let column = columnCursor; column < endColumn; column += 1) {
+        beforeColumns.push(column);
+      }
+    }
+
+    for (let padIndex = 0; padIndex < gridAfter; padIndex += 1) {
+      const column = columnCount - gridAfter + padIndex;
+      if (column >= 0 && column < columnCount) {
+        afterColumns.push(column);
+      }
+    }
+
+    rowPadding.push({ beforeColumns, afterColumns });
+
+    // Prune chains that were not extended by a continue in this row.
+    for (const [column, owner] of activeVMerges) {
+      const slot = slots[rowIndex]![column];
+      if (!slot || slot.kind !== "covered" || slot.origin !== owner) {
+        if (owner.rowIndex !== rowIndex) {
+          // Chain did not continue; drop it so later rows don't match.
+          activeVMerges.delete(column);
+        }
+      }
+    }
+  }
+
+  return {
+    table,
+    rowCount,
+    columnCount,
+    slots,
+    rowPadding,
+    warnings,
+  };
+}
+
+/**
+ * Logical column count across all rows: the widest effective row width,
+ * honoring `gridBefore + Σ(gridSpan) + gridAfter` and `gridColumns` length.
+ */
+export function computeLogicalColumnCount(table: TableNode): number {
+  const fromGrid = table.gridColumns.length;
+  const fromRows = table.rows.reduce((max, row) => {
+    const rowWidth =
+      (row.gridBefore ?? 0) +
+      row.cells.reduce((sum, cell) => sum + Math.max(1, cell.gridSpan ?? 1), 0) +
+      (row.gridAfter ?? 0);
+    return rowWidth > max ? rowWidth : max;
+  }, 0);
+  return Math.max(fromGrid, fromRows);
+}
+
+/**
+ * Look up the slot at a logical position. Returns null when the row or
+ * column is out of bounds.
+ */
+export function slotAt(
+  grid: LogicalGrid,
+  rowIndex: number,
+  columnIndex: number,
+): GridSlot | null {
+  if (rowIndex < 0 || rowIndex >= grid.rowCount) return null;
+  if (columnIndex < 0 || columnIndex >= grid.columnCount) return null;
+  return grid.slots[rowIndex]![columnIndex] ?? null;
+}
+
+/**
+ * Returns the origin slot covering `(rowIndex, columnIndex)`. If the slot
+ * is covered (by hspan or vMerge), follows the pointer back to the origin.
+ */
+export function originAt(
+  grid: LogicalGrid,
+  rowIndex: number,
+  columnIndex: number,
+): GridOriginSlot | null {
+  const slot = slotAt(grid, rowIndex, columnIndex);
+  if (!slot) return null;
+  return slot.kind === "origin" ? slot : slot.origin;
+}
+
+/**
+ * Walk the vertical-merge chain rooted at `(rowIndex, columnIndex)`.
+ * Returns the origin's row indices in order. An un-merged cell yields a
+ * single-element array. A continue cell returns the full chain from its
+ * origin through every covered row.
+ */
+export function collectVMergeChain(
+  grid: LogicalGrid,
+  rowIndex: number,
+  columnIndex: number,
+): number[] {
+  const origin = originAt(grid, rowIndex, columnIndex);
+  if (!origin) return [];
+  const rows: number[] = [];
+  for (let r = origin.rowIndex; r < grid.rowCount; r += 1) {
+    const slot: GridSlot | undefined = grid.slots[r]?.[origin.columnIndex];
+    if (!slot) break;
+    const slotOrigin: GridOriginSlot = slot.kind === "origin" ? slot : slot.origin;
+    if (slotOrigin !== origin) break;
+    rows.push(r);
+  }
+  return rows;
+}
+
+/**
+ * Determine whether a rectangular selection rect contains only whole
+ * spanning regions (no torn spans). Merge-aware commands use this to
+ * decide whether a bulk op can proceed cleanly.
+ */
+export interface RectCoverage {
+  /** Rect is clean: every origin fully inside the rect, no partial covers. */
+  clean: boolean;
+  /** Origins that were only partially covered by the rect. */
+  straddlingOrigins: GridOriginSlot[];
+  /** Origins fully enclosed by the rect. */
+  fullyCoveredOrigins: GridOriginSlot[];
+}
+
+export interface GridRect {
+  /** Inclusive. */
+  top: number;
+  /** Inclusive. */
+  left: number;
+  /** Exclusive (one past the last row). */
+  bottom: number;
+  /** Exclusive (one past the last column). */
+  right: number;
+}
+
+export function analyzeRect(grid: LogicalGrid, rect: GridRect): RectCoverage {
+  const seen = new Set<GridOriginSlot>();
+  const straddling = new Set<GridOriginSlot>();
+  for (let r = rect.top; r < rect.bottom; r += 1) {
+    for (let c = rect.left; c < rect.right; c += 1) {
+      const origin = originAt(grid, r, c);
+      if (!origin) continue;
+      seen.add(origin);
+      const originFitsHorizontally =
+        origin.columnIndex >= rect.left &&
+        origin.columnIndex + origin.columnSpan <= rect.right;
+      const originFitsVertically =
+        origin.rowIndex >= rect.top &&
+        origin.rowIndex + origin.rowSpan <= rect.bottom;
+      if (!originFitsHorizontally || !originFitsVertically) {
+        straddling.add(origin);
+      }
+    }
+  }
+  return {
+    clean: straddling.size === 0,
+    straddlingOrigins: [...straddling],
+    fullyCoveredOrigins: [...seen].filter((origin) => !straddling.has(origin)),
+  };
+}
+
+function findVMergeOwner(
+  activeVMerges: ReadonlyMap<number, GridOriginSlot>,
+  columnCursor: number,
+  columnSpan: number,
+): GridOriginSlot | null {
+  const exact = activeVMerges.get(columnCursor);
+  if (exact && exact.columnSpan === columnSpan) {
+    return exact;
+  }
+  // Fall back to any owner whose origin lies inside the cursor range —
+  // Word tolerates mismatched column spans in a vMerge chain and resolves
+  // to the nearest matching origin.
+  for (const owner of activeVMerges.values()) {
+    if (
+      owner.columnIndex >= columnCursor &&
+      owner.columnIndex < columnCursor + columnSpan
+    ) {
+      return owner;
+    }
+  }
+  return exact ?? null;
+}
+
+function clearChainsBetween(
+  activeVMerges: Map<number, GridOriginSlot>,
+  leftColumn: number,
+  rightColumn: number,
+): void {
+  for (const column of [...activeVMerges.keys()]) {
+    if (column >= leftColumn && column < rightColumn) {
+      activeVMerges.delete(column);
+    }
+  }
+}
+
+// ─── Structural invariants exposed for tests and capability snapshots ─────────
+
+export interface StructuralInvariantReport {
+  ok: boolean;
+  rowWidthMismatches: number[];
+  vMergeDangling: Array<{ rowIndex: number; columnIndex: number }>;
+  zeroColumnSpans: Array<{ rowIndex: number; columnIndex: number }>;
+}
+
+export function evaluateInvariants(grid: LogicalGrid): StructuralInvariantReport {
+  const rowWidthMismatches: number[] = [];
+  const vMergeDangling: StructuralInvariantReport["vMergeDangling"] = [];
+  const zeroColumnSpans: StructuralInvariantReport["zeroColumnSpans"] = [];
+  for (const warning of grid.warnings) {
+    if (warning.kind === "row-span-mismatch") {
+      rowWidthMismatches.push(warning.rowIndex);
+    } else if (warning.kind === "vmerge-continue-without-restart" && warning.columnIndex !== undefined) {
+      vMergeDangling.push({ rowIndex: warning.rowIndex, columnIndex: warning.columnIndex });
+    } else if (warning.kind === "column-span-zero" && warning.columnIndex !== undefined) {
+      zeroColumnSpans.push({ rowIndex: warning.rowIndex, columnIndex: warning.columnIndex });
+    }
+  }
+  return {
+    ok: rowWidthMismatches.length === 0 && vMergeDangling.length === 0 && zeroColumnSpans.length === 0,
+    rowWidthMismatches,
+    vMergeDangling,
+    zeroColumnSpans,
+  };
+}
+
+/**
+ * Helper: find the cell-array index + cell reference for a logical column
+ * in a specific row. Mirrors the `findCellAtColumn` helper previously
+ * embedded in `table-structure-commands.ts` but routes through the grid.
+ */
+export function findCellIndexAtColumn(
+  row: TableRowNode,
+  logicalColumn: number,
+): { cellIndex: number; cell: TableCellNode } | null {
+  let cursor = row.gridBefore ?? 0;
+  for (let cellIndex = 0; cellIndex < row.cells.length; cellIndex += 1) {
+    const cell = row.cells[cellIndex]!;
+    const width = Math.max(1, cell.gridSpan ?? 1);
+    if (logicalColumn >= cursor && logicalColumn < cursor + width) {
+      return { cellIndex, cell };
+    }
+    cursor += width;
+  }
+  return null;
+}