@beyondwork/docx-react-component 1.0.37 → 1.0.39

package/src/runtime/layout/page-graph.ts

@@ -102,6 +102,42 @@ export interface RuntimeBlockFragment {
   to: number;
   /** Height consumed on this page (twips). */
   heightTwips: number;
+  /**
+   * Fragment classification.
+   * - `"whole"` (default): the fragment represents the entire block; no slicing.
+   * - `"paragraph-slice"`: one of several fragments produced by intra-paragraph
+   *   line-box splitting. `paragraphLineRange` identifies which lines this
+   *   slice renders.
+   * - `"table-slice"`: one of several fragments produced by row-boundary table
+   *   splitting (emitted by the table-fidelity workstream).
+   *   `tableRowRange` identifies which canonical rows this slice renders.
+   * Consumers that predate multi-fragment blocks may treat an absent `kind`
+   * as `"whole"`.
+   */
+  kind?: "whole" | "paragraph-slice" | "table-slice";
+  /**
+   * For `kind === "paragraph-slice"`, the inclusive-exclusive line-box index
+   * range rendered by this slice plus the total line count for the source
+   * paragraph. `from`/`to` still span the full paragraph offset range on
+   * every slice — only the visible lines differ.
+   */
+  paragraphLineRange?: {
+    from: number;
+    to: number;
+    totalLines: number;
+  };
+  /**
+   * For `kind === "table-slice"`, the inclusive-exclusive row-index range
+   * rendered by this slice. Repeated header rows (when the table has
+   * `isHeader` rows and `continuation` pages) are implied by the owning
+   * table's canonical row list — consumers prepend header rows for slices
+   * whose `from > 0`.
+   */
+  tableRowRange?: {
+    from: number;
+    to: number;
+    totalRows: number;
+  };
 }
 
 export interface RuntimeLineBox {
@@ -148,6 +184,16 @@ export interface BuildPageGraphInput {
   /** Optional block fragments pre-computed by pagination; when omitted the
    *  graph produces one fragment per page spanning its entire offset range. */
   fragments?: readonly RuntimeBlockFragment[];
+  /**
+   * Optional block fragments keyed by pageIndex with the `pageId` omitted.
+   * `buildPageGraph` fills in the pageId using the graph's fresh revision
+   * stamp. Use this when the caller wants to emit per-block fragments but
+   * cannot know the pageId in advance.
+   */
+  fragmentsByPageIndex?: ReadonlyMap<
+    number,
+    ReadonlyArray<Omit<RuntimeBlockFragment, "pageId">>
+  >;
   /** Optional per-page line boxes. */
   lineBoxes?: ReadonlyMap<string, RuntimeLineBox[]>;
   /** Optional per-page note allocations. */
@@ -177,6 +223,15 @@ export function buildPageGraph(
 
   const pages: RuntimePageNode[] = [];
   const aggregatedFragments: RuntimeBlockFragment[] = [...(input.fragments ?? [])];
+  // Rehydrate fragmentsByPageIndex with the fresh graphRevision's pageIds.
+  if (input.fragmentsByPageIndex) {
+    for (const [pageIndex, fragments] of input.fragmentsByPageIndex) {
+      const pageId = `page-${graphRevision}-${pageIndex}`;
+      for (const fragment of fragments) {
+        aggregatedFragments.push({ ...fragment, pageId });
+      }
+    }
+  }
   const anchors: RuntimePageAnchor[] = [];
 
   for (let index = 0; index < input.pages.length; index += 1) {

package/src/runtime/layout/paginate-paragraph-lines.ts

@@ -0,0 +1,128 @@
+/**
+ * Line-box splitter for paragraph pagination.
+ *
+ * Given a paragraph that doesn't fit on the current page, decide how many of
+ * its lines belong on the current page and how many continue on the next.
+ * Honors the four pagination attributes that govern this in OOXML /
+ * ECMA-376 §17.3.1.33:
+ *
+ *   - `keepLines`         — if true, never split the paragraph.
+ *   - `widowControl`      — if true (Word default), keep ≥ WIDOW_MIN lines on
+ *                           each side of any split. Applies independently at
+ *                           the top (orphan) and bottom (widow) of a split.
+ *   - `keepNext`          — orthogonal to splitting itself; the engine's
+ *                           outer loop uses it to bundle the paragraph with
+ *                           the next. We only honour it here to avoid an
+ *                           awkward split on a paragraph that is about to be
+ *                           kept with the next (no gain from splitting).
+ *   - `pageBreakBefore`   — handled upstream via an unconditional page break;
+ *                           if set, callers do not consult this splitter.
+ *
+ * Pure function. No DOM, no side effects. Unit-testable in isolation.
+ */
+
+export const DEFAULT_WIDOW_MIN_LINES = 2;
+
+export interface LineSplitInput {
+  /** Total number of line boxes in the paragraph, ≥ 1. */
+  totalLines: number;
+  /**
+   * How many lines can still fit on the current page given the remaining
+   * vertical space and the paragraph's resolved line height. Callers compute
+   * this by dividing the remaining column height by the per-line height.
+   * Must be ≥ 0. Zero is legal and short-circuits to "no split" (the whole
+   * paragraph moves to the next page).
+   */
+  availableLines: number;
+  /** OOXML `w:keepLines`. */
+  keepLines: boolean;
+  /** OOXML `w:widowControl` (true in Word's default).  */
+  widowControl: boolean;
+  /** OOXML `w:keepNext`. */
+  keepNext: boolean;
+  /**
+   * Whether this paragraph is the last block on the page-in-flight.  If true,
+   * splitting buys nothing (there's no subsequent content we're squeezing in
+   * below) and we leave the whole paragraph on the current page.
+   */
+  isLastBlockOnPage: boolean;
+  /**
+   * Minimum lines required on each side of a widow/orphan-controlled split.
+   * Defaults to {@link DEFAULT_WIDOW_MIN_LINES}. Exposed for fixtures that
+   * exercise narrow paragraphs.
+   */
+  widowMinLines?: number;
+}
+
+export interface LineSplitResult {
+  linesOnCurrent: number;
+  linesOnNext: number;
+}
+
+/**
+ * Decide how to split a paragraph across a page boundary.
+ *
+ * Returns:
+ *   - `null` when no split should happen. The caller's existing "move the
+ *     whole paragraph to the next page" behavior applies.
+ *   - A `{ linesOnCurrent, linesOnNext }` split with `linesOnCurrent +
+ *     linesOnNext === totalLines` and both values ≥ 1. The caller must
+ *     render `linesOnCurrent` lines in the remaining space on the current
+ *     page and `linesOnNext` lines at the top of the next page.
+ */
+export function paginateParagraphLines(
+  input: LineSplitInput,
+): LineSplitResult | null {
+  const totalLines = Math.max(1, Math.floor(input.totalLines));
+  const availableLines = Math.max(0, Math.floor(input.availableLines));
+  const widowMin = Math.max(1, input.widowMinLines ?? DEFAULT_WIDOW_MIN_LINES);
+
+  // keepLines wins unconditionally.
+  if (input.keepLines) return null;
+
+  // If the paragraph fits wholesale on the current page, no split.
+  if (totalLines <= availableLines) return null;
+
+  // If there's nothing worth keeping on the current page (zero lines fit, or
+  // only a single line under widow control would fit), fall through to the
+  // caller's "move whole paragraph" path.
+  const effectiveOrphanMin = input.widowControl ? widowMin : 1;
+  if (availableLines < effectiveOrphanMin) return null;
+
+  // Don't split trivially-short paragraphs whose final lines could fit a
+  // page move (keeping them intact preserves Word's visual intent).
+  if (totalLines < effectiveOrphanMin * 2) return null;
+
+  // If this paragraph is the last thing on this page anyway, splitting has
+  // no downstream benefit — the next page is empty.
+  if (input.isLastBlockOnPage) return null;
+
+  // keepNext paragraphs are meant to travel with the next block. Splitting
+  // them would move half-and-half across the break, which usually contradicts
+  // author intent. Leave the paragraph intact; the outer loop will handle
+  // the keep-with-next pairing on the next page.
+  if (input.keepNext) return null;
+
+  // Candidate split: fill the current page, put the rest on the next.
+  let linesOnCurrent = availableLines;
+  let linesOnNext = totalLines - linesOnCurrent;
+
+  // Widow control: the tail on the next page needs ≥ widowMin lines too.
+  if (input.widowControl && linesOnNext < widowMin) {
+    // Pull enough lines back to the next page to meet the widow minimum.
+    const deficit = widowMin - linesOnNext;
+    linesOnCurrent -= deficit;
+    linesOnNext += deficit;
+
+    // If pulling back violates the orphan minimum, abandon the split —
+    // the whole paragraph goes on the next page.
+    if (linesOnCurrent < widowMin) return null;
+  }
+
+  // Sanity clamp (the arithmetic above should guarantee these but be
+  // defensive against bad input).
+  if (linesOnCurrent < 1 || linesOnNext < 1) return null;
+  if (linesOnCurrent + linesOnNext !== totalLines) return null;
+
+  return { linesOnCurrent, linesOnNext };
+}