@beyondwork/docx-react-component 1.0.41 → 1.0.43

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

@@ -73,6 +73,17 @@ export interface RuntimePageRegions {
    * pages, the top-level body is used and `columns` is undefined.
    */
   columns?: RuntimePageRegion[];
+  /**
+   * P4 — footnote regions reserved at the bottom of the page (above
+   * the footer band) when `noteAllocations` reserved space for one or
+   * more footnote bodies.  Empty until the page-graph builder
+   * populates them, which lands alongside the P8 per-page region
+   * rendering work.  The shape exists now so consumers
+   * (`getStoryRegionsOnPage` / `getLineBoxesForRegion("footnote-area")`)
+   * have a stable seam to read from when the builder catches up —
+   * pre-P8 reads return `[]` because no entries are populated.
+   */
+  footnotes?: RuntimePageRegion[];
 }
 
 export interface RuntimePageRegion {
@@ -158,6 +169,14 @@ export interface RuntimeNoteAllocation {
   noteId: string;
   /** Twips reserved at the bottom of the page for this note's content. */
   reservedHeightTwips: number;
+  /**
+   * P8 — fragment ID of this note's body.  The corresponding
+   * `RuntimeBlockFragment` lives in `RuntimePageGraph.fragments` with
+   * `regionKind: "footnote-area"`.  Undefined when the engine hasn't
+   * yet emitted a fragment for the allocation (back-compat for pre-P8
+   * callers).
+   */
+  fragmentId?: string;
 }
 
 export interface RuntimePageAnchor {
@@ -196,8 +215,15 @@ export interface BuildPageGraphInput {
   >;
   /** Optional per-page line boxes. */
   lineBoxes?: ReadonlyMap<string, RuntimeLineBox[]>;
-  /** Optional per-page note allocations. */
+  /** Optional per-page note allocations keyed by graph-assigned pageId. */
   noteAllocations?: ReadonlyMap<string, RuntimeNoteAllocation[]>;
+  /**
+   * P8 — per-page note allocations keyed by pageIndex (0-based).
+   * Parallel to `fragmentsByPageIndex`; `buildPageGraph` uses the index to
+   * look up allocations without requiring callers to know the graph-internal
+   * `page-${revision}-${index}` pageId in advance.
+   */
+  noteAllocationsByPageIndex?: ReadonlyMap<number, RuntimeNoteAllocation[]>;
 }
 
 export function buildPageGraph(input: BuildPageGraphInput): RuntimePageGraph;
@@ -244,10 +270,15 @@ export function buildPageGraph(
     };
 
     const pageFragments = aggregatedFragments.filter((f) => f.pageId === pageId);
-    const fragmentIds = pageFragments.map((f) => f.fragmentId);
+    // Split fragments into body-region ones (for the body fragmentIds list)
+    // and footnote-area ones (handled by buildRegions via noteAllocations).
+    const bodyPageFragments = pageFragments.filter(
+      (f) => f.regionKind !== "footnote-area",
+    );
+    const fragmentIds = bodyPageFragments.map((f) => f.fragmentId);
 
-    // If no fragments were supplied, synthesize a coarse body fragment so the
-    // graph is still internally consistent.
+    // If no body fragments were supplied, synthesize a coarse body fragment so
+    // the graph is still internally consistent.
     let bodyFragmentIds = fragmentIds;
     if (fragmentIds.length === 0 && page.endOffset > page.startOffset) {
       const coarse: RuntimeBlockFragment = {
@@ -264,6 +295,15 @@ export function buildPageGraph(
       bodyFragmentIds = [coarse.fragmentId];
     }
 
+    // Resolve per-page note allocations: prefer noteAllocationsByPageIndex
+    // (index-based, suitable when the caller doesn't know the graph-internal
+    // pageId) falling back to noteAllocations (pageId-keyed, used by the
+    // engine once it emits allocations).
+    const pageNoteAllocations: RuntimeNoteAllocation[] =
+      input.noteAllocationsByPageIndex?.get(index) ??
+      input.noteAllocations?.get(pageId) ??
+      [];
+
     const node: RuntimePageNode = {
       pageId,
       pageIndex: page.pageIndex,
@@ -273,9 +313,9 @@ export function buildPageGraph(
       endOffset: page.endOffset,
       layout: page.layout,
       stories,
-      regions: buildRegions(page.layout, bodyFragmentIds, stories),
+      regions: buildRegions(page.layout, bodyFragmentIds, stories, pageNoteAllocations),
       lineBoxes: input.lineBoxes?.get(pageId) ?? [],
-      noteAllocations: input.noteAllocations?.get(pageId) ?? [],
+      noteAllocations: pageNoteAllocations,
       isBlankFiller: page.pageInSection === -1,
     };
     pages.push(node);
@@ -302,12 +342,40 @@ function buildRegions(
   layout: PageLayoutSnapshot,
   bodyFragmentIds: readonly string[],
   stories: ResolvedPageStories,
+  noteAllocations: readonly RuntimeNoteAllocation[] = [],
 ): RuntimePageRegions {
   const bodyWidth =
     layout.pageWidth - layout.marginLeft - layout.marginRight;
-  const bodyHeight =
+  let bodyHeight =
     layout.pageHeight - layout.marginTop - layout.marginBottom;
 
+  // P8 — footnote area sits at the bottom of the page (above the footer
+  // band). Body height shrinks by the total reserved note height so
+  // band-aware consumers can stack bands without overflowing the paper frame.
+  let footnotesRegion: RuntimePageRegion | undefined;
+  if (noteAllocations.length > 0) {
+    const fragmentIds = noteAllocations
+      .filter(
+        (a): a is RuntimeNoteAllocation & { fragmentId: string } =>
+          Boolean(a.fragmentId),
+      )
+      .map((a) => a.fragmentId);
+    const totalNoteHeight = noteAllocations.reduce(
+      (sum, a) => sum + a.reservedHeightTwips,
+      0,
+    );
+    if (fragmentIds.length > 0) {
+      footnotesRegion = {
+        kind: "footnote-area",
+        originTwips: layout.pageHeight - layout.marginBottom - totalNoteHeight,
+        widthTwips: Math.max(0, bodyWidth),
+        heightTwips: Math.max(0, totalNoteHeight),
+        fragmentIds,
+      };
+      bodyHeight = Math.max(0, bodyHeight - totalNoteHeight);
+    }
+  }
+
   const body: RuntimePageRegion = {
     kind: "body",
     originTwips: layout.marginTop,
@@ -356,6 +424,10 @@ function buildRegions(
     regions.columns = columns;
   }
 
+  if (footnotesRegion) {
+    regions.footnotes = [footnotesRegion];
+  }
+
   return regions;
 }