@lotics/docx 0.1.0

package/src/layout/types.ts

@@ -0,0 +1,159 @@
+import type { ParagraphProperties } from "../model/properties";
+
+/**
+ * Block kinds the layout engine reasons about. Mirrors the OOXML structural
+ * categories that affect page-break decisions: paragraphs can split across
+ * pages (line-by-line), tables can split at row boundaries, opaque blocks
+ * are atomic, and section breaks force a new page.
+ */
+export type BlockKind =
+  | "paragraph"
+  | "table"
+  | "section_break"
+  | "opaque_block";
+
+/**
+ * A measured block in the body. Heights are in CSS pixels at 100% zoom.
+ *
+ * `lineHeights` is non-null only for paragraphs that have measured per-line
+ * geometry from the renderer. When null, the block is treated as atomic
+ * (cannot be split across pages — must move whole).
+ *
+ * Tables expose `rowHeights` instead — splits happen at row boundaries.
+ */
+export type MeasuredBlock = {
+  index: number;
+  sectionIndex: number;
+  kind: BlockKind;
+  height: number;
+  paragraphProperties: ParagraphProperties | null;
+  lineHeights: readonly number[] | null;
+  rowHeights: readonly number[] | null;
+};
+
+/**
+ * Per-section geometry derived from {@link SectionProperties}. Pre-computed
+ * once so the engine can be called many times during a session without
+ * recomputing margins.
+ */
+export type SectionGeometry = {
+  sectionIndex: number;
+  /** Inclusive index of the first body block in this section. */
+  blockStartIndex: number;
+  /** Inclusive index of the last body block in this section. */
+  blockEndIndex: number;
+  /** Total page height in px (including margins, header band, footer band). */
+  pageHeight: number;
+  /** Total page width in px (including L/R margins). */
+  pageWidth: number;
+  /** Usable content height in px (pageHeight minus margins and header/footer bands). */
+  pageContentHeight: number;
+  /** Reserved band above the content area, in px. */
+  headerBand: number;
+  /** Reserved band below the content area, in px. */
+  footerBand: number;
+  /** Whether the section's first page uses the "first" header/footer variant. */
+  titlePage: boolean;
+  /** Whether the section defines an "even" header (otherwise even pages use default). */
+  hasEvenHeader: boolean;
+};
+
+/**
+ * The set of constants the engine uses when picking break points.
+ * Tunable per call so consumers can experiment with different widow/orphan
+ * thresholds or visual page gaps without forking the engine.
+ */
+export type LayoutOptions = {
+  /**
+   * Minimum number of lines from a paragraph that may appear at the
+   * bottom of a page when the paragraph continues on the next page
+   * (orphan protection). Word's default is 2.
+   */
+  minLinesBeforeBreak: number;
+  /**
+   * Minimum number of lines from a paragraph that may appear at the
+   * top of a page when the paragraph started on the previous page
+   * (widow protection). Word's default is 2.
+   */
+  minLinesAfterBreak: number;
+  /**
+   * Visual gap between page rectangles, in CSS px. Must match the value
+   * the renderer uses for the page-chrome stack so the engine's
+   * `gapHeightBefore` lands the flow content on the next page's body slot.
+   */
+  visualPageGapPx: number;
+};
+
+export const DEFAULT_LAYOUT_OPTIONS: LayoutOptions = {
+  minLinesBeforeBreak: 2,
+  minLinesAfterBreak: 2,
+  visualPageGapPx: 24,
+};
+
+/**
+ * Identifies which variant of the header/footer to render on a given page.
+ * Maps directly to OOXML's `w:hdrRef`/`w:ftrRef` type attribute.
+ */
+export type HeaderFooterKind = "default" | "first" | "even";
+
+/**
+ * When a block must split visually across pages, this records the slice
+ * that lands on a given page. Lines are 0-based.
+ *
+ * For paragraphs: `firstLine`..`lastLine` indexes into `MeasuredBlock.lineHeights`.
+ * For tables: `firstLine`..`lastLine` indexes into `MeasuredBlock.rowHeights`.
+ *
+ * If a page contains a partialBlock at its end, the same block also appears
+ * as a partialBlock at the start of the next page (continuation).
+ */
+export type PartialBlockSlice = {
+  blockIndex: number;
+  firstLine: number;
+  lastLine: number;
+};
+
+export type Page = {
+  pageNumber: number;
+  sectionIndex: number;
+  /**
+   * The first block whose content (in whole or in part) appears on this page.
+   * If the page begins with a continuation of a split block, this is that block.
+   */
+  firstBlockIndex: number;
+  /**
+   * The last block whose content (in whole or in part) appears on this page.
+   * If the page ends with the start of a split block, this is that block.
+   */
+  lastBlockIndex: number;
+  /** Which header variant this page renders. */
+  headerKind: HeaderFooterKind;
+  /** True if this is the first page of its section. */
+  isFirstInSection: boolean;
+  /**
+   * If the page begins with a continuation of a block whose start was on
+   * the previous page, this records the slice taken by this page.
+   * Null when the page begins on a fresh block boundary.
+   */
+  startsWithContinuation: PartialBlockSlice | null;
+  /**
+   * If the page ends with the start of a block whose remainder will appear
+   * on the next page, this records the slice taken by this page.
+   * Null when the page ends on a fresh block boundary.
+   */
+  endsWithContinuation: PartialBlockSlice | null;
+  /**
+   * Height (in CSS px) of the spacer the renderer must insert *immediately
+   * before* this page's first block in the editor's flowing content. The
+   * spacer bridges the unused body-slot space at the bottom of the previous
+   * page, the visual page gap, and the header band of this page so that
+   * the first block on this page aligns with the chrome layer's body slot.
+   *
+   * 0 for page 1 — no spacer needed before the first block of the document.
+   */
+  gapHeightBefore: number;
+};
+
+export type LayoutResult = {
+  pages: readonly Page[];
+  totalPages: number;
+};

package/src/load.test.ts

@@ -0,0 +1,144 @@
+// @vitest-environment happy-dom
+import { describe, it, expect, beforeEach } from "vitest";
+import { readFileSync } from "node:fs";
+import { resolve } 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 { loadDocxIntoElement } from "./load";
+
+function paragraph(children: XmlElement[]): XmlElement {
+  return { "w:p": children };
+}
+
+async function buildSampleBytes(): Promise<Uint8Array> {
+  const doc = createBlankDocx();
+  appendElement(doc, paragraph([buildRun("Headline", { bold: true })]));
+  appendElement(doc, paragraph([buildRun("Body text follows.")]));
+  appendElement(
+    doc,
+    paragraph([
+      buildRun("Plain "),
+      buildRun("italicized", { italic: true }),
+      buildRun(" tail."),
+    ]),
+  );
+  const buffer = await saveDocxToBuffer(doc);
+  return new Uint8Array(buffer);
+}
+
+let host: HTMLElement;
+
+beforeEach(() => {
+  document.body.innerHTML = "";
+  host = document.createElement("div");
+  document.body.appendChild(host);
+});
+
+describe("loadDocxIntoElement", () => {
+  it("mounts a docx end-to-end into the host element", async () => {
+    const bytes = await buildSampleBytes();
+    const loaded = await loadDocxIntoElement(host, bytes);
+
+    expect(host.querySelector(".docx-page-stack")).not.toBeNull();
+    expect(host.textContent).toContain("Headline");
+    expect(host.textContent).toContain("Body text follows.");
+    expect(host.textContent).toContain("italicized");
+
+    expect(host.querySelector("strong")?.textContent).toBe("Headline");
+    expect(host.querySelector("em")?.textContent).toBe("italicized");
+
+    loaded.view.destroy();
+  });
+
+  it("returns the parsed document, style table, and sections", async () => {
+    const bytes = await buildSampleBytes();
+    const loaded = await loadDocxIntoElement(host, bytes);
+
+    expect(loaded.document.body.children.length).toBeGreaterThan(0);
+    expect(loaded.sections.length).toBeGreaterThan(0);
+    expect(loaded.sections[0].properties.pageSize.width).toBe(12240);
+    expect(loaded.styleTable).toBeDefined();
+
+    loaded.view.destroy();
+  });
+
+  it("emits @font-face stylesheet for the bundled fonts", async () => {
+    const bytes = await buildSampleBytes();
+    const loaded = await loadDocxIntoElement(host, bytes);
+
+    const styleEl = host.querySelector(
+      "style[data-docx-editor-styles]",
+    ) as HTMLStyleElement;
+    expect(styleEl.textContent).toContain("@font-face");
+    expect(styleEl.textContent).toContain("Liberation Serif");
+
+    loaded.view.destroy();
+  });
+
+  it("renders a non-editable view by default", async () => {
+    const bytes = await buildSampleBytes();
+    const loaded = await loadDocxIntoElement(host, bytes);
+    expect(loaded.view.editorView.editable).toBe(false);
+    loaded.view.destroy();
+  });
+
+  it("destroy() cleans up the page and the stylesheet", async () => {
+    const bytes = await buildSampleBytes();
+    const loaded = await loadDocxIntoElement(host, bytes);
+    loaded.view.destroy();
+    expect(host.querySelector(".docx-canvas")).toBeNull();
+    expect(host.querySelector("style[data-docx-editor-styles]")).toBeNull();
+  });
+
+  it("renders the pretty-printed Vietnamese contract fixture without unsupported-content placeholders", async () => {
+    const fixturePath = resolve(
+      fileURLToPath(import.meta.url),
+      "../fixtures/lotics_generated_contract.docx",
+    );
+    const bytes = new Uint8Array(readFileSync(fixturePath));
+    const loaded = await loadDocxIntoElement(host, bytes);
+
+    const placeholders = host.querySelectorAll(
+      ".docx-opaque-block__placeholder",
+    );
+    expect(
+      placeholders.length,
+      `expected zero "[unsupported content]" boxes; found ${placeholders.length}`,
+    ).toBe(0);
+
+    const opaqueInlines = host.querySelectorAll("[data-opaque-inline]");
+    expect(
+      opaqueInlines.length,
+      `expected zero opaque-inline wrapper spans; found ${opaqueInlines.length}`,
+    ).toBe(0);
+
+    expect(host.querySelectorAll("table").length).toBe(2);
+    expect(host.textContent).toContain("HỢP ĐỒNG MUA BÁN");
+    expect(host.textContent).toContain("ĐIỀU 1. ĐỐI TƯỢNG HỢP ĐỒNG");
+
+    loaded.view.destroy();
+  });
+
+  it("accepts workspace fonts override", async () => {
+    const bytes = await buildSampleBytes();
+    const loaded = await loadDocxIntoElement(host, bytes, {
+      workspaceFonts: [
+        {
+          family: "Calibri",
+          regular: { fileId: "fil_workspace_calibri" },
+          bold: null,
+          italic: null,
+          boldItalic: null,
+        },
+      ],
+    });
+    expect(loaded.view.editorView).toBeDefined();
+    loaded.view.destroy();
+  });
+});

package/src/load.ts

@@ -0,0 +1,142 @@
+import type { BundledFont, WorkspaceFont } from "./fonts/types";
+import { buildFontRegistry } from "./fonts/registry";
+import { buildBundledManifest } from "./fonts/bundled";
+import { parseDocx } from "./parse/parser";
+import { parseStyleTable } from "./parse/styles";
+import { withDefaultStyles } from "./model/default_styles";
+import { parseFontTable } from "./parse/font_table";
+import { parseBodySections } from "./parse/sections";
+import { parseDocumentRelationships } from "./parse/relationships";
+import { parseNumberingTable } from "./parse/numbering";
+import { DEFAULT_NUMBERING_TABLE } from "./model/default_numbering";
+import { parseThemeTable } from "./parse/theme";
+import { parseHeaderFooterRegistry } from "./parse/header_footer";
+import { parseFootnoteRegistry } from "./parse/footnotes";
+import { docxToPm } from "./pm/docx_to_pm";
+import {
+  createReadOnlyView,
+  type ReadOnlyView,
+  type ViewMode,
+} from "./render/view";
+import type { Node as PMNode } from "prosemirror-model";
+import { buildMediaResolver } from "./render/media_resolver";
+import {
+  createImageRegistry,
+  type ImageRegistry,
+} from "./pm/image_registry";
+import type { DocxDocument } from "./model/types";
+import type { Section } from "./model/sections";
+import type { StyleTable } from "./model/style_table";
+import type { RelationshipMap } from "./parse/relationships";
+
+export type LoadDocxOptions = {
+  workspaceFonts?: readonly WorkspaceFont[];
+  additionalBundledFonts?: readonly BundledFont[];
+  mode?: ViewMode;
+  onChange?: (doc: PMNode) => void;
+};
+
+export type LoadedDocxView = {
+  view: ReadOnlyView;
+  document: DocxDocument;
+  styleTable: StyleTable;
+  sections: readonly Section[];
+  relationships: RelationshipMap;
+  imageRegistry: ImageRegistry;
+};
+
+export async function loadDocxIntoElement(
+  host: HTMLElement,
+  bytes: Uint8Array,
+  options: LoadDocxOptions = {},
+): Promise<LoadedDocxView> {
+  const document = await parseDocx(bytes);
+  const styleTable = withDefaultStyles(parseStyleTable(document.parts));
+  // Merge the bundled bullets/decimals onto the parsed numbering table.
+  // Parsed entries win; bundled entries cover numIds the file didn't
+  // declare (e.g., a paragraph references numId 1 for bullets but the
+  // file has no numbering.xml entry for it). Pure replacement would lose
+  // markers for paragraphs whose numIds aren't in either table; merging
+  // covers both partial parsed tables and missing-numbering.xml files.
+  const parsedNumbering = parseNumberingTable(document.parts);
+  const numberingTable = mergeNumberingTables(parsedNumbering, DEFAULT_NUMBERING_TABLE);
+  const themeTable = parseThemeTable(document.parts);
+  const embeddedFonts = parseFontTable(document.parts);
+  const sections = parseBodySections(document.body);
+  const relationships = parseDocumentRelationships(document.parts);
+  const headerFooterRegistry = parseHeaderFooterRegistry(
+    document.parts,
+    relationships,
+  );
+  const footnoteRegistry = parseFootnoteRegistry(document.parts);
+
+  const additionalBundled = options.additionalBundledFonts ?? [];
+  const bundled =
+    additionalBundled.length > 0
+      ? buildBundledManifest(undefined, undefined, additionalBundled)
+      : undefined;
+
+  const fontRegistry = buildFontRegistry({
+    embeddedFonts,
+    workspaceFonts: options.workspaceFonts ?? [],
+    bundled,
+  });
+
+  const mediaResolver = buildMediaResolver(document.parts, relationships);
+
+  const imageRegistry = createImageRegistry({
+    existingRelationshipIds: new Set(relationships.keys()),
+  });
+
+  const pmDoc = docxToPm(document, { styleTable, numberingTable });
+  const innerView = createReadOnlyView(host, pmDoc, {
+    fontRegistry,
+    sections,
+    relationships,
+    mediaResolver,
+    imageRegistry,
+    numberingTable,
+    themeTable,
+    headerFooterRegistry,
+    footnoteRegistry,
+    mode: options.mode ?? "read-only",
+    onChange: options.onChange,
+  });
+
+  const view: ReadOnlyView = {
+    ...innerView,
+    destroy: () => {
+      innerView.destroy();
+      mediaResolver.destroy();
+    },
+  };
+
+  return {
+    view,
+    document,
+    styleTable,
+    sections,
+    relationships,
+    imageRegistry,
+  };
+}
+
+/**
+ * Merge two numbering tables. Parsed entries take precedence; defaults
+ * fill in any abstractNumIds / numIds the parsed table doesn't have.
+ *
+ * Use case: a file declares its own bullet numbering as numId 1 but a
+ * paragraph references numId 5 with no matching definition. Without a
+ * merge fallback, that paragraph would render markerless. The bundled
+ * defaults cover the common cases (numId 1 = bullets, numId 2 = decimals).
+ */
+function mergeNumberingTables(
+  parsed: import("./model/numbering_table").NumberingTable,
+  defaults: import("./model/numbering_table").NumberingTable,
+): import("./model/numbering_table").NumberingTable {
+  const abstractNums = new Map(defaults.abstractNums);
+  for (const [id, value] of parsed.abstractNums) abstractNums.set(id, value);
+  const nums = new Map(defaults.nums);
+  for (const [id, value] of parsed.nums) nums.set(id, value);
+  return { abstractNums, nums };
+}

package/src/model/default_numbering.ts

@@ -0,0 +1,101 @@
+import type {
+  AbstractNum,
+  Num,
+  NumberingLevel,
+  NumberingTable,
+} from "./numbering_table";
+
+/**
+ * Default numbering definitions used when a parsed document lacks a
+ * `numbering.xml` part (or when constructing a doc programmatically — e.g.,
+ * the dev demo). Mirrors the two `numId`s the editor's list commands
+ * emit:
+ *
+ *   numId 1 = bullets (• ◦ ▪ alternating per indent level)
+ *   numId 2 = decimal numbers (1. 1.1. 1.1.1. etc.)
+ *
+ * Each numId references an `abstractNum` whose levels carry `lvlText`
+ * templates that the {@link computeLabel} renderer expands at decoration
+ * time. The labels visible to the reader are produced by
+ * {@link numberingDecorationPlugin}, never by mutating the doc model.
+ */
+
+function level(args: {
+  ilvl: number;
+  numFmt: NumberingLevel["numFmt"];
+  lvlText: string;
+  start?: number;
+}): NumberingLevel {
+  return {
+    ilvl: args.ilvl,
+    start: args.start ?? 1,
+    numFmt: args.numFmt,
+    lvlText: args.lvlText,
+    lvlJc: "left",
+    lvlRestart: null,
+    paragraphProperties: null,
+    runProperties: null,
+    suff: "tab",
+  };
+}
+
+function abstractNum(args: {
+  abstractNumId: number;
+  levels: readonly NumberingLevel[];
+}): AbstractNum {
+  const map = new Map<number, NumberingLevel>();
+  for (const lvl of args.levels) map.set(lvl.ilvl, lvl);
+  return { abstractNumId: args.abstractNumId, levels: map };
+}
+
+function num(args: { numId: number; abstractNumId: number }): Num {
+  return {
+    numId: args.numId,
+    abstractNumId: args.abstractNumId,
+    overrides: new Map(),
+  };
+}
+
+// Word's default templates define 9 levels (ilvl 0..8). We mirror that
+// so deeply-nested lists in customer documents still render markers,
+// rather than silently dropping anything past level 3.
+const bulletAbstract: AbstractNum = abstractNum({
+  abstractNumId: 0,
+  levels: [
+    level({ ilvl: 0, numFmt: "bullet", lvlText: "•" }),
+    level({ ilvl: 1, numFmt: "bullet", lvlText: "◦" }),
+    level({ ilvl: 2, numFmt: "bullet", lvlText: "▪" }),
+    level({ ilvl: 3, numFmt: "bullet", lvlText: "•" }),
+    level({ ilvl: 4, numFmt: "bullet", lvlText: "◦" }),
+    level({ ilvl: 5, numFmt: "bullet", lvlText: "▪" }),
+    level({ ilvl: 6, numFmt: "bullet", lvlText: "•" }),
+    level({ ilvl: 7, numFmt: "bullet", lvlText: "◦" }),
+    level({ ilvl: 8, numFmt: "bullet", lvlText: "▪" }),
+  ],
+});
+
+const decimalAbstract: AbstractNum = abstractNum({
+  abstractNumId: 1,
+  levels: [
+    level({ ilvl: 0, numFmt: "decimal", lvlText: "%1." }),
+    level({ ilvl: 1, numFmt: "decimal", lvlText: "%1.%2." }),
+    level({ ilvl: 2, numFmt: "decimal", lvlText: "%1.%2.%3." }),
+    level({ ilvl: 3, numFmt: "lowerLetter", lvlText: "%4." }),
+    level({ ilvl: 4, numFmt: "decimal", lvlText: "%5." }),
+    level({ ilvl: 5, numFmt: "lowerLetter", lvlText: "%6." }),
+    level({ ilvl: 6, numFmt: "lowerRoman", lvlText: "%7." }),
+    level({ ilvl: 7, numFmt: "decimal", lvlText: "%8." }),
+    level({ ilvl: 8, numFmt: "lowerLetter", lvlText: "%9." }),
+  ],
+});
+
+export const DEFAULT_NUMBERING_TABLE: NumberingTable = {
+  abstractNums: new Map([
+    [bulletAbstract.abstractNumId, bulletAbstract],
+    [decimalAbstract.abstractNumId, decimalAbstract],
+  ]),
+  nums: new Map([
+    [1, num({ numId: 1, abstractNumId: 0 })],
+    [2, num({ numId: 2, abstractNumId: 1 })],
+  ]),
+};