@lotics/docx 0.1.0

package/src/index.ts

@@ -0,0 +1,16 @@
+export { parseDocx } from "./parse/parser";
+export { serializeDocx } from "./serialize/serializer";
+export type {
+  Block,
+  Body,
+  BodySectPr,
+  DocxDocument,
+  Inline,
+  OpaqueBlock,
+  OpaqueInline,
+  OpaqueRunChild,
+  Paragraph,
+  Run,
+  RunChild,
+  TextNode,
+} from "./model/types";

package/src/layout/engine.test.ts

@@ -0,0 +1,430 @@
+import { describe, expect, it } from "vitest";
+import type { ParagraphProperties } from "../model/properties";
+import { EMPTY_PARAGRAPH_PROPERTIES } from "../model/properties";
+import { runLayout } from "./engine";
+import type {
+  MeasuredBlock,
+  SectionGeometry,
+} from "./types";
+
+// =========================================================================
+// Test helpers
+// =========================================================================
+
+function section(
+  index: number,
+  blockStart: number,
+  blockEnd: number,
+  overrides: Partial<SectionGeometry> = {},
+): SectionGeometry {
+  return {
+    sectionIndex: index,
+    blockStartIndex: blockStart,
+    blockEndIndex: blockEnd,
+    pageHeight: 1056,
+    pageWidth: 816,
+    pageContentHeight: 900,
+    headerBand: 78,
+    footerBand: 78,
+    titlePage: false,
+    hasEvenHeader: false,
+    ...overrides,
+  };
+}
+
+function para(
+  index: number,
+  height: number,
+  overrides: {
+    sectionIndex?: number;
+    properties?: Partial<ParagraphProperties>;
+    lineHeights?: readonly number[];
+  } = {},
+): MeasuredBlock {
+  return {
+    index,
+    sectionIndex: overrides.sectionIndex ?? 0,
+    kind: "paragraph",
+    height,
+    paragraphProperties: overrides.properties
+      ? { ...EMPTY_PARAGRAPH_PROPERTIES, ...overrides.properties }
+      : null,
+    lineHeights: overrides.lineHeights ?? null,
+    rowHeights: null,
+  };
+}
+
+function table(
+  index: number,
+  rowHeights: readonly number[],
+  overrides: { sectionIndex?: number } = {},
+): MeasuredBlock {
+  return {
+    index,
+    sectionIndex: overrides.sectionIndex ?? 0,
+    kind: "table",
+    height: rowHeights.reduce((a, b) => a + b, 0),
+    paragraphProperties: null,
+    lineHeights: null,
+    rowHeights,
+  };
+}
+
+// =========================================================================
+// Empty / single-page cases
+// =========================================================================
+
+describe("runLayout — degenerate inputs", () => {
+  it("returns zero pages when no sections", () => {
+    const result = runLayout([], []);
+    expect(result.totalPages).toBe(0);
+  });
+
+  it("returns one page when there are no blocks", () => {
+    const result = runLayout([], [section(0, 0, 0)]);
+    expect(result.totalPages).toBe(1);
+  });
+
+  it("fits two short paragraphs on one page", () => {
+    const blocks = [para(0, 200), para(1, 200)];
+    const result = runLayout(blocks, [section(0, 0, 1)]);
+    expect(result.totalPages).toBe(1);
+    expect(result.pages[0].firstBlockIndex).toBe(0);
+    expect(result.pages[0].lastBlockIndex).toBe(1);
+  });
+});
+
+// =========================================================================
+// Natural multi-page breaks
+// =========================================================================
+
+describe("runLayout — natural breaks", () => {
+  it("starts a new page when next block won't fit", () => {
+    // pageContentHeight = 900. Three blocks of 400 each: 400+400=800 fits;
+    // adding the third (400) -> 1200 > 900, so it moves to page 2.
+    const blocks = [para(0, 400), para(1, 400), para(2, 400)];
+    const result = runLayout(blocks, [section(0, 0, 2)]);
+    expect(result.totalPages).toBe(2);
+    expect(result.pages[0].lastBlockIndex).toBe(1);
+    expect(result.pages[1].firstBlockIndex).toBe(2);
+  });
+
+  it("packs many short paragraphs across multiple pages", () => {
+    const blocks = Array.from({ length: 10 }, (_, i) => para(i, 200));
+    const result = runLayout(blocks, [section(0, 0, 9)]);
+    // 4 paragraphs per page = 800px used; 5th doesn't fit (1000 > 900).
+    expect(result.totalPages).toBe(3);
+    expect(result.pages[0].firstBlockIndex).toBe(0);
+    expect(result.pages[0].lastBlockIndex).toBe(3);
+    expect(result.pages[1].firstBlockIndex).toBe(4);
+    expect(result.pages[1].lastBlockIndex).toBe(7);
+    expect(result.pages[2].firstBlockIndex).toBe(8);
+    expect(result.pages[2].lastBlockIndex).toBe(9);
+  });
+});
+
+// =========================================================================
+// pageBreakBefore
+// =========================================================================
+
+describe("runLayout — pageBreakBefore", () => {
+  it("forces a new page when set on a paragraph mid-page", () => {
+    const blocks = [
+      para(0, 100),
+      para(1, 100, { properties: { pageBreakBefore: true } }),
+    ];
+    const result = runLayout(blocks, [section(0, 0, 1)]);
+    expect(result.totalPages).toBe(2);
+    expect(result.pages[0].lastBlockIndex).toBe(0);
+    expect(result.pages[1].firstBlockIndex).toBe(1);
+  });
+
+  it("does not create a blank page when pageBreakBefore is on the very first block", () => {
+    const blocks = [
+      para(0, 100, { properties: { pageBreakBefore: true } }),
+      para(1, 100),
+    ];
+    const result = runLayout(blocks, [section(0, 0, 1)]);
+    expect(result.totalPages).toBe(1);
+  });
+});
+
+// =========================================================================
+// keepLines
+// =========================================================================
+
+describe("runLayout — keepLines", () => {
+  it("pushes a splittable paragraph whole when keepLines is set", () => {
+    // page already has 700 of content. Next block is a 400-tall paragraph
+    // with 4 lines of 100 each. Naturally it would split (200 here, 200
+    // on next page). With keepLines, it must move whole.
+    const blocks = [
+      para(0, 700),
+      para(1, 400, {
+        properties: { keepLines: true },
+        lineHeights: [100, 100, 100, 100],
+      }),
+    ];
+    const result = runLayout(blocks, [section(0, 0, 1)]);
+    expect(result.totalPages).toBe(2);
+    expect(result.pages[0].lastBlockIndex).toBe(0);
+    expect(result.pages[1].firstBlockIndex).toBe(1);
+    expect(result.pages[1].startsWithContinuation).toBeNull();
+  });
+
+  it("splits when keepLines is not set", () => {
+    const blocks = [
+      para(0, 700),
+      para(1, 400, { lineHeights: [100, 100, 100, 100] }),
+    ];
+    const result = runLayout(blocks, [section(0, 0, 1)]);
+    expect(result.totalPages).toBe(2);
+    // Page 1 should contain the start of block 1 (2 lines fit in remaining 200).
+    expect(result.pages[0].endsWithContinuation).toEqual({
+      blockIndex: 1,
+      firstLine: 0,
+      lastLine: 1,
+    });
+    expect(result.pages[1].startsWithContinuation).toEqual({
+      blockIndex: 1,
+      firstLine: 2,
+      lastLine: 3,
+    });
+  });
+});
+
+// =========================================================================
+// Widow / orphan
+// =========================================================================
+
+describe("runLayout — widow/orphan", () => {
+  it("pushes a paragraph whole when only one line would fit (orphan)", () => {
+    // page has 800 of content; next paragraph has 4 lines of 100. Only 1
+    // line fits (100 <= remaining 100, 200 > 100). Orphan rule kicks in.
+    const blocks = [
+      para(0, 800),
+      para(1, 400, { lineHeights: [100, 100, 100, 100] }),
+    ];
+    const result = runLayout(blocks, [section(0, 0, 1)]);
+    expect(result.totalPages).toBe(2);
+    expect(result.pages[0].endsWithContinuation).toBeNull();
+    expect(result.pages[1].firstBlockIndex).toBe(1);
+    expect(result.pages[1].startsWithContinuation).toBeNull();
+  });
+
+  it("moves a short paragraph whole when no split would satisfy both min-lines rules", () => {
+    // 3-line paragraph, minLinesBeforeBreak=2, minLinesAfterBreak=2.
+    // 2 lines fit on current page, 1 would spill — but 1 < minLinesAfterBreak,
+    // and the widow rule's recomputed cut (1) is < minLinesBeforeBreak.
+    // The engine should push the whole paragraph to the next page rather
+    // than split into a widow/orphan-violating shape.
+    const blocks = [
+      para(0, 750),
+      para(1, 300, { lineHeights: [100, 100, 100] }),
+    ];
+    const result = runLayout(blocks, [section(0, 0, 1)]);
+    expect(result.totalPages).toBe(2);
+    expect(result.pages[0].endsWithContinuation).toBeNull();
+    expect(result.pages[1].firstBlockIndex).toBe(1);
+    expect(result.pages[1].startsWithContinuation).toBeNull();
+  });
+
+  it("pulls a line back when only one line would land on next page (widow)", () => {
+    // page is empty. Paragraph has 10 lines of 100 each. 9 fit (900); 1
+    // would widow on next page. Should cut at 8 instead.
+    const blocks = [
+      para(0, 1000, { lineHeights: Array(10).fill(100) }),
+    ];
+    const result = runLayout(blocks, [section(0, 0, 0)]);
+    expect(result.totalPages).toBe(2);
+    expect(result.pages[0].endsWithContinuation).toEqual({
+      blockIndex: 0,
+      firstLine: 0,
+      lastLine: 7,
+    });
+    expect(result.pages[1].startsWithContinuation).toEqual({
+      blockIndex: 0,
+      firstLine: 8,
+      lastLine: 9,
+    });
+  });
+});
+
+// =========================================================================
+// keepNext
+// =========================================================================
+
+describe("runLayout — keepNext", () => {
+  it("pulls a heading forward when its body landed on the next page", () => {
+    // Heading (50 high, keepNext) lands at the end of page 1 with no
+    // room for any of the body. Body is on page 2. keepNext fix-up should
+    // move the heading to page 2 too.
+    const blocks = [
+      para(0, 850),
+      para(1, 50, { properties: { keepNext: true } }),
+      para(2, 800),
+    ];
+    const result = runLayout(blocks, [section(0, 0, 2)]);
+    expect(result.totalPages).toBe(2);
+    expect(result.pages[0].lastBlockIndex).toBe(0);
+    expect(result.pages[1].firstBlockIndex).toBe(1);
+    expect(result.pages[1].lastBlockIndex).toBe(2);
+  });
+
+  it("leaves blocks in place when keepNext is satisfied naturally", () => {
+    const blocks = [
+      para(0, 100, { properties: { keepNext: true } }),
+      para(1, 100),
+    ];
+    const result = runLayout(blocks, [section(0, 0, 1)]);
+    expect(result.totalPages).toBe(1);
+  });
+});
+
+// =========================================================================
+// Tables — row-boundary splitting
+// =========================================================================
+
+describe("runLayout — tables", () => {
+  it("splits a table at the row boundary that fits", () => {
+    // Page has 400 used; remaining 500. Table has 7 rows of 100. 5 rows
+    // fit; 2 spill to page 2.
+    const blocks = [para(0, 400), table(1, Array(7).fill(100))];
+    const result = runLayout(blocks, [section(0, 0, 1)]);
+    expect(result.totalPages).toBe(2);
+    expect(result.pages[0].endsWithContinuation).toEqual({
+      blockIndex: 1,
+      firstLine: 0,
+      lastLine: 4,
+    });
+    expect(result.pages[1].startsWithContinuation).toEqual({
+      blockIndex: 1,
+      firstLine: 5,
+      lastLine: 6,
+    });
+  });
+
+  it("moves a table whole when zero rows fit on the current page", () => {
+    // Page has 850 used; remaining 50. First row is 100 (doesn't fit).
+    const blocks = [para(0, 850), table(1, [100, 100, 100])];
+    const result = runLayout(blocks, [section(0, 0, 1)]);
+    expect(result.totalPages).toBe(2);
+    expect(result.pages[0].endsWithContinuation).toBeNull();
+    expect(result.pages[1].firstBlockIndex).toBe(1);
+    expect(result.pages[1].startsWithContinuation).toBeNull();
+  });
+});
+
+// =========================================================================
+// Multi-section
+// =========================================================================
+
+describe("runLayout — multi-section", () => {
+  it("starts a new page at section boundaries", () => {
+    const blocks = [
+      para(0, 100, { sectionIndex: 0 }),
+      para(1, 100, { sectionIndex: 1 }),
+    ];
+    const sections: SectionGeometry[] = [
+      section(0, 0, 0),
+      section(1, 1, 1),
+    ];
+    const result = runLayout(blocks, sections);
+    expect(result.totalPages).toBe(2);
+    expect(result.pages[0].sectionIndex).toBe(0);
+    expect(result.pages[1].sectionIndex).toBe(1);
+    expect(result.pages[1].isFirstInSection).toBe(true);
+  });
+
+  it("respects different page heights per section", () => {
+    // Section 0 has small content area (200), section 1 has large (900).
+    const blocks = [
+      para(0, 150, { sectionIndex: 0 }),
+      para(1, 150, { sectionIndex: 0 }),
+      para(2, 800, { sectionIndex: 1 }),
+    ];
+    const sections: SectionGeometry[] = [
+      section(0, 0, 1, { pageContentHeight: 200 }),
+      section(1, 2, 2, { pageContentHeight: 900 }),
+    ];
+    const result = runLayout(blocks, sections);
+    // Section 0: para(0)=150 fits; para(1)=150 doesn't fit on same page
+    // (would total 300 > 200), so it goes to page 2 of section 0.
+    // Section 1: para(2)=800 fits on its own page.
+    expect(result.totalPages).toBe(3);
+    expect(result.pages[0].sectionIndex).toBe(0);
+    expect(result.pages[1].sectionIndex).toBe(0);
+    expect(result.pages[2].sectionIndex).toBe(1);
+    expect(result.pages[2].isFirstInSection).toBe(true);
+  });
+});
+
+// =========================================================================
+// Header kind selection
+// =========================================================================
+
+describe("runLayout — header kind", () => {
+  it("uses 'first' header on first page when titlePage is true", () => {
+    const blocks = [para(0, 100), para(1, 850), para(2, 100)];
+    const sections: SectionGeometry[] = [
+      section(0, 0, 2, { titlePage: true }),
+    ];
+    const result = runLayout(blocks, sections);
+    expect(result.pages[0].headerKind).toBe("first");
+    expect(result.pages[1].headerKind).toBe("default");
+  });
+
+  it("uses 'default' on first page when titlePage is false", () => {
+    const blocks = [para(0, 100)];
+    const sections: SectionGeometry[] = [section(0, 0, 0)];
+    const result = runLayout(blocks, sections);
+    expect(result.pages[0].headerKind).toBe("default");
+  });
+
+  it("uses 'even' header on even pages when hasEvenHeader is true", () => {
+    const blocks = [para(0, 850), para(1, 850), para(2, 100)];
+    const sections: SectionGeometry[] = [
+      section(0, 0, 2, { hasEvenHeader: true }),
+    ];
+    const result = runLayout(blocks, sections);
+    expect(result.pages[0].headerKind).toBe("default");
+    expect(result.pages[1].headerKind).toBe("even");
+    expect(result.pages[2].headerKind).toBe("default");
+  });
+});
+
+// =========================================================================
+// Long single block (taller than a page)
+// =========================================================================
+
+describe("runLayout — block taller than one page", () => {
+  it("splits a paragraph across multiple pages line by line", () => {
+    // 15 lines of 100 = 1500 height; page content height = 900.
+    // First page: 9 lines fit; next 6 lines on page 2 would mean a widow
+    // of 6 on page 2 — passes the widow check (>= 2). Wait — that's
+    // actually fine. So page 1 has 9, page 2 has 6.
+    const blocks = [
+      para(0, 1500, { lineHeights: Array(15).fill(100) }),
+    ];
+    const result = runLayout(blocks, [section(0, 0, 0)]);
+    expect(result.totalPages).toBe(2);
+    expect(result.pages[0].startsWithContinuation).toBeNull();
+    expect(result.pages[0].endsWithContinuation?.lastLine).toBe(8);
+    expect(result.pages[1].startsWithContinuation?.firstLine).toBe(9);
+  });
+
+  it("splits across three pages when needed", () => {
+    // 20 lines of 100 each, page height 900. 9 + 9 + 2 — but widow rule
+    // (last page has 2 lines) is OK since min is 2.
+    const blocks = [
+      para(0, 2000, { lineHeights: Array(20).fill(100) }),
+    ];
+    const result = runLayout(blocks, [section(0, 0, 0)]);
+    expect(result.totalPages).toBe(3);
+    expect(result.pages[0].endsWithContinuation?.lastLine).toBe(8);
+    expect(result.pages[1].startsWithContinuation?.firstLine).toBe(9);
+    expect(result.pages[1].endsWithContinuation?.lastLine).toBe(17);
+    expect(result.pages[2].startsWithContinuation?.firstLine).toBe(18);
+    expect(result.pages[2].endsWithContinuation).toBeNull();
+  });
+});