@beyondwork/docx-react-component 1.0.110 → 1.0.111

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

@@ -23,6 +23,7 @@ import type {
   DocumentPageSnapshot,
   EditorSurfaceSnapshot,
   SurfaceBlockSnapshot,
+  SurfaceInlineSegment,
 } from "../../api/public-types";
 import type {
   CanonicalFieldRegionIdentity,
@@ -31,7 +32,9 @@ import type { RuntimeBlockFragment } from "./page-graph.ts";
 import type {
   RuntimeFieldRegionLayoutFacts,
   RuntimeLineBox,
+  RuntimeLineRunAnchor,
   RuntimeNumberingLayoutFacts,
+  RuntimeTwipsRect,
 } from "../../model/layout/page-graph-types.ts";
 import type {
   BlockSplits,
@@ -185,8 +188,12 @@ export function projectLineBoxesForPageFragments(
     ReadonlyArray<Omit<RuntimeBlockFragment, "pageId">>
   >,
   fragmentMeasurementsByPageIndex?: ReadonlyMap<number, ReadonlyMap<string, FragmentMeasurement>>,
+  surface?: EditorSurfaceSnapshot,
 ): Map<number, RuntimeLineBox[]> {
   const byPage = new Map<number, RuntimeLineBox[]>();
+  const blocksById = surface
+    ? new Map(surface.blocks.map((block) => [block.blockId, block] as const))
+    : new Map<string, SurfaceBlockSnapshot>();
   for (const page of pages) {
     const fragments = [...(fragmentsByPageIndex.get(page.pageIndex) ?? [])]
       .filter((fragment) => fragment.regionKind === "body")
@@ -224,12 +231,33 @@ export function projectLineBoxesForPageFragments(
             page.layout.gutter,
         );
       for (let lineIndex = 0; lineIndex < lineCount; lineIndex += 1) {
+        const lineTopTwips = cursorTwips + lineIndex * lineHeight;
+        const rectTwips = lineRectForFragment(page, fragment, lineTopTwips, widthTwips, lineHeight);
+        const baselinePageYTwips = rectTwips.yTwips + Math.round(lineHeight * 0.8);
+        const block = blocksById.get(fragment.blockId);
+        const direction = block?.kind === "paragraph" && block.bidi === true ? "rtl" : "ltr";
         lines.push({
           fragmentId: fragment.fragmentId,
           lineIndex,
-          baselineTwips: cursorTwips + lineIndex * lineHeight,
+          baselineTwips: lineTopTwips,
+          baselinePageYTwips,
           heightTwips: lineHeight,
           widthTwips,
+          rectTwips,
+          direction,
+          ...(block?.kind === "paragraph"
+            ? {
+                runAnchors: buildRunAnchorsForLine({
+                  block,
+                  fragment,
+                  lineIndex,
+                  lineCount,
+                  rectTwips,
+                  baselinePageYTwips,
+                  direction,
+                }),
+              }
+            : {}),
         });
       }
       cursorTwips += Math.max(0, fragment.heightTwips);
@@ -241,6 +269,121 @@ export function projectLineBoxesForPageFragments(
   return byPage;
 }
 
+function lineRectForFragment(
+  page: DocumentPageSnapshot,
+  fragment: Omit<RuntimeBlockFragment, "pageId">,
+  lineTopTwips: number,
+  widthTwips: number,
+  heightTwips: number,
+): RuntimeTwipsRect {
+  const bodyX = page.layout.marginLeft + page.layout.gutter;
+  const bodyY = page.layout.marginTop;
+  const columnIndex = Math.max(0, fragment.columnIndex ?? 0);
+  const columnOffset = columnIndex > 0 ? columnIndex * Math.max(0, widthTwips) : 0;
+  return {
+    xTwips: bodyX + columnOffset,
+    yTwips: bodyY + lineTopTwips,
+    widthTwips: Math.max(0, widthTwips),
+    heightTwips: Math.max(0, heightTwips),
+  };
+}
+
+function buildRunAnchorsForLine(input: {
+  block: Extract<SurfaceBlockSnapshot, { kind: "paragraph" }>;
+  fragment: Omit<RuntimeBlockFragment, "pageId">;
+  lineIndex: number;
+  lineCount: number;
+  rectTwips: RuntimeTwipsRect;
+  baselinePageYTwips: number;
+  direction: "ltr" | "rtl";
+}): RuntimeLineRunAnchor[] {
+  const textSegments = input.block.segments.filter(
+    (segment): segment is Extract<SurfaceInlineSegment, { kind: "text" }> =>
+      segment.kind === "text" && segment.text.length > 0,
+  );
+  if (textSegments.length === 0) return [];
+
+  const totalChars = Math.max(
+    1,
+    textSegments.reduce((sum, segment) => sum + Array.from(segment.text).length, 0),
+  );
+  const totalLineCount =
+    input.fragment.kind === "paragraph-slice" && input.fragment.paragraphLineRange
+      ? Math.max(1, input.fragment.paragraphLineRange.totalLines)
+      : Math.max(1, input.lineCount);
+  const globalLineIndex =
+    (input.fragment.kind === "paragraph-slice" && input.fragment.paragraphLineRange
+      ? input.fragment.paragraphLineRange.from
+      : 0) + input.lineIndex;
+  const charsPerLine = Math.max(1, Math.ceil(totalChars / totalLineCount));
+  const lineCharStart = globalLineIndex * charsPerLine;
+  const lineCharEnd = Math.min(totalChars, lineCharStart + charsPerLine);
+  if (lineCharEnd <= lineCharStart) return [];
+
+  const charWidth = Math.max(1, input.rectTwips.widthTwips / charsPerLine);
+  const anchors: RuntimeLineRunAnchor[] = [];
+  let charCursor = 0;
+  for (const segment of textSegments) {
+    const segmentLength = Array.from(segment.text).length;
+    const segmentStart = charCursor;
+    const segmentEnd = charCursor + segmentLength;
+    charCursor = segmentEnd;
+
+    const overlapStart = Math.max(segmentStart, lineCharStart);
+    const overlapEnd = Math.min(segmentEnd, lineCharEnd);
+    if (overlapEnd <= overlapStart) continue;
+
+    const startInLine = overlapStart - lineCharStart;
+    const glyphCount = Math.max(1, overlapEnd - overlapStart);
+    const runWidthTwips = Math.max(1, Math.round(glyphCount * charWidth));
+    const startOffsetTwips = Math.round(startInLine * charWidth);
+    const xTwips =
+      input.direction === "rtl"
+        ? input.rectTwips.xTwips + input.rectTwips.widthTwips - startOffsetTwips - runWidthTwips
+        : input.rectTwips.xTwips + startOffsetTwips;
+    const glyphWidthTwips = Math.max(1, Math.round(charWidth));
+    const runRectTwips: RuntimeTwipsRect = {
+      xTwips,
+      yTwips: input.rectTwips.yTwips,
+      widthTwips: runWidthTwips,
+      heightTwips: input.rectTwips.heightTwips,
+    };
+    const firstGlyphRectTwips: RuntimeTwipsRect =
+      input.direction === "rtl"
+        ? {
+            ...runRectTwips,
+            xTwips: xTwips + Math.max(0, runWidthTwips - glyphWidthTwips),
+            widthTwips: glyphWidthTwips,
+          }
+        : { ...runRectTwips, widthTwips: glyphWidthTwips };
+    const lastGlyphRectTwips: RuntimeTwipsRect =
+      input.direction === "rtl"
+        ? { ...runRectTwips, widthTwips: glyphWidthTwips }
+        : {
+            ...runRectTwips,
+            xTwips: xTwips + Math.max(0, runWidthTwips - glyphWidthTwips),
+            widthTwips: glyphWidthTwips,
+          };
+    const runId = `${input.block.blockId}:${segment.segmentId}`;
+    anchors.push({
+      anchorId: `${input.fragment.fragmentId}:line-${input.lineIndex}:${segment.segmentId}`,
+      runId,
+      segmentId: segment.segmentId,
+      blockId: input.block.blockId,
+      fragmentId: input.fragment.fragmentId,
+      lineIndex: input.lineIndex,
+      direction: input.direction,
+      baselinePageYTwips: input.baselinePageYTwips,
+      lineRectTwips: { ...input.rectTwips },
+      firstGlyphRectTwips,
+      lastGlyphRectTwips,
+      runRectTwips,
+      precision: "layout-estimate",
+    });
+  }
+  return anchors;
+}
+
 /**
  * Emit one fragment per slice for a paragraph that pagination split across
  * pages. The source `block` offset range stays intact on every slice; the

package/src/runtime/layout/public-facet.ts

@@ -34,6 +34,7 @@ import type {
   RuntimePageNode,
   RuntimePageRegion,
   RuntimePageRegions,
+  RuntimeLineRunAnchor,
   RuntimeStoryAnchoredObject,
   RuntimeTwipsRect,
 } from "./page-graph.ts";
@@ -189,6 +190,7 @@ export interface PublicStoryAnchoredObject {
     widthTwips: number;
     heightTwips: number;
   };
+  anchorRectTwips?: PublicTwipsRect;
   relationshipIds?: readonly string[];
   mediaIds?: readonly string[];
   preserveOnly: boolean;
@@ -325,8 +327,28 @@ export interface PublicLineBox {
   fragmentId: string;
   lineIndex: number;
   baselineTwips: number;
+  baselinePageYTwips?: number;
   heightTwips: number;
   widthTwips: number;
+  rectTwips?: PublicTwipsRect;
+  direction?: "ltr" | "rtl";
+  runAnchors?: readonly PublicLineRunAnchor[];
+}
+
+export interface PublicLineRunAnchor {
+  anchorId: string;
+  runId: string;
+  segmentId: string;
+  blockId: string;
+  fragmentId: string;
+  lineIndex: number;
+  direction: "ltr" | "rtl";
+  baselinePageYTwips: number;
+  lineRectTwips: PublicTwipsRect;
+  firstGlyphRectTwips: PublicTwipsRect;
+  lastGlyphRectTwips: PublicTwipsRect;
+  runRectTwips: PublicTwipsRect;
+  precision: RuntimeLineRunAnchor["precision"];
 }
 
 export interface PublicNoteAllocation {
@@ -350,6 +372,36 @@ export interface PublicPageSpan {
   pageCount: number;
 }
 
+export interface PublicPagePaginationTelemetry {
+  pageId: string;
+  pageIndex: number;
+  startOffset: number;
+  endOffset: number;
+  isBlankFiller: boolean;
+  materialization: NonNullable<RuntimePageNode["materialization"]>;
+  bodyFragmentCount: number;
+  /**
+   * Unique body block ids referenced by this page. Split blocks count once
+   * on each page they occupy, which makes this the useful page-window
+   * estimator for block-index based viewport callers.
+   */
+  bodyBlockReferenceCount: number;
+  lineBoxCount: number;
+  noteAllocationCount: number;
+}
+
+export interface PublicPaginationTelemetry {
+  revision: number;
+  pageCount: number;
+  materializedPageCount: number;
+  unpaginatedPageCount: number;
+  bodyFragmentCount: number;
+  bodyBlockReferenceCount: number;
+  averageBodyFragmentsPerMaterializedPage: number;
+  averageBodyBlockReferencesPerMaterializedPage: number;
+  pages: readonly PublicPagePaginationTelemetry[];
+}
+
 export interface PublicSectionNode {
   sectionIndex: number;
   startOffset: number;
@@ -558,6 +610,13 @@ export interface WordReviewEditorLayoutFacet {
    */
   getStoryRegionsOnPage(pageIndex: number): readonly PublicPageRegion[];
   getFragmentsForPage(pageIndex: number): PublicBlockFragment[];
+  /**
+   * Per-page materialization and body block/fragment counts derived from the
+   * current page graph. Consumers that only have block-index viewport ranges
+   * can use this to estimate page windows from the actual document instead
+   * of hardcoded blocks-per-page constants.
+   */
+  getPaginationTelemetry(): PublicPaginationTelemetry;
 
   /**
    * P8 — Returns per-region block snapshots for a page.  Body resolves the
@@ -1231,6 +1290,10 @@ export function createLayoutFacet(
         .map((f) => toPublicBlockFragment(f, graph));
     },
 
+    getPaginationTelemetry() {
+      return toPublicPaginationTelemetry(currentGraph());
+    },
+
     getResolvedFormatting(blockId) {
       const state = currentFormatting();
       const formatting = state.paragraphs.get(blockId);
@@ -1557,6 +1620,9 @@ function toPublicStoryAnchoredObject(
           },
         }
       : {}),
+    ...(object.anchorRectTwips
+      ? { anchorRectTwips: toPublicTwipsRect(object.anchorRectTwips) }
+      : {}),
     ...(object.relationshipIds ? { relationshipIds: [...object.relationshipIds] } : {}),
     ...(object.mediaIds ? { mediaIds: [...object.mediaIds] } : {}),
     preserveOnly: object.preserveOnly,
@@ -1646,6 +1712,76 @@ function toPublicBlockFragment(
   };
 }
 
+function bodyFragmentsForPage(
+  node: RuntimePageNode,
+  graph: RuntimePageGraph,
+): RuntimeBlockFragment[] {
+  const bodyFragmentIds = new Set(node.regions.body.fragmentIds);
+  return graph.fragments.filter((fragment) =>
+    bodyFragmentIds.has(fragment.fragmentId),
+  );
+}
+
+function toPublicPagePaginationTelemetry(
+  node: RuntimePageNode,
+  graph: RuntimePageGraph,
+): PublicPagePaginationTelemetry {
+  const bodyFragments = bodyFragmentsForPage(node, graph);
+  const bodyBlockIds = new Set(bodyFragments.map((fragment) => fragment.blockId));
+  return {
+    pageId: node.pageId,
+    pageIndex: node.pageIndex,
+    startOffset: node.startOffset,
+    endOffset: node.endOffset,
+    isBlankFiller: node.isBlankFiller,
+    materialization: node.materialization ?? "paginated",
+    bodyFragmentCount: bodyFragments.length,
+    bodyBlockReferenceCount: bodyBlockIds.size,
+    lineBoxCount: node.lineBoxes.length,
+    noteAllocationCount: node.noteAllocations.length,
+  };
+}
+
+function average(count: number, divisor: number): number {
+  return divisor > 0 ? count / divisor : 0;
+}
+
+function toPublicPaginationTelemetry(
+  graph: RuntimePageGraph,
+): PublicPaginationTelemetry {
+  const pages = graph.pages.map((node) =>
+    toPublicPagePaginationTelemetry(node, graph),
+  );
+  const materializedPages = pages.filter(
+    (page) => page.materialization === "paginated",
+  );
+  const bodyFragmentCount = materializedPages.reduce(
+    (total, page) => total + page.bodyFragmentCount,
+    0,
+  );
+  const bodyBlockReferenceCount = materializedPages.reduce(
+    (total, page) => total + page.bodyBlockReferenceCount,
+    0,
+  );
+  return {
+    revision: graph.revision,
+    pageCount: pages.length,
+    materializedPageCount: materializedPages.length,
+    unpaginatedPageCount: pages.length - materializedPages.length,
+    bodyFragmentCount,
+    bodyBlockReferenceCount,
+    averageBodyFragmentsPerMaterializedPage: average(
+      bodyFragmentCount,
+      materializedPages.length,
+    ),
+    averageBodyBlockReferencesPerMaterializedPage: average(
+      bodyBlockReferenceCount,
+      materializedPages.length,
+    ),
+    pages,
+  };
+}
+
 function cloneContinuationCursor(
   cursor: RuntimeLayoutContinuationCursor,
 ): RuntimeLayoutContinuationCursor {
@@ -1724,8 +1860,32 @@ function toPublicLineBox(box: RuntimeLineBox): PublicLineBox {
     fragmentId: box.fragmentId,
     lineIndex: box.lineIndex,
     baselineTwips: box.baselineTwips,
+    ...(box.baselinePageYTwips !== undefined
+      ? { baselinePageYTwips: box.baselinePageYTwips }
+      : {}),
     heightTwips: box.heightTwips,
     widthTwips: box.widthTwips,
+    ...(box.rectTwips ? { rectTwips: toPublicTwipsRect(box.rectTwips) } : {}),
+    ...(box.direction ? { direction: box.direction } : {}),
+    ...(box.runAnchors ? { runAnchors: box.runAnchors.map(toPublicLineRunAnchor) } : {}),
+  };
+}
+
+function toPublicLineRunAnchor(anchor: RuntimeLineRunAnchor): PublicLineRunAnchor {
+  return {
+    anchorId: anchor.anchorId,
+    runId: anchor.runId,
+    segmentId: anchor.segmentId,
+    blockId: anchor.blockId,
+    fragmentId: anchor.fragmentId,
+    lineIndex: anchor.lineIndex,
+    direction: anchor.direction,
+    baselinePageYTwips: anchor.baselinePageYTwips,
+    lineRectTwips: toPublicTwipsRect(anchor.lineRectTwips),
+    firstGlyphRectTwips: toPublicTwipsRect(anchor.firstGlyphRectTwips),
+    lastGlyphRectTwips: toPublicTwipsRect(anchor.lastGlyphRectTwips),
+    runRectTwips: toPublicTwipsRect(anchor.runRectTwips),
+    precision: anchor.precision,
   };
 }