@beyondwork/docx-react-component 1.0.37 → 1.0.39

package/src/runtime/layout/project-block-fragments.ts

@@ -0,0 +1,225 @@
+/**
+ * Project surface blocks → per-page RuntimeBlockFragments (P4 + R3).
+ *
+ * The pagination engine produces `DocumentPageSnapshot[]` keyed by offset
+ * ranges, but for render-kernel consumers to get per-block geometry (and
+ * for the chrome to anchor tables, images, etc.) we need one block
+ * fragment per top-level surface block, assigned to the page that
+ * contains its offset range.
+ *
+ * The engine also reports **split metadata** (see `BlockSplits` in
+ * `paginated-layout-engine.ts`):
+ *   - paragraph-slice: one fragment per slice, keyed by `paragraphLineRange`
+ *   - table-slice: one fragment per row-range slice, keyed by `tableRowRange`
+ *   - otherwise: one atomic fragment per top-level block (the original P4
+ *     behavior).
+ *
+ * Consumers read `fragment.kind` to choose between whole-block rendering
+ * and slice-aware rendering (line-range clipping for paragraphs, row-range
+ * rendering + repeated header row for tables).
+ */
+
+import type {
+  DocumentPageSnapshot,
+  EditorSurfaceSnapshot,
+  SurfaceBlockSnapshot,
+} from "../../api/public-types";
+import type { RuntimeBlockFragment } from "./page-graph.ts";
+import type {
+  BlockSplits,
+  ParagraphLineSlice,
+  TableRowSlice,
+} from "./paginated-layout-engine.ts";
+
+type FragmentWithoutPageId = Omit<RuntimeBlockFragment, "pageId">;
+
+export function projectSurfaceBlocksToPageFragments(
+  surface: EditorSurfaceSnapshot,
+  pages: readonly DocumentPageSnapshot[],
+  splits?: BlockSplits,
+): Map<number, FragmentWithoutPageId[]> {
+  const byPage = new Map<number, FragmentWithoutPageId[]>();
+  const perPageCounter = new Map<number, number>();
+
+  const pushFragment = (
+    pageIndex: number,
+    fragment: FragmentWithoutPageId,
+  ): void => {
+    const existing = byPage.get(pageIndex);
+    if (existing) {
+      existing.push(fragment);
+    } else {
+      byPage.set(pageIndex, [fragment]);
+    }
+  };
+
+  const nextOrder = (pageIndex: number): number => {
+    const n = perPageCounter.get(pageIndex) ?? 0;
+    perPageCounter.set(pageIndex, n + 1);
+    return n;
+  };
+
+  for (const block of surface.blocks) {
+    // R3: table split across pages — emit one fragment per row slice.
+    // Consumers read `tableRowRange` and prepend header rows when from > 0.
+    if (block.kind === "table") {
+      const tableSliceList = splits?.tablesByBlockId.get(block.blockId);
+      if (tableSliceList && tableSliceList.length > 1) {
+        emitSlicedTable(
+          block,
+          tableSliceList,
+          (pageIndex, fragment) => {
+            pushFragment(pageIndex, {
+              ...fragment,
+              orderInRegion: nextOrder(pageIndex),
+            });
+          },
+        );
+        continue;
+      }
+    }
+
+    // Paragraph split across pages (bleed-up slice metadata): emit one
+    // fragment per slice with `paragraphLineRange` set.
+    const sliceList = splits?.byBlockId.get(block.blockId);
+    if (sliceList && sliceList.length > 1) {
+      emitSlicedParagraph(
+        block,
+        sliceList,
+        (pageIndex, fragment) => {
+          pushFragment(pageIndex, {
+            ...fragment,
+            orderInRegion: nextOrder(pageIndex),
+          });
+        },
+      );
+      continue;
+    }
+
+    // Unsplit block: single atomic fragment on the page containing its
+    // start offset.
+    const pageIndex = findPageIndexForOffset(pages, block.from);
+    if (pageIndex === null) continue;
+
+    const fragment: FragmentWithoutPageId = {
+      fragmentId: `fragment-${block.blockId}`,
+      blockId: block.blockId,
+      orderInRegion: nextOrder(pageIndex),
+      regionKind: "body",
+      from: block.from,
+      to: block.to,
+      heightTwips: estimateBlockHeightFromSpan(block),
+      kind: "whole",
+    };
+
+    pushFragment(pageIndex, fragment);
+  }
+
+  return byPage;
+}
+
+/**
+ * Emit one fragment per slice for a paragraph that pagination split across
+ * pages. The source `block` offset range stays intact on every slice; the
+ * `paragraphLineRange` identifies which lines the slice renders.
+ */
+function emitSlicedParagraph(
+  block: SurfaceBlockSnapshot,
+  slices: readonly ParagraphLineSlice[],
+  emit: (pageIndex: number, fragment: FragmentWithoutPageId) => void,
+): void {
+  for (let i = 0; i < slices.length; i += 1) {
+    const slice = slices[i]!;
+    const fragment: FragmentWithoutPageId = {
+      fragmentId: `fragment-${block.blockId}-slice-${i}`,
+      blockId: block.blockId,
+      orderInRegion: 0, // re-assigned by caller via nextOrder(pageIndex).
+      regionKind: "body",
+      from: block.from,
+      to: block.to,
+      heightTwips: estimateSliceHeightFromLines(slice.lineRange),
+      kind: "paragraph-slice",
+      paragraphLineRange: slice.lineRange,
+    };
+    emit(slice.pageIndex, fragment);
+  }
+}
+
+function estimateSliceHeightFromLines(lineRange: {
+  from: number;
+  to: number;
+  totalLines: number;
+}): number {
+  const lines = Math.max(0, lineRange.to - lineRange.from);
+  return lines * 240;
+}
+
+/**
+ * R3: emit one fragment per row-slice when a table spans multiple pages.
+ * The source `block` offset range stays intact on every slice (so selection
+ * math and incremental relayout see a single logical block); `tableRowRange`
+ * tells downstream consumers which rows to render on this page. When
+ * `rowRange.from > 0` and the owning table has `isHeader` rows, consumers
+ * prepend those header rows visually so the table's header repeats on
+ * every continuation page.
+ */
+function emitSlicedTable(
+  block: SurfaceBlockSnapshot,
+  slices: readonly TableRowSlice[],
+  emit: (pageIndex: number, fragment: FragmentWithoutPageId) => void,
+): void {
+  for (let i = 0; i < slices.length; i += 1) {
+    const slice = slices[i]!;
+    const fragment: FragmentWithoutPageId = {
+      fragmentId: `fragment-${block.blockId}-rowslice-${i}`,
+      blockId: block.blockId,
+      orderInRegion: 0, // re-assigned by caller via nextOrder(pageIndex).
+      regionKind: "body",
+      from: block.from,
+      to: block.to,
+      heightTwips: estimateSliceHeightFromRows(slice.rowRange),
+      kind: "table-slice",
+      tableRowRange: slice.rowRange,
+    };
+    emit(slice.pageIndex, fragment);
+  }
+}
+
+function estimateSliceHeightFromRows(rowRange: {
+  from: number;
+  to: number;
+  totalRows: number;
+}): number {
+  const rows = Math.max(0, rowRange.to - rowRange.from);
+  return rows * 360; // ~1 line + padding per row, approximate
+}
+
+function findPageIndexForOffset(
+  pages: readonly DocumentPageSnapshot[],
+  offset: number,
+): number | null {
+  for (let i = 0; i < pages.length; i += 1) {
+    const page = pages[i]!;
+    if (offset >= page.startOffset && offset < page.endOffset) {
+      return page.pageIndex;
+    }
+  }
+  // Fall back to the last page for offsets that equal storySize.
+  const last = pages[pages.length - 1];
+  if (last && offset >= last.startOffset && offset <= last.endOffset) {
+    return last.pageIndex;
+  }
+  return null;
+}
+
+/**
+ * Rough height estimate from the block's offset span. Only used as a
+ * fallback when the caller did not pre-measure. Chrome consumers that
+ * need accurate heights should read `facet.getMeasurement(blockId)`.
+ */
+function estimateBlockHeightFromSpan(block: SurfaceBlockSnapshot): number {
+  // 240 twips per line; approximate 80 chars per line for paragraphs.
+  const span = Math.max(0, block.to - block.from);
+  const lines = Math.max(1, Math.ceil(span / 80));
+  return lines * 240;
+}