@lotics/docx 0.1.0

package/src/pm/roundtrip.test.ts

@@ -0,0 +1,332 @@
+import { describe, it, expect } from "vitest";
+import { type XmlElement } from "@lotics/ooxml/xml";
+import {
+  createBlankDocx,
+  saveDocxToBuffer,
+  appendElement,
+} from "@lotics/ooxml/document";
+import { buildRun } from "@lotics/ooxml/builders";
+import { parseDocx } from "../parse/parser";
+import { serializeDocx } from "../serialize/serializer";
+import { docxToPm } from "./docx_to_pm";
+import { pmToDocx } from "./pm_to_docx";
+import type { DocxDocument } from "../model/types";
+
+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("plain "),
+      buildRun("bold", { bold: true }),
+      buildRun(" "),
+      buildRun("italic", { italic: true }),
+      buildRun(" "),
+      buildRun("both", { bold: true, italic: true }),
+    ]),
+  );
+  appendElement(doc, paragraph([]));
+  appendElement(
+    doc,
+    paragraph([buildRun("  spaces preserved  ")]),
+  );
+  const buffer = await saveDocxToBuffer(doc);
+  return new Uint8Array(buffer);
+}
+
+function flattenText(docx: DocxDocument): string {
+  let out = "";
+  for (const block of docx.body.children) {
+    if (block.kind !== "paragraph") continue;
+    for (const inline of block.content) {
+      if (inline.kind !== "run") continue;
+      for (const child of inline.content) {
+        if (child.kind === "text") out += child.value;
+      }
+    }
+    out += "\n";
+  }
+  return out;
+}
+
+function blockKinds(docx: DocxDocument): string[] {
+  return docx.body.children.map((b) => b.kind);
+}
+
+describe("docxToPm → pmToDocx roundtrip", () => {
+  it("preserves block structure and text content", async () => {
+    const original = await parseDocx(await buildSampleDocx());
+    const pm = docxToPm(original);
+    const reconstructed = pmToDocx(pm, {
+      parts: original.parts,
+      documentAttrs: original.documentAttrs,
+    });
+    expect(blockKinds(reconstructed)).toEqual(blockKinds(original));
+    expect(flattenText(reconstructed)).toBe(flattenText(original));
+  });
+
+  it("preserves bold/italic marks via re-emission to <w:b/>/<w:i/>", async () => {
+    const original = await parseDocx(await buildSampleDocx());
+    const pm = docxToPm(original);
+    const reconstructed = pmToDocx(pm, {
+      parts: original.parts,
+      documentAttrs: original.documentAttrs,
+    });
+
+    const findText = (text: string) => {
+      for (const block of reconstructed.body.children) {
+        if (block.kind !== "paragraph") continue;
+        for (const inline of block.content) {
+          if (inline.kind !== "run") continue;
+          for (const child of inline.content) {
+            if (child.kind === "text" && child.value === text) {
+              return inline;
+            }
+          }
+        }
+      }
+      return null;
+    };
+
+    const boldRun = findText("bold");
+    expect(boldRun).not.toBeNull();
+    if (boldRun?.kind === "run") {
+      const tags = (boldRun.properties ?? []).map(
+        (el) => Object.keys(el).find((k) => k !== ":@")!,
+      );
+      expect(tags).toContain("w:b");
+    }
+
+    const bothRun = findText("both");
+    if (bothRun?.kind === "run") {
+      const tags = (bothRun.properties ?? []).map(
+        (el) => Object.keys(el).find((k) => k !== ":@")!,
+      );
+      expect(tags).toContain("w:b");
+      expect(tags).toContain("w:i");
+    }
+  });
+
+  it("merges PM text segments with identical marks into single runs", async () => {
+    const original = await parseDocx(await buildSampleDocx());
+    const pm = docxToPm(original);
+    const reconstructed = pmToDocx(pm, {
+      parts: original.parts,
+      documentAttrs: original.documentAttrs,
+    });
+
+    const para = reconstructed.body.children[1];
+    expect(para.kind).toBe("paragraph");
+    if (para.kind !== "paragraph") return;
+
+    let runCount = 0;
+    for (const inline of para.content) {
+      if (inline.kind === "run") runCount += 1;
+    }
+    expect(runCount).toBeGreaterThanOrEqual(5);
+  });
+
+  it("preserves preserveSpace flag on text with leading/trailing whitespace", async () => {
+    const original = await parseDocx(await buildSampleDocx());
+    const pm = docxToPm(original);
+    const reconstructed = pmToDocx(pm, {
+      parts: original.parts,
+      documentAttrs: original.documentAttrs,
+    });
+
+    let foundSpaced = false;
+    for (const block of reconstructed.body.children) {
+      if (block.kind !== "paragraph") continue;
+      for (const inline of block.content) {
+        if (inline.kind !== "run") continue;
+        for (const child of inline.content) {
+          if (
+            child.kind === "text" &&
+            child.value === "  spaces preserved  "
+          ) {
+            expect(child.preserveSpace).toBe(true);
+            foundSpaced = true;
+          }
+        }
+      }
+    }
+    expect(foundSpaced).toBe(true);
+  });
+
+  it("produces serializable output that re-parses to an equivalent model", async () => {
+    const original = await parseDocx(await buildSampleDocx());
+    const pm = docxToPm(original);
+    const reconstructed = pmToDocx(pm, {
+      parts: original.parts,
+      documentAttrs: original.documentAttrs,
+    });
+
+    const bytes = await serializeDocx(reconstructed);
+    const reparsed = await parseDocx(bytes);
+
+    expect(blockKinds(reparsed)).toEqual(blockKinds(original));
+    expect(flattenText(reparsed)).toBe(flattenText(original));
+  });
+
+  it("preserves the body-level final sectPr through PM and back", async () => {
+    const original = await parseDocx(await buildSampleDocx());
+    const pm = docxToPm(original);
+    const reconstructed = pmToDocx(pm, {
+      parts: original.parts,
+      documentAttrs: original.documentAttrs,
+    });
+
+    const lastBlock =
+      reconstructed.body.children[reconstructed.body.children.length - 1];
+    expect(lastBlock.kind).toBe("body_sect_pr");
+  });
+});
+
+describe("pmToDocx — opaque pass-through", () => {
+  it("preserves opaque_block content verbatim", async () => {
+    const fakeXml = {
+      "w:sdt": [{ "w:sdtPr": [] }],
+      ":@": { "@_w:foo": "bar" },
+    };
+    const docx: DocxDocument = {
+      parts: new Map(),
+      documentAttrs: {},
+      body: {
+        children: [
+          { kind: "paragraph", properties: null, content: [] },
+          { kind: "opaque_block", xml: fakeXml },
+        ],
+      },
+    };
+    const pm = docxToPm(docx);
+    const reconstructed = pmToDocx(pm, {
+      parts: docx.parts,
+      documentAttrs: docx.documentAttrs,
+    });
+    const opaque = reconstructed.body.children.find(
+      (b) => b.kind === "opaque_block",
+    );
+    expect(opaque).toBeDefined();
+    if (opaque?.kind === "opaque_block") {
+      expect(opaque.xml).toEqual(fakeXml);
+    }
+  });
+
+  it("preserves opaque_inline content verbatim inside a paragraph", async () => {
+    const fldSimple = {
+      "w:fldSimple": [{ "w:r": [{ "w:t": [{ "#text": "3" }] }] }],
+      ":@": { "@_w:instr": " PAGE " },
+    };
+    const docx: DocxDocument = {
+      parts: new Map(),
+      documentAttrs: {},
+      body: {
+        children: [
+          {
+            kind: "paragraph",
+            properties: null,
+            content: [{ kind: "opaque_inline", xml: fldSimple }],
+          },
+        ],
+      },
+    };
+    const pm = docxToPm(docx);
+    const reconstructed = pmToDocx(pm, {
+      parts: docx.parts,
+      documentAttrs: docx.documentAttrs,
+    });
+    const para = reconstructed.body.children[0];
+    if (para.kind !== "paragraph") throw new Error("expected paragraph");
+    const run = para.content[0];
+    if (run?.kind !== "run") throw new Error("expected run");
+    const child = run.content[0];
+    expect(child.kind).toBe("opaque_run_child");
+    if (child.kind === "opaque_run_child") {
+      expect(child.xml).toEqual(fldSimple);
+    }
+  });
+
+  it("preserves unknown paragraph properties (unknownProperties bucket)", async () => {
+    const divIdEl = {
+      "w:divId": [],
+      ":@": { "@_w:val": "12345" },
+    };
+    const docx: DocxDocument = {
+      parts: new Map(),
+      documentAttrs: {},
+      body: {
+        children: [
+          {
+            kind: "paragraph",
+            properties: [
+              { "w:pStyle": [], ":@": { "@_w:val": "Normal" } },
+              divIdEl,
+            ],
+            content: [],
+          },
+        ],
+      },
+    };
+    const pm = docxToPm(docx);
+    const reconstructed = pmToDocx(pm, {
+      parts: docx.parts,
+      documentAttrs: docx.documentAttrs,
+    });
+    const para = reconstructed.body.children[0];
+    if (para.kind !== "paragraph") throw new Error("expected paragraph");
+    expect(para.properties).not.toBeNull();
+    const tags = (para.properties ?? []).map(
+      (el) => Object.keys(el).find((k) => k !== ":@")!,
+    );
+    expect(tags).toContain("w:pStyle");
+    expect(tags).toContain("w:divId");
+  });
+});
+
+describe("pmToDocx — sections", () => {
+  it("emits inline sectPr inside the preceding paragraph's pPr", () => {
+    const docx: DocxDocument = {
+      parts: new Map(),
+      documentAttrs: {},
+      body: {
+        children: [
+          { kind: "paragraph", properties: null, content: [] },
+          {
+            kind: "paragraph",
+            properties: [
+              {
+                "w:sectPr": [{ "w:type": [], ":@": { "@_w:val": "continuous" } }],
+              },
+            ],
+            content: [],
+          },
+          { kind: "paragraph", properties: null, content: [] },
+          {
+            kind: "body_sect_pr",
+            xml: { "w:sectPr": [{ "w:pgSz": [], ":@": { "@_w:w": "11906", "@_w:h": "16838" } }] },
+          },
+        ],
+      },
+    };
+    const pm = docxToPm(docx);
+    const reconstructed = pmToDocx(pm, {
+      parts: docx.parts,
+      documentAttrs: docx.documentAttrs,
+    });
+
+    const inlineParagraph = reconstructed.body.children[1];
+    if (inlineParagraph.kind !== "paragraph") throw new Error("expected paragraph");
+    const tags = (inlineParagraph.properties ?? []).map(
+      (el) => Object.keys(el).find((k) => k !== ":@")!,
+    );
+    expect(tags).toContain("w:sectPr");
+
+    const finalBlock = reconstructed.body.children[reconstructed.body.children.length - 1];
+    expect(finalBlock.kind).toBe("body_sect_pr");
+  });
+});

package/src/pm/schema.test.ts

@@ -0,0 +1,188 @@
+import { describe, it, expect } from "vitest";
+import { docxSchema } from "./schema";
+import { EMPTY_PARAGRAPH_PROPERTIES } from "../model/properties";
+import { DEFAULT_SECTION_PROPERTIES } from "../model/sections";
+
+describe("docx ProseMirror schema", () => {
+  it("has all expected node types", () => {
+    const expected = [
+      "doc",
+      "paragraph",
+      "section_break",
+      "opaque_block",
+      "text",
+      "hard_break",
+      "image_inline",
+      "opaque_inline",
+      "field_inline",
+      "bookmark_start",
+      "bookmark_end",
+      "table",
+      "table_row",
+      "table_cell",
+      "table_header",
+    ];
+    for (const name of expected) {
+      expect(docxSchema.nodes[name], `missing node: ${name}`).toBeDefined();
+    }
+  });
+
+  it("has all expected marks", () => {
+    const expected = [
+      "bold",
+      "italic",
+      "underline",
+      "strike",
+      "doubleStrike",
+      "caps",
+      "smallCaps",
+      "superscript",
+      "subscript",
+      "color",
+      "highlight",
+      "font",
+      "size",
+      "styleRef",
+      "link",
+      "insertion",
+      "deletion",
+    ];
+    for (const name of expected) {
+      expect(docxSchema.marks[name], `missing mark: ${name}`).toBeDefined();
+    }
+  });
+
+  it("constructs a paragraph with bold + italic + colored text", () => {
+    const { paragraph, text } = docxSchema.nodes;
+    const { bold, italic, color } = docxSchema.marks;
+
+    const node = paragraph.create(
+      {
+        properties: { ...EMPTY_PARAGRAPH_PROPERTIES, alignment: "center" },
+        unknownProperties: [],
+      },
+      [
+        text.schema.text("Hello ", [bold.create()]),
+        text.schema.text("World", [italic.create(), color.create({ value: "FF0000" })]),
+      ],
+    );
+
+    expect(node.type.name).toBe("paragraph");
+    expect(node.attrs.properties.alignment).toBe("center");
+    expect(node.childCount).toBe(2);
+    expect(node.child(0).marks.map((m) => m.type.name)).toEqual(["bold"]);
+    expect(node.child(1).marks.map((m) => m.type.name)).toEqual(["italic", "color"]);
+    expect(node.child(1).marks[1].attrs.value).toBe("FF0000");
+  });
+
+  it("permits opaque_inline carrying arbitrary attrs (XML pass-through)", () => {
+    const { paragraph, opaque_inline, text } = docxSchema.nodes;
+    const opaque = opaque_inline.create({
+      xml: { "w:fldSimple": [], ":@": { "@_w:instr": " PAGE " } },
+    });
+    const node = paragraph.create({}, [
+      text.schema.text("before "),
+      opaque,
+      text.schema.text(" after"),
+    ]);
+    expect(node.childCount).toBe(3);
+    expect(node.child(1).type.name).toBe("opaque_inline");
+    expect(node.child(1).attrs.xml).toMatchObject({
+      "w:fldSimple": [],
+    });
+  });
+
+  it("permits opaque_block carrying arbitrary attrs", () => {
+    const { doc, paragraph, opaque_block } = docxSchema.nodes;
+    const node = doc.create({}, [
+      paragraph.create({}, []),
+      opaque_block.create({ xml: { "w:tbl": [] } }),
+    ]);
+    expect(node.childCount).toBe(2);
+    expect(node.child(1).attrs.xml).toEqual({ "w:tbl": [] });
+  });
+
+  it("constructs a section_break with SectionProperties", () => {
+    const { doc, paragraph, section_break } = docxSchema.nodes;
+    const node = doc.create({}, [
+      paragraph.create({}, []),
+      section_break.create({
+        properties: { ...DEFAULT_SECTION_PROPERTIES },
+        isFinal: true,
+      }),
+    ]);
+    expect(node.child(1).attrs.properties.pageSize.width).toBe(12240);
+    expect(node.child(1).attrs.isFinal).toBe(true);
+  });
+
+  it("survives JSON serialization roundtrip with opaque attrs intact", () => {
+    const { doc, paragraph, opaque_inline, text } = docxSchema.nodes;
+    const original = doc.create({}, [
+      paragraph.create({}, [
+        text.schema.text("a"),
+        opaque_inline.create({
+          xml: { "w:tab": [], ":@": { "@_w:val": "clear" } },
+        }),
+      ]),
+    ]);
+    const json = original.toJSON();
+    const restored = docxSchema.nodeFromJSON(json);
+    expect(restored.eq(original)).toBe(true);
+    expect((restored.child(0).child(1).attrs.xml as Record<string, unknown>)).toEqual({
+      "w:tab": [],
+      ":@": { "@_w:val": "clear" },
+    });
+  });
+
+  it("constructs a table with rows, cells, and content", () => {
+    const { doc, paragraph, table, table_row, table_cell, text } =
+      docxSchema.nodes;
+    const cell = (s: string) =>
+      table_cell.create({}, [paragraph.create({}, [text.schema.text(s)])]);
+    const node = doc.create({}, [
+      table.create({}, [
+        table_row.create({}, [cell("a"), cell("b")]),
+        table_row.create({}, [cell("c"), cell("d")]),
+      ]),
+    ]);
+    expect(node.child(0).childCount).toBe(2);
+    expect(node.child(0).child(0).childCount).toBe(2);
+  });
+
+  it("preserves font mark attrs through JSON roundtrip", () => {
+    const { paragraph, text } = docxSchema.nodes;
+    const { font, size } = docxSchema.marks;
+    const node = paragraph.create({}, [
+      text.schema.text("typed", [
+        font.create({
+          ascii: "Calibri",
+          hAnsi: "Calibri",
+          eastAsia: null,
+          complexScript: null,
+        }),
+        size.create({ halfPoints: 24 }),
+      ]),
+    ]);
+    const restored = docxSchema.nodeFromJSON(node.toJSON());
+    expect(restored.eq(node)).toBe(true);
+    const restoredMarks = restored.child(0).marks;
+    expect(restoredMarks[0].attrs.ascii).toBe("Calibri");
+    expect(restoredMarks[1].attrs.halfPoints).toBe(24);
+  });
+
+  it("declares mutual exclusion between superscript and subscript", () => {
+    const { superscript, subscript } = docxSchema.marks;
+    const sup = superscript.create();
+    const sub = subscript.create();
+    const merged = sub.addToSet([sup]);
+    const names = merged.map((m) => m.type.name);
+    expect(names).toEqual(["subscript"]);
+  });
+
+  it("rejects nesting block content directly inside paragraph (createChecked)", () => {
+    const { paragraph } = docxSchema.nodes;
+    expect(() =>
+      paragraph.createChecked({}, [paragraph.create({}, [])]),
+    ).toThrow();
+  });
+});

package/src/pm/schema.ts

@@ -0,0 +1,79 @@
+import { Schema } from "prosemirror-model";
+import { tableNodes } from "prosemirror-tables";
+import { nodeSpecs } from "./nodes";
+import { markSpecs } from "./marks";
+
+function passthrough(name: string) {
+  return {
+    default: null,
+    getFromDOM: (el: HTMLElement) => {
+      const raw = el.getAttribute(`data-${name}`);
+      if (!raw) return null;
+      try {
+        return JSON.parse(raw) as unknown;
+      } catch {
+        return null;
+      }
+    },
+    setDOMAttr: (value: unknown, attrs: Record<string, unknown>) => {
+      if (value !== null && value !== undefined) {
+        attrs[`data-${name}`] = JSON.stringify(value);
+      }
+    },
+  };
+}
+
+const tableNodeBundle = tableNodes({
+  tableGroup: "block",
+  cellContent: "block+",
+  cellAttributes: {
+    background: {
+      default: null,
+      getFromDOM: (el) => (el as HTMLElement).style.backgroundColor || null,
+      setDOMAttr: (value, attrs) => {
+        if (value !== null) {
+          attrs.style = `${(attrs.style as string | undefined) ?? ""}background-color: ${value as string};`;
+        }
+      },
+    },
+    gridSpan: passthrough("grid-span"),
+    vMerge: passthrough("v-merge"),
+    borders: passthrough("borders"),
+    shading: passthrough("shading"),
+    vAlign: passthrough("v-align"),
+    cellWidth: passthrough("cell-width"),
+  },
+});
+
+const tableSpec = {
+  ...tableNodeBundle.table,
+  attrs: {
+    ...tableNodeBundle.table.attrs,
+    tableProperties: { default: null },
+    columnGrid: { default: null },
+  },
+};
+
+const tableRowSpec = {
+  ...tableNodeBundle.table_row,
+  attrs: {
+    ...tableNodeBundle.table_row.attrs,
+    rowProperties: { default: null },
+  },
+};
+
+const tables = {
+  ...tableNodeBundle,
+  table: tableSpec,
+  table_row: tableRowSpec,
+};
+
+export const docxSchema = new Schema({
+  nodes: {
+    ...nodeSpecs,
+    ...tables,
+  },
+  marks: markSpecs,
+});
+
+export type DocxSchema = typeof docxSchema;

package/src/pm/search.ts

@@ -0,0 +1,46 @@
+import {
+  SearchQuery,
+  findNext,
+  findPrev,
+  replaceAll,
+  replaceCurrent,
+  replaceNext,
+  search,
+  setSearchState,
+} from "prosemirror-search";
+import type { EditorView } from "prosemirror-view";
+import type { Plugin } from "prosemirror-state";
+
+export type SearchOptions = {
+  caseSensitive?: boolean;
+  wholeWord?: boolean;
+  regexp?: boolean;
+  replace?: string;
+};
+
+export function searchPlugin(): Plugin {
+  return search();
+}
+
+export function setQuery(view: EditorView, text: string, opts: SearchOptions = {}): void {
+  const query = new SearchQuery({
+    search: text,
+    caseSensitive: opts.caseSensitive ?? false,
+    wholeWord: opts.wholeWord ?? false,
+    regexp: opts.regexp ?? false,
+    replace: opts.replace ?? "",
+  });
+  view.dispatch(setSearchState(view.state.tr, query));
+}
+
+export function clearQuery(view: EditorView): void {
+  view.dispatch(setSearchState(view.state.tr, new SearchQuery({ search: "" })));
+}
+
+export const searchCommands = {
+  findNext,
+  findPrev,
+  replaceNext,
+  replaceCurrent,
+  replaceAll,
+};

package/src/pm/table_attrs.ts

@@ -0,0 +1,48 @@
+/**
+ * Typed views over OOXML-aware table cell passthrough attrs.
+ *
+ * The PM schema declares these as opaque (any JSON is allowed). Code that
+ * reads or writes them goes through these helpers so the typed shape lives
+ * in one place.
+ */
+
+export type TableBorder = {
+  style: string;
+  color: string | null;
+  sizePts: number;
+};
+
+export type TableCellBorders = {
+  top?: TableBorder;
+  right?: TableBorder;
+  bottom?: TableBorder;
+  left?: TableBorder;
+};
+
+export type TableCellShading = {
+  fill: string;
+  pattern?: string;
+  color?: string | null;
+};
+
+export type TableCellWidth = {
+  value: number;
+  type: "dxa" | "pct" | "auto" | "nil";
+};
+
+export type VMergeKind = "restart" | "continue";
+
+export type VAlignKind = "top" | "center" | "bottom";
+
+export type DocxCellAttrs = {
+  colspan?: number;
+  rowspan?: number;
+  colwidth?: number[] | null;
+  background?: string | null;
+  gridSpan?: number | null;
+  vMerge?: VMergeKind | null;
+  borders?: TableCellBorders | null;
+  shading?: TableCellShading | null;
+  vAlign?: VAlignKind | null;
+  cellWidth?: TableCellWidth | null;
+};