docxmlater 10.3.6 → 10.4.0

package/src/elements/Table.ts

@@ -5,23 +5,17 @@
 import { Paragraph } from './Paragraph';
 import { TableRow, RowFormatting } from './TableRow';
 import { TableCell, CellFormatting } from './TableCell';
-import { Run } from './Run';
 import { Revision } from './Revision';
 import { XMLBuilder, XMLElement } from '../xml/XMLBuilder';
 import { deepClone } from '../utils/deepClone';
 import { TableGridChange } from './TableGridChange';
-import { formatDateForXml } from '../utils/dateFormatting';
 import {
   TableAlignment as CommonTableAlignment,
   BorderStyle,
-  BorderDefinition,
-  TableBorderDefinitions,
   HorizontalAnchor,
   VerticalAnchor,
   HorizontalAlignment,
   VerticalAlignment,
-  WidthType,
-  ShadingPattern,
   ShadingConfig,
   buildShadingAttributes,
 } from './CommonTypes';
@@ -119,7 +113,7 @@ export interface TablePositionProperties {
 /**
  * Table width type
  */
-export type TableWidthType = 'auto' | 'dxa' | 'pct';
+export type TableWidthType = 'auto' | 'dxa' | 'nil' | 'pct';
 
 /**
  * Table shading/background
@@ -176,6 +170,7 @@ export interface TableFormatting {
   cellSpacingType?: TableWidthType; // Cell spacing type
   cellMargins?: TableCellMargins; // Default cell margins (padding) for all cells
   indent?: number; // Left indent in twips
+  indentType?: TableWidthType; // Indent type (auto, dxa, nil, pct)
   tblLook?: string; // Table look flags (appearance settings)
   shading?: TableShading; // Table background shading
   // Batch 1 properties
@@ -325,6 +320,103 @@ export class Table {
     return this;
   }
 
+  /**
+   * Adds a row from an array of cell text values
+   *
+   * Creates a TableRow with cells populated from the string array and appends
+   * it to the table. This is the single-row counterpart to `Table.fromArray()`.
+   *
+   * @param cells - Array of text values, one per cell
+   * @returns The created TableRow for further customization
+   *
+   * @example
+   * ```typescript
+   * const table = Table.fromArray([['Name', 'Age', 'City']]);
+   * table.addRowFromArray(['Alice', '30', 'NYC']);
+   * table.addRowFromArray(['Bob', '25', 'London']);
+   * ```
+   */
+  addRowFromArray(cells: string[]): TableRow {
+    const row = new TableRow();
+    for (const text of cells) {
+      row.createCell(text || undefined);
+    }
+    this.rows.push(row);
+    row._setParentTable(this);
+    return row;
+  }
+
+  /**
+   * Adds a summary/totals row computed from column data
+   *
+   * Appends a new row where each cell's value is computed by applying an
+   * aggregation function to that column's data rows (header row excluded).
+   * By default, numeric columns are summed and non-numeric columns show a
+   * count. The first column shows a label.
+   *
+   * @param options - Summary configuration
+   * @param options.label - Label for the first cell (default: 'Total')
+   * @param options.startRow - First data row index to include (default: 1, skipping header)
+   * @param options.compute - Custom function to compute a cell value from its column's text values.
+   *   Receives `(values: string[], colIndex: number)`. If not provided, defaults to
+   *   numeric sum for parseable columns, empty string otherwise.
+   * @returns The created summary TableRow
+   *
+   * @example
+   * ```typescript
+   * const table = Table.fromArray([
+   *   ['Product', 'Price', 'Qty'],
+   *   ['Widget', '10', '5'],
+   *   ['Gadget', '25', '2'],
+   * ]);
+   * table.addSummaryRow();
+   * // Adds: ['Total', '35', '7']
+   * ```
+   *
+   * @example
+   * ```typescript
+   * // Custom compute: average instead of sum
+   * table.addSummaryRow({
+   *   label: 'Average',
+   *   compute: (values) => {
+   *     const nums = values.map(Number).filter(n => !isNaN(n));
+   *     return nums.length ? (nums.reduce((a, b) => a + b, 0) / nums.length).toFixed(1) : '';
+   *   },
+   * });
+   * ```
+   */
+  addSummaryRow(options?: {
+    label?: string;
+    startRow?: number;
+    compute?: (values: string[], colIndex: number) => string;
+  }): TableRow {
+    const label = options?.label ?? 'Total';
+    const startRow = options?.startRow ?? 1;
+    const colCount = this.getColumnCount();
+
+    const defaultCompute = (values: string[]): string => {
+      const nums = values.map((v) => parseFloat(v)).filter((n) => !isNaN(n));
+      if (nums.length === 0) return '';
+      return String(nums.reduce((a, b) => a + b, 0));
+    };
+
+    const compute = options?.compute ?? defaultCompute;
+    const cells: string[] = [];
+
+    for (let c = 0; c < colCount; c++) {
+      if (c === 0) {
+        cells.push(label);
+        continue;
+      }
+
+      const colTexts = this.getColumnTexts(c);
+      const dataValues = colTexts.slice(startRow);
+      cells.push(compute(dataValues, c));
+    }
+
+    return this.addRowFromArray(cells);
+  }
+
   /**
    * Creates a new row and adds it to the table
    *
@@ -459,6 +551,46 @@ export class Table {
     return row ? row.getCell(columnIndex) : undefined;
   }
 
+  /**
+   * Sets the text content of a cell, replacing any existing content
+   *
+   * Convenience method that locates the cell at (row, col) and sets its
+   * text. If the cell has existing paragraphs, the first paragraph's text
+   * is replaced and extra paragraphs are removed. If the cell is empty,
+   * a new paragraph is created.
+   *
+   * @param rowIndex - Row index (0-based)
+   * @param colIndex - Column index (0-based)
+   * @param text - New text content for the cell
+   * @returns This table for chaining, or this table (no-op if cell not found)
+   *
+   * @example
+   * ```typescript
+   * const table = new Table(3, 3);
+   * table.setCell(0, 0, 'Name');
+   * table.setCell(0, 1, 'Age');
+   * table.setCell(1, 0, 'Alice');
+   * table.setCell(1, 1, '30');
+   * ```
+   */
+  setCell(rowIndex: number, colIndex: number, text: string): this {
+    const cell = this.getCell(rowIndex, colIndex);
+    if (!cell) return this;
+
+    const paragraphs = cell.getParagraphs();
+    if (paragraphs.length > 0) {
+      paragraphs[0]!.setText(text);
+      // Remove extra paragraphs
+      for (let p = paragraphs.length - 1; p >= 1; p--) {
+        cell.removeParagraph(p);
+      }
+    } else {
+      cell.createParagraph(text);
+    }
+
+    return this;
+  }
+
   /**
    * Sets the table width
    *
@@ -774,6 +906,25 @@ export class Table {
     return this;
   }
 
+  /**
+   * Sets the indent width type per ECMA-376 ST_TblWidth
+   */
+  setIndentType(type: TableWidthType): this {
+    const prev = this.formatting.indentType;
+    this.formatting.indentType = type;
+    if (this.trackingContext?.isEnabled() && prev !== type) {
+      this.trackingContext.trackTableChange(this, 'indentType', prev, type);
+    }
+    return this;
+  }
+
+  /**
+   * Gets the indent width type
+   */
+  getIndentType(): TableWidthType | undefined {
+    return this.formatting.indentType;
+  }
+
   /**
    * Sets table style reference
    * @param style - Table style ID (e.g., 'Table1', 'TableGrid')
@@ -1508,8 +1659,8 @@ export class Table {
 
     // 5-6. tblStyleRowBandSize / tblStyleColBandSize
     // Only valid within table style definitions (CT_TblPrBase in w:style),
-    // not in direct tblPr. Style.ts handles serialization in style context.
-    // Values are preserved in formatting for round-trip and style use.
+    // not in direct tblPr per Transitional schema. Style.ts handles serialization.
+    // Values are preserved in formatting for style use and tblPrChange serialization.
 
     // 7. tblW
     if (this.formatting.width !== undefined) {
@@ -1543,7 +1694,7 @@ export class Table {
       tblPrChildren.push(
         XMLBuilder.wSelf('tblInd', {
           'w:w': this.formatting.indent,
-          'w:type': 'dxa',
+          'w:type': this.formatting.indentType || 'dxa',
         })
       );
     }
@@ -1659,12 +1810,54 @@ export class Table {
         'w:author': this.tblPrChange.author,
         'w:date': this.tblPrChange.date,
       };
+      // tblPrChange previousProperties — same CT_TblPr order as main tblPr per ECMA-376 §17.4.58:
+      // tblStyle, tblpPr, tblOverlap, bidiVisual, tblStyleRowBandSize, tblStyleColBandSize,
+      // tblW, jc, tblCellSpacing, tblInd, tblBorders, shd, tblLayout, tblCellMar, tblLook,
+      // tblCaption, tblDescription
       const prevTblPrChildren: XMLElement[] = [];
       const prev = this.tblPrChange.previousProperties;
       if (prev) {
+        // 1. tblStyle
         if (prev.style) {
           prevTblPrChildren.push(XMLBuilder.wSelf('tblStyle', { 'w:val': prev.style }));
         }
+        // 2. tblpPr (floating table position) — passthrough if present
+        if (prev.position) {
+          const posAttrs: Record<string, string | number> = {};
+          const pos = prev.position;
+          if (pos.x !== undefined) posAttrs['w:tblpX'] = pos.x;
+          if (pos.y !== undefined) posAttrs['w:tblpY'] = pos.y;
+          if (pos.horizontalAnchor) posAttrs['w:horzAnchor'] = pos.horizontalAnchor;
+          if (pos.verticalAnchor) posAttrs['w:vertAnchor'] = pos.verticalAnchor;
+          if (pos.leftFromText !== undefined) posAttrs['w:leftFromText'] = pos.leftFromText;
+          if (pos.rightFromText !== undefined) posAttrs['w:rightFromText'] = pos.rightFromText;
+          if (pos.topFromText !== undefined) posAttrs['w:topFromText'] = pos.topFromText;
+          if (pos.bottomFromText !== undefined) posAttrs['w:bottomFromText'] = pos.bottomFromText;
+          if (Object.keys(posAttrs).length > 0) {
+            prevTblPrChildren.push(XMLBuilder.wSelf('tblpPr', posAttrs));
+          }
+        }
+        // 3. tblOverlap
+        if (prev.overlap) {
+          prevTblPrChildren.push(XMLBuilder.wSelf('tblOverlap', { 'w:val': prev.overlap }));
+        }
+        // 4. bidiVisual
+        if (prev.bidiVisual) {
+          prevTblPrChildren.push(XMLBuilder.wSelf('bidiVisual'));
+        }
+        // 5. tblStyleRowBandSize
+        if (prev.tblStyleRowBandSize !== undefined) {
+          prevTblPrChildren.push(
+            XMLBuilder.wSelf('tblStyleRowBandSize', { 'w:val': prev.tblStyleRowBandSize })
+          );
+        }
+        // 6. tblStyleColBandSize
+        if (prev.tblStyleColBandSize !== undefined) {
+          prevTblPrChildren.push(
+            XMLBuilder.wSelf('tblStyleColBandSize', { 'w:val': prev.tblStyleColBandSize })
+          );
+        }
+        // 7. tblW
         if (prev.width !== undefined) {
           prevTblPrChildren.push(
             XMLBuilder.wSelf('tblW', {
@@ -1673,14 +1866,25 @@ export class Table {
             })
           );
         }
+        // 8. jc
         if (prev.alignment) {
           prevTblPrChildren.push(XMLBuilder.wSelf('jc', { 'w:val': prev.alignment }));
         }
+        // 9. tblCellSpacing
+        if (prev.cellSpacing !== undefined) {
+          const csAttrs: Record<string, string | number> = {
+            'w:w': prev.cellSpacing,
+            'w:type': prev.cellSpacingType || 'dxa',
+          };
+          prevTblPrChildren.push(XMLBuilder.wSelf('tblCellSpacing', csAttrs));
+        }
+        // 10. tblInd
         if (prev.indent !== undefined) {
           prevTblPrChildren.push(
-            XMLBuilder.wSelf('tblInd', { 'w:w': prev.indent, 'w:type': 'dxa' })
+            XMLBuilder.wSelf('tblInd', { 'w:w': prev.indent, 'w:type': prev.indentType || 'dxa' })
           );
         }
+        // 11. tblBorders
         if (prev.borders) {
           const borderChildren: XMLElement[] = [];
           const bNames = ['top', 'left', 'bottom', 'right', 'insideH', 'insideV'] as const;
@@ -1698,56 +1902,53 @@ export class Table {
             prevTblPrChildren.push(XMLBuilder.w('tblBorders', undefined, borderChildren));
           }
         }
+        // 12. shd
         if (prev.shading) {
           const shadingAttrs = buildShadingAttributes(prev.shading);
           if (Object.keys(shadingAttrs).length > 0) {
             prevTblPrChildren.push(XMLBuilder.wSelf('shd', shadingAttrs));
           }
         }
+        // 13. tblLayout
         if (prev.layout) {
           prevTblPrChildren.push(XMLBuilder.wSelf('tblLayout', { 'w:type': prev.layout }));
         }
-        if (prev.cellSpacing !== undefined) {
-          const csAttrs: Record<string, string | number> = {
-            'w:w': prev.cellSpacing,
-            'w:type': prev.cellSpacingType || 'dxa',
-          };
-          prevTblPrChildren.push(XMLBuilder.wSelf('tblCellSpacing', csAttrs));
-        }
-        if (prev.bidiVisual) {
-          prevTblPrChildren.push(XMLBuilder.wSelf('bidiVisual'));
-        }
+        // 14. tblCellMar
         if (prev.cellMargins) {
           const cmChildren: XMLElement[] = [];
-          for (const side of ['top', 'start', 'bottom', 'end'] as const) {
-            const val = (prev.cellMargins as Record<string, number | undefined>)[side];
-            if (val !== undefined) {
-              cmChildren.push(XMLBuilder.wSelf(side, { 'w:w': val, 'w:type': 'dxa' }));
-            }
+          if (prev.cellMargins.top !== undefined) {
+            cmChildren.push(
+              XMLBuilder.wSelf('top', { 'w:w': prev.cellMargins.top, 'w:type': 'dxa' })
+            );
+          }
+          if (prev.cellMargins.left !== undefined) {
+            cmChildren.push(
+              XMLBuilder.wSelf('left', { 'w:w': prev.cellMargins.left, 'w:type': 'dxa' })
+            );
+          }
+          if (prev.cellMargins.bottom !== undefined) {
+            cmChildren.push(
+              XMLBuilder.wSelf('bottom', { 'w:w': prev.cellMargins.bottom, 'w:type': 'dxa' })
+            );
+          }
+          if (prev.cellMargins.right !== undefined) {
+            cmChildren.push(
+              XMLBuilder.wSelf('right', { 'w:w': prev.cellMargins.right, 'w:type': 'dxa' })
+            );
           }
           if (cmChildren.length > 0) {
             prevTblPrChildren.push(XMLBuilder.w('tblCellMar', undefined, cmChildren));
           }
         }
+        // 15. tblLook
         if (prev.tblLook) {
           prevTblPrChildren.push(XMLBuilder.wSelf('tblLook', buildTblLookAttributes(prev.tblLook)));
         }
-        if (prev.tblStyleRowBandSize !== undefined) {
-          prevTblPrChildren.push(
-            XMLBuilder.wSelf('tblStyleRowBandSize', { 'w:val': prev.tblStyleRowBandSize })
-          );
-        }
-        if (prev.tblStyleColBandSize !== undefined) {
-          prevTblPrChildren.push(
-            XMLBuilder.wSelf('tblStyleColBandSize', { 'w:val': prev.tblStyleColBandSize })
-          );
-        }
-        if (prev.overlap) {
-          prevTblPrChildren.push(XMLBuilder.wSelf('tblOverlap', { 'w:val': prev.overlap }));
-        }
+        // 16. tblCaption
         if (prev.caption) {
           prevTblPrChildren.push(XMLBuilder.wSelf('tblCaption', { 'w:val': prev.caption }));
         }
+        // 17. tblDescription
         if (prev.description) {
           prevTblPrChildren.push(XMLBuilder.wSelf('tblDescription', { 'w:val': prev.description }));
         }
@@ -1816,6 +2017,10 @@ export class Table {
    */
   removeRow(index: number): boolean {
     if (index >= 0 && index < this.rows.length) {
+      // Per ECMA-376 §17.4.38, a table must contain at least one row
+      if (this.rows.length <= 1 && !this.trackingContext?.isEnabled()) {
+        return false;
+      }
       // When tracking enabled, mark cells with cellDel and wrap content in w:del
       if (this.trackingContext?.isEnabled()) {
         const author = this.trackingContext.getAuthor();
@@ -1865,10 +2070,13 @@ export class Table {
     if (index < 0) index = 0;
     if (index > this.rows.length) index = this.rows.length;
 
-    // Create new row if not provided, matching the column count
+    // Create new row if not provided, matching the grid column count
+    // Use getTotalGridSpan() instead of getColumnCount() to account for merged cells
     if (!row) {
-      const columnCount = this.getColumnCount();
-      row = new TableRow(columnCount);
+      const gridColumns = this.formatting.tableGrid
+        ? this.formatting.tableGrid.length
+        : Math.max(...this.rows.map((r) => r.getTotalGridSpan()), 1);
+      row = new TableRow(gridColumns);
     }
 
     // Insert the row
@@ -1995,6 +2203,283 @@ export class Table {
     return Math.max(...this.rows.map((row) => row.getCellCount()));
   }
 
+  /**
+   * Gets all cells at a given column index across all rows
+   *
+   * Returns the cell at position `colIndex` from each row. Rows that have
+   * fewer cells than the requested index are skipped (their slot is not
+   * included in the result). This uses simple cell-index addressing, not
+   * grid-span-aware column mapping.
+   *
+   * @param colIndex - Column index (0-based)
+   * @returns Array of cells at that column position
+   *
+   * @example
+   * ```typescript
+   * // Sum values in the third column
+   * const cells = table.getColumnCells(2);
+   * const total = cells.reduce((sum, cell) => sum + Number(cell.getText()), 0);
+   * ```
+   */
+  getColumnCells(colIndex: number): TableCell[] {
+    const cells: TableCell[] = [];
+    for (const row of this.rows) {
+      const cell = row.getCell(colIndex);
+      if (cell) cells.push(cell);
+    }
+    return cells;
+  }
+
+  /**
+   * Gets the text content of all cells in a column as a string array
+   *
+   * Like `getColumnCells()` but returns just the text values, skipping
+   * the cell object layer. Rows with fewer cells than the column index
+   * are skipped.
+   *
+   * @param colIndex - Column index (0-based)
+   * @returns Array of cell text values
+   *
+   * @example
+   * ```typescript
+   * const names = table.getColumnTexts(0); // ['Name', 'Alice', 'Bob']
+   * const total = table.getColumnTexts(2)
+   *   .slice(1)
+   *   .reduce((sum, v) => sum + Number(v), 0);
+   * ```
+   */
+  getColumnTexts(colIndex: number): string[] {
+    return this.getColumnCells(colIndex).map((cell) => cell.getText());
+  }
+
+  /**
+   * Transforms the text content of every cell in a column
+   *
+   * Calls the transform function for each cell in the column with the
+   * current text and row index. The return value replaces the cell's content.
+   * Useful for formatting values, applying calculations, or normalizing data.
+   *
+   * @param colIndex - Column index (0-based)
+   * @param transform - Function that receives cell text and row index, returns new text
+   * @returns This table for chaining
+   *
+   * @example
+   * ```typescript
+   * // Uppercase all values in column 0
+   * table.mapColumn(0, (text) => text.toUpperCase());
+   *
+   * // Format numbers in column 2 (skip header row)
+   * table.mapColumn(2, (text, rowIndex) =>
+   *   rowIndex === 0 ? text : `$${Number(text).toFixed(2)}`
+   * );
+   *
+   * // Add prefix to a column
+   * table.mapColumn(1, (text) => `ID-${text}`);
+   * ```
+   */
+  mapColumn(colIndex: number, transform: (text: string, rowIndex: number) => string): this {
+    for (let r = 0; r < this.rows.length; r++) {
+      const cell = this.rows[r]!.getCell(colIndex);
+      if (!cell) continue;
+
+      const currentText = cell.getText();
+      const newText = transform(currentText, r);
+
+      if (newText !== currentText) {
+        // Clear existing paragraphs and set new text
+        const paragraphs = cell.getParagraphs();
+        if (paragraphs.length > 0) {
+          // Preserve first paragraph's formatting, replace text
+          const firstPara = paragraphs[0]!;
+          firstPara.setText(newText);
+          // Remove extra paragraphs if cell had multiple
+          for (let p = paragraphs.length - 1; p >= 1; p--) {
+            cell.removeParagraph(p);
+          }
+        } else {
+          cell.createParagraph(newText);
+        }
+      }
+    }
+
+    return this;
+  }
+
+  /**
+   * Iterates over every cell in the table, providing row and column indices
+   *
+   * Calls the callback for each cell with its row index, column index,
+   * and the cell itself. Useful for bulk operations like formatting or
+   * data extraction without manual nested loops.
+   *
+   * @param callback - Function called for each cell. Return `false` to stop iteration early.
+   *
+   * @example
+   * ```typescript
+   * // Apply shading to every other row
+   * table.forEachCell((rowIndex, colIndex, cell) => {
+   *   if (rowIndex % 2 === 1) {
+   *     cell.setShading({ fill: 'F2F2F2', pattern: 'clear' });
+   *   }
+   * });
+   *
+   * // Find a cell by content
+   * let found: TableCell | undefined;
+   * table.forEachCell((row, col, cell) => {
+   *   if (cell.getText().includes('Total')) {
+   *     found = cell;
+   *     return false; // stop early
+   *   }
+   * });
+   * ```
+   */
+  forEachCell(
+    callback: (rowIndex: number, colIndex: number, cell: TableCell) => void | false
+  ): void {
+    for (let r = 0; r < this.rows.length; r++) {
+      const cells = this.rows[r]!.getCells();
+      for (let c = 0; c < cells.length; c++) {
+        const result = callback(r, c, cells[c]!);
+        if (result === false) return;
+      }
+    }
+  }
+
+  /**
+   * Finds the first cell matching a predicate, with its coordinates
+   *
+   * Iterates all cells in row-major order and returns the first one for
+   * which the predicate returns true, along with its row and column index.
+   *
+   * @param predicate - Function that tests each cell
+   * @returns Object with row, col, and cell, or undefined if not found
+   *
+   * @example
+   * ```typescript
+   * const result = table.findCell((cell) => cell.getText().includes('Total'));
+   * if (result) {
+   *   console.log(`Found at row ${result.row}, col ${result.col}`);
+   * }
+   * ```
+   */
+  findCell(
+    predicate: (cell: TableCell, rowIndex: number, colIndex: number) => boolean
+  ): { row: number; col: number; cell: TableCell } | undefined {
+    for (let r = 0; r < this.rows.length; r++) {
+      const cells = this.rows[r]!.getCells();
+      for (let c = 0; c < cells.length; c++) {
+        if (predicate(cells[c]!, r, c)) {
+          return { row: r, col: c, cell: cells[c]! };
+        }
+      }
+    }
+    return undefined;
+  }
+
+  /**
+   * Returns indices of rows matching a predicate
+   *
+   * Tests each row by passing all its cells to the predicate function.
+   * Returns an array of row indices where the predicate returned true.
+   *
+   * @param predicate - Function that tests a row's cells
+   * @returns Array of matching row indices (0-based)
+   *
+   * @example
+   * ```typescript
+   * // Find rows where the first cell contains "Total"
+   * const totals = table.filterRows((cells) =>
+   *   cells[0]?.getText().includes('Total') ?? false
+   * );
+   *
+   * // Find rows where all cells are empty
+   * const empty = table.filterRows((cells) =>
+   *   cells.every((c) => c.getText().trim() === '')
+   * );
+   * ```
+   */
+  filterRows(predicate: (cells: TableCell[], rowIndex: number) => boolean): number[] {
+    const indices: number[] = [];
+    for (let r = 0; r < this.rows.length; r++) {
+      if (predicate(this.rows[r]!.getCells(), r)) {
+        indices.push(r);
+      }
+    }
+    return indices;
+  }
+
+  /**
+   * Removes rows where all cells are empty (no text content)
+   *
+   * A row is considered empty if every cell's trimmed text is the empty string.
+   * Respects the ECMA-376 constraint that at least one row must remain — if all
+   * rows are empty, the first row is kept.
+   *
+   * @returns Number of rows removed
+   *
+   * @example
+   * ```typescript
+   * const table = Table.fromArray([
+   *   ['Name', 'Age'],
+   *   ['', ''],
+   *   ['Alice', '30'],
+   *   ['', ''],
+   * ]);
+   * table.removeEmptyRows(); // Returns 2, table now has 2 rows
+   * ```
+   */
+  removeEmptyRows(): number {
+    const emptyIndices = this.filterRows((cells) => cells.every((c) => c.getText().trim() === ''));
+
+    // Keep at least one row (ECMA-376 requires >= 1 row)
+    const toRemove =
+      emptyIndices.length === this.rows.length
+        ? emptyIndices.slice(1) // keep first row
+        : emptyIndices;
+
+    // Remove in reverse order to preserve indices
+    for (let i = toRemove.length - 1; i >= 0; i--) {
+      this.removeRow(toRemove[i]!);
+    }
+
+    return toRemove.length;
+  }
+
+  /**
+   * Removes columns where all cells are empty (no text content)
+   *
+   * A column is considered empty if every cell at that column index has
+   * trimmed text equal to the empty string.
+   *
+   * @returns Number of columns removed
+   *
+   * @example
+   * ```typescript
+   * const table = Table.fromArray([
+   *   ['Name', '', 'Age'],
+   *   ['Alice', '', '30'],
+   * ]);
+   * table.removeEmptyColumns(); // Returns 1, middle column removed
+   * ```
+   */
+  removeEmptyColumns(): number {
+    const colCount = this.getColumnCount();
+    let removed = 0;
+
+    // Check columns in reverse order to preserve indices
+    for (let c = colCount - 1; c >= 0; c--) {
+      const columnCells = this.getColumnCells(c);
+      const isEmpty = columnCells.every((cell) => cell.getText().trim() === '');
+
+      if (isEmpty) {
+        this.removeColumn(c);
+        removed++;
+      }
+    }
+
+    return removed;
+  }
+
   /**
    * Sets specific widths for table columns
    *
@@ -2039,6 +2524,53 @@ export class Table {
     return new Table(rows, columns, formatting);
   }
 
+  /**
+   * Creates a table from a 2D string array
+   *
+   * Each inner array becomes a row; each string becomes a cell with a single
+   * paragraph. The table column count is determined by the longest row.
+   * Shorter rows are padded with empty cells to keep the grid rectangular.
+   *
+   * @param data - 2D array of cell text values
+   * @param formatting - Optional table formatting
+   * @returns New Table populated with the data
+   *
+   * @example
+   * ```typescript
+   * const table = Table.fromArray([
+   *   ['Name', 'Age', 'City'],
+   *   ['Alice', '30', 'New York'],
+   *   ['Bob', '25', 'London'],
+   * ]);
+   * ```
+   *
+   * @example
+   * ```typescript
+   * // With formatting
+   * const table = Table.fromArray(
+   *   [['Header 1', 'Header 2'], ['Data 1', 'Data 2']],
+   *   { alignment: 'center', layout: 'fixed' }
+   * );
+   * ```
+   */
+  static fromArray(data: string[][], formatting?: TableFormatting): Table {
+    if (data.length === 0) return new Table(0, 0, formatting);
+
+    const maxCols = Math.max(...data.map((row) => row.length));
+    const table = new Table(0, 0, formatting);
+
+    for (const rowData of data) {
+      const row = new TableRow();
+      for (let c = 0; c < maxCols; c++) {
+        const text = c < rowData.length ? rowData[c] : undefined;
+        row.createCell(text || undefined);
+      }
+      table.addRow(row);
+    }
+
+    return table;
+  }
+
   /**
    * Merges cells into a single cell (uses columnSpan and rowSpan)
    * @param startRow - Starting row index (0-based)
@@ -2349,7 +2881,10 @@ export class Table {
    */
   insertRows(startIndex: number, count: number): TableRow[] {
     const insertedRows: TableRow[] = [];
-    const columnCount = this.getColumnCount();
+    // Use grid column count (accounting for merged cells) instead of cell count
+    const columnCount = this.formatting.tableGrid
+      ? this.formatting.tableGrid.length
+      : Math.max(...this.rows.map((r) => r.getTotalGridSpan()), 1);
 
     for (let i = 0; i < count; i++) {
       const row = new TableRow(columnCount);
@@ -2468,6 +3003,235 @@ export class Table {
     return this;
   }
 
+  /**
+   * Extracts table content as a 2D string array
+   *
+   * Returns an array of rows, where each row is an array of cell text values.
+   * Multi-paragraph cells join their text with newlines. Rows with fewer cells
+   * than the widest row are NOT padded — the inner arrays may have different lengths.
+   *
+   * @returns 2D array of cell text content
+   *
+   * @example
+   * ```typescript
+   * const table = new Table(2, 3);
+   * table.getCell(0, 0)!.createParagraph('Name');
+   * table.getCell(0, 1)!.createParagraph('Age');
+   * table.getCell(1, 0)!.createParagraph('Alice');
+   * table.getCell(1, 1)!.createParagraph('30');
+   *
+   * const data = table.toArray();
+   * // [['Name', 'Age', ''], ['Alice', '30', '']]
+   * ```
+   */
+  toArray(): string[][] {
+    return this.rows.map((row) => row.getCells().map((cell) => cell.getText()));
+  }
+
+  /**
+   * Converts table content to a plain text representation
+   *
+   * Renders the table as tab-separated values with rows on separate lines.
+   * Useful for logging, debugging, or simple text export.
+   *
+   * @param columnSeparator - Separator between columns (default: tab)
+   * @param rowSeparator - Separator between rows (default: newline)
+   * @returns Plain text representation of the table
+   *
+   * @example
+   * ```typescript
+   * console.log(table.toPlainText());
+   * // "Name\tAge\nAlice\t30"
+   *
+   * // CSV-style output
+   * console.log(table.toPlainText(',', '\n'));
+   * // "Name,Age\nAlice,30"
+   * ```
+   */
+  toPlainText(columnSeparator = '\t', rowSeparator = '\n'): string {
+    return this.rows
+      .map((row) =>
+        row
+          .getCells()
+          .map((cell) => cell.getText())
+          .join(columnSeparator)
+      )
+      .join(rowSeparator);
+  }
+
+  /**
+   * Exports table content as a CSV string
+   *
+   * Produces RFC 4180-compliant CSV: fields containing commas, quotes,
+   * or newlines are quoted, and embedded quotes are escaped by doubling.
+   *
+   * @param delimiter - Field delimiter (default: ',')
+   * @returns CSV string
+   *
+   * @example
+   * ```typescript
+   * const csv = table.toCSV();
+   * // "Name,Age,City\nAlice,30,New York\nBob,25,London"
+   *
+   * // TSV variant
+   * const tsv = table.toCSV('\t');
+   * ```
+   */
+  toCSV(delimiter = ','): string {
+    return this.rows
+      .map((row) =>
+        row
+          .getCells()
+          .map((cell) => {
+            const text = cell.getText();
+            // Quote field if it contains delimiter, quotes, or newlines
+            if (text.includes(delimiter) || text.includes('"') || text.includes('\n')) {
+              return '"' + text.replace(/"/g, '""') + '"';
+            }
+            return text;
+          })
+          .join(delimiter)
+      )
+      .join('\n');
+  }
+
+  /**
+   * Creates a table from a CSV string
+   *
+   * Parses RFC 4180-compliant CSV: handles quoted fields, escaped quotes
+   * (doubled `""`), and newlines within quoted fields.
+   *
+   * @param csv - CSV string to parse
+   * @param delimiter - Field delimiter (default: ',')
+   * @param formatting - Optional table formatting
+   * @returns New Table populated with the parsed data
+   *
+   * @example
+   * ```typescript
+   * const table = Table.fromCSV('Name,Age\nAlice,30\nBob,25');
+   *
+   * // TSV input
+   * const table2 = Table.fromCSV('Name\tAge\nAlice\t30', '\t');
+   *
+   * // Handles quoted fields
+   * const table3 = Table.fromCSV('"City, State",Pop\n"New York, NY",8336817');
+   * ```
+   */
+  static fromCSV(csv: string, delimiter = ',', formatting?: TableFormatting): Table {
+    const rows: string[][] = [];
+    let currentRow: string[] = [];
+    let currentField = '';
+    let inQuotes = false;
+    let i = 0;
+
+    while (i < csv.length) {
+      const ch = csv[i]!;
+
+      if (inQuotes) {
+        if (ch === '"') {
+          // Check for escaped quote ""
+          if (i + 1 < csv.length && csv[i + 1] === '"') {
+            currentField += '"';
+            i += 2;
+          } else {
+            // End of quoted field
+            inQuotes = false;
+            i++;
+          }
+        } else {
+          currentField += ch;
+          i++;
+        }
+      } else {
+        if (ch === '"') {
+          inQuotes = true;
+          i++;
+        } else if (ch === delimiter) {
+          currentRow.push(currentField);
+          currentField = '';
+          i++;
+        } else if (ch === '\n') {
+          currentRow.push(currentField);
+          currentField = '';
+          rows.push(currentRow);
+          currentRow = [];
+          i++;
+        } else if (ch === '\r') {
+          // Handle \r\n
+          if (i + 1 < csv.length && csv[i + 1] === '\n') {
+            i++;
+          }
+          currentRow.push(currentField);
+          currentField = '';
+          rows.push(currentRow);
+          currentRow = [];
+          i++;
+        } else {
+          currentField += ch;
+          i++;
+        }
+      }
+    }
+
+    // Push last field and row
+    if (currentField || currentRow.length > 0) {
+      currentRow.push(currentField);
+      rows.push(currentRow);
+    }
+
+    if (rows.length === 0) return new Table(0, 0, formatting);
+    return Table.fromArray(rows, formatting);
+  }
+
+  /**
+   * Creates a new table with rows and columns swapped
+   *
+   * Returns a new Table where the original rows become columns and columns
+   * become rows. Cell text content is preserved; cell formatting from the
+   * source is deep-cloned to the transposed position. The original table
+   * is not modified.
+   *
+   * For non-rectangular tables (rows with different cell counts), the
+   * result is padded to the longest row's length with empty cells.
+   *
+   * @returns New Table with transposed data
+   *
+   * @example
+   * ```typescript
+   * const table = Table.fromArray([
+   *   ['Name', 'Alice', 'Bob'],
+   *   ['Age',  '30',    '25'],
+   * ]);
+   * const transposed = table.transpose();
+   * transposed.toArray();
+   * // [['Name', 'Age'], ['Alice', '30'], ['Bob', '25']]
+   * ```
+   */
+  transpose(): Table {
+    const srcRows = this.rows.length;
+    if (srcRows === 0) return new Table(0, 0);
+
+    const srcCols = this.getColumnCount();
+    if (srcCols === 0) return new Table(0, 0);
+
+    const transposed = new Table(0, 0);
+
+    for (let c = 0; c < srcCols; c++) {
+      const newRow = new TableRow();
+      for (let r = 0; r < srcRows; r++) {
+        const srcCell = this.getCell(r, c);
+        if (srcCell) {
+          newRow.addCell(srcCell.clone());
+        } else {
+          newRow.createCell();
+        }
+      }
+      transposed.addRow(newRow);
+    }
+
+    return transposed;
+  }
+
   /**
    * Creates a deep clone of this table
    *
@@ -2487,33 +3251,58 @@ export class Table {
    * ```
    */
   clone(): Table {
-    // Clone formatting
     const clonedFormatting: TableFormatting = deepClone(this.formatting);
-
-    // Create new table with same structure
     const clonedTable = new Table(0, 0, clonedFormatting);
 
-    // Clone all rows
     for (const row of this.rows) {
-      // Clone row by creating new cells with same content
-      const cells = row.getCells();
-      const clonedRow = new TableRow(0);
+      clonedTable.addRow(row.clone());
+    }
 
-      for (const cell of cells) {
-        const cellFormatting = cell.getFormatting();
-        const clonedCell = new TableCell(deepClone(cellFormatting));
+    return clonedTable;
+  }
 
-        // Clone paragraphs in cell
-        for (const para of cell.getParagraphs()) {
-          clonedCell.addParagraph(para.clone());
-        }
+  /**
+   * Duplicates a row at the given index, inserting copies after it
+   *
+   * Creates deep clones of the specified row (including all cell content,
+   * formatting, and merged cell spans) and inserts them immediately after
+   * the source row. Useful for template-based document generation where
+   * a styled row needs to be repeated with different data.
+   *
+   * @param rowIndex - Index of the row to duplicate (0-based)
+   * @param count - Number of copies to insert (default 1)
+   * @returns Array of the newly inserted rows
+   * @throws RangeError if rowIndex is out of bounds
+   *
+   * @example
+   * ```typescript
+   * // Create a table with a header and one data row
+   * const table = new Table(2, 3);
+   * table.getCell(0, 0)?.createParagraph('Name');
+   * table.getCell(1, 0)?.createParagraph('Alice');
+   *
+   * // Duplicate the data row twice for more entries
+   * const [row2, row3] = table.duplicateRow(1, 2);
+   * row2.getCell(0)?.getParagraphs()[0]?.setText('Bob');
+   * row3.getCell(0)?.getParagraphs()[0]?.setText('Charlie');
+   * ```
+   */
+  duplicateRow(rowIndex: number, count = 1): TableRow[] {
+    if (rowIndex < 0 || rowIndex >= this.rows.length) {
+      throw new RangeError(`Row index ${rowIndex} is out of bounds (0-${this.rows.length - 1})`);
+    }
+    if (count < 1) return [];
 
-        clonedRow.addCell(clonedCell);
-      }
+    const sourceRow = this.rows[rowIndex]!;
+    const inserted: TableRow[] = [];
 
-      clonedTable.addRow(clonedRow);
+    for (let i = 0; i < count; i++) {
+      const clonedRow = sourceRow.clone();
+      this.rows.splice(rowIndex + 1 + i, 0, clonedRow);
+      clonedRow._setParentTable(this);
+      inserted.push(clonedRow);
     }
 
-    return clonedTable;
+    return inserted;
   }
 }