@lotics/docx 0.1.0

package/src/pm/pagination_plugin.ts

@@ -0,0 +1,590 @@
+import { Plugin, PluginKey } from "prosemirror-state";
+import type { EditorState, Transaction } from "prosemirror-state";
+import type { EditorView } from "prosemirror-view";
+import { Decoration, DecorationSet } from "prosemirror-view";
+import type { Node as PMNode } from "prosemirror-model";
+
+import type { ParagraphProperties } from "../model/properties";
+import type { Section } from "../model/sections";
+import type {
+  LayoutResult,
+  MeasuredBlock,
+  SectionGeometry,
+} from "../layout/types";
+import { runLayout } from "../layout/engine";
+
+export const paginationPluginKey = new PluginKey<PaginationPluginState>(
+  "docx-pagination",
+);
+
+export type PaginationPluginOptions = {
+  /** Sections parsed from the document. The plugin maps each PM block to a section. */
+  sections: readonly Section[];
+  /** Pre-computed per-section geometries (pageHeight, content area, etc.). */
+  sectionGeometries: readonly SectionGeometry[];
+  /**
+   * Visual gap between page rectangles in CSS pixels. Used by the layout
+   * engine to compute each page's `gapHeightBefore` (which the renderer
+   * emits as a widget decoration so flow content aligns with chrome).
+   */
+  pageGapPx: number;
+  /** Notified whenever the layout result changes (page count, page boundaries). */
+  onLayoutChange?: (layout: LayoutResult) => void;
+};
+
+export type PaginationPluginState = {
+  layout: LayoutResult | null;
+  decorations: DecorationSet;
+};
+
+/**
+ * Pagination coordinator.
+ *
+ * On every doc change, schedules a rAF in which it measures each top-level
+ * block's offsetHeight via the editor view, runs {@link runLayout}, and
+ * emits widget decorations at page boundaries. The {@link PaginationPluginState}
+ * exposes the most recent {@link LayoutResult} so other components (status
+ * bar, PageChromeManager) can subscribe via {@link paginationPluginKey}.
+ *
+ * Decorations are visual only — they never mutate the doc model. Page-gap
+ * widgets are inserted via {@link Decoration.widget} immediately before the
+ * first block of each subsequent page and produce a transparent spacer
+ * matching the chrome layer's gap height. This keeps the editor's flowing
+ * content aligned with the absolutely-positioned page rectangles behind it.
+ *
+ * The plugin does not assume a particular DOM layout; it only requires that
+ * the editor's DOM contains one direct child per top-level PM block. This
+ * matches PM's default rendering for block nodes.
+ */
+export function paginationPlugin(
+  options: PaginationPluginOptions,
+): Plugin<PaginationPluginState> {
+  return new Plugin<PaginationPluginState>({
+    key: paginationPluginKey,
+    state: {
+      init: () => ({ layout: null, decorations: DecorationSet.empty }),
+      apply: (tr, value) => {
+        const meta = tr.getMeta(paginationPluginKey) as
+          | { layout: LayoutResult; decorations: DecorationSet }
+          | undefined;
+        if (meta) return meta;
+        if (!tr.docChanged) return value;
+        // Map existing decorations through the transaction's mapping so
+        // they survive position-preserving changes. They'll be replaced
+        // on the next layout pass.
+        return {
+          layout: value.layout,
+          decorations: value.decorations.map(tr.mapping, tr.doc),
+        };
+      },
+    },
+    props: {
+      decorations(state) {
+        return paginationPluginKey.getState(state)?.decorations ?? null;
+      },
+    },
+    view(editorView) {
+      let rafHandle: number | null = null;
+      let disposed = false;
+
+      const recompute = () => {
+        rafHandle = null;
+        if (disposed) return;
+        const state = editorView.state;
+        const blocks = measureBlocks(editorView, state, options);
+        const layout = runLayout(blocks, options.sectionGeometries, {
+          minLinesBeforeBreak: 2,
+          minLinesAfterBreak: 2,
+          visualPageGapPx: options.pageGapPx,
+        });
+        const decorations = buildDecorations(state.doc, layout, editorView);
+        const prev = paginationPluginKey.getState(state);
+        if (prev && layoutsEqual(prev.layout, layout)) return;
+        editorView.dispatch(
+          state.tr.setMeta(paginationPluginKey, { layout, decorations }),
+        );
+        options.onLayoutChange?.(layout);
+      };
+
+      const schedule = () => {
+        if (disposed) return;
+        if (rafHandle !== null) return;
+        rafHandle = window.requestAnimationFrame(recompute);
+      };
+
+      // Initial pass — deferred to a microtask so the EditorView
+      // constructor finishes before the plugin dispatches the first
+      // pagination transaction. PM forbids `view.dispatch` from inside
+      // a plugin's `view()` callback because the EditorView is not yet
+      // fully constructed. queueMicrotask gives us the earliest legal
+      // dispatch slot (before paint) so users still see chrome on first
+      // paint instead of after an rAF tick.
+      queueMicrotask(() => {
+        if (!disposed) recompute();
+      });
+
+      // ResizeObserver catches font-load and container-resize cases that
+      // PM transactions don't trigger.
+      const ro =
+        typeof ResizeObserver !== "undefined"
+          ? new ResizeObserver(schedule)
+          : null;
+      ro?.observe(editorView.dom);
+
+      return {
+        update: (_view, prevState) => {
+          if (editorView.state.doc !== prevState.doc) {
+            schedule();
+          }
+        },
+        destroy: () => {
+          disposed = true;
+          if (rafHandle !== null) cancelAnimationFrame(rafHandle);
+          ro?.disconnect();
+        },
+      };
+    },
+  });
+}
+
+// =========================================================================
+// Measurement
+// =========================================================================
+
+/**
+ * Walk the top-level blocks in the PM doc, look up each block's DOM node,
+ * and produce {@link MeasuredBlock}s. Blocks that are paragraphs also
+ * receive a line-height array reconstructed from the rendered DOM so the
+ * engine can split them at line boundaries.
+ *
+ * The mapping from block to section uses the section blockStart/blockEnd
+ * ranges. Section breaks inside the doc (as `section_break` PM nodes)
+ * advance the active section.
+ */
+function measureBlocks(
+  view: EditorView,
+  state: EditorState,
+  options: PaginationPluginOptions,
+): MeasuredBlock[] {
+  const blocks: MeasuredBlock[] = [];
+  const doc = state.doc;
+  let sectionIndex = 0;
+  let blockIndex = 0;
+  let hasWarnedSectionMismatch = false;
+
+  doc.forEach((node, _offset, index) => {
+    const dom = view.nodeDOM(positionOfChild(doc, index));
+    const el = dom instanceof HTMLElement ? dom : null;
+    // Use the flow extent (offsetHeight + margin to next sibling) rather
+    // than offsetHeight alone. Block-level CSS margins between paragraphs
+    // contribute to the actual flow position of subsequent content; if
+    // the engine ignores them, heightUsed undercounts and the gap widget
+    // ends up too short by ~10 px per inter-paragraph margin on each
+    // page, drifting content above the chrome's body slot over time.
+    const height = el ? effectiveFlowHeight(el) : 0;
+    const lineHeights =
+      node.type.name === "paragraph" && el
+        ? measureParagraphLineHeights(el)
+        : null;
+    const rowHeights =
+      isTableNode(node) && el ? measureTableRowHeights(el) : null;
+
+    blocks.push({
+      index: blockIndex,
+      sectionIndex,
+      kind: classifyBlockKind(node),
+      height,
+      paragraphProperties: node.attrs.properties as ParagraphProperties | null,
+      lineHeights,
+      rowHeights,
+    });
+
+    if (node.type.name === "section_break") {
+      const next = sectionIndex + 1;
+      if (next >= options.sections.length) {
+        // The doc has more section_break nodes than the parsed
+        // sections array describes. Throwing here would crash the
+        // editor mid-render; clamping silently produces wrong page
+        // geometry. Compromise: clamp and warn so developers see the
+        // mismatch in the console without losing the surface.
+        if (!hasWarnedSectionMismatch) {
+          // eslint-disable-next-line no-console
+          console.warn(
+            `[docx-editor] section_break at block ${blockIndex} exceeds sections.length (${options.sections.length}). ` +
+              "Blocks past the last section will reuse its geometry. Caller should keep `sections` in sync with the document's section_break count.",
+          );
+          hasWarnedSectionMismatch = true;
+        }
+      } else {
+        sectionIndex = next;
+      }
+    }
+    blockIndex += 1;
+  });
+
+  return blocks;
+}
+
+/**
+ * Effective flow height of a block: `offsetHeight` plus the whitespace
+ * between this element's bottom and the next sibling's top (i.e. the
+ * resolved block margin after CSS margin-collapse).
+ *
+ * Why this matters for pagination: the editor content's flow extent is
+ * what determines where the next page's content lands. CSS `<p>` margins
+ * are visible in the layout but not in `offsetHeight`. Without
+ * accounting for them the engine undercounts heightUsed per page, the
+ * gap widget ends up too short, and content drifts above each page's
+ * body slot.
+ *
+ * For the last child of the editor (no next sibling) we return
+ * `offsetHeight` — the trailing margin has no in-flow consumer.
+ *
+ * Page-gap widget siblings are deliberately included in the diff:
+ * a paragraph that sits immediately before a gap widget contributes its
+ * own margin-bottom (the widget itself has margin: 0, so the diff to its
+ * top is exactly the paragraph's margin-bottom).
+ */
+function effectiveFlowHeight(el: HTMLElement): number {
+  const next = el.nextElementSibling;
+  if (!(next instanceof HTMLElement)) return el.offsetHeight;
+  const myBottom = el.getBoundingClientRect().bottom;
+  const nextTop = next.getBoundingClientRect().top;
+  const margin = nextTop - myBottom;
+  return el.offsetHeight + Math.max(0, margin);
+}
+
+function positionOfChild(doc: PMNode, index: number): number {
+  let pos = 0;
+  for (let i = 0; i < index; i++) {
+    pos += doc.child(i).nodeSize;
+  }
+  return pos;
+}
+
+function classifyBlockKind(node: PMNode): MeasuredBlock["kind"] {
+  switch (node.type.name) {
+    case "paragraph":
+      return "paragraph";
+    case "table":
+      return "table";
+    case "section_break":
+      return "section_break";
+    default:
+      return "opaque_block";
+  }
+}
+
+function isTableNode(node: PMNode): boolean {
+  return node.type.name === "table";
+}
+
+/**
+ * Measure per-line heights of a paragraph DOM node. The renderer uses
+ * standard `<p>` flow layout, so we approximate line heights by walking
+ * the paragraph's client rects via `Range.getClientRects` and grouping
+ * adjacent rects on the same baseline.
+ *
+ * Returns null if the paragraph has only one line (no split possible).
+ */
+function measureParagraphLineHeights(el: HTMLElement): readonly number[] | null {
+  // Skip when the paragraph is empty or doesn't render multiple lines.
+  const range = document.createRange();
+  try {
+    range.selectNodeContents(el);
+  } catch {
+    return null;
+  }
+  const rects = Array.from(range.getClientRects());
+  if (rects.length <= 1) return null;
+
+  // Each rect roughly corresponds to a line in flow. Group by approximate
+  // top position to coalesce rects belonging to the same line that PM/CSS
+  // split across child spans.
+  const lines: number[] = [];
+  let currentTop: number | null = null;
+  let currentHeight = 0;
+  const TOLERANCE = 0.5; // px — same-baseline rect tolerance.
+  for (const r of rects) {
+    if (currentTop === null || Math.abs(r.top - currentTop) > TOLERANCE) {
+      if (currentTop !== null) lines.push(currentHeight);
+      currentTop = r.top;
+      currentHeight = r.height;
+    } else {
+      currentHeight = Math.max(currentHeight, r.height);
+    }
+  }
+  if (currentTop !== null) lines.push(currentHeight);
+  // If the line array is still singular, no split is possible.
+  if (lines.length <= 1) return null;
+  return lines;
+}
+
+/**
+ * Measure per-row heights of a table by reading offsetHeight from each
+ * `<tr>` child. Returns null when no rows are present.
+ */
+function measureTableRowHeights(el: HTMLElement): readonly number[] | null {
+  const rows = el.querySelectorAll("tr");
+  if (rows.length === 0) return null;
+  const heights: number[] = [];
+  rows.forEach((row) => {
+    heights.push((row as HTMLElement).offsetHeight);
+  });
+  return heights;
+}
+
+// =========================================================================
+// Decorations
+// =========================================================================
+
+function buildDecorations(
+  doc: PMNode,
+  layout: LayoutResult,
+  view: EditorView,
+): DecorationSet {
+  if (layout.pages.length <= 1) return DecorationSet.empty;
+
+  const decorations: Decoration[] = [];
+  // Build a list of block index → PM position for top-level blocks.
+  const positionByBlockIndex: number[] = [];
+  let pos = 0;
+  doc.forEach((node) => {
+    positionByBlockIndex.push(pos);
+    pos += node.nodeSize;
+  });
+
+  // Place a gap widget at the layout-determined boundary for every page
+  // after page 1. The engine-computed `gapHeightBefore` bridges the
+  // unused body-slot space on the previous page, the previous footer
+  // band, the visual gap between rectangles, and the next header band —
+  // so the flow position immediately after the widget equals the next
+  // page's body-slot top.
+  //
+  // Real-world wrinkle: the first block on a page often carries a CSS
+  // `margin-top` (Heading 1 / Title styles have one by default). With
+  // the widget at its engine-computed height, the block's box top would
+  // sit at body-slot top, but its CSS margin pushes the box DOWN by
+  // `margin-top` from the gap widget's bottom — overshooting by that
+  // amount. To compensate, we measure the next block's resolved
+  // `margin-top` and subtract it from the widget height. The CSS margin
+  // then "fills" the same space the widget would have occupied; the
+  // block's box lands exactly at body-slot top.
+  //
+  // When a page starts with the *continuation* of a block from the
+  // previous page (long paragraph spanning pages), the widget must be
+  // inserted MID-paragraph at the line boundary, not before the block —
+  // otherwise the entire paragraph slides to the next page. We use DOM
+  // measurement to find the PM position corresponding to the start of
+  // the next page's first line; falling back to block start when the
+  // measurement isn't possible.
+  for (let i = 1; i < layout.pages.length; i++) {
+    const page = layout.pages[i];
+    let widgetPos: number;
+    let blockDom: HTMLElement | null = null;
+    if (page.startsWithContinuation) {
+      const inlinePos = resolveInlineSplitPos({
+        view,
+        doc,
+        positionByBlockIndex,
+        slice: page.startsWithContinuation,
+      });
+      widgetPos =
+        inlinePos ??
+        positionByBlockIndex[page.startsWithContinuation.blockIndex] ??
+        0;
+      const blockPos =
+        positionByBlockIndex[page.startsWithContinuation.blockIndex];
+      if (blockPos !== undefined) {
+        const dom = view.nodeDOM(blockPos);
+        if (dom instanceof HTMLElement) blockDom = dom;
+      }
+    } else {
+      const blockPos = positionByBlockIndex[page.firstBlockIndex];
+      widgetPos = blockPos ?? 0;
+      if (blockPos !== undefined) {
+        const dom = view.nodeDOM(blockPos);
+        if (dom instanceof HTMLElement) blockDom = dom;
+      }
+    }
+    const marginTopPx = blockDom ? readMarginTop(blockDom) : 0;
+    // Continuation paragraphs are visually a single block split across
+    // pages — the heading's margin-top doesn't apply mid-paragraph, so
+    // we skip the adjustment when there's a continuation.
+    const adjustedGap = page.startsWithContinuation
+      ? page.gapHeightBefore
+      : Math.max(0, page.gapHeightBefore - marginTopPx);
+    decorations.push(
+      Decoration.widget(widgetPos, gapWidget(adjustedGap, page.pageNumber), {
+        side: -1,
+        key: `page-gap-${page.pageNumber}-${adjustedGap}`,
+        ignoreSelection: true,
+      }),
+    );
+  }
+
+  return DecorationSet.create(doc, decorations);
+}
+
+/**
+ * Map a paragraph's `startsWithContinuation` slice to the PM position that
+ * starts the slice's first visual line in the rendered DOM.
+ *
+ * Strategy: measure per-line client rects of the paragraph via Range. For
+ * each rect, find the first DOM character whose bounding rect aligns with
+ * that line's top. The slice's `firstLine` index picks the target rect.
+ * `view.posAtDOM` translates the DOM offset to a PM position.
+ *
+ * Returns null when the paragraph isn't a paragraph node, the DOM isn't
+ * available (e.g., during initial mount), or measurement returns
+ * unexpected geometry (RTL, complex inline atoms). The caller falls back
+ * to block-start placement.
+ */
+function resolveInlineSplitPos(args: {
+  view: EditorView;
+  doc: PMNode;
+  positionByBlockIndex: readonly number[];
+  slice: import("../layout/types").PartialBlockSlice;
+}): number | null {
+  const blockPos = args.positionByBlockIndex[args.slice.blockIndex];
+  if (blockPos === undefined) return null;
+  const blockNode = args.doc.maybeChild(args.slice.blockIndex);
+  if (!blockNode || blockNode.type.name !== "paragraph") return null;
+
+  const dom = args.view.nodeDOM(blockPos);
+  const el = dom instanceof HTMLElement ? dom : null;
+  if (!el) return null;
+
+  const range = document.createRange();
+  range.selectNodeContents(el);
+  const rects = Array.from(range.getClientRects());
+  if (rects.length === 0) return null;
+  // Coalesce rects on the same baseline to per-line records.
+  const lines: number[] = []; // top Y of each line
+  const TOL = 0.5;
+  let currentTop: number | null = null;
+  for (const r of rects) {
+    if (currentTop === null || Math.abs(r.top - currentTop) > TOL) {
+      lines.push(r.top);
+      currentTop = r.top;
+    }
+  }
+  if (args.slice.firstLine >= lines.length) return null;
+  const targetTop = lines[args.slice.firstLine];
+
+  // Find the first text node character whose bounding rect aligns with
+  // `targetTop`. Walk text descendants in DOM order.
+  const walker = document.createTreeWalker(el, NodeFilter.SHOW_TEXT, null);
+  let node: Node | null = walker.nextNode();
+  while (node) {
+    const text = node.textContent ?? "";
+    for (let offset = 0; offset < text.length; offset++) {
+      const r = document.createRange();
+      r.setStart(node, offset);
+      r.setEnd(node, Math.min(offset + 1, text.length));
+      const rect = r.getBoundingClientRect();
+      if (rect.height > 0 && Math.abs(rect.top - targetTop) <= TOL) {
+        // Found a character on the target line. Convert to PM position.
+        // posAtDOM throws only for genuinely-invalid (node, offset) pairs
+        // that we never construct here — the walker gives us live text
+        // nodes from the editor's own DOM. If it throws, the doc state
+        // is inconsistent and we want a loud failure, not a silent
+        // mis-pagination.
+        return args.view.posAtDOM(node, offset);
+      }
+    }
+    node = walker.nextNode();
+  }
+  return null;
+}
+
+/**
+ * Read the computed `margin-top` (in CSS pixels) on a block element. We
+ * use this to compensate the gap widget for headings (and other styles)
+ * whose CSS margin would otherwise push the block past the chrome's
+ * body-slot top by that margin's width.
+ */
+function readMarginTop(el: HTMLElement): number {
+  const raw = getComputedStyle(el).marginTop;
+  const parsed = Number.parseFloat(raw);
+  return Number.isFinite(parsed) ? parsed : 0;
+}
+
+function gapWidget(heightPx: number, pageNumber: number): () => HTMLElement {
+  return () => {
+    const el = document.createElement("div");
+    el.className = "docx-page-gap";
+    el.setAttribute("data-page-gap-after", String(pageNumber - 1));
+    el.setAttribute("aria-hidden", "true");
+    el.style.display = "block";
+    el.style.height = `${heightPx}px`;
+    el.style.width = "100%";
+    el.style.pointerEvents = "none";
+    return el;
+  };
+}
+
+// =========================================================================
+// Helpers
+// =========================================================================
+
+function layoutsEqual(a: LayoutResult | null, b: LayoutResult): boolean {
+  if (a === null) return false;
+  if (a.totalPages !== b.totalPages) return false;
+  if (a.pages.length !== b.pages.length) return false;
+  for (let i = 0; i < a.pages.length; i++) {
+    const pa = a.pages[i];
+    const pb = b.pages[i];
+    if (pa.firstBlockIndex !== pb.firstBlockIndex) return false;
+    if (pa.lastBlockIndex !== pb.lastBlockIndex) return false;
+    if (pa.headerKind !== pb.headerKind) return false;
+    if (pa.sectionIndex !== pb.sectionIndex) return false;
+    // gapHeightBefore feeds the widget decoration's height; missing it
+    // here would let a font-load or measurement change leave stale gap
+    // widgets that no longer match the chrome's body-slot positions.
+    if (pa.gapHeightBefore !== pb.gapHeightBefore) return false;
+    if (
+      partialEqual(pa.startsWithContinuation, pb.startsWithContinuation) ===
+      false
+    )
+      return false;
+    if (partialEqual(pa.endsWithContinuation, pb.endsWithContinuation) === false)
+      return false;
+  }
+  return true;
+}
+
+function partialEqual(
+  a: import("../layout/types").PartialBlockSlice | null,
+  b: import("../layout/types").PartialBlockSlice | null,
+): boolean {
+  if (a === null && b === null) return true;
+  if (a === null || b === null) return false;
+  return (
+    a.blockIndex === b.blockIndex &&
+    a.firstLine === b.firstLine &&
+    a.lastLine === b.lastLine
+  );
+}
+
+/**
+ * Read the current pagination state from an EditorState. Public for the
+ * status bar, PageChromeManager hookup, and tests.
+ */
+export function getPaginationState(
+  state: EditorState,
+): PaginationPluginState | null {
+  return paginationPluginKey.getState(state) ?? null;
+}
+
+/**
+ * Manually push a new layout result into the plugin state. Used by
+ * tests that bypass the rAF measurement loop.
+ */
+export function setPaginationLayout(
+  view: EditorView,
+  layout: LayoutResult,
+): Transaction {
+  const decorations = buildDecorations(view.state.doc, layout, view);
+  return view.state.tr.setMeta(paginationPluginKey, { layout, decorations });
+}