@lotics/docx 0.1.0

package/src/roundtrip.test.ts

@@ -0,0 +1,179 @@
+import { describe, it, expect } from "vitest";
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import {
+  createBlankDocx,
+  saveDocxToBuffer,
+  appendElement,
+} from "@lotics/ooxml/document";
+import { buildRun } from "@lotics/ooxml/builders";
+import type { XmlElement } from "@lotics/ooxml/xml";
+import { parseDocx } from "./parse/parser";
+import { serializeDocx } from "./serialize/serializer";
+import type { DocxDocument } from "./model/types";
+
+const FIXTURES_DIR = path.join(
+  path.dirname(fileURLToPath(import.meta.url)),
+  "fixtures",
+);
+
+function paragraph(children: XmlElement[]): XmlElement {
+  return { "w:p": children };
+}
+
+async function buildSampleDocx(): Promise<Uint8Array> {
+  const doc = createBlankDocx();
+
+  appendElement(doc, paragraph([buildRun("Hello world")]));
+  appendElement(doc, paragraph([buildRun("Bold text", { bold: true })]));
+  appendElement(
+    doc,
+    paragraph([
+      buildRun("Mixed: "),
+      buildRun("italic ", { italic: true }),
+      buildRun("and "),
+      buildRun("bold", { bold: true }),
+      buildRun(" together"),
+    ]),
+  );
+  appendElement(doc, paragraph([]));
+  appendElement(doc, paragraph([buildRun("  leading and trailing spaces  ")]));
+
+  const buffer = await saveDocxToBuffer(doc);
+  return new Uint8Array(buffer);
+}
+
+async function loadFixtures(): Promise<{ name: string; bytes: Uint8Array }[]> {
+  let entries: string[];
+  try {
+    entries = await fs.readdir(FIXTURES_DIR);
+  } catch {
+    return [];
+  }
+  const out: { name: string; bytes: Uint8Array }[] = [];
+  for (const name of entries) {
+    if (!name.endsWith(".docx")) continue;
+    const bytes = await fs.readFile(path.join(FIXTURES_DIR, name));
+    out.push({ name, bytes: new Uint8Array(bytes) });
+  }
+  return out;
+}
+
+function assertModelStable(original: DocxDocument, roundtripped: DocxDocument): void {
+  expect(roundtripped.documentAttrs).toEqual(original.documentAttrs);
+  expect(roundtripped.body).toEqual(original.body);
+}
+
+function assertNonDocumentPartsIdentical(
+  original: DocxDocument,
+  roundtripped: DocxDocument,
+): void {
+  for (const [path, originalBytes] of original.parts) {
+    if (path === "word/document.xml") continue;
+    const newBytes = roundtripped.parts.get(path);
+    expect(newBytes, `missing part ${path} after roundtrip`).toBeDefined();
+    expect(
+      Buffer.from(newBytes!).equals(Buffer.from(originalBytes)),
+      `part ${path} differs after roundtrip`,
+    ).toBe(true);
+  }
+}
+
+describe("docx roundtrip — programmatic fixture", () => {
+  it("preserves document model and non-document parts", async () => {
+    const bytes = await buildSampleDocx();
+    const original = await parseDocx(bytes);
+
+    const reEmitted = await serializeDocx(original);
+    const roundtripped = await parseDocx(reEmitted);
+
+    assertModelStable(original, roundtripped);
+    assertNonDocumentPartsIdentical(original, roundtripped);
+  });
+
+  it("parses paragraphs, runs, and text with preserveSpace", async () => {
+    const bytes = await buildSampleDocx();
+    const doc = await parseDocx(bytes);
+
+    expect(doc.body.children).toHaveLength(6);
+
+    const para0 = doc.body.children[0];
+    expect(para0.kind).toBe("paragraph");
+    if (para0.kind !== "paragraph") return;
+    expect(para0.content).toHaveLength(1);
+    const run0 = para0.content[0];
+    expect(run0.kind).toBe("run");
+    if (run0.kind !== "run") return;
+    expect(run0.content[0]).toEqual({
+      kind: "text",
+      value: "Hello world",
+      preserveSpace: true,
+    });
+
+    const empty = doc.body.children[3];
+    expect(empty.kind).toBe("paragraph");
+    if (empty.kind !== "paragraph") return;
+    expect(empty.content).toHaveLength(0);
+
+    const last = doc.body.children[5];
+    expect(last.kind).toBe("body_sect_pr");
+  });
+});
+
+describe("docx roundtrip — file fixtures", () => {
+  it("roundtrips every .docx in src/fixtures/", async () => {
+    const fixtures = await loadFixtures();
+    if (fixtures.length === 0) {
+      // No fixtures yet — Phase 0 ships the harness; fixtures land as we
+      // collect real-world .docx files in later phases.
+      return;
+    }
+    for (const fixture of fixtures) {
+      const original = await parseDocx(fixture.bytes);
+      const reEmitted = await serializeDocx(original);
+      const roundtripped = await parseDocx(reEmitted);
+
+      assertModelStable(original, roundtripped);
+      assertNonDocumentPartsIdentical(original, roundtripped);
+    }
+  });
+
+  it("never produces opaque #text nodes from pretty-printed XML whitespace", async () => {
+    const fixtures = await loadFixtures();
+    for (const fixture of fixtures) {
+      const doc = await parseDocx(fixture.bytes);
+      assertNoTextOnlyOpaques(doc, fixture.name);
+    }
+  });
+});
+
+function assertNoTextOnlyOpaques(doc: DocxDocument, fixtureName: string): void {
+  for (const block of doc.body.children) {
+    if (block.kind === "opaque_block") {
+      assertNotTextOnly(block.xml, `${fixtureName}: body block`);
+      continue;
+    }
+    if (block.kind !== "paragraph") continue;
+    for (const inline of block.content) {
+      if (inline.kind === "opaque_inline") {
+        assertNotTextOnly(inline.xml, `${fixtureName}: paragraph inline`);
+        continue;
+      }
+      if (inline.kind !== "run") continue;
+      for (const rc of inline.content) {
+        if (rc.kind === "opaque_run_child") {
+          assertNotTextOnly(rc.xml, `${fixtureName}: run child`);
+        }
+      }
+    }
+  }
+}
+
+function assertNotTextOnly(xml: XmlElement, where: string): void {
+  const keys = Object.keys(xml).filter((k) => k !== ":@");
+  expect(
+    keys,
+    `${where}: #text-only opaque node — insignificant whitespace leaked into the model`,
+  ).not.toEqual(["#text"]);
+}

package/src/serialize/default_parts.ts

@@ -0,0 +1,128 @@
+/**
+ * Fabricate the minimal set of OOXML parts so a from-scratch document
+ * (parts: empty Map) round-trips into a valid Word-openable .docx.
+ *
+ * Inserted only when the corresponding path is missing from the provided
+ * parts map — never overrides an explicit definition.
+ */
+
+const encoder = new TextEncoder();
+
+const CONTENT_TYPES_XML = `<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
+<Types xmlns="http://schemas.openxmlformats.org/package/2006/content-types">
+  <Default Extension="rels" ContentType="application/vnd.openxmlformats-package.relationships+xml"/>
+  <Default Extension="xml" ContentType="application/xml"/>
+  <Default Extension="png" ContentType="image/png"/>
+  <Default Extension="jpg" ContentType="image/jpeg"/>
+  <Default Extension="jpeg" ContentType="image/jpeg"/>
+  <Default Extension="gif" ContentType="image/gif"/>
+  <Default Extension="webp" ContentType="image/webp"/>
+  <Override PartName="/word/document.xml" ContentType="application/vnd.openxmlformats-officedocument.wordprocessingml.document.main+xml"/>
+  <Override PartName="/word/styles.xml" ContentType="application/vnd.openxmlformats-officedocument.wordprocessingml.styles+xml"/>
+  <Override PartName="/word/numbering.xml" ContentType="application/vnd.openxmlformats-officedocument.wordprocessingml.numbering+xml"/>
+  <Override PartName="/word/theme/theme1.xml" ContentType="application/vnd.openxmlformats-officedocument.theme+xml"/>
+  <Override PartName="/word/settings.xml" ContentType="application/vnd.openxmlformats-officedocument.wordprocessingml.settings+xml"/>
+  <Override PartName="/word/fontTable.xml" ContentType="application/vnd.openxmlformats-officedocument.wordprocessingml.fontTable+xml"/>
+</Types>`;
+
+const PACKAGE_RELS_XML = `<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
+<Relationships xmlns="http://schemas.openxmlformats.org/package/2006/relationships">
+  <Relationship Id="rId1" Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/officeDocument" Target="word/document.xml"/>
+</Relationships>`;
+
+const DOCUMENT_RELS_XML = `<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
+<Relationships xmlns="http://schemas.openxmlformats.org/package/2006/relationships">
+  <Relationship Id="rId1" Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/styles" Target="styles.xml"/>
+  <Relationship Id="rId2" Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/numbering" Target="numbering.xml"/>
+  <Relationship Id="rId3" Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/theme" Target="theme/theme1.xml"/>
+  <Relationship Id="rId4" Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/settings" Target="settings.xml"/>
+  <Relationship Id="rId5" Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/fontTable" Target="fontTable.xml"/>
+</Relationships>`;
+
+const STYLES_XML = `<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
+<w:styles xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main">
+  <w:docDefaults>
+    <w:rPrDefault><w:rPr><w:rFonts w:ascii="Calibri" w:hAnsi="Calibri" w:cs="Calibri"/><w:sz w:val="22"/><w:szCs w:val="22"/></w:rPr></w:rPrDefault>
+    <w:pPrDefault><w:pPr><w:spacing w:after="160" w:line="276" w:lineRule="auto"/></w:pPr></w:pPrDefault>
+  </w:docDefaults>
+  <w:style w:type="paragraph" w:default="1" w:styleId="Normal"><w:name w:val="Normal"/><w:qFormat/></w:style>
+  <w:style w:type="paragraph" w:styleId="Title"><w:name w:val="Title"/><w:basedOn w:val="Normal"/><w:next w:val="Normal"/><w:qFormat/><w:pPr><w:spacing w:before="0" w:after="80"/></w:pPr><w:rPr><w:rFonts w:ascii="Calibri Light" w:hAnsi="Calibri Light"/><w:sz w:val="56"/></w:rPr></w:style>
+  <w:style w:type="paragraph" w:styleId="Subtitle"><w:name w:val="Subtitle"/><w:basedOn w:val="Normal"/><w:next w:val="Normal"/><w:qFormat/><w:rPr><w:i/><w:color w:val="595959"/><w:sz w:val="28"/></w:rPr></w:style>
+  <w:style w:type="paragraph" w:styleId="Heading1"><w:name w:val="heading 1"/><w:basedOn w:val="Normal"/><w:next w:val="Normal"/><w:qFormat/><w:pPr><w:keepNext/><w:keepLines/><w:spacing w:before="240" w:after="0"/><w:outlineLvl w:val="0"/></w:pPr><w:rPr><w:rFonts w:ascii="Calibri Light" w:hAnsi="Calibri Light"/><w:b/><w:color w:val="2E74B5"/><w:sz w:val="32"/></w:rPr></w:style>
+  <w:style w:type="paragraph" w:styleId="Heading2"><w:name w:val="heading 2"/><w:basedOn w:val="Normal"/><w:next w:val="Normal"/><w:qFormat/><w:pPr><w:keepNext/><w:keepLines/><w:spacing w:before="160" w:after="0"/><w:outlineLvl w:val="1"/></w:pPr><w:rPr><w:rFonts w:ascii="Calibri Light" w:hAnsi="Calibri Light"/><w:b/><w:color w:val="2E74B5"/><w:sz w:val="26"/></w:rPr></w:style>
+  <w:style w:type="paragraph" w:styleId="Heading3"><w:name w:val="heading 3"/><w:basedOn w:val="Normal"/><w:next w:val="Normal"/><w:qFormat/><w:pPr><w:keepNext/><w:keepLines/><w:spacing w:before="160" w:after="0"/><w:outlineLvl w:val="2"/></w:pPr><w:rPr><w:rFonts w:ascii="Calibri Light" w:hAnsi="Calibri Light"/><w:b/><w:color w:val="1F4E79"/><w:sz w:val="24"/></w:rPr></w:style>
+  <w:style w:type="paragraph" w:styleId="Quote"><w:name w:val="Quote"/><w:basedOn w:val="Normal"/><w:next w:val="Normal"/><w:qFormat/><w:pPr><w:ind w:left="360" w:right="360"/><w:spacing w:before="160" w:after="160"/></w:pPr><w:rPr><w:i/><w:color w:val="404040"/></w:rPr></w:style>
+  <w:style w:type="paragraph" w:styleId="Code"><w:name w:val="Code"/><w:basedOn w:val="Normal"/><w:next w:val="Normal"/><w:qFormat/><w:rPr><w:rFonts w:ascii="Consolas" w:hAnsi="Consolas"/><w:sz w:val="20"/></w:rPr></w:style>
+</w:styles>`;
+
+const NUMBERING_XML = `<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
+<w:numbering xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main">
+  <w:abstractNum w:abstractNumId="0">
+    <w:lvl w:ilvl="0"><w:start w:val="1"/><w:numFmt w:val="bullet"/><w:lvlText w:val="•"/><w:lvlJc w:val="left"/><w:pPr><w:ind w:left="720" w:hanging="360"/></w:pPr></w:lvl>
+  </w:abstractNum>
+  <w:abstractNum w:abstractNumId="1">
+    <w:lvl w:ilvl="0"><w:start w:val="1"/><w:numFmt w:val="decimal"/><w:lvlText w:val="%1."/><w:lvlJc w:val="left"/><w:pPr><w:ind w:left="720" w:hanging="360"/></w:pPr></w:lvl>
+  </w:abstractNum>
+  <w:num w:numId="1"><w:abstractNumId w:val="0"/></w:num>
+  <w:num w:numId="2"><w:abstractNumId w:val="1"/></w:num>
+</w:numbering>`;
+
+const SETTINGS_XML = `<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
+<w:settings xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main">
+  <w:defaultTabStop w:val="720"/>
+  <w:characterSpacingControl w:val="doNotCompress"/>
+</w:settings>`;
+
+const FONT_TABLE_XML = `<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
+<w:fonts xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main">
+  <w:font w:name="Calibri"><w:family w:val="swiss"/></w:font>
+  <w:font w:name="Calibri Light"><w:family w:val="swiss"/></w:font>
+  <w:font w:name="Consolas"><w:family w:val="modern"/></w:font>
+</w:fonts>`;
+
+const THEME_XML = `<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
+<a:theme xmlns:a="http://schemas.openxmlformats.org/drawingml/2006/main" name="Office">
+  <a:themeElements>
+    <a:clrScheme name="Office">
+      <a:dk1><a:sysClr val="windowText" lastClr="000000"/></a:dk1>
+      <a:lt1><a:sysClr val="window" lastClr="FFFFFF"/></a:lt1>
+      <a:dk2><a:srgbClr val="44546A"/></a:dk2>
+      <a:lt2><a:srgbClr val="E7E6E6"/></a:lt2>
+      <a:accent1><a:srgbClr val="5B9BD5"/></a:accent1>
+      <a:accent2><a:srgbClr val="ED7D31"/></a:accent2>
+      <a:accent3><a:srgbClr val="A5A5A5"/></a:accent3>
+      <a:accent4><a:srgbClr val="FFC000"/></a:accent4>
+      <a:accent5><a:srgbClr val="4472C4"/></a:accent5>
+      <a:accent6><a:srgbClr val="70AD47"/></a:accent6>
+      <a:hlink><a:srgbClr val="0563C1"/></a:hlink>
+      <a:folHlink><a:srgbClr val="954F72"/></a:folHlink>
+    </a:clrScheme>
+    <a:fontScheme name="Office">
+      <a:majorFont><a:latin typeface="Calibri Light"/><a:ea typeface=""/><a:cs typeface=""/></a:majorFont>
+      <a:minorFont><a:latin typeface="Calibri"/><a:ea typeface=""/><a:cs typeface=""/></a:minorFont>
+    </a:fontScheme>
+    <a:fmtScheme name="Office"/>
+  </a:themeElements>
+</a:theme>`;
+
+export const DEFAULT_PARTS: ReadonlyArray<readonly [string, () => Uint8Array]> = [
+  ["[Content_Types].xml", () => encoder.encode(CONTENT_TYPES_XML)],
+  ["_rels/.rels", () => encoder.encode(PACKAGE_RELS_XML)],
+  ["word/_rels/document.xml.rels", () => encoder.encode(DOCUMENT_RELS_XML)],
+  ["word/styles.xml", () => encoder.encode(STYLES_XML)],
+  ["word/numbering.xml", () => encoder.encode(NUMBERING_XML)],
+  ["word/settings.xml", () => encoder.encode(SETTINGS_XML)],
+  ["word/fontTable.xml", () => encoder.encode(FONT_TABLE_XML)],
+  ["word/theme/theme1.xml", () => encoder.encode(THEME_XML)],
+];
+
+export function fillDefaultParts(
+  parts: Map<string, Uint8Array>,
+): Map<string, Uint8Array> {
+  for (const [path, makeBytes] of DEFAULT_PARTS) {
+    if (!parts.has(path)) {
+      parts.set(path, makeBytes());
+    }
+  }
+  return parts;
+}

package/src/serialize/header_footer_pm.ts

@@ -0,0 +1,82 @@
+import type { Node as PMNode } from "prosemirror-model";
+import { buildXml, type XmlElement } from "@lotics/ooxml/xml";
+import type { Block, Paragraph, Run, RunChild, TextNode } from "../model/types";
+import { pmDocToHeaderFooterBlocks } from "../pm/pm_to_docx";
+
+const W_NS = "http://schemas.openxmlformats.org/wordprocessingml/2006/main";
+
+/**
+ * Serialize a header/footer PM doc to the OOXML w:hdr / w:ftr part.
+ *
+ * Reuses the same Paragraph/Run/Table builders as the body via
+ * pmDocToHeaderFooterBlocks, so tables, marks, opaque pass-through, and run
+ * properties all round-trip with no fidelity loss compared to the body.
+ */
+export function pmDocToHeaderFooterXml(
+  pmDoc: PMNode,
+  kind: "hdr" | "ftr",
+): string {
+  const blocks = pmDocToHeaderFooterBlocks(pmDoc);
+  const children = blocks.map(serializeBlock);
+  const root: XmlElement = {
+    [`w:${kind}`]: children,
+    ":@": { "@_xmlns:w": W_NS },
+  };
+  return buildXml([root]);
+}
+
+function serializeBlock(block: Block): XmlElement {
+  switch (block.kind) {
+    case "paragraph":
+      return serializeParagraph(block);
+    case "opaque_block":
+      return block.xml;
+    case "body_sect_pr":
+      return block.xml;
+  }
+}
+
+function serializeParagraph(p: Paragraph): XmlElement {
+  const children: XmlElement[] = [];
+  if (p.properties !== null) {
+    children.push({ "w:pPr": [...p.properties] });
+  }
+  for (const inline of p.content) {
+    if (inline.kind === "run") {
+      children.push(serializeRun(inline));
+    } else {
+      children.push(inline.xml);
+    }
+  }
+  return { "w:p": children };
+}
+
+function serializeRun(r: Run): XmlElement {
+  const children: XmlElement[] = [];
+  if (r.properties !== null) {
+    children.push({ "w:rPr": [...r.properties] });
+  }
+  for (const child of r.content) {
+    children.push(serializeRunChild(child));
+  }
+  return { "w:r": children };
+}
+
+function serializeRunChild(child: RunChild): XmlElement {
+  switch (child.kind) {
+    case "text":
+      return serializeText(child);
+    case "opaque_run_child":
+      return child.xml;
+  }
+}
+
+function serializeText(t: TextNode): XmlElement {
+  const el: XmlElement = {
+    "w:t": t.value === "" ? [] : [{ "#text": t.value }],
+  };
+  if (t.preserveSpace) {
+    el[":@"] = { "@_xml:space": "preserve" };
+  }
+  return el;
+}

package/src/serialize/serializer.ts

@@ -0,0 +1,114 @@
+import JSZip from "jszip";
+import { buildXml, type XmlElement } from "@lotics/ooxml/xml";
+import type {
+  Block,
+  Body,
+  DocxDocument,
+  Inline,
+  Paragraph,
+  Run,
+  RunChild,
+  TextNode,
+} from "../model/types";
+import { fillDefaultParts } from "./default_parts";
+
+export async function serializeDocx(doc: DocxDocument): Promise<Uint8Array> {
+  const zip = new JSZip();
+
+  // Fabricate any missing structural parts so the resulting .docx is
+  // openable in Word even when the source is fully synthetic (e.g. a
+  // hand-built demo doc with parts: empty Map).
+  const parts = fillDefaultParts(new Map(doc.parts));
+
+  for (const [path, bytes] of parts) {
+    if (path === "word/document.xml") continue;
+    zip.file(path, bytes);
+  }
+
+  const documentXml = serializeDocumentXml(doc);
+  zip.file("word/document.xml", documentXml);
+
+  const out = await zip.generateAsync({
+    type: "uint8array",
+    compression: "DEFLATE",
+  });
+  return out;
+}
+
+function serializeDocumentXml(doc: DocxDocument): string {
+  const bodyChildren = serializeBody(doc.body);
+  const documentEl: XmlElement = {
+    "w:document": [{ "w:body": bodyChildren }],
+    ":@": { ...doc.documentAttrs },
+  };
+  return buildXml([documentEl]);
+}
+
+function serializeBody(body: Body): XmlElement[] {
+  const out: XmlElement[] = [];
+  for (const block of body.children) {
+    out.push(serializeBlock(block));
+  }
+  return out;
+}
+
+function serializeBlock(block: Block): XmlElement {
+  switch (block.kind) {
+    case "paragraph":
+      return serializeParagraph(block);
+    case "body_sect_pr":
+      return block.xml;
+    case "opaque_block":
+      return block.xml;
+  }
+}
+
+function serializeParagraph(p: Paragraph): XmlElement {
+  const children: XmlElement[] = [];
+  if (p.properties !== null) {
+    children.push({ "w:pPr": [...p.properties] });
+  }
+  for (const inline of p.content) {
+    children.push(serializeInline(inline));
+  }
+  return { "w:p": children };
+}
+
+function serializeInline(inline: Inline): XmlElement {
+  switch (inline.kind) {
+    case "run":
+      return serializeRun(inline);
+    case "opaque_inline":
+      return inline.xml;
+  }
+}
+
+function serializeRun(r: Run): XmlElement {
+  const children: XmlElement[] = [];
+  if (r.properties !== null) {
+    children.push({ "w:rPr": [...r.properties] });
+  }
+  for (const child of r.content) {
+    children.push(serializeRunChild(child));
+  }
+  return { "w:r": children };
+}
+
+function serializeRunChild(child: RunChild): XmlElement {
+  switch (child.kind) {
+    case "text":
+      return serializeText(child);
+    case "opaque_run_child":
+      return child.xml;
+  }
+}
+
+function serializeText(t: TextNode): XmlElement {
+  const el: XmlElement = {
+    "w:t": t.value === "" ? [] : [{ "#text": t.value }],
+  };
+  if (t.preserveSpace) {
+    el[":@"] = { "@_xml:space": "preserve" };
+  }
+  return el;
+}