@beyondwork/docx-react-component 1.0.29 → 1.0.31

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

@@ -0,0 +1,854 @@
+import type {
+  RuntimeRenderSnapshot as PublicRuntimeRenderSnapshot,
+  TableOperationCapabilitySnapshot,
+  TableStructureContextSnapshot,
+} from "../../api/public-types";
+import type {
+  DocumentRootNode,
+  ParagraphNode,
+  TableCellNode,
+  TableNode,
+  TableRowNode,
+} from "../../model/canonical-document.ts";
+import type { TableSelectionDescriptor } from "../../runtime/table-commands.ts";
+import type { CanonicalDocumentEnvelope, SelectionSnapshot } from "../state/editor-state.ts";
+import {
+  createDetachedAnchor,
+  createNodeAnchor,
+  createRangeAnchor,
+} from "../selection/mapping.ts";
+import {
+  createEmptyParagraph,
+  createNoopStructuralMutation,
+  findTableCellParagraphSelection,
+  findTopLevelParagraphSelectionNearBlock,
+  type StructuralMutationResult,
+} from "./structural-helpers.ts";
+
+type TableStructureOperation =
+  | { type: "add-row-before" }
+  | { type: "add-row-after" }
+  | { type: "add-column-before" }
+  | { type: "add-column-after" }
+  | { type: "delete-row" }
+  | { type: "delete-column" }
+  | { type: "delete-table" }
+  | { type: "merge-cells" }
+  | { type: "split-cell" }
+  | { type: "set-cell-background"; color: string };
+
+export function applyTableStructureOperation(
+  document: CanonicalDocumentEnvelope,
+  snapshot: PublicRuntimeRenderSnapshot,
+  selectionDescriptor: TableSelectionDescriptor | null,
+  operation: TableStructureOperation,
+): StructuralMutationResult {
+  const root = document.content;
+  const fallbackSelection = toInternalSelectionSnapshot(snapshot.selection);
+  if (!root || root.type !== "doc") {
+    return createNoopStructuralMutation(document, fallbackSelection);
+  }
+
+  const effectiveSelection =
+    selectionDescriptor ?? resolveTableSelectionFromSnapshot(snapshot);
+  if (!effectiveSelection) {
+    return createNoopStructuralMutation(document, fallbackSelection);
+  }
+
+  const target = root.children[effectiveSelection.tableBlockIndex];
+  if (!target || target.type !== "table") {
+    return createNoopStructuralMutation(document, fallbackSelection);
+  }
+
+  switch (operation.type) {
+    case "delete-table":
+      return deleteTableBlock(document, root, effectiveSelection.tableBlockIndex, fallbackSelection);
+    case "set-cell-background":
+      return setCellBackground(document, root, target, effectiveSelection, operation.color, fallbackSelection);
+    case "split-cell":
+      return splitSelectedCell(document, root, target, effectiveSelection, fallbackSelection);
+    case "merge-cells":
+      return mergeSelectedCells(document, root, target, effectiveSelection, fallbackSelection);
+    case "add-row-before":
+      return addRow(document, root, target, effectiveSelection, "before", fallbackSelection);
+    case "add-row-after":
+      return addRow(document, root, target, effectiveSelection, "after", fallbackSelection);
+    case "delete-row":
+      return deleteRow(document, root, target, effectiveSelection, fallbackSelection);
+    case "add-column-before":
+      return addColumn(document, root, target, effectiveSelection, "before", fallbackSelection);
+    case "add-column-after":
+      return addColumn(document, root, target, effectiveSelection, "after", fallbackSelection);
+    case "delete-column":
+      return deleteColumn(document, root, target, effectiveSelection, fallbackSelection);
+    default:
+      return createNoopStructuralMutation(document, fallbackSelection);
+  }
+}
+
+export function getTableStructureContext(
+  document: CanonicalDocumentEnvelope,
+  snapshot: PublicRuntimeRenderSnapshot,
+  selectionDescriptor: TableSelectionDescriptor | null,
+): TableStructureContextSnapshot | null {
+  const root = document.content;
+  if (!root || root.type !== "doc") {
+    return null;
+  }
+
+  const effectiveSelection = selectionDescriptor ?? resolveTableSelectionFromSnapshot(snapshot);
+  if (!effectiveSelection) {
+    return null;
+  }
+
+  const target = root.children[effectiveSelection.tableBlockIndex];
+  if (!target || target.type !== "table") {
+    return null;
+  }
+
+  const row = target.rows[effectiveSelection.anchorCell.rowIndex];
+  const cellRef = row
+    ? findCellAtColumn(row, effectiveSelection.anchorCell.columnIndex)
+    : null;
+  if (!row || !cellRef) {
+    return null;
+  }
+
+  const simpleTable = isSimpleTable(target);
+  const columnCount = getLogicalColumnCount(target);
+  const splitWidth = Math.max(1, cellRef.cell.gridSpan ?? 1);
+  const splitHeight = Math.max(
+    1,
+    computeRowSpan(
+      target,
+      effectiveSelection.anchorCell.rowIndex,
+      effectiveSelection.anchorCell.columnIndex,
+      splitWidth,
+    ),
+  );
+  const selectedCellCount =
+    effectiveSelection.selectionKind === "cell"
+      ? Math.max(
+          1,
+          (effectiveSelection.rect.bottom - effectiveSelection.rect.top) *
+            (effectiveSelection.rect.right - effectiveSelection.rect.left),
+        )
+      : 1;
+
+  return {
+    tableBlockIndex: effectiveSelection.tableBlockIndex,
+    currentStyleId: target.styleId ?? null,
+    selectionKind: effectiveSelection.selectionKind,
+    rowCount: target.rows.length,
+    columnCount,
+    selectedCellCount,
+    isSimpleTable: simpleTable,
+    currentCell: {
+      rowIndex: effectiveSelection.anchorCell.rowIndex,
+      columnIndex: effectiveSelection.anchorCell.columnIndex,
+      isHeader: row.isHeader === true,
+    },
+    operations: {
+      setTableStyle: enabledCapability(),
+      setCellBackground: enabledCapability(),
+      addRowBefore: simpleTable
+        ? enabledCapability()
+        : disabledCapability("Only simple rectangular tables support row insertion right now."),
+      addRowAfter: simpleTable
+        ? enabledCapability()
+        : disabledCapability("Only simple rectangular tables support row insertion right now."),
+      deleteRow:
+        !simpleTable
+          ? disabledCapability("Only simple rectangular tables support row deletion right now.")
+          : target.rows.length <= 1
+            ? disabledCapability("At least two rows are required before a row can be deleted.")
+            : enabledCapability(),
+      addColumnBefore: simpleTable
+        ? enabledCapability()
+        : disabledCapability("Only simple rectangular tables support column insertion right now."),
+      addColumnAfter: simpleTable
+        ? enabledCapability()
+        : disabledCapability("Only simple rectangular tables support column insertion right now."),
+      deleteColumn:
+        !simpleTable
+          ? disabledCapability("Only simple rectangular tables support column deletion right now.")
+          : columnCount <= 1
+            ? disabledCapability("At least two columns are required before a column can be deleted.")
+            : enabledCapability(),
+      mergeCells:
+        !simpleTable
+          ? disabledCapability("Only simple rectangular tables support merging right now.")
+          : effectiveSelection.selectionKind !== "cell" || selectedCellCount <= 1
+            ? disabledCapability("Select more than one cell to merge them.")
+            : enabledCapability(),
+      splitCell:
+        splitWidth === 1 && splitHeight === 1
+          ? disabledCapability("Select a merged or spanning cell to split it.")
+          : enabledCapability(),
+      deleteTable: enabledCapability(),
+    },
+  };
+}
+
+function addRow(
+  document: CanonicalDocumentEnvelope,
+  root: DocumentRootNode,
+  table: TableNode,
+  selection: TableSelectionDescriptor,
+  position: "before" | "after",
+  fallbackSelection: SelectionSnapshot,
+): StructuralMutationResult {
+  if (!isSimpleTable(table)) {
+    return createNoopStructuralMutation(document, fallbackSelection);
+  }
+
+  const columnCount = getLogicalColumnCount(table);
+  const insertIndex =
+    position === "before" ? selection.anchorCell.rowIndex : selection.anchorCell.rowIndex + 1;
+  const nextRow: TableRowNode = {
+    type: "table_row",
+    cells: Array.from({ length: columnCount }, () => createEmptyCell()),
+  };
+  const nextTable: TableNode = {
+    ...table,
+    rows: [
+      ...table.rows.slice(0, insertIndex),
+      nextRow,
+      ...table.rows.slice(insertIndex),
+    ],
+  };
+
+  return commitTableChange(
+    document,
+    root,
+    selection.tableBlockIndex,
+    nextTable,
+    fallbackSelection,
+    insertIndex,
+    selection.anchorCell.columnIndex,
+  );
+}
+
+function deleteRow(
+  document: CanonicalDocumentEnvelope,
+  root: DocumentRootNode,
+  table: TableNode,
+  selection: TableSelectionDescriptor,
+  fallbackSelection: SelectionSnapshot,
+): StructuralMutationResult {
+  if (!isSimpleTable(table) || table.rows.length <= 1) {
+    return createNoopStructuralMutation(document, fallbackSelection);
+  }
+
+  const deleteIndex = selection.anchorCell.rowIndex;
+  const nextRows = table.rows.filter((_, rowIndex) => rowIndex !== deleteIndex);
+  const focusRowIndex = Math.max(0, Math.min(deleteIndex, nextRows.length - 1));
+  const nextTable: TableNode = {
+    ...table,
+    rows: nextRows,
+  };
+
+  return commitTableChange(
+    document,
+    root,
+    selection.tableBlockIndex,
+    nextTable,
+    fallbackSelection,
+    focusRowIndex,
+    selection.anchorCell.columnIndex,
+  );
+}
+
+function addColumn(
+  document: CanonicalDocumentEnvelope,
+  root: DocumentRootNode,
+  table: TableNode,
+  selection: TableSelectionDescriptor,
+  position: "before" | "after",
+  fallbackSelection: SelectionSnapshot,
+): StructuralMutationResult {
+  if (!isSimpleTable(table)) {
+    return createNoopStructuralMutation(document, fallbackSelection);
+  }
+
+  const insertIndex =
+    position === "before"
+      ? selection.anchorCell.columnIndex
+      : selection.anchorCell.columnIndex + 1;
+  const nextTable: TableNode = {
+    ...table,
+    gridColumns: insertGridColumn(table.gridColumns, insertIndex),
+    rows: table.rows.map((row) => ({
+      ...row,
+      cells: [
+        ...row.cells.slice(0, insertIndex),
+        createEmptyCell(),
+        ...row.cells.slice(insertIndex),
+      ],
+    })),
+  };
+
+  return commitTableChange(
+    document,
+    root,
+    selection.tableBlockIndex,
+    nextTable,
+    fallbackSelection,
+    selection.anchorCell.rowIndex,
+    insertIndex,
+  );
+}
+
+function deleteColumn(
+  document: CanonicalDocumentEnvelope,
+  root: DocumentRootNode,
+  table: TableNode,
+  selection: TableSelectionDescriptor,
+  fallbackSelection: SelectionSnapshot,
+): StructuralMutationResult {
+  if (!isSimpleTable(table) || getLogicalColumnCount(table) <= 1) {
+    return createNoopStructuralMutation(document, fallbackSelection);
+  }
+
+  const deleteIndex = selection.anchorCell.columnIndex;
+  const nextTable: TableNode = {
+    ...table,
+    gridColumns: deleteGridColumn(table.gridColumns, deleteIndex),
+    rows: table.rows.map((row) => ({
+      ...row,
+      cells: row.cells.filter((_, cellIndex) => cellIndex !== deleteIndex),
+    })),
+  };
+  const focusColumnIndex = Math.max(0, Math.min(deleteIndex, getLogicalColumnCount(nextTable) - 1));
+
+  return commitTableChange(
+    document,
+    root,
+    selection.tableBlockIndex,
+    nextTable,
+    fallbackSelection,
+    selection.anchorCell.rowIndex,
+    focusColumnIndex,
+  );
+}
+
+function mergeSelectedCells(
+  document: CanonicalDocumentEnvelope,
+  root: DocumentRootNode,
+  table: TableNode,
+  selection: TableSelectionDescriptor,
+  fallbackSelection: SelectionSnapshot,
+): StructuralMutationResult {
+  if (
+    !isSimpleTable(table) ||
+    selection.selectionKind !== "cell" ||
+    selection.rect.bottom - selection.rect.top < 1 ||
+    selection.rect.right - selection.rect.left < 1
+  ) {
+    return createNoopStructuralMutation(document, fallbackSelection);
+  }
+
+  const height = selection.rect.bottom - selection.rect.top;
+  const width = selection.rect.right - selection.rect.left;
+  if (height === 1 && width === 1) {
+    return createNoopStructuralMutation(document, fallbackSelection);
+  }
+
+  const nextRows = table.rows.map((row) => ({
+    ...row,
+    cells: row.cells.map((cell) => cloneCell(cell)),
+  }));
+  const mergedChildren: ParagraphNode[] = [];
+
+  for (let rowIndex = selection.rect.top; rowIndex < selection.rect.bottom; rowIndex += 1) {
+    const row = nextRows[rowIndex];
+    if (!row) {
+      return createNoopStructuralMutation(document, fallbackSelection);
+    }
+
+    for (let columnIndex = selection.rect.left; columnIndex < selection.rect.right; columnIndex += 1) {
+      const cellRef = findCellAtColumn(row, columnIndex);
+      if (!cellRef) {
+        return createNoopStructuralMutation(document, fallbackSelection);
+      }
+
+      const paragraphs = cellRef.cell.children.filter(
+        (child): child is ParagraphNode => child.type === "paragraph",
+      );
+      mergedChildren.push(...paragraphs.map((paragraph) => structuredClone(paragraph) as ParagraphNode));
+    }
+  }
+
+  const topRow = nextRows[selection.rect.top];
+  if (!topRow) {
+    return createNoopStructuralMutation(document, fallbackSelection);
+  }
+  const topLeftRef = findCellAtColumn(topRow, selection.rect.left);
+  if (!topLeftRef) {
+    return createNoopStructuralMutation(document, fallbackSelection);
+  }
+
+  topRow.cells[topLeftRef.cellIndex] = {
+    ...topLeftRef.cell,
+    ...(width > 1 ? { gridSpan: width } : {}),
+    ...(height > 1 ? { verticalMerge: "restart" as const } : {}),
+    children: mergedChildren.length > 0 ? mergedChildren : [createEmptyParagraph()],
+  };
+  topRow.cells.splice(topLeftRef.cellIndex + 1, width - 1);
+
+  for (let rowIndex = selection.rect.top + 1; rowIndex < selection.rect.bottom; rowIndex += 1) {
+    const row = nextRows[rowIndex];
+    const leftRef = findCellAtColumn(row, selection.rect.left);
+    if (!leftRef) {
+      return createNoopStructuralMutation(document, fallbackSelection);
+    }
+
+    row.cells.splice(
+      leftRef.cellIndex,
+      width,
+      {
+        ...createEmptyCell(),
+        ...(width > 1 ? { gridSpan: width } : {}),
+        verticalMerge: "continue",
+      },
+    );
+  }
+
+  const nextTable: TableNode = {
+    ...table,
+    rows: nextRows,
+  };
+  return commitTableChange(
+    document,
+    root,
+    selection.tableBlockIndex,
+    nextTable,
+    fallbackSelection,
+    selection.rect.top,
+    selection.rect.left,
+  );
+}
+
+function splitSelectedCell(
+  document: CanonicalDocumentEnvelope,
+  root: DocumentRootNode,
+  table: TableNode,
+  selection: TableSelectionDescriptor,
+  fallbackSelection: SelectionSnapshot,
+): StructuralMutationResult {
+  const row = table.rows[selection.anchorCell.rowIndex];
+  if (!row) {
+    return createNoopStructuralMutation(document, fallbackSelection);
+  }
+  const cellRef = findCellAtColumn(row, selection.anchorCell.columnIndex);
+  if (!cellRef) {
+    return createNoopStructuralMutation(document, fallbackSelection);
+  }
+
+  const width = Math.max(1, cellRef.cell.gridSpan ?? 1);
+  const height = Math.max(
+    1,
+    computeRowSpan(table, selection.anchorCell.rowIndex, selection.anchorCell.columnIndex, width),
+  );
+  if (width === 1 && height === 1) {
+    return createNoopStructuralMutation(document, fallbackSelection);
+  }
+
+  const nextRows = table.rows.map((currentRow) => ({
+    ...currentRow,
+    cells: currentRow.cells.map((cell) => cloneCell(cell)),
+  }));
+  const topRow = nextRows[selection.anchorCell.rowIndex];
+  topRow.cells.splice(
+    cellRef.cellIndex,
+    1,
+    stripCellSpan(cellRef.cell),
+    ...Array.from({ length: width - 1 }, () => createEmptyCell()),
+  );
+
+  for (let rowOffset = 1; rowOffset < height; rowOffset += 1) {
+    const rowIndex = selection.anchorCell.rowIndex + rowOffset;
+    const currentRow = nextRows[rowIndex];
+    if (!currentRow) {
+      break;
+    }
+
+    const continueRef = findCellAtColumn(currentRow, selection.anchorCell.columnIndex);
+    if (!continueRef) {
+      return createNoopStructuralMutation(document, fallbackSelection);
+    }
+
+    currentRow.cells.splice(
+      continueRef.cellIndex,
+      1,
+      ...Array.from({ length: width }, () => createEmptyCell()),
+    );
+  }
+
+  const nextTable: TableNode = {
+    ...table,
+    rows: nextRows,
+  };
+  return commitTableChange(
+    document,
+    root,
+    selection.tableBlockIndex,
+    nextTable,
+    fallbackSelection,
+    selection.anchorCell.rowIndex,
+    selection.anchorCell.columnIndex,
+  );
+}
+
+function setCellBackground(
+  document: CanonicalDocumentEnvelope,
+  root: DocumentRootNode,
+  table: TableNode,
+  selection: TableSelectionDescriptor,
+  color: string,
+  fallbackSelection: SelectionSnapshot,
+): StructuralMutationResult {
+  const normalized = normalizeFillColor(color);
+  if (!normalized) {
+    return createNoopStructuralMutation(document, fallbackSelection);
+  }
+
+  const activeRow = table.rows[selection.anchorCell.rowIndex];
+  const activeCellRef = activeRow
+    ? findCellAtColumn(activeRow, selection.anchorCell.columnIndex)
+    : null;
+  const activeCellWidth = Math.max(1, activeCellRef?.cell.gridSpan ?? 1);
+  const activeCellHeight = Math.max(
+    1,
+    computeRowSpan(
+      table,
+      selection.anchorCell.rowIndex,
+      selection.anchorCell.columnIndex,
+      activeCellWidth,
+    ),
+  );
+  const targetRect =
+    selection.selectionKind === "text"
+      ? {
+          top: selection.anchorCell.rowIndex,
+          left: selection.anchorCell.columnIndex,
+          bottom: selection.anchorCell.rowIndex + activeCellHeight,
+          right: selection.anchorCell.columnIndex + activeCellWidth,
+        }
+      : selection.rect;
+  let changed = false;
+  const nextRows = table.rows.map((row, rowIndex) => {
+    if (rowIndex < targetRect.top || rowIndex >= targetRect.bottom) {
+      return row;
+    }
+
+    let cursor = 0;
+    const cells = row.cells.map((cell) => {
+      const start = cursor;
+      const width = cell.gridSpan ?? 1;
+      const end = start + width;
+      cursor = end;
+
+      if (end <= targetRect.left || start >= targetRect.right) {
+        return cell;
+      }
+
+      changed = true;
+      return {
+        ...cell,
+        shading: {
+          ...(cell.shading ?? {}),
+          fill: normalized,
+        },
+      };
+    });
+
+    return {
+      ...row,
+      cells,
+    };
+  });
+
+  if (!changed) {
+    return createNoopStructuralMutation(document, fallbackSelection);
+  }
+
+  const nextTable: TableNode = {
+    ...table,
+    rows: nextRows,
+  };
+  return commitTableChange(
+    document,
+    root,
+    selection.tableBlockIndex,
+    nextTable,
+    fallbackSelection,
+    selection.anchorCell.rowIndex,
+    selection.anchorCell.columnIndex,
+  );
+}
+
+function deleteTableBlock(
+  document: CanonicalDocumentEnvelope,
+  root: DocumentRootNode,
+  tableBlockIndex: number,
+  fallbackSelection: SelectionSnapshot,
+): StructuralMutationResult {
+  const nextChildren = root.children.filter((_, index) => index !== tableBlockIndex);
+  if (nextChildren.length === 0) {
+    nextChildren.push(createEmptyParagraph());
+  }
+
+  const nextDocument: CanonicalDocumentEnvelope = {
+    ...document,
+    content: {
+      ...root,
+      children: nextChildren,
+    },
+  };
+  const nextSelection =
+    findTopLevelParagraphSelectionNearBlock(nextDocument, tableBlockIndex) ??
+    fallbackSelection;
+
+  return {
+    changed: true,
+    document: nextDocument,
+    selection: nextSelection,
+  };
+}
+
+function commitTableChange(
+  document: CanonicalDocumentEnvelope,
+  root: DocumentRootNode,
+  tableBlockIndex: number,
+  nextTable: TableNode,
+  fallbackSelection: SelectionSnapshot,
+  focusRowIndex: number,
+  focusColumnIndex: number,
+): StructuralMutationResult {
+  const nextDocument: CanonicalDocumentEnvelope = {
+    ...document,
+    content: {
+      ...root,
+      children: root.children.map((child, index) =>
+        index === tableBlockIndex ? nextTable : child,
+      ),
+    },
+  };
+  const nextSelection =
+    findTableCellParagraphSelection(
+      nextDocument,
+      tableBlockIndex,
+      focusRowIndex,
+      focusColumnIndex,
+    ) ?? fallbackSelection;
+
+  return {
+    changed: true,
+    document: nextDocument,
+    selection: nextSelection,
+  };
+}
+
+function resolveTableSelectionFromSnapshot(
+  snapshot: Pick<PublicRuntimeRenderSnapshot, "selection" | "surface">,
+): TableSelectionDescriptor | null {
+  const selectionFrom = Math.min(snapshot.selection.anchor, snapshot.selection.head);
+  const selectionTo = Math.max(snapshot.selection.anchor, snapshot.selection.head);
+  const surface = snapshot.surface;
+  if (!surface) {
+    return null;
+  }
+
+  for (let tableBlockIndex = 0; tableBlockIndex < surface.blocks.length; tableBlockIndex += 1) {
+    const block = surface.blocks[tableBlockIndex];
+    if (block.kind !== "table") {
+      continue;
+    }
+
+    for (let rowIndex = 0; rowIndex < block.rows.length; rowIndex += 1) {
+      const row = block.rows[rowIndex];
+      for (let cellIndex = 0; cellIndex < row.cells.length; cellIndex += 1) {
+        const cell = row.cells[cellIndex];
+        const hit = cell.content.find(
+          (child) =>
+            child.kind === "paragraph" &&
+            selectionFrom >= child.from &&
+            selectionTo <= child.to,
+        );
+        if (!hit) {
+          continue;
+        }
+
+        let logicalColumn = 0;
+        for (let currentIndex = 0; currentIndex < cellIndex; currentIndex += 1) {
+          logicalColumn += row.cells[currentIndex]?.gridSpan ?? 1;
+        }
+
+        return {
+          tableBlockIndex,
+          selectionKind: "text",
+          anchorCell: {
+            rowIndex,
+            columnIndex: logicalColumn,
+          },
+          headCell: {
+            rowIndex,
+            columnIndex: logicalColumn,
+          },
+          rect: {
+            top: rowIndex,
+            left: logicalColumn,
+            bottom: rowIndex + 1,
+            right: logicalColumn + (cell.gridSpan ?? 1),
+          },
+        };
+      }
+    }
+  }
+
+  return null;
+}
+
+function toInternalSelectionSnapshot(
+  selection: PublicRuntimeRenderSnapshot["selection"],
+): SelectionSnapshot {
+  return {
+    anchor: selection.anchor,
+    head: selection.head,
+    isCollapsed: selection.isCollapsed,
+    activeRange:
+      selection.activeRange.kind === "range"
+        ? createRangeAnchor(
+            selection.activeRange.from,
+            selection.activeRange.to,
+            selection.activeRange.assoc,
+          )
+        : selection.activeRange.kind === "node"
+          ? createNodeAnchor(selection.activeRange.at, selection.activeRange.assoc)
+          : createDetachedAnchor(
+              selection.activeRange.lastKnownRange,
+              selection.activeRange.reason,
+            ),
+  };
+}
+
+function enabledCapability(): TableOperationCapabilitySnapshot {
+  return { enabled: true };
+}
+
+function disabledCapability(reason: string): TableOperationCapabilitySnapshot {
+  return {
+    enabled: false,
+    reason,
+  };
+}
+
+function isSimpleTable(table: TableNode): boolean {
+  const width = getLogicalColumnCount(table);
+  return table.rows.every((row) => {
+    let rowWidth = 0;
+    for (const cell of row.cells) {
+      if ((cell.gridSpan ?? 1) !== 1 || cell.verticalMerge) {
+        return false;
+      }
+      rowWidth += 1;
+    }
+    return rowWidth === width;
+  });
+}
+
+function getLogicalColumnCount(table: TableNode): number {
+  if (table.gridColumns.length > 0) {
+    return table.gridColumns.length;
+  }
+
+  return table.rows.reduce((max, row) => {
+    const width = row.cells.reduce((sum, cell) => sum + (cell.gridSpan ?? 1), 0);
+    return Math.max(max, width);
+  }, 0);
+}
+
+function computeRowSpan(
+  table: TableNode,
+  rowIndex: number,
+  columnIndex: number,
+  width: number,
+): number {
+  let rowspan = 1;
+
+  for (let currentRowIndex = rowIndex + 1; currentRowIndex < table.rows.length; currentRowIndex += 1) {
+    const cellRef = findCellAtColumn(table.rows[currentRowIndex], columnIndex);
+    if (
+      !cellRef ||
+      cellRef.cell.verticalMerge !== "continue" ||
+      (cellRef.cell.gridSpan ?? 1) !== width
+    ) {
+      break;
+    }
+    rowspan += 1;
+  }
+
+  return rowspan;
+}
+
+function findCellAtColumn(
+  row: TableRowNode,
+  logicalColumnIndex: number,
+): { cellIndex: number; cell: TableCellNode } | null {
+  let cursor = 0;
+
+  for (let cellIndex = 0; cellIndex < row.cells.length; cellIndex += 1) {
+    const cell = row.cells[cellIndex];
+    const width = cell.gridSpan ?? 1;
+    if (logicalColumnIndex >= cursor && logicalColumnIndex < cursor + width) {
+      return {
+        cellIndex,
+        cell,
+      };
+    }
+    cursor += width;
+  }
+
+  return null;
+}
+
+function createEmptyCell(): TableCellNode {
+  return {
+    type: "table_cell",
+    children: [createEmptyParagraph()],
+  };
+}
+
+function cloneCell(cell: TableCellNode): TableCellNode {
+  return structuredClone(cell) as TableCellNode;
+}
+
+function stripCellSpan(cell: TableCellNode): TableCellNode {
+  return {
+    ...cell,
+    gridSpan: undefined,
+    verticalMerge: undefined,
+  };
+}
+
+function insertGridColumn(columns: number[], index: number): number[] {
+  if (columns.length === 0) {
+    return columns;
+  }
+
+  const current = columns[index] ?? columns[index - 1] ?? columns[columns.length - 1] ?? 2400;
+  return [...columns.slice(0, index), current, ...columns.slice(index)];
+}
+
+function deleteGridColumn(columns: number[], index: number): number[] {
+  if (columns.length <= 1) {
+    return columns;
+  }
+  return columns.filter((_, columnIndex) => columnIndex !== index);
+}
+
+function normalizeFillColor(color: string): string | null {
+  const normalized = color.trim().replace(/^#/, "");
+  return /^[0-9A-Fa-f]{3,8}$/.test(normalized) ? normalized.toUpperCase() : null;
+}