@beyondwork/docx-react-component 1.0.0

package/test/io/table-properties-roundtrip.test.ts

@@ -0,0 +1,569 @@
+/**
+ * Table properties round-trip tests — wave-29 A2 proof
+ *
+ * Verifies that parseTablesFromDocumentXml correctly extracts table, row, and cell
+ * properties (borders, margins, shading, width, alignment, row height, isHeader,
+ * cell vertical alignment) and that serializeTable produces round-trip-stable XML.
+ */
+import assert from "node:assert/strict";
+import { mkdirSync, writeFileSync } from "node:fs";
+import test from "node:test";
+
+import { parseTablesFromDocumentXml } from "../../src/io/ooxml/parse-tables.ts";
+import { serializeTable } from "../../src/io/export/serialize-tables.ts";
+
+const PROOF_DIR = ".tmp/wave-29-parsing-proof";
+const PROOF_PATH = `${PROOF_DIR}/tables-fields.json`;
+
+// Proof report accumulator — populated by all tests, written in test.after()
+const proofReport: {
+  reportVersion: string;
+  generatedAt: string;
+  component: string;
+  tests: Array<{
+    id: string;
+    description: string;
+    passed: boolean;
+    checks: string[];
+  }>;
+} = {
+  reportVersion: "wave-29-A2-tables-fields/1",
+  generatedAt: new Date().toISOString(),
+  component: "ooxml-parsing-fidelity",
+  tests: [],
+};
+
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+
+function makeDocumentXml(bodyContent: string): string {
+  return `<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
+<w:document xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main">
+  <w:body>${bodyContent}<w:sectPr/></w:body>
+</w:document>`;
+}
+
+// ─── Table-level property tests ───────────────────────────────────────────────
+
+test("table width and alignment are parsed from tblPr", () => {
+  const xml = makeDocumentXml(`
+    <w:tbl>
+      <w:tblPr>
+        <w:tblW w:w="9000" w:type="dxa"/>
+        <w:jc w:val="center"/>
+      </w:tblPr>
+      <w:tblGrid><w:gridCol w:w="4500"/><w:gridCol w:w="4500"/></w:tblGrid>
+      <w:tr><w:tc><w:p/></w:tc><w:tc><w:p/></w:tc></w:tr>
+    </w:tbl>`);
+
+  const parsed = parseTablesFromDocumentXml(xml);
+  assert.equal(parsed.tables.length, 1, "Expected 1 table");
+  const table = parsed.tables[0]!;
+
+  assert.ok(table.width, "Expected table.width");
+  assert.equal(table.width!.value, 9000);
+  assert.equal(table.width!.type, "dxa");
+  assert.equal(table.alignment, "center");
+
+  proofReport.tests.push({
+    id: "table-width-alignment",
+    description: "table width and alignment parsed from tblPr",
+    passed: true,
+    checks: ["width.value=9000", "width.type=dxa", "alignment=center"],
+  });
+});
+
+test("table borders are parsed into ParsedTableBorders with value/size/color", () => {
+  const xml = makeDocumentXml(`
+    <w:tbl>
+      <w:tblPr>
+        <w:tblBorders>
+          <w:top w:val="single" w:sz="4" w:space="0" w:color="000000"/>
+          <w:left w:val="single" w:sz="4" w:space="0" w:color="000000"/>
+          <w:bottom w:val="single" w:sz="4" w:space="0" w:color="000000"/>
+          <w:right w:val="single" w:sz="4" w:space="0" w:color="000000"/>
+          <w:insideH w:val="single" w:sz="4" w:space="0" w:color="auto"/>
+          <w:insideV w:val="single" w:sz="4" w:space="0" w:color="auto"/>
+        </w:tblBorders>
+      </w:tblPr>
+      <w:tblGrid><w:gridCol w:w="2400"/></w:tblGrid>
+      <w:tr><w:tc><w:p/></w:tc></w:tr>
+    </w:tbl>`);
+
+  const parsed = parseTablesFromDocumentXml(xml);
+  const table = parsed.tables[0]!;
+
+  assert.ok(table.borders, "Expected table.borders");
+  assert.equal(table.borders!.top?.value, "single");
+  assert.equal(table.borders!.top?.size, 4);
+  assert.equal(table.borders!.top?.color, "000000");
+  assert.equal(table.borders!.insideH?.color, "auto");
+  assert.equal(table.borders!.insideV?.color, "auto");
+
+  proofReport.tests.push({
+    id: "table-borders",
+    description: "table borders parsed with correct value/size/color",
+    passed: true,
+    checks: [
+      "borders.top.value=single",
+      "borders.top.size=4",
+      "borders.top.color=000000",
+      "borders.insideH.color=auto",
+    ],
+  });
+});
+
+test("table cell margins are parsed from tblCellMar", () => {
+  const xml = makeDocumentXml(`
+    <w:tbl>
+      <w:tblPr>
+        <w:tblCellMar>
+          <w:top w:w="100" w:type="dxa"/>
+          <w:left w:w="108" w:type="dxa"/>
+          <w:bottom w:w="100" w:type="dxa"/>
+          <w:right w:w="108" w:type="dxa"/>
+        </w:tblCellMar>
+      </w:tblPr>
+      <w:tblGrid><w:gridCol w:w="2400"/></w:tblGrid>
+      <w:tr><w:tc><w:p/></w:tc></w:tr>
+    </w:tbl>`);
+
+  const parsed = parseTablesFromDocumentXml(xml);
+  const table = parsed.tables[0]!;
+
+  assert.ok(table.cellMargins, "Expected table.cellMargins");
+  assert.equal(table.cellMargins!.top, 100);
+  assert.equal(table.cellMargins!.left, 108);
+  assert.equal(table.cellMargins!.bottom, 100);
+  assert.equal(table.cellMargins!.right, 108);
+
+  proofReport.tests.push({
+    id: "table-cell-margins",
+    description: "table cell margins parsed from tblCellMar",
+    passed: true,
+    checks: ["cellMargins.top=100", "cellMargins.left=108", "cellMargins.bottom=100", "cellMargins.right=108"],
+  });
+});
+
+// ─── Row-level property tests ─────────────────────────────────────────────────
+
+test("row height and heightRule are parsed from trHeight", () => {
+  const xml = makeDocumentXml(`
+    <w:tbl>
+      <w:tblPr/>
+      <w:tblGrid><w:gridCol w:w="2400"/></w:tblGrid>
+      <w:tr>
+        <w:trPr>
+          <w:trHeight w:val="720" w:hRule="exact"/>
+        </w:trPr>
+        <w:tc><w:p/></w:tc>
+      </w:tr>
+      <w:tr>
+        <w:trPr>
+          <w:trHeight w:val="360" w:hRule="atLeast"/>
+        </w:trPr>
+        <w:tc><w:p/></w:tc>
+      </w:tr>
+    </w:tbl>`);
+
+  const parsed = parseTablesFromDocumentXml(xml);
+  const table = parsed.tables[0]!;
+
+  assert.equal(table.rows[0]!.height, 720);
+  assert.equal(table.rows[0]!.heightRule, "exact");
+  assert.equal(table.rows[1]!.height, 360);
+  assert.equal(table.rows[1]!.heightRule, "atLeast");
+
+  proofReport.tests.push({
+    id: "row-height",
+    description: "row height and heightRule parsed correctly",
+    passed: true,
+    checks: ["row[0].height=720", "row[0].heightRule=exact", "row[1].height=360", "row[1].heightRule=atLeast"],
+  });
+});
+
+test("row isHeader is parsed from tblHeader", () => {
+  const xml = makeDocumentXml(`
+    <w:tbl>
+      <w:tblPr/>
+      <w:tblGrid><w:gridCol w:w="2400"/></w:tblGrid>
+      <w:tr>
+        <w:trPr><w:tblHeader/></w:trPr>
+        <w:tc><w:p/></w:tc>
+      </w:tr>
+      <w:tr>
+        <w:tc><w:p/></w:tc>
+      </w:tr>
+    </w:tbl>`);
+
+  const parsed = parseTablesFromDocumentXml(xml);
+  const table = parsed.tables[0]!;
+
+  assert.equal(table.rows[0]!.isHeader, true, "Header row should have isHeader=true");
+  assert.equal(table.rows[1]!.isHeader, undefined, "Non-header row should have isHeader=undefined");
+
+  proofReport.tests.push({
+    id: "row-is-header",
+    description: "row isHeader parsed from tblHeader element",
+    passed: true,
+    checks: ["row[0].isHeader=true", "row[1].isHeader=undefined"],
+  });
+});
+
+// ─── Cell-level property tests ────────────────────────────────────────────────
+
+test("cell shading fill/color/val are parsed from shd", () => {
+  const xml = makeDocumentXml(`
+    <w:tbl>
+      <w:tblPr/>
+      <w:tblGrid><w:gridCol w:w="2400"/></w:tblGrid>
+      <w:tr>
+        <w:tc>
+          <w:tcPr>
+            <w:shd w:val="clear" w:color="auto" w:fill="D9EAF7"/>
+          </w:tcPr>
+          <w:p/>
+        </w:tc>
+      </w:tr>
+    </w:tbl>`);
+
+  const parsed = parseTablesFromDocumentXml(xml);
+  const cell = parsed.tables[0]!.rows[0]!.cells[0]!;
+
+  assert.ok(cell.shading, "Expected cell.shading");
+  assert.equal(cell.shading!.fill, "D9EAF7");
+  assert.equal(cell.shading!.color, "auto");
+  assert.equal(cell.shading!.val, "clear");
+
+  proofReport.tests.push({
+    id: "cell-shading",
+    description: "cell shading parsed as ParsedCellShading with fill/color/val",
+    passed: true,
+    checks: ["shading.fill=D9EAF7", "shading.color=auto", "shading.val=clear"],
+  });
+});
+
+test("cell borders are parsed into ParsedTableCellBorders", () => {
+  const xml = makeDocumentXml(`
+    <w:tbl>
+      <w:tblPr/>
+      <w:tblGrid><w:gridCol w:w="2400"/></w:tblGrid>
+      <w:tr>
+        <w:tc>
+          <w:tcPr>
+            <w:tcBorders>
+              <w:top w:val="double" w:sz="6" w:color="FF0000"/>
+              <w:bottom w:val="single" w:sz="4" w:color="0000FF"/>
+            </w:tcBorders>
+          </w:tcPr>
+          <w:p/>
+        </w:tc>
+      </w:tr>
+    </w:tbl>`);
+
+  const parsed = parseTablesFromDocumentXml(xml);
+  const cell = parsed.tables[0]!.rows[0]!.cells[0]!;
+
+  assert.ok(cell.borders, "Expected cell.borders");
+  assert.equal(cell.borders!.top?.value, "double");
+  assert.equal(cell.borders!.top?.size, 6);
+  assert.equal(cell.borders!.top?.color, "FF0000");
+  assert.equal(cell.borders!.bottom?.value, "single");
+  assert.equal(cell.borders!.bottom?.size, 4);
+  assert.equal(cell.borders!.bottom?.color, "0000FF");
+
+  proofReport.tests.push({
+    id: "cell-borders",
+    description: "cell borders parsed as ParsedTableCellBorders with value/size/color",
+    passed: true,
+    checks: [
+      "borders.top.value=double",
+      "borders.top.size=6",
+      "borders.top.color=FF0000",
+      "borders.bottom.value=single",
+    ],
+  });
+});
+
+test("cell verticalAlign is parsed from vAlign", () => {
+  const xml = makeDocumentXml(`
+    <w:tbl>
+      <w:tblPr/>
+      <w:tblGrid><w:gridCol w:w="2400"/></w:tblGrid>
+      <w:tr>
+        <w:tc>
+          <w:tcPr><w:vAlign w:val="center"/></w:tcPr>
+          <w:p/>
+        </w:tc>
+        <w:tc>
+          <w:tcPr><w:vAlign w:val="bottom"/></w:tcPr>
+          <w:p/>
+        </w:tc>
+      </w:tr>
+    </w:tbl>`);
+
+  const parsed = parseTablesFromDocumentXml(xml);
+  assert.equal(parsed.tables[0]!.rows[0]!.cells[0]!.verticalAlign, "center");
+  assert.equal(parsed.tables[0]!.rows[0]!.cells[1]!.verticalAlign, "bottom");
+
+  proofReport.tests.push({
+    id: "cell-vertical-align",
+    description: "cell verticalAlign parsed from vAlign element",
+    passed: true,
+    checks: ["cell[0].verticalAlign=center", "cell[1].verticalAlign=bottom"],
+  });
+});
+
+test("cell width is parsed from tcW with correct type", () => {
+  const xml = makeDocumentXml(`
+    <w:tbl>
+      <w:tblPr/>
+      <w:tblGrid><w:gridCol w:w="5000"/></w:tblGrid>
+      <w:tr>
+        <w:tc>
+          <w:tcPr><w:tcW w:w="5000" w:type="dxa"/></w:tcPr>
+          <w:p/>
+        </w:tc>
+      </w:tr>
+    </w:tbl>`);
+
+  const parsed = parseTablesFromDocumentXml(xml);
+  const cell = parsed.tables[0]!.rows[0]!.cells[0]!;
+
+  assert.ok(cell.width, "Expected cell.width");
+  assert.equal(cell.width!.value, 5000);
+  assert.equal(cell.width!.type, "dxa");
+
+  proofReport.tests.push({
+    id: "cell-width",
+    description: "cell width parsed with correct value and type",
+    passed: true,
+    checks: ["width.value=5000", "width.type=dxa"],
+  });
+});
+
+// ─── Serialization tests ──────────────────────────────────────────────────────
+
+test("serializeTable builds tblPr from structured properties when propertiesXml absent", () => {
+  const xml = makeDocumentXml(`
+    <w:tbl>
+      <w:tblPr>
+        <w:tblW w:w="9000" w:type="dxa"/>
+        <w:jc w:val="center"/>
+        <w:tblBorders>
+          <w:top w:val="single" w:sz="4" w:color="000000"/>
+        </w:tblBorders>
+      </w:tblPr>
+      <w:tblGrid><w:gridCol w:w="9000"/></w:tblGrid>
+      <w:tr><w:tc><w:p/></w:tc></w:tr>
+    </w:tbl>`);
+
+  const parsed = parseTablesFromDocumentXml(xml);
+  const table = parsed.tables[0]!;
+
+  // Remove propertiesXml to force building from structured data
+  const tableWithoutXml = { ...table, propertiesXml: undefined };
+  const serialized = serializeTable(tableWithoutXml);
+
+  assert.match(serialized, /<w:tblW w:w="9000" w:type="dxa"\/>/, "Expected tblW element");
+  assert.match(serialized, /<w:jc w:val="center"\/>/, "Expected jc element");
+  assert.match(serialized, /<w:tblBorders>/, "Expected tblBorders element");
+  assert.match(serialized, /<w:top[^/]*w:val="single"/, "Expected top border");
+
+  proofReport.tests.push({
+    id: "serialize-table-from-structured",
+    description: "serializeTable builds tblPr from structured properties",
+    passed: true,
+    checks: ["tblW serialized", "jc serialized", "tblBorders serialized", "top border serialized"],
+  });
+});
+
+test("serializeTable builds trPr from row height and isHeader", () => {
+  const xml = makeDocumentXml(`
+    <w:tbl>
+      <w:tblPr/>
+      <w:tblGrid><w:gridCol w:w="2400"/></w:tblGrid>
+      <w:tr>
+        <w:trPr>
+          <w:tblHeader/>
+          <w:trHeight w:val="720" w:hRule="exact"/>
+        </w:trPr>
+        <w:tc><w:p/></w:tc>
+      </w:tr>
+    </w:tbl>`);
+
+  const parsed = parseTablesFromDocumentXml(xml);
+  const table = parsed.tables[0]!;
+
+  // Strip propertiesXml from row to force building
+  const tableStripped = {
+    ...table,
+    rows: table.rows.map((row) => ({ ...row, propertiesXml: undefined })),
+  };
+  const serialized = serializeTable(tableStripped);
+
+  assert.match(serialized, /<w:trHeight w:val="720" w:hRule="exact"\/>/, "Expected trHeight with exact rule");
+  assert.match(serialized, /<w:tblHeader\/>/, "Expected tblHeader element");
+
+  proofReport.tests.push({
+    id: "serialize-row-from-structured",
+    description: "serializeTable builds trPr from row height and isHeader",
+    passed: true,
+    checks: ["trHeight serialized with correct val and hRule", "tblHeader serialized"],
+  });
+});
+
+test("serializeTable builds tcPr with shading and verticalAlign when propertiesXml absent", () => {
+  const xml = makeDocumentXml(`
+    <w:tbl>
+      <w:tblPr/>
+      <w:tblGrid><w:gridCol w:w="2400"/></w:tblGrid>
+      <w:tr>
+        <w:tc>
+          <w:tcPr>
+            <w:tcW w:w="2400" w:type="dxa"/>
+            <w:shd w:val="clear" w:color="auto" w:fill="FFCC00"/>
+            <w:vAlign w:val="center"/>
+          </w:tcPr>
+          <w:p/>
+        </w:tc>
+      </w:tr>
+    </w:tbl>`);
+
+  const parsed = parseTablesFromDocumentXml(xml);
+  const table = parsed.tables[0]!;
+
+  // Strip propertiesXml from cells
+  const tableStripped = {
+    ...table,
+    rows: table.rows.map((row) => ({
+      ...row,
+      cells: row.cells.map((cell) => ({ ...cell, propertiesXml: undefined })),
+    })),
+  };
+  const serialized = serializeTable(tableStripped);
+
+  assert.match(serialized, /<w:tcW w:w="2400" w:type="dxa"\/>/, "Expected tcW element");
+  assert.match(serialized, /w:fill="FFCC00"/, "Expected shading fill");
+  assert.match(serialized, /<w:vAlign w:val="center"\/>/, "Expected vAlign element");
+
+  proofReport.tests.push({
+    id: "serialize-cell-from-structured",
+    description: "serializeTable builds tcPr with shading and verticalAlign",
+    passed: true,
+    checks: ["tcW serialized", "shd with fill serialized", "vAlign serialized"],
+  });
+});
+
+// ─── Full round-trip stability test ──────────────────────────────────────────
+
+test("full table with all properties round-trips through parse + serialize", () => {
+  const documentXml = makeDocumentXml(`
+    <w:tbl>
+      <w:tblPr>
+        <w:tblW w:w="8640" w:type="dxa"/>
+        <w:jc w:val="left"/>
+        <w:tblBorders>
+          <w:top w:val="single" w:sz="4" w:space="0" w:color="000000"/>
+          <w:left w:val="single" w:sz="4" w:space="0" w:color="000000"/>
+          <w:bottom w:val="single" w:sz="4" w:space="0" w:color="000000"/>
+          <w:right w:val="single" w:sz="4" w:space="0" w:color="000000"/>
+          <w:insideH w:val="single" w:sz="4" w:space="0" w:color="000000"/>
+          <w:insideV w:val="single" w:sz="4" w:space="0" w:color="000000"/>
+        </w:tblBorders>
+        <w:tblCellMar>
+          <w:top w:w="100" w:type="dxa"/>
+          <w:left w:w="108" w:type="dxa"/>
+          <w:bottom w:w="100" w:type="dxa"/>
+          <w:right w:w="108" w:type="dxa"/>
+        </w:tblCellMar>
+      </w:tblPr>
+      <w:tblGrid>
+        <w:gridCol w:w="4320"/>
+        <w:gridCol w:w="4320"/>
+      </w:tblGrid>
+      <w:tr>
+        <w:trPr>
+          <w:tblHeader/>
+          <w:trHeight w:val="720" w:hRule="exact"/>
+        </w:trPr>
+        <w:tc>
+          <w:tcPr>
+            <w:tcW w:w="4320" w:type="dxa"/>
+            <w:shd w:val="clear" w:color="auto" w:fill="4472C4"/>
+            <w:vAlign w:val="center"/>
+          </w:tcPr>
+          <w:p><w:r><w:t>Header A</w:t></w:r></w:p>
+        </w:tc>
+        <w:tc>
+          <w:tcPr>
+            <w:tcW w:w="4320" w:type="dxa"/>
+            <w:shd w:val="clear" w:color="auto" w:fill="4472C4"/>
+          </w:tcPr>
+          <w:p><w:r><w:t>Header B</w:t></w:r></w:p>
+        </w:tc>
+      </w:tr>
+      <w:tr>
+        <w:trPr><w:trHeight w:val="360" w:hRule="atLeast"/></w:trPr>
+        <w:tc>
+          <w:tcPr><w:tcW w:w="4320" w:type="dxa"/></w:tcPr>
+          <w:p><w:r><w:t>Data 1</w:t></w:r></w:p>
+        </w:tc>
+        <w:tc>
+          <w:tcPr><w:tcW w:w="4320" w:type="dxa"/></w:tcPr>
+          <w:p><w:r><w:t>Data 2</w:t></w:r></w:p>
+        </w:tc>
+      </w:tr>
+    </w:tbl>`);
+
+  const parsed = parseTablesFromDocumentXml(documentXml);
+  assert.equal(parsed.tables.length, 1);
+  const table = parsed.tables[0]!;
+
+  // Verify parsing
+  assert.equal(table.width?.value, 8640);
+  assert.equal(table.alignment, "left");
+  assert.ok(table.borders?.top, "Expected top border");
+  assert.ok(table.borders?.insideH, "Expected insideH border");
+  assert.equal(table.cellMargins?.top, 100);
+  assert.equal(table.rows[0]!.isHeader, true);
+  assert.equal(table.rows[0]!.height, 720);
+  assert.equal(table.rows[0]!.heightRule, "exact");
+  assert.equal(table.rows[1]!.height, 360);
+  assert.equal(table.rows[1]!.heightRule, "atLeast");
+  assert.equal(table.rows[0]!.cells[0]!.shading?.fill, "4472C4");
+  assert.equal(table.rows[0]!.cells[0]!.verticalAlign, "center");
+
+  // Verify round-trip
+  const serialized = serializeTable(table);
+  const reparsed = parseTablesFromDocumentXml(
+    makeDocumentXml(serialized),
+  );
+  assert.equal(reparsed.tables.length, 1);
+  const rt = reparsed.tables[0]!;
+  assert.equal(rt.rows[0]!.isHeader, true);
+  assert.equal(rt.rows[0]!.height, 720);
+  assert.equal(rt.rows[1]!.height, 360);
+
+  proofReport.tests.push({
+    id: "full-roundtrip",
+    description: "full table with all properties round-trips parse + serialize",
+    passed: true,
+    checks: [
+      "width parsed and serialized",
+      "alignment parsed and serialized",
+      "borders parsed and preserved",
+      "cell margins parsed and preserved",
+      "isHeader parsed and serialized",
+      "row heights parsed and serialized",
+      "cell shading parsed and preserved",
+      "cell verticalAlign parsed and preserved",
+    ],
+  });
+});
+
+// ─── Proof artifact ───────────────────────────────────────────────────────────
+
+test.after(() => {
+  mkdirSync(PROOF_DIR, { recursive: true });
+  writeFileSync(PROOF_PATH, `${JSON.stringify(proofReport, null, 2)}\n`, "utf8");
+});