@beyondwork/docx-react-component 1.0.37 → 1.0.39

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

@@ -6,9 +6,15 @@ import type {
 import type {
   DocumentRootNode,
   ParagraphNode,
+  TableBorders,
+  TableCellBorders,
+  TableCellMargins,
   TableCellNode,
+  TableIndent,
   TableNode,
   TableRowNode,
+  TableWidth,
+  CellShading,
 } from "../../model/canonical-document.ts";
 import type { TableSelectionDescriptor } from "../../runtime/table-commands.ts";
 import type { CanonicalDocumentEnvelope, SelectionSnapshot } from "../state/editor-state.ts";
@@ -24,8 +30,26 @@ import {
   findTopLevelParagraphSelectionNearBlock,
   type StructuralMutationResult,
 } from "./structural-helpers.ts";
-
-type TableStructureOperation =
+import {
+  analyzeRect,
+  buildLogicalGrid,
+  computeLogicalColumnCount as computeLogicalColumnCountFromGrid,
+  findCellIndexAtColumn,
+  originAt,
+  slotAt,
+  type GridOriginSlot,
+  type LogicalGrid,
+} from "./table-grid.ts";
+
+export type CellLocator =
+  | { kind: "anchor" }
+  | { kind: "index"; rowIndex: number; columnIndex: number }
+  | { kind: "rect"; rect: { top: number; left: number; bottom: number; right: number } }
+  | { kind: "row"; rowIndex: number }
+  | { kind: "column"; columnIndex: number }
+  | { kind: "selection" };
+
+export type TableStructureOperation =
   | { type: "add-row-before" }
   | { type: "add-row-after" }
   | { type: "add-column-before" }
@@ -35,7 +59,35 @@ type TableStructureOperation =
   | { type: "delete-table" }
   | { type: "merge-cells" }
   | { type: "split-cell" }
-  | { type: "set-cell-background"; color: string };
+  | { type: "set-cell-background"; color: string }
+  // P2g — table-level
+  | { type: "set-table-width"; width: TableWidth }
+  | { type: "set-table-alignment"; alignment: "left" | "center" | "right" }
+  | { type: "set-table-indent"; indent: TableIndent }
+  | { type: "set-table-layout-mode"; mode: "fixed" | "autofit" }
+  | { type: "set-table-cell-margins"; margins: Partial<TableCellMargins> }
+  | { type: "set-table-borders"; borders: Partial<TableBorders> }
+  | { type: "set-table-style"; styleId: string | null }
+  | { type: "set-table-caption"; caption: string | null }
+  | { type: "set-table-description"; description: string | null }
+  // P2h — column / row sizing + row props
+  | { type: "set-column-width"; columnIndex: number; twips: number }
+  | { type: "distribute-columns-evenly"; columnRange?: { from: number; to: number } }
+  | { type: "set-row-height"; rowIndex: number; twips: number; rule: "auto" | "atLeast" | "exact" }
+  | { type: "set-row-cant-split"; rowIndex: number; value: boolean }
+  | { type: "set-row-is-header"; rowIndex: number; value: boolean }
+  | { type: "set-row-alignment"; rowIndex: number; alignment: "left" | "center" | "right" }
+  | { type: "insert-rows"; rowIndex: number; at: "before" | "after"; count: number }
+  | { type: "insert-columns"; columnIndex: number; at: "before" | "after"; count: number; widths?: readonly number[] }
+  // P2i — cell-level
+  | { type: "set-cell-borders"; locator: CellLocator; borders: Partial<TableCellBorders> }
+  | { type: "set-cell-shading"; locator: CellLocator; shading: Partial<CellShading> | null }
+  | { type: "clear-cell-shading"; locator: CellLocator }
+  | { type: "set-cell-margins"; locator: CellLocator; margins: Partial<TableCellMargins> }
+  | { type: "set-cell-vertical-align"; locator: CellLocator; align: "top" | "center" | "bottom" }
+  | { type: "set-cell-text-direction"; locator: CellLocator; direction: "lrTb" | "tbRl" | "btLr" }
+  | { type: "set-cell-no-wrap"; locator: CellLocator; value: boolean }
+  | { type: "set-cell-fit-text"; locator: CellLocator; value: boolean };
 
 export function applyTableStructureOperation(
   document: CanonicalDocumentEnvelope,
@@ -81,6 +133,127 @@ export function applyTableStructureOperation(
       return addColumn(document, root, target, effectiveSelection, "after", fallbackSelection);
     case "delete-column":
       return deleteColumn(document, root, target, effectiveSelection, fallbackSelection);
+    case "set-table-width":
+      return patchTable(document, root, target, effectiveSelection, { width: operation.width }, fallbackSelection);
+    case "set-table-alignment":
+      return patchTable(document, root, target, effectiveSelection, { alignment: operation.alignment }, fallbackSelection);
+    case "set-table-indent":
+      return patchTable(document, root, target, effectiveSelection, { indent: operation.indent }, fallbackSelection);
+    case "set-table-layout-mode":
+      return patchTable(document, root, target, effectiveSelection, { layoutMode: operation.mode }, fallbackSelection);
+    case "set-table-cell-margins":
+      return patchTable(
+        document,
+        root,
+        target,
+        effectiveSelection,
+        { cellMargins: mergeTableCellMargins(target.cellMargins, operation.margins) },
+        fallbackSelection,
+      );
+    case "set-table-borders":
+      return patchTable(
+        document,
+        root,
+        target,
+        effectiveSelection,
+        { borders: mergeTableBorders(target.borders, operation.borders) },
+        fallbackSelection,
+      );
+    case "set-table-style":
+      return patchTable(
+        document,
+        root,
+        target,
+        effectiveSelection,
+        { styleId: operation.styleId ?? undefined },
+        fallbackSelection,
+      );
+    case "set-table-caption":
+      return patchTable(
+        document,
+        root,
+        target,
+        effectiveSelection,
+        { caption: operation.caption ?? undefined },
+        fallbackSelection,
+      );
+    case "set-table-description":
+      return patchTable(
+        document,
+        root,
+        target,
+        effectiveSelection,
+        { description: operation.description ?? undefined },
+        fallbackSelection,
+      );
+    case "set-column-width":
+      return setColumnWidth(document, root, target, effectiveSelection, operation.columnIndex, operation.twips, fallbackSelection);
+    case "distribute-columns-evenly":
+      return distributeColumnsEvenly(document, root, target, effectiveSelection, operation.columnRange, fallbackSelection);
+    case "set-row-height":
+      return patchRow(document, root, target, effectiveSelection, operation.rowIndex, {
+        height: operation.twips,
+        heightRule: operation.rule,
+      }, fallbackSelection);
+    case "set-row-cant-split":
+      return patchRow(document, root, target, effectiveSelection, operation.rowIndex, {
+        cantSplit: operation.value,
+      }, fallbackSelection);
+    case "set-row-is-header":
+      return patchRow(document, root, target, effectiveSelection, operation.rowIndex, {
+        isHeader: operation.value,
+      }, fallbackSelection);
+    case "set-row-alignment":
+      return patchRow(document, root, target, effectiveSelection, operation.rowIndex, {
+        horizontalAlignment: operation.alignment,
+      }, fallbackSelection);
+    case "insert-rows":
+      return insertRows(document, root, target, effectiveSelection, operation.rowIndex, operation.at, operation.count, fallbackSelection);
+    case "insert-columns":
+      return insertColumns(document, root, target, effectiveSelection, operation.columnIndex, operation.at, operation.count, operation.widths, fallbackSelection);
+    case "set-cell-borders":
+      return patchCells(document, root, target, effectiveSelection, operation.locator, (cell) => ({
+        ...cell,
+        borders: mergeCellBorders(cell.borders, operation.borders),
+      }), fallbackSelection);
+    case "set-cell-shading":
+      return patchCells(document, root, target, effectiveSelection, operation.locator, (cell) => {
+        if (operation.shading === null) {
+          const { shading: _drop, ...rest } = cell;
+          return rest as TableCellNode;
+        }
+        return { ...cell, shading: { ...(cell.shading ?? {}), ...operation.shading } };
+      }, fallbackSelection);
+    case "clear-cell-shading":
+      return patchCells(document, root, target, effectiveSelection, operation.locator, (cell) => {
+        const { shading: _drop, ...rest } = cell;
+        return rest as TableCellNode;
+      }, fallbackSelection);
+    case "set-cell-margins":
+      return patchCells(document, root, target, effectiveSelection, operation.locator, (cell) => ({
+        ...cell,
+        margins: { ...(cell.margins ?? {}), ...operation.margins },
+      }), fallbackSelection);
+    case "set-cell-vertical-align":
+      return patchCells(document, root, target, effectiveSelection, operation.locator, (cell) => ({
+        ...cell,
+        verticalAlign: operation.align,
+      }), fallbackSelection);
+    case "set-cell-text-direction":
+      return patchCells(document, root, target, effectiveSelection, operation.locator, (cell) => ({
+        ...cell,
+        textDirection: operation.direction,
+      }), fallbackSelection);
+    case "set-cell-no-wrap":
+      return patchCells(document, root, target, effectiveSelection, operation.locator, (cell) => ({
+        ...cell,
+        noWrap: operation.value,
+      }), fallbackSelection);
+    case "set-cell-fit-text":
+      return patchCells(document, root, target, effectiveSelection, operation.locator, (cell) => ({
+        ...cell,
+        fitText: operation.value,
+      }), fallbackSelection);
     default:
       return createNoopStructuralMutation(document, fallbackSelection);
   }
@@ -135,6 +308,19 @@ export function getTableStructureContext(
         )
       : 1;
 
+  // Build the logical grid once so merge-aware capability checks share the
+  // same traversal as the commands they gate.
+  const grid = buildLogicalGrid(target);
+  const mergeRectCoverage =
+    effectiveSelection.selectionKind === "cell" && selectedCellCount > 1
+      ? analyzeRect(grid, {
+          top: effectiveSelection.rect.top,
+          left: effectiveSelection.rect.left,
+          bottom: effectiveSelection.rect.bottom,
+          right: effectiveSelection.rect.right,
+        })
+      : null;
+
   return {
     tableBlockIndex: effectiveSelection.tableBlockIndex,
     currentStyleId: target.styleId ?? null,
@@ -151,41 +337,73 @@ export function getTableStructureContext(
     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."),
+      addRowBefore: enabledCapability(),
+      addRowAfter: enabledCapability(),
       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."),
+        target.rows.length <= 1
+          ? disabledCapability("At least two rows are required before a row can be deleted.")
+          : enabledCapability(),
+      addColumnBefore: enabledCapability(),
+      addColumnAfter: enabledCapability(),
       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(),
+        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
+        effectiveSelection.selectionKind !== "cell"
+          ? disabledCapability("Select more than one cell to merge them.")
+          : selectedCellCount <= 1
             ? disabledCapability("Select more than one cell to merge them.")
-            : enabledCapability(),
+            : mergeRectCoverage && !mergeRectCoverage.clean
+              ? disabledCapability(
+                  "Selection cuts through a merged cell. Extend the selection to fully enclose the span.",
+                )
+              : mergeRectCoverage &&
+                  mergeRectCoverage.fullyCoveredOrigins.some(
+                    (origin) => origin.columnSpan > 1 || origin.rowSpan > 1,
+                  )
+                ? disabledCapability(
+                    "Selection encloses an already-merged cell. Split it first, then merge.",
+                  )
+                : enabledCapability(),
       splitCell:
         splitWidth === 1 && splitHeight === 1
           ? disabledCapability("Select a merged or spanning cell to split it.")
           : enabledCapability(),
       deleteTable: enabledCapability(),
+      // P2g — table-level
+      setTableWidth: enabledCapability(),
+      setTableAlignment: enabledCapability(),
+      setTableIndent: enabledCapability(),
+      setTableLayoutMode: enabledCapability(),
+      setTableCellMargins: enabledCapability(),
+      setTableBorders: enabledCapability(),
+      setTableCaption: enabledCapability(),
+      setTableDescription: enabledCapability(),
+      // P2h — column/row sizing + row props
+      setColumnWidth:
+        target.gridColumns.length > 0
+          ? enabledCapability()
+          : disabledCapability("Table has no grid columns to size."),
+      distributeColumnsEvenly:
+        target.gridColumns.length > 1
+          ? enabledCapability()
+          : disabledCapability("At least two columns are required to distribute width."),
+      setRowHeight: enabledCapability(),
+      setRowCantSplit: enabledCapability(),
+      setRowIsHeader: enabledCapability(),
+      setRowAlignment: enabledCapability(),
+      insertRows: enabledCapability(),
+      insertColumns: enabledCapability(),
+      // P2i — cell-level
+      setCellBorders: enabledCapability(),
+      setCellShading: enabledCapability(),
+      clearCellShading: enabledCapability(),
+      setCellMargins: enabledCapability(),
+      setCellVerticalAlign: enabledCapability(),
+      setCellTextDirection: enabledCapability(),
+      setCellNoWrap: enabledCapability(),
+      setCellFitText: enabledCapability(),
     },
   };
 }
@@ -198,17 +416,15 @@ function addRow(
   position: "before" | "after",
   fallbackSelection: SelectionSnapshot,
 ): StructuralMutationResult {
-  if (!isSimpleTable(table)) {
+  const grid = buildLogicalGrid(table);
+  const columnCount = grid.columnCount;
+  if (columnCount === 0) {
     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 nextRow = buildInsertedRow(grid, insertIndex);
   const nextTable: TableNode = {
     ...table,
     rows: [
@@ -229,6 +445,58 @@ function addRow(
   );
 }
 
+/**
+ * Build the cells for a new row inserted at `insertIndex` (index in the
+ * original table, before the insertion is applied). For each logical column,
+ * if both the row above and the row below belong to the same vMerge chain,
+ * the new row extends that chain with a `verticalMerge: "continue"` cell.
+ * Otherwise an empty cell is emitted with gridSpan=1.
+ */
+function buildInsertedRow(grid: LogicalGrid, insertIndex: number): TableRowNode {
+  const cells: TableCellNode[] = [];
+  const columnCount = grid.columnCount;
+  let column = 0;
+  while (column < columnCount) {
+    const above = insertIndex > 0 ? originAt(grid, insertIndex - 1, column) : null;
+    const below =
+      insertIndex < grid.rowCount ? originAt(grid, insertIndex, column) : null;
+
+    // A vMerge chain continues across the insertion point when:
+    //  - both above and below resolve to the same origin, and
+    //  - that origin lives above the insertion point (otherwise the chain
+    //    starts at `below` and is fully below the insertion point).
+    if (
+      above &&
+      below &&
+      above === below &&
+      above.rowIndex < insertIndex
+    ) {
+      const span = above.columnSpan;
+      // Align to the origin's leftmost column: if we started iteration
+      // mid-span, still treat the full span as the unit.
+      if (column !== above.columnIndex) {
+        // We're scanning forward, so this shouldn't happen — if it does,
+        // fall through to an empty cell for this column only.
+        cells.push(createEmptyCell());
+        column += 1;
+        continue;
+      }
+      cells.push({
+        type: "table_cell",
+        children: [createEmptyParagraph()],
+        verticalMerge: "continue",
+        ...(span > 1 ? { gridSpan: span } : {}),
+      });
+      column += span;
+      continue;
+    }
+
+    cells.push(createEmptyCell());
+    column += 1;
+  }
+  return { type: "table_row", cells };
+}
+
 function deleteRow(
   document: CanonicalDocumentEnvelope,
   root: DocumentRootNode,
@@ -236,12 +504,52 @@ function deleteRow(
   selection: TableSelectionDescriptor,
   fallbackSelection: SelectionSnapshot,
 ): StructuralMutationResult {
-  if (!isSimpleTable(table) || table.rows.length <= 1) {
+  if (table.rows.length <= 1) {
     return createNoopStructuralMutation(document, fallbackSelection);
   }
 
   const deleteIndex = selection.anchorCell.rowIndex;
-  const nextRows = table.rows.filter((_, rowIndex) => rowIndex !== deleteIndex);
+  const grid = buildLogicalGrid(table);
+
+  // For every logical column, check if this row is the origin of a vMerge
+  // chain that extends beyond this row. If so, we must promote the first
+  // following continue cell to "restart" and copy over the origin's
+  // content/properties so the chain survives the deletion.
+  //
+  // For columns where this row is a mid-chain continue, the chain's owner
+  // origin stays in place — we just need to drop 1 from its effective
+  // rowSpan (which happens automatically when the row is removed from
+  // the canonical tree).
+  const promotions: Array<{
+    originColumnIndex: number;
+    originColumnSpan: number;
+    promotedRowIndex: number;
+    originCell: TableCellNode;
+  }> = [];
+
+  for (let column = 0; column < grid.columnCount; ) {
+    const origin = originAt(grid, deleteIndex, column);
+    if (!origin) {
+      column += 1;
+      continue;
+    }
+    if (origin.rowIndex === deleteIndex && origin.rowSpan > 1) {
+      promotions.push({
+        originColumnIndex: origin.columnIndex,
+        originColumnSpan: origin.columnSpan,
+        promotedRowIndex: deleteIndex + 1,
+        originCell: origin.cell,
+      });
+    }
+    column = origin.columnIndex + origin.columnSpan;
+  }
+
+  // Apply promotions to the row immediately after the deleted one.
+  const nextRows = table.rows.map((row, rowIndex) => {
+    if (rowIndex !== deleteIndex + 1 || promotions.length === 0) return row;
+    return applyVMergePromotions(row, promotions);
+  }).filter((_, rowIndex) => rowIndex !== deleteIndex);
+
   const focusRowIndex = Math.max(0, Math.min(deleteIndex, nextRows.length - 1));
   const nextTable: TableNode = {
     ...table,
@@ -259,6 +567,43 @@ function deleteRow(
   );
 }
 
+function applyVMergePromotions(
+  row: TableRowNode,
+  promotions: Array<{
+    originColumnIndex: number;
+    originColumnSpan: number;
+    promotedRowIndex: number;
+    originCell: TableCellNode;
+  }>,
+): TableRowNode {
+  const nextCells = row.cells.map((cell, cellIndex) => {
+    let cursor = row.gridBefore ?? 0;
+    // Recompute the cell's logical column position.
+    for (let i = 0; i < cellIndex; i += 1) {
+      cursor += Math.max(1, row.cells[i]!.gridSpan ?? 1);
+    }
+    const logicalColumn = cursor;
+
+    const promotion = promotions.find(
+      (p) =>
+        p.originColumnIndex === logicalColumn &&
+        (cell.gridSpan ?? 1) === p.originColumnSpan &&
+        cell.verticalMerge === "continue",
+    );
+    if (!promotion) return cell;
+
+    // Promote: copy origin's cell content + properties, mark as restart.
+    const { children, ...properties } = promotion.originCell;
+    return {
+      ...properties,
+      children: structuredClone(children),
+      verticalMerge: "restart" as const,
+      ...(promotion.originColumnSpan > 1 ? { gridSpan: promotion.originColumnSpan } : {}),
+    };
+  });
+  return { ...row, cells: nextCells };
+}
+
 function addColumn(
   document: CanonicalDocumentEnvelope,
   root: DocumentRootNode,
@@ -267,25 +612,90 @@ function addColumn(
   position: "before" | "after",
   fallbackSelection: SelectionSnapshot,
 ): StructuralMutationResult {
-  if (!isSimpleTable(table)) {
+  const grid = buildLogicalGrid(table);
+  const columnCount = grid.columnCount;
+  if (columnCount === 0) {
     return createNoopStructuralMutation(document, fallbackSelection);
   }
 
-  const insertIndex =
+  const insertColumn =
     position === "before"
       ? selection.anchorCell.columnIndex
       : selection.anchorCell.columnIndex + 1;
-  const nextTable: TableNode = {
-    ...table,
-    gridColumns: insertGridColumn(table.gridColumns, insertIndex),
-    rows: table.rows.map((row) => ({
+
+  // Rewrite each row. For rows where the insert column falls strictly
+  // inside an existing horizontal span (origin.columnIndex < insertColumn
+  // < origin.columnIndex + origin.columnSpan), extend that span by 1.
+  // Otherwise insert a plain empty cell at the appropriate cellIndex.
+  const insertedOriginsExtended = new Set<GridOriginSlot>();
+  const nextRows = table.rows.map((row, rowIndex) => {
+    // Find the origin that covers the insertion column in this row, if any.
+    const leftOrigin =
+      insertColumn > 0 ? originAt(grid, rowIndex, insertColumn - 1) : null;
+    const rightSlot = slotAt(grid, rowIndex, insertColumn);
+    const rightOrigin = rightSlot
+      ? rightSlot.kind === "origin"
+        ? rightSlot
+        : rightSlot.origin
+      : null;
+
+    const insideHSpan =
+      leftOrigin &&
+      rightOrigin &&
+      leftOrigin === rightOrigin &&
+      leftOrigin.columnSpan > 1;
+
+    if (insideHSpan && leftOrigin && !insertedOriginsExtended.has(leftOrigin)) {
+      // Extend the owner cell's gridSpan by 1 (only once per origin across
+      // rows — each origin lives in exactly one row).
+      const ownerCellIndex = leftOrigin.cellIndex;
+      insertedOriginsExtended.add(leftOrigin);
+      return {
+        ...row,
+        cells: row.cells.map((cell, cellIndex) =>
+          cellIndex === ownerCellIndex
+            ? { ...cell, gridSpan: (cell.gridSpan ?? 1) + 1 }
+            : cell,
+        ),
+      };
+    }
+
+    if (insideHSpan) {
+      // The owner has already been extended in its origin row; this row
+      // is a vMerge continuation covered by the same column range. Extend
+      // the continue cell's gridSpan so the logical grid stays consistent.
+      const continueRef = findCellIndexAtColumn(row, leftOrigin!.columnIndex);
+      if (continueRef) {
+        return {
+          ...row,
+          cells: row.cells.map((cell, cellIndex) =>
+            cellIndex === continueRef.cellIndex
+              ? { ...cell, gridSpan: (cell.gridSpan ?? 1) + 1 }
+              : cell,
+          ),
+        };
+      }
+      return row;
+    }
+
+    // Not inside an hspan — insert a plain empty cell at the cellIndex
+    // corresponding to the insertion column. Account for gridBefore
+    // padding and any earlier cell spans.
+    const insertCellIndex = resolveInsertCellIndex(row, insertColumn);
+    return {
       ...row,
       cells: [
-        ...row.cells.slice(0, insertIndex),
+        ...row.cells.slice(0, insertCellIndex),
         createEmptyCell(),
-        ...row.cells.slice(insertIndex),
+        ...row.cells.slice(insertCellIndex),
       ],
-    })),
+    };
+  });
+
+  const nextTable: TableNode = {
+    ...table,
+    gridColumns: insertGridColumn(table.gridColumns, insertColumn),
+    rows: nextRows,
   };
 
   return commitTableChange(
@@ -295,10 +705,24 @@ function addColumn(
     nextTable,
     fallbackSelection,
     selection.anchorCell.rowIndex,
-    insertIndex,
+    insertColumn,
   );
 }
 
+/**
+ * Find the index in row.cells where a new cell should be inserted so it
+ * lands at logical column `logicalColumn`. Accounts for gridBefore padding
+ * and any earlier cell spans.
+ */
+function resolveInsertCellIndex(row: TableRowNode, logicalColumn: number): number {
+  let cursor = row.gridBefore ?? 0;
+  for (let cellIndex = 0; cellIndex < row.cells.length; cellIndex += 1) {
+    if (logicalColumn <= cursor) return cellIndex;
+    cursor += Math.max(1, row.cells[cellIndex]!.gridSpan ?? 1);
+  }
+  return row.cells.length;
+}
+
 function deleteColumn(
   document: CanonicalDocumentEnvelope,
   root: DocumentRootNode,
@@ -306,20 +730,67 @@ function deleteColumn(
   selection: TableSelectionDescriptor,
   fallbackSelection: SelectionSnapshot,
 ): StructuralMutationResult {
-  if (!isSimpleTable(table) || getLogicalColumnCount(table) <= 1) {
+  if (getLogicalColumnCount(table) <= 1) {
     return createNoopStructuralMutation(document, fallbackSelection);
   }
 
-  const deleteIndex = selection.anchorCell.columnIndex;
+  const deleteColumn = selection.anchorCell.columnIndex;
+  const grid = buildLogicalGrid(table);
+
+  // For each row, determine whether the deleted column hits a cell that
+  // is a pure single-column cell (drop it) or is inside a gridSpan > 1
+  // cell (decrement the span). Rows where the column lies outside the
+  // cell range (gridBefore/gridAfter padding) simply pass through.
+  const nextRows = table.rows.map((row, rowIndex) => {
+    const origin = originAt(grid, rowIndex, deleteColumn);
+    if (!origin) return row;
+
+    const cellRef = findCellIndexAtColumn(row, origin.columnIndex);
+    if (!cellRef) return row;
+
+    if (origin.columnSpan <= 1) {
+      // Pure single-column cell — drop it from the row.
+      return {
+        ...row,
+        cells: row.cells.filter((_, cellIndex) => cellIndex !== cellRef.cellIndex),
+      };
+    }
+
+    // Inside an hspan — decrement gridSpan. If the new span would be 1,
+    // drop the gridSpan attribute entirely so the canonical model stays
+    // tidy.
+    const nextSpan = origin.columnSpan - 1;
+    const nextCell: TableCellNode = {
+      ...cellRef.cell,
+      ...(nextSpan > 1 ? { gridSpan: nextSpan } : { gridSpan: undefined }),
+    };
+    // Remove the explicit gridSpan field when nextSpan === 1.
+    if (nextSpan === 1) {
+      const { gridSpan: _drop, ...rest } = nextCell;
+      return {
+        ...row,
+        cells: row.cells.map((cell, cellIndex) =>
+          cellIndex === cellRef.cellIndex ? (rest as TableCellNode) : cell,
+        ),
+      };
+    }
+    return {
+      ...row,
+      cells: row.cells.map((cell, cellIndex) =>
+        cellIndex === cellRef.cellIndex ? nextCell : cell,
+      ),
+    };
+  });
+
   const nextTable: TableNode = {
     ...table,
-    gridColumns: deleteGridColumn(table.gridColumns, deleteIndex),
-    rows: table.rows.map((row) => ({
-      ...row,
-      cells: row.cells.filter((_, cellIndex) => cellIndex !== deleteIndex),
-    })),
+    gridColumns: deleteGridColumn(table.gridColumns, deleteColumn),
+    rows: nextRows,
   };
-  const focusColumnIndex = Math.max(0, Math.min(deleteIndex, getLogicalColumnCount(nextTable) - 1));
+  const focusColumnIndex = Math.max(
+    0,
+    Math.min(deleteColumn, getLogicalColumnCount(nextTable) - 1),
+  );
 
   return commitTableChange(
     document,
@@ -339,14 +810,36 @@ function mergeSelectedCells(
   selection: TableSelectionDescriptor,
   fallbackSelection: SelectionSnapshot,
 ): StructuralMutationResult {
+  // R1a: the merge command was previously gated on `!isSimpleTable(table)`,
+  // which blocked merging on any table that already carried a single merged
+  // span anywhere in the table, even when the user's current selection was
+  // over a simple region. The correct gate is whether the rect itself is:
+  //   (a) clean — every origin it touches is fully enclosed (analyzeRect);
+  //   (b) internally simple — no pre-existing merged origin lives inside
+  //       the rect. findCellAtColumn in the splice body below assumes cells
+  //       at logical column C correspond 1:1 with row.cells entries; that
+  //       assumption holds iff the rect's internal cells are all gridSpan=1
+  //       and verticalMerge=undefined.
+  // A rect that satisfies both is safe to merge even on a table that has
+  // merged spans elsewhere (the common imported-agreement case).
   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 grid = buildLogicalGrid(table);
+  const coverage = analyzeRect(grid, selection.rect);
+  if (!coverage.clean) {
+    return createNoopStructuralMutation(document, fallbackSelection);
+  }
+  const rectInternallySimple = coverage.fullyCoveredOrigins.every(
+    (origin) => origin.columnSpan === 1 && origin.rowSpan === 1,
+  );
+  if (!rectInternallySimple) {
+    return createNoopStructuralMutation(document, fallbackSelection);
+  }
 
   const height = selection.rect.bottom - selection.rect.top;
   const width = selection.rect.right - selection.rect.left;
@@ -852,3 +1345,299 @@ function normalizeFillColor(color: string): string | null {
   const normalized = color.trim().replace(/^#/, "");
   return /^[0-9A-Fa-f]{3,8}$/.test(normalized) ? normalized.toUpperCase() : null;
 }
+
+// ─── P2g helpers: table-level patches ────────────────────────────────────────
+
+function patchTable(
+  document: CanonicalDocumentEnvelope,
+  root: DocumentRootNode,
+  table: TableNode,
+  selection: TableSelectionDescriptor,
+  patch: Partial<TableNode>,
+  fallbackSelection: SelectionSnapshot,
+): StructuralMutationResult {
+  const nextTable: TableNode = { ...table, ...patch };
+  return commitTableChange(
+    document,
+    root,
+    selection.tableBlockIndex,
+    nextTable,
+    fallbackSelection,
+    selection.anchorCell.rowIndex,
+    selection.anchorCell.columnIndex,
+  );
+}
+
+function mergeTableBorders(
+  base: TableBorders | undefined,
+  override: Partial<TableBorders>,
+): TableBorders {
+  return { ...(base ?? {}), ...override };
+}
+
+function mergeCellBorders(
+  base: TableCellBorders | undefined,
+  override: Partial<TableCellBorders>,
+): TableCellBorders {
+  return { ...(base ?? {}), ...override };
+}
+
+function mergeTableCellMargins(
+  base: TableCellMargins | undefined,
+  override: Partial<TableCellMargins>,
+): TableCellMargins {
+  return { ...(base ?? {}), ...override };
+}
+
+// ─── P2h helpers: column/row sizing + row-level patches ──────────────────────
+
+function setColumnWidth(
+  document: CanonicalDocumentEnvelope,
+  root: DocumentRootNode,
+  table: TableNode,
+  selection: TableSelectionDescriptor,
+  columnIndex: number,
+  twips: number,
+  fallbackSelection: SelectionSnapshot,
+): StructuralMutationResult {
+  if (columnIndex < 0 || columnIndex >= table.gridColumns.length) {
+    return createNoopStructuralMutation(document, fallbackSelection);
+  }
+  const clamped = Math.max(0, Math.round(twips));
+  const nextGridColumns = table.gridColumns.map((w, i) => (i === columnIndex ? clamped : w));
+  return patchTable(document, root, table, selection, { gridColumns: nextGridColumns }, fallbackSelection);
+}
+
+function distributeColumnsEvenly(
+  document: CanonicalDocumentEnvelope,
+  root: DocumentRootNode,
+  table: TableNode,
+  selection: TableSelectionDescriptor,
+  columnRange: { from: number; to: number } | undefined,
+  fallbackSelection: SelectionSnapshot,
+): StructuralMutationResult {
+  const gridColumns = table.gridColumns;
+  if (gridColumns.length === 0) {
+    return createNoopStructuralMutation(document, fallbackSelection);
+  }
+  const from = columnRange ? Math.max(0, columnRange.from) : 0;
+  const to = columnRange ? Math.min(gridColumns.length, columnRange.to) : gridColumns.length;
+  if (to - from <= 1) {
+    return createNoopStructuralMutation(document, fallbackSelection);
+  }
+  const total = gridColumns.slice(from, to).reduce((sum, w) => sum + w, 0);
+  const even = Math.floor(total / (to - from));
+  const remainder = total - even * (to - from);
+  const nextGridColumns = gridColumns.map((w, i) => {
+    if (i < from || i >= to) return w;
+    const offset = i - from;
+    return offset === (to - from - 1) ? even + remainder : even;
+  });
+  return patchTable(document, root, table, selection, { gridColumns: nextGridColumns }, fallbackSelection);
+}
+
+function patchRow(
+  document: CanonicalDocumentEnvelope,
+  root: DocumentRootNode,
+  table: TableNode,
+  selection: TableSelectionDescriptor,
+  rowIndex: number,
+  patch: Partial<TableRowNode>,
+  fallbackSelection: SelectionSnapshot,
+): StructuralMutationResult {
+  if (rowIndex < 0 || rowIndex >= table.rows.length) {
+    return createNoopStructuralMutation(document, fallbackSelection);
+  }
+  const nextRows = table.rows.map((row, i) => (i === rowIndex ? { ...row, ...patch } : row));
+  return patchTable(document, root, table, selection, { rows: nextRows }, fallbackSelection);
+}
+
+function insertRows(
+  document: CanonicalDocumentEnvelope,
+  root: DocumentRootNode,
+  table: TableNode,
+  selection: TableSelectionDescriptor,
+  rowIndex: number,
+  at: "before" | "after",
+  count: number,
+  fallbackSelection: SelectionSnapshot,
+): StructuralMutationResult {
+  if (count <= 0) {
+    return createNoopStructuralMutation(document, fallbackSelection);
+  }
+  let current = table;
+  const insertAt = at === "before" ? rowIndex : rowIndex + 1;
+  for (let i = 0; i < count; i += 1) {
+    const grid = buildLogicalGrid(current);
+    const inserted = buildInsertedRow(grid, insertAt + i);
+    current = {
+      ...current,
+      rows: [
+        ...current.rows.slice(0, insertAt + i),
+        inserted,
+        ...current.rows.slice(insertAt + i),
+      ],
+    };
+  }
+  return patchTable(document, root, current, selection, {}, fallbackSelection);
+}
+
+function insertColumns(
+  document: CanonicalDocumentEnvelope,
+  root: DocumentRootNode,
+  table: TableNode,
+  selection: TableSelectionDescriptor,
+  columnIndex: number,
+  at: "before" | "after",
+  count: number,
+  widths: readonly number[] | undefined,
+  fallbackSelection: SelectionSnapshot,
+): StructuralMutationResult {
+  if (count <= 0) {
+    return createNoopStructuralMutation(document, fallbackSelection);
+  }
+  let current = table;
+  const baseInsert = at === "before" ? columnIndex : columnIndex + 1;
+  for (let i = 0; i < count; i += 1) {
+    const insertColumnIndex = baseInsert + i;
+    const result = addColumn(
+      { ...document, content: { ...root, children: [...root.children] } } as CanonicalDocumentEnvelope,
+      root,
+      current,
+      {
+        ...selection,
+        anchorCell: {
+          rowIndex: selection.anchorCell.rowIndex,
+          columnIndex: at === "before" ? insertColumnIndex : insertColumnIndex - 1,
+        },
+      } as TableSelectionDescriptor,
+      at,
+      fallbackSelection,
+    );
+    if (!result.changed) break;
+    current = result.document.content.children[selection.tableBlockIndex] as TableNode;
+  }
+  // Apply explicit widths if provided (overwrites widths at the inserted positions).
+  if (widths && widths.length > 0) {
+    const nextGridColumns = [...current.gridColumns];
+    for (let i = 0; i < count && i < widths.length; i += 1) {
+      const idx = baseInsert + i;
+      if (idx >= 0 && idx < nextGridColumns.length) {
+        nextGridColumns[idx] = Math.max(0, Math.round(widths[i] ?? 0));
+      }
+    }
+    current = { ...current, gridColumns: nextGridColumns };
+  }
+  return patchTable(document, root, current, selection, {}, fallbackSelection);
+}
+
+// ─── P2i helpers: cell-level patches over a locator ──────────────────────────
+
+function patchCells(
+  document: CanonicalDocumentEnvelope,
+  root: DocumentRootNode,
+  table: TableNode,
+  selection: TableSelectionDescriptor,
+  locator: CellLocator,
+  transform: (cell: TableCellNode) => TableCellNode,
+  fallbackSelection: SelectionSnapshot,
+): StructuralMutationResult {
+  const grid = buildLogicalGrid(table);
+  const targets = resolveLocatorTargets(grid, selection, locator);
+  if (targets.size === 0) {
+    return createNoopStructuralMutation(document, fallbackSelection);
+  }
+
+  // Group by row so we can do one map per row.
+  const byRow = new Map<number, Set<number>>();
+  for (const { rowIndex, cellIndex } of targets) {
+    let set = byRow.get(rowIndex);
+    if (!set) {
+      set = new Set();
+      byRow.set(rowIndex, set);
+    }
+    set.add(cellIndex);
+  }
+
+  const nextRows = table.rows.map((row, rowIndex) => {
+    const indices = byRow.get(rowIndex);
+    if (!indices) return row;
+    return {
+      ...row,
+      cells: row.cells.map((cell, cellIndex) =>
+        indices.has(cellIndex) ? transform(cell) : cell,
+      ),
+    };
+  });
+
+  return patchTable(document, root, table, selection, { rows: nextRows }, fallbackSelection);
+}
+
+function resolveLocatorTargets(
+  grid: LogicalGrid,
+  selection: TableSelectionDescriptor,
+  locator: CellLocator,
+): Set<{ rowIndex: number; cellIndex: number }> {
+  const targets = new Set<{ rowIndex: number; cellIndex: number }>();
+  const seenOrigins = new Set<GridOriginSlot>();
+
+  const addOrigin = (origin: GridOriginSlot): void => {
+    if (seenOrigins.has(origin)) return;
+    seenOrigins.add(origin);
+    targets.add({ rowIndex: origin.rowIndex, cellIndex: origin.cellIndex });
+  };
+
+  if (locator.kind === "anchor") {
+    const origin = originAt(grid, selection.anchorCell.rowIndex, selection.anchorCell.columnIndex);
+    if (origin) addOrigin(origin);
+    return targets;
+  }
+
+  if (locator.kind === "index") {
+    const origin = originAt(grid, locator.rowIndex, locator.columnIndex);
+    if (origin) addOrigin(origin);
+    return targets;
+  }
+
+  if (locator.kind === "row") {
+    const rowIndex = locator.rowIndex;
+    for (let c = 0; c < grid.columnCount; c += 1) {
+      const origin = originAt(grid, rowIndex, c);
+      if (origin && origin.rowIndex === rowIndex) addOrigin(origin);
+    }
+    return targets;
+  }
+
+  if (locator.kind === "column") {
+    const columnIndex = locator.columnIndex;
+    for (let r = 0; r < grid.rowCount; r += 1) {
+      const origin = originAt(grid, r, columnIndex);
+      if (origin && origin.columnIndex === columnIndex) addOrigin(origin);
+    }
+    return targets;
+  }
+
+  if (locator.kind === "rect") {
+    for (let r = locator.rect.top; r < locator.rect.bottom; r += 1) {
+      for (let c = locator.rect.left; c < locator.rect.right; c += 1) {
+        const origin = originAt(grid, r, c);
+        if (origin) addOrigin(origin);
+      }
+    }
+    return targets;
+  }
+
+  // "selection" — use the descriptor's rect or the anchor cell.
+  if (selection.selectionKind === "cell") {
+    for (let r = selection.rect.top; r < selection.rect.bottom; r += 1) {
+      for (let c = selection.rect.left; c < selection.rect.right; c += 1) {
+        const origin = originAt(grid, r, c);
+        if (origin) addOrigin(origin);
+      }
+    }
+  } else {
+    const origin = originAt(grid, selection.anchorCell.rowIndex, selection.anchorCell.columnIndex);
+    if (origin) addOrigin(origin);
+  }
+  return targets;
+}