@beyondwork/docx-react-component 1.0.105 → 1.0.108

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

@@ -24,14 +24,22 @@ import type {
   EditorSurfaceSnapshot,
   SurfaceBlockSnapshot,
 } from "../../api/public-types";
+import type {
+  CanonicalFieldRegionIdentity,
+} from "../../model/canonical-layout-inputs.ts";
 import type { RuntimeBlockFragment } from "./page-graph.ts";
-import type { RuntimeLineBox } from "../../model/layout/page-graph-types.ts";
+import type {
+  RuntimeFieldRegionLayoutFacts,
+  RuntimeLineBox,
+  RuntimeNumberingLayoutFacts,
+} from "../../model/layout/page-graph-types.ts";
 import type {
   BlockSplits,
   FragmentMeasurement,
   ParagraphLineSlice,
   TableRowSlice,
 } from "./paginated-layout-engine.ts";
+import { collectSplitRowCarryForPage } from "./table-row-continuation-contract.ts";
 
 type FragmentWithoutPageId = Omit<RuntimeBlockFragment, "pageId">;
 
@@ -41,9 +49,11 @@ export function projectSurfaceBlocksToPageFragments(
   splits?: BlockSplits,
   columnByBlockIdByPageIndex?: ReadonlyMap<number, ReadonlyMap<string, number>>,
   fragmentMeasurementsByPageIndex?: ReadonlyMap<number, ReadonlyMap<string, FragmentMeasurement>>,
+  fieldRegions: readonly CanonicalFieldRegionIdentity[] = [],
 ): Map<number, FragmentWithoutPageId[]> {
   const byPage = new Map<number, FragmentWithoutPageId[]>();
   const perPageCounter = new Map<number, number>();
+  const fieldRegionsByParagraphIndex = buildFieldRegionsByParagraphIndex(fieldRegions);
 
   const pushFragment = (
     pageIndex: number,
@@ -74,7 +84,9 @@ export function projectSurfaceBlocksToPageFragments(
     fragmentMeasurementsByPageIndex?.get(pageIndex)?.get(blockId)?.heightTwips ??
     fallback;
 
-  for (const block of surface.blocks) {
+  for (let blockIndex = 0; blockIndex < surface.blocks.length; blockIndex += 1) {
+    const block = surface.blocks[blockIndex]!;
+    const blockPath = `main/block[${blockIndex}]`;
     // 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") {
@@ -93,9 +105,11 @@ export function projectSurfaceBlocksToPageFragments(
                 ? { columnIndex: fragment.columnIndex }
                 : columnIndex !== undefined
                   ? { columnIndex }
-                  : {}),
+                : {}),
             });
           },
+          fieldRegionsByParagraphIndex,
+          blockPath,
         );
         continue;
       }
@@ -116,6 +130,8 @@ export function projectSurfaceBlocksToPageFragments(
             ...(columnIndex !== undefined ? { columnIndex } : {}),
           });
         },
+        fieldRegionsByParagraphIndex,
+        blockPath,
       );
       continue;
     }
@@ -126,6 +142,14 @@ export function projectSurfaceBlocksToPageFragments(
     if (pageIndex === null) continue;
 
     const columnIndex = columnIndexFor(pageIndex, block.blockId);
+    const heightTwips = measuredHeightFor(
+      pageIndex,
+      block.blockId,
+      estimateBlockHeightFromSpan(block),
+    );
+    const widthTwips = fragmentMeasurementsByPageIndex
+      ?.get(pageIndex)
+      ?.get(block.blockId)?.widthTwips;
     const fragment: FragmentWithoutPageId = {
       fragmentId: `fragment-${block.blockId}`,
       blockId: block.blockId,
@@ -133,13 +157,18 @@ export function projectSurfaceBlocksToPageFragments(
       regionKind: "body",
       from: block.from,
       to: block.to,
-      heightTwips: measuredHeightFor(
-        pageIndex,
-        block.blockId,
-        estimateBlockHeightFromSpan(block),
-      ),
+      heightTwips,
       ...deriveStyleMetadata(block),
       kind: "whole",
+      layoutObject: buildFragmentLayoutObject({
+        block,
+        fragmentId: `fragment-${block.blockId}`,
+        heightTwips,
+        widthTwips,
+        paginationRole: "whole",
+        fieldRegionsByParagraphIndex,
+        blockPath,
+      }),
       ...(columnIndex !== undefined ? { columnIndex } : {}),
     };
 
@@ -221,9 +250,12 @@ function emitSlicedParagraph(
   block: SurfaceBlockSnapshot,
   slices: readonly ParagraphLineSlice[],
   emit: (pageIndex: number, fragment: FragmentWithoutPageId) => void,
+  fieldRegionsByParagraphIndex: ReadonlyMap<number, readonly CanonicalFieldRegionIdentity[]> = new Map(),
+  blockPath?: string,
 ): void {
   for (let i = 0; i < slices.length; i += 1) {
     const slice = slices[i]!;
+    const heightTwips = slice.heightTwips ?? estimateSliceHeightFromLines(slice.lineRange);
     const fragment: FragmentWithoutPageId = {
       fragmentId: `fragment-${block.blockId}-slice-${i}`,
       blockId: block.blockId,
@@ -231,11 +263,20 @@ function emitSlicedParagraph(
       regionKind: "body",
       from: block.from,
       to: block.to,
-      heightTwips: slice.heightTwips ?? estimateSliceHeightFromLines(slice.lineRange),
+      heightTwips,
       ...deriveStyleMetadata(block),
       kind: "paragraph-slice",
       paragraphLineRange: slice.lineRange,
       continuation: buildParagraphContinuationCursor(slice, i, slices.length),
+      layoutObject: buildFragmentLayoutObject({
+        block,
+        fragmentId: `fragment-${block.blockId}-slice-${i}`,
+        heightTwips,
+        widthTwips: slice.widthTwips,
+        paginationRole: slice.lineRange.from > 0 ? "continuation" : "slice",
+        fieldRegionsByParagraphIndex,
+        blockPath,
+      }),
     };
     emit(slice.pageIndex, fragment);
   }
@@ -278,9 +319,12 @@ function emitSlicedTable(
   block: Extract<SurfaceBlockSnapshot, { kind: "table" }>,
   slices: readonly TableRowSlice[],
   emit: (pageIndex: number, fragment: FragmentWithoutPageId) => void,
+  fieldRegionsByParagraphIndex: ReadonlyMap<number, readonly CanonicalFieldRegionIdentity[]> = new Map(),
+  blockPath?: string,
 ): void {
   for (let i = 0; i < slices.length; i += 1) {
     const slice = slices[i]!;
+    const heightTwips = slice.heightTwips ?? estimateSliceHeightFromRows(slice.rowRange);
     const fragment: FragmentWithoutPageId = {
       fragmentId: `fragment-${block.blockId}-rowslice-${i}`,
       blockId: block.blockId,
@@ -288,11 +332,19 @@ function emitSlicedTable(
       regionKind: "body",
       from: block.from,
       to: block.to,
-      heightTwips: slice.heightTwips ?? estimateSliceHeightFromRows(slice.rowRange),
+      heightTwips,
       ...deriveStyleMetadata(block),
       kind: "table-slice",
       tableRowRange: slice.rowRange,
-      continuation: buildTableContinuationCursor(block, slice, i, slices.length),
+      continuation: buildTableContinuationCursor(block, slices, i),
+      layoutObject: buildFragmentLayoutObject({
+        block,
+        fragmentId: `fragment-${block.blockId}-rowslice-${i}`,
+        heightTwips,
+        paginationRole: slice.rowRange.from > 0 ? "continuation" : "slice",
+        fieldRegionsByParagraphIndex,
+        blockPath,
+      }),
       ...(slice.columnIndex !== undefined ? { columnIndex: slice.columnIndex } : {}),
     };
     emit(slice.pageIndex, fragment);
@@ -301,14 +353,15 @@ function emitSlicedTable(
 
 function buildTableContinuationCursor(
   block: Extract<SurfaceBlockSnapshot, { kind: "table" }>,
-  slice: TableRowSlice,
+  slices: readonly TableRowSlice[],
   sequenceIndex: number,
-  sliceCount: number,
 ): NonNullable<RuntimeBlockFragment["continuation"]> {
+  const slice = slices[sequenceIndex]!;
+  const splitRowCarry = collectSplitRowCarryForPage(slices, sequenceIndex);
   return {
     kind: "table",
     sequenceIndex,
-    sliceCount,
+    sliceCount: slices.length,
     rowRange: slice.rowRange,
     continuesFromPreviousPage: slice.rowRange.from > 0,
     continuesToNextPage: slice.rowRange.to < slice.rowRange.totalRows,
@@ -316,6 +369,7 @@ function buildTableContinuationCursor(
       slice.rowRange.from > 0
         ? collectRepeatedHeaderRowIndexes(block, slice.rowRange.from)
         : [],
+    ...(splitRowCarry.length > 0 ? { splitRowCarry } : {}),
     verticalMergeCarry: collectVerticalMergeCarry(block, slice.rowRange.from),
   };
 }
@@ -391,6 +445,289 @@ function estimateSliceHeightFromRows(rowRange: {
   return rows * 360; // ~1 line + padding per row, approximate
 }
 
+function buildFragmentLayoutObject(input: {
+  block: SurfaceBlockSnapshot;
+  fragmentId: string;
+  heightTwips: number;
+  widthTwips?: number;
+  paginationRole: NonNullable<RuntimeBlockFragment["layoutObject"]>["paginationRole"];
+  fieldRegionsByParagraphIndex?: ReadonlyMap<number, readonly CanonicalFieldRegionIdentity[]>;
+  blockPath?: string;
+}): NonNullable<RuntimeBlockFragment["layoutObject"]> {
+  const fieldFamilies = collectFieldFamilies(input.block);
+  const kind = resolveFragmentLayoutObjectKind(input.block, fieldFamilies);
+  const numberingRows = collectNumberingLayoutFactsForBlock(input.block, input.blockPath);
+  const numbering = input.block.kind === "paragraph" ? numberingRows[0] : undefined;
+  const fieldRegions = collectFieldRegionLayoutFacts(
+    input.block,
+    input.fragmentId,
+    input.fieldRegionsByParagraphIndex,
+  );
+  return {
+    objectId: `${kind}:${input.fragmentId}`,
+    kind,
+    sourceBlockId: input.block.blockId,
+    paginationRole: input.paginationRole,
+    measuredExtentTwips: {
+      heightTwips: Math.max(0, input.heightTwips),
+      ...(input.widthTwips !== undefined
+        ? { widthTwips: Math.max(0, input.widthTwips) }
+        : {}),
+    },
+    ...(fieldFamilies.length > 0 ? { fieldFamilies } : {}),
+    ...(fieldRegions.length > 0 ? { fieldRegions } : {}),
+    ...(numbering ? { numbering } : {}),
+    ...(numberingRows.length > 0 ? { numberingRows } : {}),
+  };
+}
+
+function resolveFragmentLayoutObjectKind(
+  block: SurfaceBlockSnapshot,
+  fieldFamilies: readonly string[],
+): NonNullable<RuntimeBlockFragment["layoutObject"]>["kind"] {
+  switch (block.kind) {
+    case "paragraph":
+      if (fieldFamilies.length > 0) return "field-region";
+      return block.numbering ? "numbered-paragraph" : "paragraph";
+    case "table":
+      return "table";
+    case "sdt_block":
+      return "sdt-block";
+    case "opaque_block":
+      return "opaque-block";
+  }
+}
+
+function collectFieldFamilies(block: SurfaceBlockSnapshot): string[] {
+  if (block.kind !== "paragraph") return [];
+  const families: string[] = [];
+  const seen = new Set<string>();
+  for (const segment of block.segments) {
+    if (segment.kind !== "field_ref" || seen.has(segment.fieldFamily)) continue;
+    seen.add(segment.fieldFamily);
+    families.push(segment.fieldFamily);
+  }
+  return families;
+}
+
+function buildFieldRegionsByParagraphIndex(
+  regions: readonly CanonicalFieldRegionIdentity[],
+): Map<number, CanonicalFieldRegionIdentity[]> {
+  const byParagraph = new Map<number, CanonicalFieldRegionIdentity[]>();
+  for (const region of regions) {
+    const bucket = byParagraph.get(region.paragraphIndex);
+    if (bucket) bucket.push(region);
+    else byParagraph.set(region.paragraphIndex, [region]);
+  }
+  return byParagraph;
+}
+
+function collectFieldRegionLayoutFacts(
+  block: SurfaceBlockSnapshot,
+  fragmentId: string,
+  fieldRegionsByParagraphIndex:
+    | ReadonlyMap<number, readonly CanonicalFieldRegionIdentity[]>
+    | undefined,
+): RuntimeFieldRegionLayoutFacts[] {
+  if (!fieldRegionsByParagraphIndex || fieldRegionsByParagraphIndex.size === 0) {
+    return [];
+  }
+
+  const paragraphIndexes = collectParagraphIndexesForBlock(block);
+  if (paragraphIndexes.length === 0) return [];
+
+  const facts: RuntimeFieldRegionLayoutFacts[] = [];
+  const seen = new Set<string>();
+  for (const paragraphIndex of paragraphIndexes) {
+    for (const region of fieldRegionsByParagraphIndex.get(paragraphIndex) ?? []) {
+      const fieldRegionId = `field-region:${region.canonicalFieldId}`;
+      const key = `${fieldRegionId}:${fragmentId}`;
+      if (seen.has(key)) continue;
+      seen.add(key);
+      facts.push(toRuntimeFieldRegionLayoutFacts(region, fieldRegionId));
+    }
+  }
+  return facts;
+}
+
+function collectParagraphIndexesForBlock(block: SurfaceBlockSnapshot): number[] {
+  const indexes: number[] = [];
+  visitParagraphBlocks(block, (paragraph) => {
+    const index = parseParagraphBlockIndex(paragraph.blockId);
+    if (index !== undefined) indexes.push(index);
+  });
+  return indexes;
+}
+
+function visitParagraphBlocks(
+  block: SurfaceBlockSnapshot,
+  visit: (
+    paragraph: Extract<SurfaceBlockSnapshot, { kind: "paragraph" }>,
+    context: { readonly path?: string },
+  ) => void,
+  path?: string,
+): void {
+  switch (block.kind) {
+    case "paragraph":
+      visit(block, path !== undefined ? { path } : {});
+      return;
+    case "table":
+      for (let rowIndex = 0; rowIndex < block.rows.length; rowIndex += 1) {
+        const row = block.rows[rowIndex]!;
+        for (let cellIndex = 0; cellIndex < row.cells.length; cellIndex += 1) {
+          const cell = row.cells[cellIndex]!;
+          for (let childIndex = 0; childIndex < cell.content.length; childIndex += 1) {
+            const child = cell.content[childIndex]!;
+            visitParagraphBlocks(
+              child,
+              visit,
+              path !== undefined
+                ? `${path}/row[${rowIndex}]/cell[${cellIndex}]/block[${childIndex}]`
+                : undefined,
+            );
+          }
+        }
+      }
+      return;
+    case "sdt_block":
+      for (let childIndex = 0; childIndex < block.children.length; childIndex += 1) {
+        const child = block.children[childIndex]!;
+        visitParagraphBlocks(
+          child,
+          visit,
+          path !== undefined ? `${path}/block[${childIndex}]` : undefined,
+        );
+      }
+      return;
+    case "opaque_block":
+      return;
+  }
+}
+
+function parseParagraphBlockIndex(blockId: string): number | undefined {
+  const match = /^paragraph-(\d+)$/.exec(blockId);
+  return match ? Number(match[1]) : undefined;
+}
+
+function toRuntimeFieldRegionLayoutFacts(
+  region: CanonicalFieldRegionIdentity,
+  fieldRegionId: string,
+): RuntimeFieldRegionLayoutFacts {
+  return {
+    fieldRegionId,
+    regionId: region.regionId,
+    canonicalFieldId: region.canonicalFieldId,
+    regionKind: region.kind,
+    storyKey: region.storyKey,
+    fieldIndex: region.fieldIndex,
+    paragraphIndex: region.paragraphIndex,
+    fieldFamily: region.fieldFamily,
+    refreshStatus: region.refreshStatus,
+    ...(region.sourceRef !== undefined ? { sourceRef: { ...region.sourceRef } } : {}),
+    ...(region.fieldEvidence !== undefined
+      ? {
+          fieldEvidence: {
+            ...region.fieldEvidence,
+            ...(region.fieldEvidence.sourceRef !== undefined
+              ? { sourceRef: { ...region.fieldEvidence.sourceRef } }
+              : {}),
+          },
+        }
+      : {}),
+  };
+}
+
+function collectNumberingLayoutFacts(
+  block: SurfaceBlockSnapshot,
+): RuntimeNumberingLayoutFacts | undefined {
+  if (block.kind !== "paragraph") return undefined;
+  if (!block.numbering && !block.resolvedNumbering && block.numberingPrefix === undefined) {
+    return undefined;
+  }
+
+  const markerLane = block.resolvedNumbering?.geometry.markerLane;
+  const textColumn = block.resolvedNumbering?.geometry.textColumn;
+  const tabStops = block.resolvedNumbering?.geometry.tabStops;
+  return {
+    ...(block.numbering?.numberingInstanceId !== undefined
+      ? { numberingInstanceId: block.numbering.numberingInstanceId }
+      : {}),
+    ...(block.numbering?.level !== undefined ? { level: block.numbering.level } : {}),
+    ...(block.resolvedNumbering?.format !== undefined
+      ? { format: block.resolvedNumbering.format }
+      : {}),
+    ...(block.numberingPrefix !== undefined ? { markerText: block.numberingPrefix } : {}),
+    ...(block.numberingSuffix !== undefined ? { markerSuffix: block.numberingSuffix } : {}),
+    ...(block.resolvedNumbering?.geometry.markerJustification !== undefined
+      ? { markerJustification: block.resolvedNumbering.geometry.markerJustification }
+      : {}),
+    ...(markerLane
+      ? {
+          markerLane: {
+            startTwips: markerLane.start,
+            widthTwips: markerLane.width,
+            textStartTwips: markerLane.textStart,
+          },
+        }
+      : {}),
+    ...(textColumn
+      ? {
+          textColumn: {
+            startTwips: textColumn.start,
+            ...(textColumn.right !== undefined ? { rightTwips: textColumn.right } : {}),
+            ...(textColumn.firstLine !== undefined
+              ? { firstLineTwips: textColumn.firstLine }
+              : {}),
+            ...(textColumn.hanging !== undefined ? { hangingTwips: textColumn.hanging } : {}),
+          },
+        }
+      : {}),
+    ...(tabStops && tabStops.length > 0
+      ? {
+          tabStops: tabStops.map((tab) => ({
+            positionTwips: tab.pos,
+            ...(tab.val !== undefined ? { align: tab.val } : {}),
+            ...(tab.leader !== undefined ? { leader: tab.leader } : {}),
+          })),
+        }
+      : {}),
+  };
+}
+
+function collectNumberingLayoutFactsForBlock(
+  block: SurfaceBlockSnapshot,
+  blockPath?: string,
+): RuntimeNumberingLayoutFacts[] {
+  const rows: RuntimeNumberingLayoutFacts[] = [];
+  const seen = new Set<string>();
+  visitParagraphBlocks(block, (paragraph, context) => {
+    const numbering = collectNumberingLayoutFacts(paragraph);
+    if (!numbering) return;
+    const paragraphIndex = parseParagraphBlockIndex(paragraph.blockId);
+    const numberingKey =
+      context.path !== undefined ? `main:${context.path}:numbering` : undefined;
+    const numberingLayoutId =
+      numberingKey ??
+      [
+        "numbering",
+        paragraph.blockId,
+        numbering.numberingInstanceId ?? "unknown-instance",
+        numbering.level ?? "unknown-level",
+      ].join(":");
+    if (seen.has(numberingLayoutId)) return;
+    seen.add(numberingLayoutId);
+    rows.push({
+      numberingLayoutId,
+      ...(numberingKey !== undefined ? { numberingKey } : {}),
+      ...(context.path !== undefined ? { sourceBlockPath: context.path } : {}),
+      sourceBlockId: paragraph.blockId,
+      ...(paragraphIndex !== undefined ? { paragraphIndex } : {}),
+      ...numbering,
+    });
+  }, blockPath);
+  return rows;
+}
+
 function findPageIndexForOffset(
   pages: readonly DocumentPageSnapshot[],
   offset: number,