@lotics/docx 0.1.0

package/src/layout/engine.ts

@@ -0,0 +1,566 @@
+import type {
+  HeaderFooterKind,
+  LayoutOptions,
+  LayoutResult,
+  MeasuredBlock,
+  Page,
+  PartialBlockSlice,
+  SectionGeometry,
+} from "./types";
+import { DEFAULT_LAYOUT_OPTIONS } from "./types";
+
+
+/**
+ * Pure page-break planner.
+ *
+ * The engine consumes measured block heights, section geometry, and the
+ * paragraph-level layout properties parsed from OOXML, and returns the
+ * sequence of pages plus which block (or slice) starts and ends each page.
+ *
+ * The renderer consumes the result to emit widget decorations at page
+ * boundaries and to mount the per-page chrome rectangles behind the editor
+ * content. The engine itself never touches the DOM.
+ *
+ * Algorithm:
+ *   1. Greedy fill: pack blocks onto pages by accumulating heights against
+ *      the section's content area. When a block doesn't fit, decide whether
+ *      it can be split (paragraphs, tables) or must move whole.
+ *   2. Apply paragraph break rules during the same pass:
+ *      - `pageBreakBefore`: force a new page before this block.
+ *      - `keepLines`: a paragraph that would split must move whole instead.
+ *      - widow/orphan: a paragraph may not leave < `minLinesBeforeBreak`
+ *        lines on the current page nor < `minLinesAfterBreak` on the next.
+ *   3. Fix-up pass for `keepNext`: bind a paragraph to the following block.
+ *      If they end up on different pages, push the earlier one forward.
+ *
+ * Complexity is O(N) in the number of blocks. The keepNext fix-up is at
+ * most O(N) on a single linear sweep because we never re-evaluate blocks
+ * we've already settled.
+ */
+export function runLayout(
+  blocks: readonly MeasuredBlock[],
+  sectionGeometries: readonly SectionGeometry[],
+  options: LayoutOptions = DEFAULT_LAYOUT_OPTIONS,
+): LayoutResult {
+  if (sectionGeometries.length === 0) {
+    return { pages: [], totalPages: 0 };
+  }
+
+  const builder = new PageBuilder(sectionGeometries, options);
+
+  for (const block of blocks) {
+    builder.place(block);
+  }
+  builder.finalize();
+
+  const pagesAfterKeepNext = applyKeepNext(builder.pages, blocks, options);
+  return {
+    pages: pagesAfterKeepNext,
+    totalPages: pagesAfterKeepNext.length,
+  };
+}
+
+/**
+ * After all placement (greedy fill + keepNext fix-up) is complete, walk
+ * pages in order and compute the gap each page's first block needs in
+ * flow coordinates so that block lands at the chrome layer's body-slot
+ * top for that page.
+ *
+ * The editor content's flow Y at the END of page N's last block equals:
+ *   mountPaddingTop + heightUsed_N
+ *   = page_N_body_slot_top + heightUsed_N  (since mountPaddingTop = headerBand_first)
+ *
+ * The next block must land at page (N+1)'s body slot top:
+ *   page_N+1_body_slot_top = page_N_chrome_top + pageHeight_N + visualGap + headerBand_N+1
+ *
+ * Solving for the gap:
+ *   gap = page_N+1_body_slot_top - (page_N_body_slot_top + heightUsed_N)
+ *       = (pageContentHeight_N - heightUsed_N)   // unused body slot
+ *         + footerBand_N                          // band below body slot
+ *         + visualGap                             // gray space between rectangles
+ *         + headerBand_N+1                        // band above next body slot
+ */
+function computeGapHeights(
+  workingPages: readonly WorkingPage[],
+  visualPageGapPx: number,
+): readonly WorkingPage[] {
+  if (workingPages.length === 0) return workingPages;
+  const out = workingPages.map((p) => ({ ...p }));
+  for (let i = 1; i < out.length; i++) {
+    const prev = out[i - 1];
+    const cur = out[i];
+    const unusedOnPrev = Math.max(
+      0,
+      prev.geometry.pageContentHeight - prev.heightUsed,
+    );
+    cur.gapHeightBefore =
+      unusedOnPrev +
+      prev.geometry.footerBand +
+      visualPageGapPx +
+      cur.geometry.headerBand;
+  }
+  return out;
+}
+
+// =========================================================================
+// PageBuilder — internal, mutable scratch space for the greedy fill pass.
+// =========================================================================
+
+type WorkingPage = {
+  pageNumber: number;
+  sectionIndex: number;
+  firstBlockIndex: number;
+  lastBlockIndex: number;
+  startsWithContinuation: PartialBlockSlice | null;
+  endsWithContinuation: PartialBlockSlice | null;
+  headerKind: HeaderFooterKind;
+  isFirstInSection: boolean;
+  heightUsed: number;
+  geometry: SectionGeometry;
+  empty: boolean;
+  gapHeightBefore: number;
+};
+
+class PageBuilder {
+  readonly pages: WorkingPage[] = [];
+  private current: WorkingPage;
+  private sectionPageCount = new Map<number, number>();
+
+  constructor(
+    private readonly sections: readonly SectionGeometry[],
+    private readonly opts: LayoutOptions,
+  ) {
+    this.current = this.openPage(sections[0]);
+  }
+
+  /**
+   * Place a block onto the working page. May close the current page and
+   * open one or more new pages if the block doesn't fit or contains a
+   * forced break.
+   */
+  place(block: MeasuredBlock): void {
+    // Section transition. The OOXML parser groups blocks into sections; a
+    // change in `block.sectionIndex` marks a hard section boundary that
+    // forces a page break (sections may also have different page sizes).
+    if (block.sectionIndex !== this.current.sectionIndex) {
+      this.closeCurrent();
+      this.current = this.openPage(this.sections[block.sectionIndex]);
+    }
+
+    // Honor `w:pageBreakBefore`. The only exception is the very first
+    // block of a section, where forcing a break would create a blank
+    // leading page.
+    if (
+      block.paragraphProperties?.pageBreakBefore === true &&
+      !this.current.empty
+    ) {
+      this.closeCurrent();
+      this.current = this.openPage(this.current.geometry);
+    }
+
+    if (block.kind === "section_break") {
+      this.closeCurrent();
+      this.current = this.openPage(this.sections[block.sectionIndex]);
+      return;
+    }
+
+    this.placeRespectingBreakRules(block);
+  }
+
+  private placeRespectingBreakRules(block: MeasuredBlock): void {
+    const remaining =
+      this.current.geometry.pageContentHeight - this.current.heightUsed;
+
+    // Block fits whole on the current page.
+    if (block.height <= remaining) {
+      this.appendWhole(block);
+      return;
+    }
+
+    // Block doesn't fit and cannot be split — push to next page whole.
+    if (!isSplittable(block)) {
+      this.closeCurrent();
+      this.current = this.openPage(this.current.geometry);
+      this.appendWhole(block);
+      return;
+    }
+
+    // Block doesn't fit but could be split. Apply paragraph rules.
+    if (block.kind === "paragraph") {
+      this.splitParagraph(block, remaining);
+      return;
+    }
+
+    if (block.kind === "table") {
+      this.splitTable(block, remaining);
+      return;
+    }
+  }
+
+  // -------- Paragraph splitting (line-level) ---------------------------
+
+  private splitParagraph(block: MeasuredBlock, remaining: number): void {
+    const lineHeights = block.lineHeights;
+    if (!lineHeights || lineHeights.length === 0) {
+      // Defensive — shouldn't reach here because `isSplittable` checks.
+      this.appendWhole(block);
+      return;
+    }
+
+    const linesThatFit = countLinesThatFit(lineHeights, remaining);
+    const linesRemaining = lineHeights.length - linesThatFit;
+
+    // `keepLines`: paragraph must move whole rather than split. If it
+    // already doesn't fit anywhere, treat the whole-page placement as
+    // the best we can do (matches Word's behavior).
+    if (block.paragraphProperties?.keepLines === true) {
+      if (!this.current.empty) {
+        this.closeCurrent();
+        this.current = this.openPage(this.current.geometry);
+      }
+      this.appendWhole(block);
+      return;
+    }
+
+    // Orphan rule: too few lines fit on the current page. Push whole.
+    if (
+      linesThatFit > 0 &&
+      linesThatFit < this.opts.minLinesBeforeBreak &&
+      !this.current.empty
+    ) {
+      this.closeCurrent();
+      this.current = this.openPage(this.current.geometry);
+      this.appendWhole(block);
+      return;
+    }
+
+    // Widow rule: only a tiny tail would land on the next page. Pull more
+    // lines forward to the next page by reducing what fits here.
+    let cut = linesThatFit;
+    if (
+      linesRemaining > 0 &&
+      linesRemaining < this.opts.minLinesAfterBreak &&
+      cut > this.opts.minLinesBeforeBreak
+    ) {
+      cut = Math.max(
+        this.opts.minLinesBeforeBreak,
+        lineHeights.length - this.opts.minLinesAfterBreak,
+      );
+    }
+
+    // Validate that the split respects BOTH minima. When the paragraph
+    // is too short for any legal split (total lines < before+after), no
+    // split satisfies both rules — fall back to moving the whole block
+    // to the next page so it renders intact. Without this guard, a 3-line
+    // paragraph with minLines=2 would produce a 2/1 split (widow) or a
+    // 1/2 split (orphan).
+    if (
+      cut === 0 ||
+      cut < this.opts.minLinesBeforeBreak ||
+      lineHeights.length - cut < this.opts.minLinesAfterBreak
+    ) {
+      if (!this.current.empty) {
+        this.closeCurrent();
+        this.current = this.openPage(this.current.geometry);
+      }
+      this.appendWhole(block);
+      return;
+    }
+
+    // Split: `cut` lines on this page, the rest on subsequent page(s).
+    const heightOnThisPage = sumLines(lineHeights, 0, cut);
+    this.current.endsWithContinuation = {
+      blockIndex: block.index,
+      firstLine: 0,
+      lastLine: cut - 1,
+    };
+    this.current.lastBlockIndex = block.index;
+    this.current.heightUsed += heightOnThisPage;
+    this.current.empty = false;
+
+    // Carry remaining lines onto subsequent pages.
+    let nextStart = cut;
+    while (nextStart < lineHeights.length) {
+      this.closeCurrent();
+      this.current = this.openPage(this.current.geometry);
+      const continuationRemaining = this.current.geometry.pageContentHeight;
+      const linesFitNext = countLinesThatFit(
+        lineHeights.slice(nextStart),
+        continuationRemaining,
+      );
+      // Defensive: if even one line is taller than a whole page, place
+      // exactly one line per page so we don't loop forever.
+      const taken = Math.max(1, linesFitNext);
+      const lastIdx = Math.min(
+        nextStart + taken - 1,
+        lineHeights.length - 1,
+      );
+      this.current.firstBlockIndex = block.index;
+      this.current.lastBlockIndex = block.index;
+      this.current.startsWithContinuation = {
+        blockIndex: block.index,
+        firstLine: nextStart,
+        lastLine: lastIdx,
+      };
+      const usedNext = sumLines(lineHeights, nextStart, lastIdx + 1);
+      this.current.heightUsed = usedNext;
+      this.current.empty = false;
+      // If this is the final chunk, do not set endsWithContinuation; the
+      // block has finished on this page.
+      if (lastIdx < lineHeights.length - 1) {
+        this.current.endsWithContinuation = {
+          blockIndex: block.index,
+          firstLine: nextStart,
+          lastLine: lastIdx,
+        };
+      }
+      nextStart = lastIdx + 1;
+    }
+  }
+
+  // -------- Table splitting (row-level) --------------------------------
+
+  private splitTable(block: MeasuredBlock, remaining: number): void {
+    const rowHeights = block.rowHeights;
+    if (!rowHeights || rowHeights.length === 0) {
+      this.appendWhole(block);
+      return;
+    }
+    const rowsThatFit = countLinesThatFit(rowHeights, remaining);
+
+    // If at least one row fits, split at that row. Otherwise move whole.
+    if (rowsThatFit === 0) {
+      if (!this.current.empty) {
+        this.closeCurrent();
+        this.current = this.openPage(this.current.geometry);
+      }
+      this.appendWhole(block);
+      return;
+    }
+
+    this.current.endsWithContinuation = {
+      blockIndex: block.index,
+      firstLine: 0,
+      lastLine: rowsThatFit - 1,
+    };
+    this.current.lastBlockIndex = block.index;
+    this.current.heightUsed += sumLines(rowHeights, 0, rowsThatFit);
+    this.current.empty = false;
+
+    let nextStart = rowsThatFit;
+    while (nextStart < rowHeights.length) {
+      this.closeCurrent();
+      this.current = this.openPage(this.current.geometry);
+      const fitNext = countLinesThatFit(
+        rowHeights.slice(nextStart),
+        this.current.geometry.pageContentHeight,
+      );
+      const taken = Math.max(1, fitNext);
+      const lastIdx = Math.min(
+        nextStart + taken - 1,
+        rowHeights.length - 1,
+      );
+      this.current.firstBlockIndex = block.index;
+      this.current.lastBlockIndex = block.index;
+      this.current.startsWithContinuation = {
+        blockIndex: block.index,
+        firstLine: nextStart,
+        lastLine: lastIdx,
+      };
+      this.current.heightUsed = sumLines(rowHeights, nextStart, lastIdx + 1);
+      this.current.empty = false;
+      if (lastIdx < rowHeights.length - 1) {
+        this.current.endsWithContinuation = {
+          blockIndex: block.index,
+          firstLine: nextStart,
+          lastLine: lastIdx,
+        };
+      }
+      nextStart = lastIdx + 1;
+    }
+  }
+
+  // -------- Page life-cycle --------------------------------------------
+
+  private appendWhole(block: MeasuredBlock): void {
+    if (this.current.empty) {
+      this.current.firstBlockIndex = block.index;
+    }
+    this.current.lastBlockIndex = block.index;
+    this.current.heightUsed += block.height;
+    this.current.empty = false;
+  }
+
+  private openPage(geometry: SectionGeometry): WorkingPage {
+    const sectionPageNumber =
+      (this.sectionPageCount.get(geometry.sectionIndex) ?? 0) + 1;
+    this.sectionPageCount.set(geometry.sectionIndex, sectionPageNumber);
+    const isFirstInSection = sectionPageNumber === 1;
+    const pageNumber = this.pages.length + 1;
+    return {
+      pageNumber,
+      sectionIndex: geometry.sectionIndex,
+      firstBlockIndex: geometry.blockStartIndex,
+      lastBlockIndex: geometry.blockStartIndex,
+      startsWithContinuation: null,
+      endsWithContinuation: null,
+      headerKind: pickHeaderKind({
+        pageNumber,
+        isFirstInSection,
+        geometry,
+      }),
+      isFirstInSection,
+      heightUsed: 0,
+      geometry,
+      empty: true,
+      // Filled in by `finalizeGapHeights` after keepNext settles. The
+      // gap depends on the previous page's final heightUsed, which can
+      // change during the keepNext fix-up pass, so we defer.
+      gapHeightBefore: 0,
+    };
+  }
+
+  private closeCurrent(): void {
+    if (this.current.empty) {
+      // Don't push empty leading pages, but always push if we've already
+      // accumulated pages (preserves the section's first-page slot even
+      // when it was forcibly broken from immediately).
+      if (this.pages.length === 0) return;
+    }
+    this.pages.push(this.current);
+  }
+
+  finalize(): void {
+    if (!this.current.empty || this.pages.length === 0) {
+      this.pages.push(this.current);
+    }
+  }
+}
+
+// =========================================================================
+// keepNext fix-up (second pass)
+// =========================================================================
+
+/**
+ * `w:keepNext` binds a paragraph to the start of the next block. If the
+ * greedy pass left the paragraph at the end of page N and the next block
+ * starts on page N+1, push the paragraph forward to page N+1 as well.
+ *
+ * Implementation: walk pages back-to-front. For each page, if its last
+ * block has `keepNext` and the next page's first block is the block
+ * immediately after it, move the last block forward.
+ *
+ * We bound the fix-up: only one pass. Chains of keepNext can in theory
+ * cascade (A keepNext B keepNext C and C moves), but cascading shoves are
+ * rare and an extra page on the previous page is the only side effect.
+ * A second pass would handle them; for MVP we accept the rare cosmetic
+ * drift.
+ */
+function applyKeepNext(
+  pages: readonly WorkingPage[],
+  blocks: readonly MeasuredBlock[],
+  options: LayoutOptions,
+): readonly Page[] {
+  if (pages.length === 0) return [];
+  if (pages.length < 2) {
+    const single = computeGapHeights(pages, options.visualPageGapPx);
+    return single.map(workingPageToPage);
+  }
+  const mutable: WorkingPage[] = pages.map((p) => ({ ...p }));
+
+  for (let i = mutable.length - 2; i >= 0; i--) {
+    const page = mutable[i];
+    const next = mutable[i + 1];
+    if (page.endsWithContinuation !== null) continue;
+    const lastBlock = blocks[page.lastBlockIndex];
+    if (!lastBlock?.paragraphProperties?.keepNext) continue;
+    if (next.firstBlockIndex !== page.lastBlockIndex + 1) continue;
+    if (next.startsWithContinuation !== null) continue;
+
+    // Move `lastBlock` from page i to page i+1's start, if it fits.
+    const nextRemaining =
+      next.geometry.pageContentHeight - next.heightUsed;
+    if (lastBlock.height > nextRemaining) continue;
+
+    page.heightUsed -= lastBlock.height;
+    page.lastBlockIndex -= 1;
+    // If the page is now empty, drop it. Otherwise leave it.
+    if (page.lastBlockIndex < page.firstBlockIndex) {
+      page.empty = true;
+    }
+
+    next.firstBlockIndex = lastBlock.index;
+    next.heightUsed += lastBlock.height;
+  }
+
+  // Drop pages that became empty after keepNext moves.
+  const filtered = mutable.filter((p) => !p.empty);
+  // Re-number pages after any drops, then compute gap heights against the
+  // final (post-keepNext) heightUsed values.
+  const renumbered = filtered.map((p, idx) => ({ ...p, pageNumber: idx + 1 }));
+  return computeGapHeights(renumbered, options.visualPageGapPx).map(
+    workingPageToPage,
+  );
+}
+
+function workingPageToPage(p: WorkingPage): Page {
+  return {
+    pageNumber: p.pageNumber,
+    sectionIndex: p.sectionIndex,
+    firstBlockIndex: p.firstBlockIndex,
+    lastBlockIndex: p.lastBlockIndex,
+    headerKind: p.headerKind,
+    isFirstInSection: p.isFirstInSection,
+    startsWithContinuation: p.startsWithContinuation,
+    endsWithContinuation: p.endsWithContinuation,
+    gapHeightBefore: p.gapHeightBefore,
+  };
+}
+
+// =========================================================================
+// Helpers
+// =========================================================================
+
+function pickHeaderKind(args: {
+  pageNumber: number;
+  isFirstInSection: boolean;
+  geometry: SectionGeometry;
+}): HeaderFooterKind {
+  if (args.isFirstInSection && args.geometry.titlePage) return "first";
+  if (args.geometry.hasEvenHeader && args.pageNumber % 2 === 0) return "even";
+  return "default";
+}
+
+function isSplittable(block: MeasuredBlock): boolean {
+  if (block.kind === "paragraph") {
+    return (block.lineHeights?.length ?? 0) > 1;
+  }
+  if (block.kind === "table") {
+    return (block.rowHeights?.length ?? 0) > 1;
+  }
+  return false;
+}
+
+function countLinesThatFit(
+  heights: readonly number[],
+  budget: number,
+): number {
+  let total = 0;
+  for (let i = 0; i < heights.length; i++) {
+    if (total + heights[i] > budget) return i;
+    total += heights[i];
+  }
+  return heights.length;
+}
+
+function sumLines(
+  heights: readonly number[],
+  fromInclusive: number,
+  toExclusive: number,
+): number {
+  let total = 0;
+  for (let i = fromInclusive; i < toExclusive; i++) {
+    total += heights[i];
+  }
+  return total;
+}

package/src/layout/page_geometry.ts

@@ -0,0 +1,43 @@
+import type { Section } from "../model/sections";
+import { dxaToPx } from "../render/units";
+import type { SectionGeometry } from "./types";
+
+/**
+ * Derive per-section page geometry in CSS pixels from the parsed
+ * SectionProperties (which use OOXML dxa units throughout).
+ *
+ * The result is intentionally a plain readonly array, indexed by
+ * `sectionIndex` so the engine can look up a section's geometry in O(1)
+ * during the layout pass.
+ */
+export function computeSectionGeometries(
+  sections: readonly Section[],
+): readonly SectionGeometry[] {
+  return sections.map((section, sectionIndex) => {
+    const { pageSize, margins, headerRefs, footerRefs, titlePage } =
+      section.properties;
+    const pageHeight = dxaToPx(pageSize.height);
+    const pageWidth = dxaToPx(pageSize.width);
+    const marginTop = dxaToPx(margins.top);
+    const marginBottom = dxaToPx(margins.bottom);
+    // The header band is the space between the page edge and the start of
+    // content. Word reserves `margin.top` even when there is no header, so
+    // we always set headerBand = marginTop. Same applies to footers.
+    const headerBand = marginTop;
+    const footerBand = marginBottom;
+    const pageContentHeight = pageHeight - headerBand - footerBand;
+
+    return {
+      sectionIndex,
+      blockStartIndex: section.blockStartIndex,
+      blockEndIndex: section.blockEndIndex,
+      pageHeight,
+      pageWidth,
+      pageContentHeight,
+      headerBand,
+      footerBand,
+      titlePage,
+      hasEvenHeader: headerRefs.some((r) => r.type === "even"),
+    };
+  });
+}