@lotics/docx 0.1.0

package/src/pm/table_borders.test.ts

@@ -0,0 +1,117 @@
+import { describe, it, expect } from "vitest";
+import {
+  borderToCss,
+  parseBorders,
+  tableBordersFromTblPr,
+  DEFAULT_TABLE_BORDER,
+} from "./table_borders";
+
+const W_NS = "http://schemas.openxmlformats.org/wordprocessingml/2006/main";
+
+function tblPrWithBorders(
+  borders: Record<string, { val?: string; sz?: string; color?: string }>,
+): import("@lotics/ooxml/xml").XmlElement {
+  const borderEls = Object.entries(borders).map(([tag, attrs]) => ({
+    [`w:${tag}`]: [],
+    ":@": {
+      "@_w:val": attrs.val ?? "single",
+      ...(attrs.sz ? { "@_w:sz": attrs.sz } : {}),
+      ...(attrs.color ? { "@_w:color": attrs.color } : {}),
+    },
+  }));
+  return {
+    "w:tblPr": [{ "w:tblBorders": borderEls }],
+    ":@": { "@_xmlns:w": W_NS },
+  };
+}
+
+describe("parseBorders", () => {
+  it("returns empty object on null input", () => {
+    expect(parseBorders(null)).toEqual({});
+  });
+
+  it("parses single-pt single-style top border", () => {
+    const el = {
+      "w:tblBorders": [
+        {
+          "w:top": [],
+          ":@": { "@_w:val": "single", "@_w:sz": "8", "@_w:color": "FF0000" },
+        },
+      ],
+    };
+    const borders = parseBorders(el as import("@lotics/ooxml/xml").XmlElement);
+    expect(borders.top).toEqual({ style: "single", color: "FF0000", sizePts: 1 });
+  });
+
+  it("treats nil/none as no border", () => {
+    const el = {
+      "w:tblBorders": [{ "w:top": [], ":@": { "@_w:val": "nil" } }],
+    };
+    const borders = parseBorders(el as import("@lotics/ooxml/xml").XmlElement);
+    expect(borders.top).toBeUndefined();
+  });
+
+  it("normalizes start/end aliases to left/right", () => {
+    const el = {
+      "w:tblBorders": [
+        { "w:start": [], ":@": { "@_w:val": "single" } },
+        { "w:end": [], ":@": { "@_w:val": "single" } },
+      ],
+    };
+    const borders = parseBorders(el as import("@lotics/ooxml/xml").XmlElement);
+    expect(borders.left).toBeDefined();
+    expect(borders.right).toBeDefined();
+  });
+
+  it("treats auto color as currentColor (null)", () => {
+    const el = {
+      "w:tblBorders": [
+        { "w:top": [], ":@": { "@_w:val": "single", "@_w:color": "auto" } },
+      ],
+    };
+    const borders = parseBorders(el as import("@lotics/ooxml/xml").XmlElement);
+    expect(borders.top?.color).toBeNull();
+  });
+
+  it("clamps sizePts to a minimum of 0.25", () => {
+    const el = {
+      "w:tblBorders": [{ "w:top": [], ":@": { "@_w:val": "single", "@_w:sz": "0" } }],
+    };
+    const borders = parseBorders(el as import("@lotics/ooxml/xml").XmlElement);
+    expect(borders.top?.sizePts).toBeCloseTo(0.25);
+  });
+});
+
+describe("tableBordersFromTblPr", () => {
+  it("returns empty object when tblPr is null", () => {
+    expect(tableBordersFromTblPr(null)).toEqual({});
+  });
+
+  it("extracts borders from a tblPr element", () => {
+    const el = tblPrWithBorders({
+      top: { val: "single", sz: "12", color: "00FF00" },
+      bottom: { val: "double", sz: "16" },
+    });
+    const borders = tableBordersFromTblPr(el);
+    expect(borders.top?.color).toBe("00FF00");
+    expect(borders.top?.sizePts).toBe(1.5);
+    expect(borders.bottom?.style).toBe("double");
+    expect(borders.bottom?.sizePts).toBe(2);
+  });
+});
+
+describe("borderToCss", () => {
+  it("emits px+style+color shorthand", () => {
+    expect(borderToCss(DEFAULT_TABLE_BORDER)).toBe("1px solid #000000");
+  });
+
+  it("maps double / dotted / dashed styles", () => {
+    expect(borderToCss({ style: "double", color: "000000", sizePts: 1.5 })).toContain("double");
+    expect(borderToCss({ style: "dotted", color: "000000", sizePts: 1 })).toContain("dotted");
+    expect(borderToCss({ style: "dashed", color: "000000", sizePts: 1 })).toContain("dashed");
+  });
+
+  it("falls back to currentColor when color is null", () => {
+    expect(borderToCss({ style: "single", color: null, sizePts: 1 })).toContain("currentColor");
+  });
+});

package/src/pm/table_borders.ts

@@ -0,0 +1,130 @@
+import {
+  getAttr,
+  getChildren,
+  getTagName,
+  type XmlElement,
+} from "@lotics/ooxml/xml";
+
+export type Border = {
+  /**
+   * OOXML border style: single, double, dashed, dotted, etc. The CSS
+   * mapping is in `borderToCss` below.
+   */
+  style: string;
+  /** Hex color (no leading #), or null for "auto" → CSS currentColor. */
+  color: string | null;
+  /** Border width in points. OOXML stores eighths-of-a-point; we convert. */
+  sizePts: number;
+};
+
+export type TableBorders = {
+  top?: Border;
+  left?: Border;
+  bottom?: Border;
+  right?: Border;
+  insideH?: Border;
+  insideV?: Border;
+};
+
+const NONE_STYLES = new Set(["nil", "none"]);
+
+/** Word's default `TableGrid` style: single 0.5pt black on every edge. */
+export const DEFAULT_TABLE_BORDER: Border = {
+  style: "single",
+  color: "000000",
+  sizePts: 0.5,
+};
+
+export const DEFAULT_TABLE_BORDERS: TableBorders = {
+  top: DEFAULT_TABLE_BORDER,
+  left: DEFAULT_TABLE_BORDER,
+  bottom: DEFAULT_TABLE_BORDER,
+  right: DEFAULT_TABLE_BORDER,
+  insideH: DEFAULT_TABLE_BORDER,
+  insideV: DEFAULT_TABLE_BORDER,
+};
+
+function parseBorderEl(el: XmlElement): Border | null {
+  const style = getAttr(el, "w:val") ?? "single";
+  if (NONE_STYLES.has(style)) return null;
+  const colorRaw = getAttr(el, "w:color");
+  const color = !colorRaw || colorRaw === "auto" ? null : colorRaw;
+  const sizeAttr = getAttr(el, "w:sz");
+  const sizePts = sizeAttr
+    ? Math.max(0.25, Number.parseInt(sizeAttr, 10) / 8)
+    : 0.5;
+  return { style, color, sizePts };
+}
+
+/**
+ * Parse the set of borders from a `<w:tblBorders>` or `<w:tcBorders>` element.
+ * Returns an empty object when the element is null; partial coverage is
+ * preserved (e.g. only `top` set).
+ */
+export function parseBorders(borderEl: XmlElement | null): TableBorders {
+  if (!borderEl) return {};
+  const out: TableBorders = {};
+  for (const child of getChildren(borderEl)) {
+    const tag = getTagName(child);
+    const border = parseBorderEl(child);
+    if (!border) continue;
+    if (tag === "w:top") out.top = border;
+    else if (tag === "w:left" || tag === "w:start") out.left = border;
+    else if (tag === "w:bottom") out.bottom = border;
+    else if (tag === "w:right" || tag === "w:end") out.right = border;
+    else if (tag === "w:insideH") out.insideH = border;
+    else if (tag === "w:insideV") out.insideV = border;
+  }
+  return out;
+}
+
+/** Walk a `<w:tblPr>` element and pluck the `<w:tblBorders>` child. */
+export function tableBordersFromTblPr(
+  tblPr: XmlElement | null,
+): TableBorders {
+  if (!tblPr) return {};
+  for (const child of getChildren(tblPr)) {
+    if (getTagName(child) === "w:tblBorders") {
+      return parseBorders(child);
+    }
+  }
+  return {};
+}
+
+/**
+ * Convert a parsed Border to a CSS `border-*: ...;` shorthand value. Maps
+ * common OOXML styles to their CSS equivalents; falls back to `solid`.
+ */
+export function borderToCss(b: Border): string {
+  const cssStyle = (() => {
+    switch (b.style) {
+      case "double":
+      case "doubleWave":
+        return "double";
+      case "dotted":
+      case "dotDash":
+      case "dotDotDash":
+        return "dotted";
+      case "dashed":
+      case "dashSmallGap":
+      case "dashLong":
+        return "dashed";
+      case "wave":
+      case "wavy":
+      case "wavyDouble":
+      case "wavyHeavy":
+        return "wavy";
+      case "thinThickSmallGap":
+      case "thickThinSmallGap":
+        return "ridge";
+      case "single":
+      case "thick":
+      default:
+        return "solid";
+    }
+  })();
+  // 1pt = 1.333… px at 96dpi.
+  const widthPx = Math.max(1, Math.round(b.sizePts * (96 / 72)));
+  const color = b.color ? `#${b.color}` : "currentColor";
+  return `${widthPx}px ${cssStyle} ${color}`;
+}

package/src/pm/table_convert.test.ts

@@ -0,0 +1,221 @@
+import { describe, it, expect } from "vitest";
+import { parseXml } from "@lotics/ooxml/xml";
+import { docxToPm } from "./docx_to_pm";
+import { pmToDocx } from "./pm_to_docx";
+import type { DocxDocument } from "../model/types";
+
+const NS = `xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main"`;
+
+function tableDocx(tableXml: string): DocxDocument {
+  const xml = parseXml(`<w:tbl ${NS}>${tableXml}</w:tbl>`)[0];
+  return {
+    parts: new Map(),
+    documentAttrs: {},
+    body: { children: [{ kind: "opaque_block", xml }] },
+  };
+}
+
+describe("xmlToTableNode — basic structure", () => {
+  it("produces a 2x2 PM table with cell text content", () => {
+    const docx = tableDocx(`
+      <w:tr>
+        <w:tc><w:p><w:r><w:t>A1</w:t></w:r></w:p></w:tc>
+        <w:tc><w:p><w:r><w:t>B1</w:t></w:r></w:p></w:tc>
+      </w:tr>
+      <w:tr>
+        <w:tc><w:p><w:r><w:t>A2</w:t></w:r></w:p></w:tc>
+        <w:tc><w:p><w:r><w:t>B2</w:t></w:r></w:p></w:tc>
+      </w:tr>
+    `);
+    const pm = docxToPm(docx);
+    const table = pm.firstChild!;
+    expect(table.type.name).toBe("table");
+    expect(table.childCount).toBe(2);
+    expect(table.firstChild!.childCount).toBe(2);
+    expect(table.firstChild!.firstChild!.textContent).toBe("A1");
+    expect(table.lastChild!.lastChild!.textContent).toBe("B2");
+  });
+
+  it("preserves marks inside cells", () => {
+    const docx = tableDocx(`
+      <w:tr><w:tc>
+        <w:p><w:r><w:rPr><w:b/></w:rPr><w:t>bold</w:t></w:r></w:p>
+      </w:tc></w:tr>
+    `);
+    const pm = docxToPm(docx);
+    const cell = pm.firstChild!.firstChild!.firstChild!;
+    const para = cell.firstChild!;
+    const text = para.firstChild!;
+    expect(text.marks.map((m) => m.type.name)).toContain("bold");
+  });
+});
+
+describe("xmlToTableNode — gridSpan / vMerge", () => {
+  it("converts gridSpan into colspan", () => {
+    const docx = tableDocx(`
+      <w:tr>
+        <w:tc>
+          <w:tcPr><w:gridSpan w:val="2"/></w:tcPr>
+          <w:p><w:r><w:t>spanning</w:t></w:r></w:p>
+        </w:tc>
+      </w:tr>
+    `);
+    const pm = docxToPm(docx);
+    const cell = pm.firstChild!.firstChild!.firstChild!;
+    expect(cell.attrs.colspan).toBe(2);
+    expect(cell.attrs.gridSpan).toBe(2);
+  });
+
+  it("converts vMerge restart + continue into rowspan", () => {
+    const docx = tableDocx(`
+      <w:tr>
+        <w:tc><w:tcPr><w:vMerge w:val="restart"/></w:tcPr><w:p><w:r><w:t>top</w:t></w:r></w:p></w:tc>
+        <w:tc><w:p/></w:tc>
+      </w:tr>
+      <w:tr>
+        <w:tc><w:tcPr><w:vMerge/></w:tcPr><w:p/></w:tc>
+        <w:tc><w:p/></w:tc>
+      </w:tr>
+      <w:tr>
+        <w:tc><w:tcPr><w:vMerge/></w:tcPr><w:p/></w:tc>
+        <w:tc><w:p/></w:tc>
+      </w:tr>
+    `);
+    const pm = docxToPm(docx);
+    const table = pm.firstChild!;
+    const firstRow = table.firstChild!;
+    const originCell = firstRow.firstChild!;
+    expect(originCell.attrs.rowspan).toBe(3);
+    expect(originCell.attrs.vMerge).toBe("restart");
+    expect(originCell.textContent).toBe("top");
+
+    const secondRow = table.child(1);
+    expect(secondRow.childCount).toBe(1);
+    const thirdRow = table.child(2);
+    expect(thirdRow.childCount).toBe(1);
+  });
+});
+
+describe("xmlToTableNode — cell properties", () => {
+  it("captures borders + shading + vAlign as typed cell attrs", () => {
+    const docx = tableDocx(`
+      <w:tr><w:tc>
+        <w:tcPr>
+          <w:tcBorders>
+            <w:top w:val="single" w:sz="8" w:color="333333"/>
+          </w:tcBorders>
+          <w:shd w:val="clear" w:color="auto" w:fill="EEEEEE"/>
+          <w:vAlign w:val="center"/>
+        </w:tcPr>
+        <w:p><w:r><w:t>x</w:t></w:r></w:p>
+      </w:tc></w:tr>
+    `);
+    const pm = docxToPm(docx);
+    const cell = pm.firstChild!.firstChild!.firstChild!;
+    expect(cell.attrs.vAlign).toBe("center");
+    expect((cell.attrs.shading as { fill: string }).fill).toBe("EEEEEE");
+    const borders = cell.attrs.borders as { top: { color: string; sizePts: number } };
+    expect(borders.top.color).toBe("333333");
+    expect(borders.top.sizePts).toBe(1);
+  });
+});
+
+describe("xmlToTableNode — nested tables", () => {
+  it("recursively converts tables inside cells", () => {
+    const docx = tableDocx(`
+      <w:tr><w:tc>
+        <w:tbl>
+          <w:tr><w:tc><w:p><w:r><w:t>inner</w:t></w:r></w:p></w:tc></w:tr>
+        </w:tbl>
+      </w:tc></w:tr>
+    `);
+    const pm = docxToPm(docx);
+    const cell = pm.firstChild!.firstChild!.firstChild!;
+    const innerTable = cell.firstChild!;
+    expect(innerTable.type.name).toBe("table");
+    expect(innerTable.textContent).toContain("inner");
+  });
+});
+
+describe("tableNodeToXml — roundtrip", () => {
+  function reparse(docx: DocxDocument) {
+    const pm = docxToPm(docx);
+    return pmToDocx(pm, {
+      parts: docx.parts,
+      documentAttrs: docx.documentAttrs,
+    });
+  }
+
+  it("preserves text content through PM → OOXML → PM cycle", () => {
+    const docx = tableDocx(`
+      <w:tr>
+        <w:tc><w:p><w:r><w:t>A1</w:t></w:r></w:p></w:tc>
+        <w:tc><w:p><w:r><w:t>B1</w:t></w:r></w:p></w:tc>
+      </w:tr>
+    `);
+    const round = reparse(docx);
+    const pm = docxToPm(round);
+    expect(pm.firstChild!.textContent).toContain("A1");
+    expect(pm.firstChild!.textContent).toContain("B1");
+  });
+
+  it("preserves rowspan via vMerge restart/continue chain", () => {
+    const docx = tableDocx(`
+      <w:tr>
+        <w:tc><w:tcPr><w:vMerge w:val="restart"/></w:tcPr><w:p><w:r><w:t>top</w:t></w:r></w:p></w:tc>
+        <w:tc><w:p><w:r><w:t>r1c2</w:t></w:r></w:p></w:tc>
+      </w:tr>
+      <w:tr>
+        <w:tc><w:tcPr><w:vMerge/></w:tcPr><w:p/></w:tc>
+        <w:tc><w:p><w:r><w:t>r2c2</w:t></w:r></w:p></w:tc>
+      </w:tr>
+    `);
+    const pm = docxToPm(docx);
+    expect(pm.firstChild!.firstChild!.firstChild!.attrs.rowspan).toBe(2);
+
+    const round = reparse(docx);
+    const pm2 = docxToPm(round);
+    expect(pm2.firstChild!.firstChild!.firstChild!.attrs.rowspan).toBe(2);
+    expect(pm2.firstChild!.firstChild!.firstChild!.textContent).toBe("top");
+  });
+
+  it("preserves colspan via gridSpan", () => {
+    const docx = tableDocx(`
+      <w:tr>
+        <w:tc>
+          <w:tcPr><w:gridSpan w:val="2"/></w:tcPr>
+          <w:p><w:r><w:t>spanning</w:t></w:r></w:p>
+        </w:tc>
+      </w:tr>
+    `);
+    const round = reparse(docx);
+    const pm = docxToPm(round);
+    const cell = pm.firstChild!.firstChild!.firstChild!;
+    expect(cell.attrs.colspan).toBe(2);
+  });
+
+  it("preserves table properties (tblPr) verbatim through roundtrip", () => {
+    const docx = tableDocx(`
+      <w:tblPr>
+        <w:tblStyle w:val="GridTable1Light"/>
+        <w:tblW w:w="5000" w:type="pct"/>
+      </w:tblPr>
+      <w:tblGrid>
+        <w:gridCol w:w="2400"/>
+        <w:gridCol w:w="2400"/>
+      </w:tblGrid>
+      <w:tr>
+        <w:tc><w:p><w:r><w:t>x</w:t></w:r></w:p></w:tc>
+        <w:tc><w:p><w:r><w:t>y</w:t></w:r></w:p></w:tc>
+      </w:tr>
+    `);
+    const round = reparse(docx);
+    const block = round.body.children[0];
+    expect(block.kind).toBe("opaque_block");
+    if (block.kind !== "opaque_block") return;
+    const tblChildren = block.xml["w:tbl"] as Array<Record<string, unknown>>;
+    const tagsAtRoot = tblChildren.map((c) => Object.keys(c).find((k) => k !== ":@"));
+    expect(tagsAtRoot).toContain("w:tblPr");
+    expect(tagsAtRoot).toContain("w:tblGrid");
+  });
+});