@beyondwork/docx-react-component 1.0.37 → 1.0.38

package/src/runtime/layout/page-format-catalog.ts

@@ -0,0 +1,233 @@
+/**
+ * Page-format catalog — named page sizes that back the section page-size
+ * picker and the real-dimension page frame.
+ *
+ * The canonical storage of page geometry remains
+ * `SectionProperties.pageSize` in twips.  This catalog adds a layer of
+ * semantic naming on top so the UI can render "A4" or "US Letter" and
+ * the render kernel can pick a sensible default per locale.
+ *
+ * Unit reference (OOXML):
+ *   - 1 inch = 1440 twips
+ *   - 1 mm   = 56.6929 twips
+ *
+ * The catalog deliberately ships a single default match tolerance (1 twip)
+ * so legacy documents whose page sizes were round-tripped through third-
+ * party tools still identify as the named format they were authored at.
+ */
+
+// ---------------------------------------------------------------------------
+// Public types
+// ---------------------------------------------------------------------------
+
+export type PageFormatId =
+  | "letter"
+  | "legal"
+  | "tabloid"
+  | "executive"
+  | "a3"
+  | "a4"
+  | "a5"
+  | "b4-iso"
+  | "b5-iso"
+  | "custom";
+
+export type PageFormatRegion = "us" | "iso" | "jp" | "custom";
+
+export type PageFormatLocaleDefault = "en-us" | "en-gb" | "eu" | "jp";
+
+export interface PageFormatDisplay {
+  inches?: string;
+  millimeters?: string;
+}
+
+export interface PageFormatDefinition {
+  /** Stable identifier. */
+  id: PageFormatId;
+  /** Human-facing label used in pickers. */
+  label: string;
+  /** Locale or region hint. */
+  region: PageFormatRegion;
+  /** Width in twips at portrait orientation. */
+  portraitWidthTwips: number;
+  /** Height in twips at portrait orientation. */
+  portraitHeightTwips: number;
+  /** Default-for-locale hint so consumers can pick a sensible default. */
+  localeDefault?: PageFormatLocaleDefault;
+  /** Pre-computed inches/millimeters strings for the picker. */
+  display: PageFormatDisplay;
+}
+
+export interface ActivePageFormat {
+  sectionIndex: number;
+  format: PageFormatDefinition;
+  orientation: "portrait" | "landscape";
+  /** True when the section matches a catalog format within the match tolerance. */
+  matchesCatalog: boolean;
+  /** When matchesCatalog is false, the raw twips (custom format). */
+  customTwips?: { width: number; height: number };
+}
+
+// ---------------------------------------------------------------------------
+// Catalog
+// ---------------------------------------------------------------------------
+
+/**
+ * Pre-defined named page formats.  Ordering intentionally puts the most
+ * common sizes (Letter, A4) first because UI dropdowns render in list order.
+ */
+export const PAGE_FORMAT_CATALOG: readonly PageFormatDefinition[] = Object.freeze([
+  {
+    id: "letter",
+    label: "US Letter",
+    region: "us",
+    portraitWidthTwips: 12240,
+    portraitHeightTwips: 15840,
+    localeDefault: "en-us",
+    display: { inches: "8.5 × 11 in", millimeters: "215.9 × 279.4 mm" },
+  },
+  {
+    id: "a4",
+    label: "A4",
+    region: "iso",
+    portraitWidthTwips: 11906,
+    portraitHeightTwips: 16838,
+    localeDefault: "eu",
+    display: { inches: "8.27 × 11.69 in", millimeters: "210 × 297 mm" },
+  },
+  {
+    id: "legal",
+    label: "US Legal",
+    region: "us",
+    portraitWidthTwips: 12240,
+    portraitHeightTwips: 20160,
+    display: { inches: "8.5 × 14 in", millimeters: "215.9 × 355.6 mm" },
+  },
+  {
+    id: "tabloid",
+    label: "Tabloid / Ledger",
+    region: "us",
+    portraitWidthTwips: 15840,
+    portraitHeightTwips: 24480,
+    display: { inches: "11 × 17 in", millimeters: "279.4 × 431.8 mm" },
+  },
+  {
+    id: "executive",
+    label: "Executive",
+    region: "us",
+    portraitWidthTwips: 10440,
+    portraitHeightTwips: 15120,
+    display: { inches: "7.25 × 10.5 in", millimeters: "184.1 × 266.7 mm" },
+  },
+  {
+    id: "a3",
+    label: "A3",
+    region: "iso",
+    portraitWidthTwips: 16838,
+    portraitHeightTwips: 23811,
+    display: { inches: "11.69 × 16.54 in", millimeters: "297 × 420 mm" },
+  },
+  {
+    id: "a5",
+    label: "A5",
+    region: "iso",
+    portraitWidthTwips: 8391,
+    portraitHeightTwips: 11906,
+    display: { inches: "5.83 × 8.27 in", millimeters: "148 × 210 mm" },
+  },
+  {
+    id: "b4-iso",
+    label: "B4 (ISO)",
+    region: "iso",
+    portraitWidthTwips: 14173,
+    portraitHeightTwips: 20016,
+    display: { inches: "9.84 × 13.90 in", millimeters: "250 × 353 mm" },
+  },
+  {
+    id: "b5-iso",
+    label: "B5 (ISO)",
+    region: "iso",
+    portraitWidthTwips: 9977,
+    portraitHeightTwips: 14173,
+    display: { inches: "6.93 × 9.84 in", millimeters: "176 × 250 mm" },
+  },
+  {
+    id: "custom",
+    label: "Custom",
+    region: "custom",
+    portraitWidthTwips: 0,
+    portraitHeightTwips: 0,
+    display: {},
+  },
+]);
+
+/**
+ * Match tolerance in twips.  Historic round-trips through third-party tools
+ * sometimes drift by sub-twip amounts; a 1-twip window catches those while
+ * keeping intentionally custom sizes genuinely custom.
+ */
+const MATCH_TOLERANCE_TWIPS = 1;
+
+// ---------------------------------------------------------------------------
+// Matching
+// ---------------------------------------------------------------------------
+
+export interface MatchPageFormatInput {
+  sectionIndex: number;
+  widthTwips: number;
+  heightTwips: number;
+}
+
+/**
+ * Match a section's page dimensions against the catalog.
+ *
+ * The matcher tolerates either orientation — if the supplied (width, height)
+ * match a catalog entry rotated by 90°, the active format is reported as
+ * `landscape`.  Custom sizes fall through to the `custom` entry.
+ */
+export function matchPageFormat(input: MatchPageFormatInput): ActivePageFormat {
+  const { sectionIndex, widthTwips, heightTwips } = input;
+
+  for (const format of PAGE_FORMAT_CATALOG) {
+    if (format.id === "custom") continue;
+
+    const portraitMatch =
+      near(widthTwips, format.portraitWidthTwips) &&
+      near(heightTwips, format.portraitHeightTwips);
+    const landscapeMatch =
+      near(widthTwips, format.portraitHeightTwips) &&
+      near(heightTwips, format.portraitWidthTwips);
+
+    if (portraitMatch || landscapeMatch) {
+      return {
+        sectionIndex,
+        format,
+        orientation: portraitMatch ? "portrait" : "landscape",
+        matchesCatalog: true,
+      };
+    }
+  }
+
+  const custom = PAGE_FORMAT_CATALOG.find((f) => f.id === "custom")!;
+  return {
+    sectionIndex,
+    format: custom,
+    orientation: widthTwips > heightTwips ? "landscape" : "portrait",
+    matchesCatalog: false,
+    customTwips: { width: widthTwips, height: heightTwips },
+  };
+}
+
+function near(a: number, b: number): boolean {
+  return Math.abs(a - b) <= MATCH_TOLERANCE_TWIPS;
+}
+
+/**
+ * Look up a format by id.  Returns the `custom` entry for unknown ids so
+ * callers can chain `.format` reads without null-checking.
+ */
+export function getPageFormatById(id: string): PageFormatDefinition {
+  const found = PAGE_FORMAT_CATALOG.find((f) => f.id === id);
+  if (found) return found;
+  return PAGE_FORMAT_CATALOG.find((f) => f.id === "custom")!;
+}

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

@@ -148,6 +148,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 +187,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/paginated-layout-engine.ts

@@ -61,6 +61,7 @@ import {
   resolveTextWidth,
 } from "./resolved-formatting-state.ts";
 import { analyzeInvalidation as analyzeInvalidationFn } from "./layout-invalidation.ts";
+import type { LayoutMeasurementProvider } from "./layout-measurement-provider.ts";
 
 // ---------------------------------------------------------------------------
 // Types
@@ -90,11 +91,18 @@ export interface PageStackResult {
  * This is the single entry point for page composition.  All consumers
  * (document-navigation, view-state, page mode) should call this instead
  * of directly using the estimation helpers.
+ *
+ * `measurementProvider` is optional.  When supplied, paragraph line counts
+ * and block heights consult the provider's `measureLineFragments` so the
+ * canvas backend can participate.  When omitted, measurement falls through
+ * to the empirical path baked into this module — which matches the
+ * provider's empirical backend numerically, keeping pagination stable.
  */
 export function buildPageStack(
   document: CanonicalDocumentEnvelope,
   sections: ResolvedDocumentSection[],
   mainSurface: EditorSurfaceSnapshot,
+  measurementProvider?: LayoutMeasurementProvider,
 ): DocumentPageSnapshot[] {
   const pages: DocumentPageSnapshot[] = [];
   let globalPageIndex = 0;
@@ -154,6 +162,7 @@ export function buildPageStack(
       sectionBlocks,
       layout,
       document.subParts?.footnoteCollection,
+      measurementProvider,
     );
 
     // continuous / nextColumn: merge the first page of this section into the
@@ -228,6 +237,7 @@ export function buildPageStackFrom(
   sections: readonly ResolvedDocumentSection[],
   mainSurface: EditorSurfaceSnapshot,
   resumeAt: { startPageIndex: number; startOffset: number },
+  measurementProvider?: LayoutMeasurementProvider,
 ): DocumentPageSnapshot[] {
   // Correctness-first: run the full pipeline and return pages from the
   // requested start.  `startOffset` is accepted for forward compatibility
@@ -237,6 +247,7 @@ export function buildPageStackFrom(
     document,
     sections as ResolvedDocumentSection[],
     mainSurface,
+    measurementProvider,
   );
   const startIndex = Math.max(0, resumeAt.startPageIndex);
   return full.slice(startIndex);
@@ -342,10 +353,15 @@ const FOOTNOTE_REFERENCE_RESERVATION_TWIPS = 180;
 /**
  * Compute block height using resolved formatting when available.
  * Uses improved table measurement for legal contracts.
+ *
+ * When `measurementProvider` is supplied, paragraph line counts are produced
+ * by `provider.measureLineFragments(...)`; otherwise the inline empirical
+ * path runs (which matches the empirical backend numerically).
  */
 function measureBlockHeight(
   block: SurfaceBlockSnapshot | undefined,
   columnWidth: number,
+  measurementProvider?: LayoutMeasurementProvider,
 ): number {
   if (!block) return 0;
 
@@ -353,17 +369,26 @@ function measureBlockHeight(
     case "paragraph": {
       const formatting = resolveBlockFormatting(block);
       if (formatting) {
-        const lineCount = measureParagraphLineCount(block, formatting, columnWidth);
+        const lineCount = measureParagraphLineCount(
+          block,
+          formatting,
+          columnWidth,
+          measurementProvider,
+        );
         return calculateParagraphHeight(formatting, lineCount);
       }
       return estimateBlockHeight(block, columnWidth);
     }
     case "table":
-      return measureTableHeight(block, columnWidth);
+      return measureTableHeight(block, columnWidth, measurementProvider);
     case "sdt_block":
       return Math.max(
         MIN_BLOCK_HEIGHT_TWIPS,
-        block.children.reduce((total, child) => total + measureBlockHeight(child, columnWidth), 0),
+        block.children.reduce(
+          (total, child) =>
+            total + measureBlockHeight(child, columnWidth, measurementProvider),
+          0,
+        ),
       );
     case "opaque_block":
       return block.label === "Section break" ? 0 : MIN_BLOCK_HEIGHT_TWIPS;
@@ -372,33 +397,76 @@ function measureBlockHeight(
 
 /**
  * Improved table height estimation.
+ *
  * Uses resolved formatting for cell content paragraphs and respects
  * explicit row heights and height rules.
+ *
+ * Per-cell width is derived from the table's `gridColumns` and each
+ * cell's `colspan` (honoring `gridBefore`/`gridAfter` row padding).
+ * This replaces the prior `columnWidth / cellCount` approximation,
+ * which was wrong whenever columns carried non-uniform widths or any
+ * cell had `colspan > 1`.
  */
 function measureTableHeight(
   block: Extract<SurfaceBlockSnapshot, { kind: "table" }>,
   columnWidth: number,
+  measurementProvider?: LayoutMeasurementProvider,
 ): number {
   const TABLE_ROW_PADDING_TWIPS = 120;
   let totalHeight = 0;
 
+  const gridColumnCount = block.gridColumns.length;
+  const totalGridTwips = block.gridColumns.reduce((sum, w) => sum + w, 0);
+  // Scale the canonical gridColumns to the available column width so that
+  // a table defined in 9000-twip grid on a 12240-twip canvas measures
+  // against the actual canvas width, not the OOXML-declared width.
+  const gridScale =
+    totalGridTwips > 0 && columnWidth > 0 ? columnWidth / totalGridTwips : 1;
+
   for (const row of block.rows) {
     const explicitHeight = row.height ?? 0;
     const heightRule = row.heightRule ?? "auto";
+    const gridBefore = row.gridBefore ?? 0;
 
-    // Calculate content-driven height
+    // Calculate content-driven height using real per-cell widths.
     let contentHeight = MIN_BLOCK_HEIGHT_TWIPS;
-    const cellCount = Math.max(1, row.cells.length);
-    const cellWidth = Math.max(720, Math.floor(columnWidth / cellCount));
+    let columnCursor = gridBefore;
 
     for (const cell of row.cells) {
+      const span = Math.max(1, cell.colspan ?? 1);
+      const cellWidth = resolveCellWidth(
+        block.gridColumns,
+        columnCursor,
+        span,
+        columnWidth,
+        gridScale,
+      );
+      columnCursor += span;
+
+      if (cell.verticalMerge === "continue") {
+        // Continuation cells don't contribute their own content height —
+        // the origin cell's height covers the whole span.
+        continue;
+      }
+
       let cellContentHeight = 0;
       for (const child of cell.content) {
-        cellContentHeight += measureBlockHeight(child, cellWidth);
+        cellContentHeight += measureBlockHeight(
+          child,
+          cellWidth,
+          measurementProvider,
+        );
       }
       contentHeight = Math.max(contentHeight, cellContentHeight + TABLE_ROW_PADDING_TWIPS);
     }
 
+    // Sanity fallback if the row declared more columns than the grid
+    // (malformed input) — clamp the cursor back so subsequent rows
+    // continue to measure without throwing.
+    if (gridColumnCount > 0 && columnCursor > gridColumnCount) {
+      // no-op; kept for documentation — width resolution handles overflow.
+    }
+
     if (heightRule === "exact" && explicitHeight > 0) {
       totalHeight += explicitHeight;
     } else if (heightRule === "atLeast" && explicitHeight > 0) {
@@ -413,15 +481,78 @@ function measureTableHeight(
   return Math.max(MIN_BLOCK_HEIGHT_TWIPS, totalHeight);
 }
 
+/**
+ * Sum the widths of `columnSpan` columns starting at `startColumn` from
+ * the table's `gridColumns`, scaled to the available column width.
+ *
+ * Falls back to an even split of `fallbackColumnWidth` when the grid has
+ * no entries (no `gridColumns` declared).
+ *
+ * Exported via `__resolveCellWidth` for unit tests; not part of the
+ * stable surface.
+ */
+export function __resolveCellWidth(
+  gridColumns: readonly number[],
+  startColumn: number,
+  columnSpan: number,
+  fallbackColumnWidth: number,
+  gridScale: number,
+): number {
+  return resolveCellWidth(gridColumns, startColumn, columnSpan, fallbackColumnWidth, gridScale);
+}
+
+function resolveCellWidth(
+  gridColumns: readonly number[],
+  startColumn: number,
+  columnSpan: number,
+  fallbackColumnWidth: number,
+  gridScale: number,
+): number {
+  if (gridColumns.length === 0) {
+    // No grid declared — best-effort even split of the canvas.
+    return Math.max(240, Math.floor(fallbackColumnWidth));
+  }
+  let gridWidth = 0;
+  for (let i = 0; i < columnSpan; i += 1) {
+    const column = startColumn + i;
+    if (column < 0 || column >= gridColumns.length) continue;
+    gridWidth += gridColumns[column] ?? 0;
+  }
+  const scaled = Math.floor(gridWidth * gridScale);
+  return Math.max(240, scaled);
+}
+
 /**
  * Count lines in a paragraph using resolved formatting.
  * Accounts for proper indentation, font metrics, and numbering geometry.
+ *
+ * When a measurement provider is supplied, delegates line counting to the
+ * provider's `measureLineFragments`.  The provider's empirical backend
+ * returns the same numerical result as the inline path, so switching does
+ * not change pagination behavior; the canvas backend returns canvas-
+ * measured line counts once fonts resolve.
  */
 function measureParagraphLineCount(
   block: Extract<SurfaceBlockSnapshot, { kind: "paragraph" }>,
   formatting: import("./resolved-formatting-state.ts").ResolvedParagraphFormatting,
   columnWidth: number,
+  measurementProvider?: LayoutMeasurementProvider,
 ): number {
+  if (measurementProvider) {
+    const measured = measurementProvider.measureLineFragments({
+      block,
+      formatting,
+      // The paginated pipeline currently resolves formatting at the
+      // paragraph level only; per-run formatting is not yet threaded
+      // through.  Pass an empty map; the provider's empirical backend
+      // does not consult per-run metrics and the canvas backend falls
+      // back to the paragraph defaults when a run is missing.
+      runs: new Map(),
+      columnWidth,
+    });
+    return Math.max(1, measured.lineCount);
+  }
+
   const firstLineWidth = resolveTextWidth(formatting, columnWidth, true);
   const subsequentLineWidth = resolveTextWidth(formatting, columnWidth, false);
   const firstLineCapacity = resolveCharsPerLine(firstLineWidth, formatting.averageCharWidthTwips);
@@ -534,6 +665,7 @@ function paginateSectionBlocks(
   blocks: readonly SurfaceBlockSnapshot[],
   layout: DocumentPageSnapshot["layout"],
   footnotes: FootnoteCollection | undefined,
+  measurementProvider?: LayoutMeasurementProvider,
 ): Omit<DocumentPageSnapshot, "pageIndex">[] {
   if (blocks.length === 0) {
     return [
@@ -585,12 +717,13 @@ function paginateSectionBlocks(
       const columnWidth =
         columnMetrics[Math.min(columnIndex, columnMetrics.length - 1)]?.width ??
         getUsableColumnWidth(layout);
-      const baseHeight = measureBlockHeight(block, columnWidth);
+      const baseHeight = measureBlockHeight(block, columnWidth, measurementProvider);
 
       // keepNext: this paragraph must stay with the next one on the same page
       const keepWithNextHeight =
         block.kind === "paragraph" && block.keepNext
-          ? baseHeight + measureBlockHeight(blocks[index + 1], columnWidth)
+          ? baseHeight +
+            measureBlockHeight(blocks[index + 1], columnWidth, measurementProvider)
           : baseHeight;
 
       // keepLines: the entire paragraph must fit on one page.

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

@@ -0,0 +1,91 @@
+/**
+ * Project surface blocks → per-page RuntimeBlockFragments (P4).
+ *
+ * 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.
+ *
+ * Today the engine does not split tables across pages, so this emission
+ * pass treats each top-level SurfaceBlockSnapshot as an atomic fragment
+ * with `pageIndex` resolved from `pages[i].startOffset..endOffset`. Row-
+ * level splitting (for header-row repeat + per-row cantSplit) will refine
+ * this to multiple fragments per block.
+ */
+
+import type {
+  DocumentPageSnapshot,
+  EditorSurfaceSnapshot,
+  SurfaceBlockSnapshot,
+} from "../../api/public-types";
+import type { RuntimeBlockFragment } from "./page-graph.ts";
+
+type FragmentWithoutPageId = Omit<RuntimeBlockFragment, "pageId">;
+
+export function projectSurfaceBlocksToPageFragments(
+  surface: EditorSurfaceSnapshot,
+  pages: readonly DocumentPageSnapshot[],
+): Map<number, FragmentWithoutPageId[]> {
+  const byPage = new Map<number, FragmentWithoutPageId[]>();
+  const perPageCounter = new Map<number, number>();
+
+  for (const block of surface.blocks) {
+    const pageIndex = findPageIndexForOffset(pages, block.from);
+    if (pageIndex === null) continue;
+    const orderInRegion = perPageCounter.get(pageIndex) ?? 0;
+    perPageCounter.set(pageIndex, orderInRegion + 1);
+
+    const fragment: FragmentWithoutPageId = {
+      fragmentId: `fragment-${block.blockId}`,
+      blockId: block.blockId,
+      orderInRegion,
+      regionKind: "body",
+      from: block.from,
+      to: block.to,
+      // Height is not recomputed here — the pagination engine already
+      // measured the block to assign it to this page. Chrome surfaces
+      // that need precise heights can consult layout facet measurements.
+      heightTwips: estimateBlockHeightFromSpan(block),
+    };
+
+    const existing = byPage.get(pageIndex);
+    if (existing) {
+      existing.push(fragment);
+    } else {
+      byPage.set(pageIndex, [fragment]);
+    }
+  }
+
+  return byPage;
+}
+
+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;
+}