@beyondwork/docx-react-component 1.0.37 → 1.0.39

package/src/runtime/layout/resolve-page-fields.ts

@@ -0,0 +1,70 @@
+/**
+ * Resolve `PAGE` and `NUMPAGES` field values per page.
+ *
+ * These two field families (now in `SupportedFieldFamily`) compute differently
+ * from `REF` / `PAGEREF` because the resolved value depends on the *owning
+ * page* of each header/footer instance, not on a single document-level
+ * computation.  A header part is shared across many pages; the same PAGE
+ * field must render "1" on page 1, "2" on page 2, and so on.
+ *
+ * The resolver is a pure function over the page graph — no DOM, no side
+ * effects.  Consumers (per-page header/footer bands) call
+ * `resolvePageFieldDisplayText` at render time to substitute the cached
+ * preserve-only text that currently sits inside the paragraph inline atom.
+ */
+
+import type { RuntimePageGraph, RuntimePageNode } from "./page-graph.ts";
+import type { SupportedFieldFamily } from "../../model/canonical-document.ts";
+
+export interface PageFieldContext {
+  /** The page this header/footer copy renders on. */
+  page: RuntimePageNode;
+  /** The graph the page belongs to (for NUMPAGES resolution). */
+  graph: RuntimePageGraph;
+}
+
+/**
+ * Resolve the display text for a PAGE / NUMPAGES field on a specific page.
+ *
+ * Returns the original cached `displayText` for unsupported families so the
+ * caller can use this as a single resolution helper.
+ */
+export function resolvePageFieldDisplayText(
+  family: SupportedFieldFamily | string,
+  cachedDisplayText: string,
+  context: PageFieldContext,
+): string {
+  switch (family) {
+    case "PAGE":
+      return String(context.page.stories.displayPageNumber);
+    case "NUMPAGES":
+      // Blank fillers (evenPage/oddPage section breaks) don't count toward
+      // NUMPAGES — the graph already excludes them from contentPageCount.
+      return String(context.graph.contentPageCount);
+    default:
+      return cachedDisplayText;
+  }
+}
+
+/**
+ * Build a lookup keyed by pageId → (fieldFamily → resolvedText).  Useful when
+ * a renderer wants to bulk-resolve every page's fields before emitting DOM.
+ * Absent keys mean no override; the cached field text should be used.
+ */
+export function buildPageFieldResolutionTable(
+  graph: RuntimePageGraph,
+  families: ReadonlySet<string> = new Set(["PAGE", "NUMPAGES"]),
+): Map<string, Map<string, string>> {
+  const result = new Map<string, Map<string, string>>();
+  for (const page of graph.pages) {
+    const perPage = new Map<string, string>();
+    for (const family of families) {
+      perPage.set(
+        family,
+        resolvePageFieldDisplayText(family, "", { page, graph }),
+      );
+    }
+    result.set(page.pageId, perPage);
+  }
+  return result;
+}

package/src/runtime/layout/resolve-page-previews.ts

@@ -0,0 +1,185 @@
+/**
+ * Flatten header/footer sub-part blocks to short text previews with PAGE /
+ * NUMPAGES fields resolved for the owning page.  Used by the in-flow page
+ * chrome widgets so the bands show live content ("Page 3 of 5") rather
+ * than a static "Header" / "Footer" placeholder.
+ *
+ * This is a **preview**, not a full renderer — we flatten to plain text
+ * and cap the length.  A per-page band is ~32 px tall; anything more
+ * elaborate belongs to the full editing path, which is entered by double-
+ * clicking the band.
+ */
+
+import type {
+  BlockNode,
+  HeaderDocument,
+  FooterDocument,
+  InlineNode,
+} from "../../model/canonical-document.ts";
+import type {
+  RuntimePageGraph,
+  RuntimePageNode,
+} from "./page-graph.ts";
+import { resolvePageFieldDisplayText } from "./resolve-page-fields.ts";
+
+const MAX_PREVIEW_CHARS = 140;
+
+export interface PagePreviewMaps {
+  /** pageId → short text preview of the resolved header story (if any). */
+  headerPreviewByPageId: Map<string, string>;
+  /** pageId → short text preview of the resolved footer story (if any). */
+  footerPreviewByPageId: Map<string, string>;
+}
+
+export function buildPagePreviewMaps(
+  graph: RuntimePageGraph,
+  subParts: {
+    headers?: ReadonlyArray<HeaderDocument>;
+    footers?: ReadonlyArray<FooterDocument>;
+  },
+): PagePreviewMaps {
+  const headerPreviewByPageId = new Map<string, string>();
+  const footerPreviewByPageId = new Map<string, string>();
+
+  for (const page of graph.pages) {
+    if (page.isBlankFiller) continue;
+    const headerStory = page.stories.header;
+    if (headerStory && headerStory.kind === "header") {
+      const source = findSubPart(subParts.headers, headerStory.relationshipId);
+      if (source) {
+        headerPreviewByPageId.set(
+          page.pageId,
+          flattenBlocksToPreview(source.blocks, page, graph),
+        );
+      }
+    }
+    const footerStory = page.stories.footer;
+    if (footerStory && footerStory.kind === "footer") {
+      const source = findSubPart(subParts.footers, footerStory.relationshipId);
+      if (source) {
+        footerPreviewByPageId.set(
+          page.pageId,
+          flattenBlocksToPreview(source.blocks, page, graph),
+        );
+      }
+    }
+  }
+
+  return { headerPreviewByPageId, footerPreviewByPageId };
+}
+
+function findSubPart<T extends HeaderDocument | FooterDocument>(
+  parts: ReadonlyArray<T> | undefined,
+  relationshipId: string,
+): T | undefined {
+  if (!parts) return undefined;
+  return parts.find((p) => p.relationshipId === relationshipId);
+}
+
+function flattenBlocksToPreview(
+  blocks: ReadonlyArray<BlockNode>,
+  page: RuntimePageNode,
+  graph: RuntimePageGraph,
+): string {
+  const parts: string[] = [];
+  for (const block of blocks) {
+    collectBlockText(block, page, graph, parts);
+    if (joinPreview(parts).length >= MAX_PREVIEW_CHARS) break;
+  }
+  return truncate(joinPreview(parts));
+}
+
+function collectBlockText(
+  block: BlockNode,
+  page: RuntimePageNode,
+  graph: RuntimePageGraph,
+  out: string[],
+): void {
+  switch (block.type) {
+    case "paragraph":
+      for (const child of block.children) {
+        collectInlineText(child, page, graph, out);
+      }
+      break;
+    case "table":
+      for (const row of block.rows) {
+        for (const cell of row.cells) {
+          for (const childBlock of cell.children) {
+            collectBlockText(childBlock, page, graph, out);
+          }
+        }
+      }
+      break;
+    case "sdt":
+      for (const child of block.children) {
+        collectBlockText(child, page, graph, out);
+      }
+      break;
+    // opaque_block / section_break / custom_xml / alt_chunk — no preview text.
+    default:
+      break;
+  }
+}
+
+function collectInlineText(
+  inline: InlineNode,
+  page: RuntimePageNode,
+  graph: RuntimePageGraph,
+  out: string[],
+): void {
+  switch (inline.type) {
+    case "text":
+      out.push(inline.text);
+      break;
+    case "tab":
+      out.push(" ");
+      break;
+    case "hard_break":
+      out.push(" ");
+      break;
+    case "field": {
+      const family = inline.fieldFamily ?? classifyFieldInstructionLocal(inline.instruction);
+      const cached = flattenInline(inline.children);
+      if (family === "PAGE" || family === "NUMPAGES") {
+        out.push(
+          resolvePageFieldDisplayText(family, cached, { page, graph }),
+        );
+      } else {
+        out.push(cached);
+      }
+      break;
+    }
+    case "hyperlink":
+      for (const child of inline.children) {
+        collectInlineText(child, page, graph, out);
+      }
+      break;
+    // bookmark_start/end, opaque_inline, note_ref etc — skip.
+    default:
+      break;
+  }
+}
+
+function flattenInline(inlines: ReadonlyArray<InlineNode> | undefined): string {
+  if (!inlines) return "";
+  let buf = "";
+  for (const inline of inlines) {
+    if (inline.type === "text") buf += inline.text;
+    else if (inline.type === "hard_break" || inline.type === "tab") buf += " ";
+  }
+  return buf;
+}
+
+function classifyFieldInstructionLocal(instr: string): string {
+  const match = /^\s*(\w+)/.exec(instr);
+  return match ? match[1]!.toUpperCase() : "UNKNOWN";
+}
+
+function joinPreview(parts: readonly string[]): string {
+  return parts.join("").replace(/\s+/g, " ").trim();
+}
+
+function truncate(s: string): string {
+  if (s.length <= MAX_PREVIEW_CHARS) return s;
+  return s.slice(0, MAX_PREVIEW_CHARS - 1).trimEnd() + "…";
+}

package/src/runtime/layout/resolved-formatting-state.ts

@@ -151,11 +151,11 @@ export function resolveBlockFormatting(
     fontSizeHalfPoints: fontInfo.fontSizeHalfPoints,
     averageCharWidthTwips: fontInfo.avgCharWidth,
     tabStops: resolveTabStops(block),
-    keepNext: Boolean(block.keepNext),
-    keepLines: Boolean(block.keepLines),
-    pageBreakBefore: Boolean(block.pageBreakBefore),
-    widowControl: block.widowControl !== false, // default true in Word
-    contextualSpacing: Boolean(block.contextualSpacing),
+    keepNext: Boolean(block.keepNext ?? block.resolvedParagraphFormatting?.keepNext),
+    keepLines: Boolean(block.keepLines ?? block.resolvedParagraphFormatting?.keepLines),
+    pageBreakBefore: Boolean(block.pageBreakBefore ?? block.resolvedParagraphFormatting?.pageBreakBefore),
+    widowControl: (block.widowControl ?? block.resolvedParagraphFormatting?.widowControl) !== false, // default true in Word
+    contextualSpacing: Boolean(block.contextualSpacing ?? block.resolvedParagraphFormatting?.contextualSpacing),
   };
 }
 
@@ -166,9 +166,10 @@ export function resolveBlockFormatting(
 function resolveSpacing(
   block: Extract<SurfaceBlockSnapshot, { kind: "paragraph" }>,
 ): ParagraphSpacing {
-  // Numbering geometry spacing overrides direct paragraph spacing
+  // Priority: numbering geometry > direct paragraph > style cascade
   const numbering = block.resolvedNumbering?.geometry.spacing;
   const direct = block.spacing;
+  const cascade = block.resolvedParagraphFormatting?.spacing;
 
   const normalizeLineRule = (
     rule: string | undefined,
@@ -177,21 +178,15 @@ function resolveSpacing(
     return undefined;
   };
 
-  if (numbering) {
+  if (numbering || direct || cascade) {
     return {
-      before: numbering.before ?? direct?.before,
-      after: numbering.after ?? direct?.after,
-      line: numbering.line ?? direct?.line,
-      lineRule: normalizeLineRule(numbering.lineRule) ?? normalizeLineRule(direct?.lineRule),
-    };
-  }
-
-  if (direct) {
-    return {
-      before: direct.before,
-      after: direct.after,
-      line: direct.line,
-      lineRule: normalizeLineRule(direct.lineRule),
+      before: numbering?.before ?? direct?.before ?? cascade?.before,
+      after: numbering?.after ?? direct?.after ?? cascade?.after,
+      line: numbering?.line ?? direct?.line ?? cascade?.line,
+      lineRule:
+        normalizeLineRule(numbering?.lineRule) ??
+        normalizeLineRule(direct?.lineRule) ??
+        normalizeLineRule(cascade?.lineRule),
     };
   }
 
@@ -228,16 +223,25 @@ function resolveIndentation(
     };
   }
 
-  const ind = block.indentation;
-  if (!ind) {
+  const direct = block.indentation;
+  const cascade = block.resolvedParagraphFormatting?.indentation;
+
+  if (!direct && !cascade) {
     return { left: 0, right: 0, firstLine: 0, hanging: 0 };
   }
 
   return {
-    left: ind.left ?? 0,
-    right: ind.right ?? 0,
-    firstLine: ind.firstLine ?? 0,
-    hanging: ind.hanging ?? (typeof ind.firstLine === "number" && ind.firstLine < 0 ? Math.abs(ind.firstLine) : 0),
+    left: direct?.left ?? cascade?.left ?? 0,
+    right: direct?.right ?? cascade?.right ?? 0,
+    firstLine: direct?.firstLine ?? cascade?.firstLine ?? 0,
+    hanging:
+      direct?.hanging ??
+      cascade?.hanging ??
+      (typeof direct?.firstLine === "number" && direct.firstLine < 0
+        ? Math.abs(direct.firstLine)
+        : typeof cascade?.firstLine === "number" && cascade.firstLine < 0
+          ? Math.abs(cascade.firstLine)
+          : 0),
   };
 }
 

package/src/runtime/layout/table-render-plan.ts

@@ -0,0 +1,249 @@
+/**
+ * Table render plan (P3e).
+ *
+ * Per `docs/reference/docx/runtime-rendering-and-chrome-phase.md` §1, the
+ * render kernel consumes a `TableRenderPlan` per table per page so the
+ * chrome can:
+ *   - render band-aware cell styling without pre-flattening into inline
+ *     CSS strings,
+ *   - position column-resize grips at logical column edges without
+ *     re-measuring the DOM,
+ *   - show repeated header rows on continuation pages (when row-level
+ *     pagination lands; today the field is empty),
+ *   - walk vertical-merge chains for merged-cell hit-testing.
+ *
+ * The plan is a pure function of the table block + resolved style
+ * resolution + gridColumns + the effective page column width. It does
+ * not read DOM or mutate state.
+ */
+
+import type {
+  SurfaceBlockSnapshot,
+  SurfaceTableCellSnapshot,
+  SurfaceTableRowSnapshot,
+} from "../../api/public-types";
+import type { TableStyleConditionalRegion } from "../../model/canonical-document.ts";
+import type { ResolvedTableStyleResolution } from "../table-style-resolver.ts";
+
+// ─── Public shapes ───────────────────────────────────────────────────────────
+
+export type TableBandRegion = TableStyleConditionalRegion;
+
+export interface TableCellBandAssignment {
+  rowIndex: number;
+  columnIndex: number;
+  regions: readonly TableBandRegion[];
+}
+
+export interface TableRowBandAssignment {
+  rowIndex: number;
+  regions: readonly TableBandRegion[];
+}
+
+export interface TableBandClasses {
+  /** Active regions per row (firstRow, lastRow, band1Horz, band2Horz). */
+  rows: readonly TableRowBandAssignment[];
+  /** Active regions per cell (row regions ∪ column regions). */
+  cells: readonly TableCellBandAssignment[];
+}
+
+export interface VerticalMergeRef {
+  /** Logical column the chain lives in. */
+  columnIndex: number;
+  /** Row where the chain starts (verticalMerge: "restart"). */
+  startRowIndex: number;
+  /** Inclusive row where the chain ends. */
+  endRowIndex: number;
+  /** Horizontal span of the merged cell. */
+  columnSpan: number;
+}
+
+export interface RepeatedHeaderRowRef {
+  /** Row index in the source table whose header is repeated. */
+  sourceRowIndex: number;
+  /** Virtual fragment id the render kernel uses to address this repeat. */
+  virtualFragmentId: string;
+}
+
+export interface ColumnResizeHandle {
+  /** Logical column index the handle sits at (0-based, right edge of column i). */
+  columnIndex: number;
+  /** X-origin of the handle in twips, measured from the table's left edge. */
+  originTwips: number;
+  /** Handle height in twips (table visual height). */
+  heightTwips: number;
+}
+
+export interface TableRenderPlan {
+  blockId: string;
+  pageIndex: number;
+  /** Logical column widths in twips (may be scaled from canonical). */
+  columnsTwips: readonly number[];
+  /** Band-class assignments derived from resolved table style. */
+  bandClasses: TableBandClasses;
+  /** Vertical-merge chains in the visible table range. */
+  verticalMerges: readonly VerticalMergeRef[];
+  /** Header rows repeated on this page (empty until row-level split lands). */
+  repeatedHeaderRows: readonly RepeatedHeaderRowRef[];
+  /** Column-resize handle origins for chrome grip placement. */
+  columnResizeHandles: readonly ColumnResizeHandle[];
+}
+
+// ─── Builder ────────────────────────────────────────────────────────────────
+
+export interface BuildTableRenderPlanInput {
+  blockId: string;
+  pageIndex: number;
+  block: Extract<SurfaceBlockSnapshot, { kind: "table" }>;
+  resolved: ResolvedTableStyleResolution;
+  /** Total height of the table in twips (for grip geometry). */
+  tableHeightTwips: number;
+  /** If `columnsTwips` was scaled to the canvas width, pass the scale
+   *  factor here; otherwise leave undefined. */
+  columnsTwipsScale?: number;
+  /**
+   * R3: true when this plan is for a continuation page of a multi-page
+   * table (i.e. a page other than the one the table first appears on).
+   * When true, header rows from the source table are emitted in
+   * `repeatedHeaderRows` so the consumer can prepend them on render.
+   */
+  isContinuationPage?: boolean;
+}
+
+export function buildTableRenderPlan(
+  input: BuildTableRenderPlanInput,
+): TableRenderPlan {
+  const { blockId, pageIndex, block, resolved, tableHeightTwips } = input;
+  const scale = input.columnsTwipsScale ?? 1;
+  const columnsTwips = block.gridColumns.map((w) => Math.round(w * scale));
+
+  const bandClasses = buildBandClasses(block.rows, resolved);
+  const verticalMerges = collectVerticalMerges(block.rows);
+  // R3: header rows are repeated on every continuation page.  When the
+  // render-plan builder is invoked for a page with `isContinuationPage`,
+  // every row with `isHeader === true` gets an entry in repeatedHeaderRows.
+  // First-page plans (or tables that fit on a single page) return an empty
+  // array.  `virtualFragmentId` is deterministic so consumers can key off it.
+  const repeatedHeaderRows: RepeatedHeaderRowRef[] = input.isContinuationPage
+    ? block.rows
+        .map((row, rowIndex) => ({ row, rowIndex }))
+        .filter(({ row }) => row.isHeader === true)
+        .map(({ rowIndex }) => ({
+          sourceRowIndex: rowIndex,
+          virtualFragmentId: `fragment-${blockId}-vheader-p${pageIndex}-r${rowIndex}`,
+        }))
+    : [];
+  const columnResizeHandles = buildColumnResizeHandles(columnsTwips, tableHeightTwips);
+
+  return {
+    blockId,
+    pageIndex,
+    columnsTwips,
+    bandClasses,
+    verticalMerges,
+    repeatedHeaderRows,
+    columnResizeHandles,
+  };
+}
+
+// ─── Internals ───────────────────────────────────────────────────────────────
+
+function buildBandClasses(
+  rows: readonly SurfaceTableRowSnapshot[],
+  resolved: ResolvedTableStyleResolution,
+): TableBandClasses {
+  const rowAssignments: TableRowBandAssignment[] = [];
+  const cellAssignments: TableCellBandAssignment[] = [];
+
+  for (let rowIndex = 0; rowIndex < rows.length; rowIndex += 1) {
+    const resolvedRow = resolved.rows[rowIndex];
+    const rowRegions = resolvedRow?.style.activeConditionalRegions ?? [];
+    rowAssignments.push({ rowIndex, regions: rowRegions });
+
+    const resolvedCells = resolvedRow?.cells ?? [];
+    const sourceRow = rows[rowIndex]!;
+    let columnCursor = sourceRow.gridBefore ?? 0;
+    for (let cellIndex = 0; cellIndex < sourceRow.cells.length; cellIndex += 1) {
+      const cell = sourceRow.cells[cellIndex]!;
+      const columnSpan = Math.max(1, cell.colspan ?? 1);
+      const resolvedCell = resolvedCells[cellIndex];
+      const regions = resolvedCell?.activeConditionalRegions ?? [];
+      cellAssignments.push({
+        rowIndex,
+        columnIndex: columnCursor,
+        regions,
+      });
+      columnCursor += columnSpan;
+    }
+  }
+
+  return { rows: rowAssignments, cells: cellAssignments };
+}
+
+function collectVerticalMerges(
+  rows: readonly SurfaceTableRowSnapshot[],
+): VerticalMergeRef[] {
+  const merges: VerticalMergeRef[] = [];
+  // Track active chains by column: maps startColumn → { startRow, span }.
+  const active = new Map<number, { startRow: number; span: number }>();
+
+  for (let rowIndex = 0; rowIndex < rows.length; rowIndex += 1) {
+    const row = rows[rowIndex]!;
+    let columnCursor = row.gridBefore ?? 0;
+    const seenThisRow = new Set<number>();
+
+    for (const cell of row.cells) {
+      const span = Math.max(1, cell.colspan ?? 1);
+      if (cell.verticalMerge === "restart") {
+        active.set(columnCursor, { startRow: rowIndex, span });
+        seenThisRow.add(columnCursor);
+      } else if (cell.verticalMerge === "continue") {
+        seenThisRow.add(columnCursor);
+        // chain stays open; ended rowIndex extends via the flush below
+      }
+      columnCursor += span;
+    }
+
+    // Flush chains that did NOT appear as a continue in this row.
+    for (const [startColumn, chain] of [...active.entries()]) {
+      if (!seenThisRow.has(startColumn)) {
+        merges.push({
+          columnIndex: startColumn,
+          startRowIndex: chain.startRow,
+          endRowIndex: rowIndex - 1,
+          columnSpan: chain.span,
+        });
+        active.delete(startColumn);
+      }
+    }
+  }
+
+  // Flush any still-open chains at end of table.
+  for (const [startColumn, chain] of active.entries()) {
+    merges.push({
+      columnIndex: startColumn,
+      startRowIndex: chain.startRow,
+      endRowIndex: rows.length - 1,
+      columnSpan: chain.span,
+    });
+  }
+
+  return merges;
+}
+
+function buildColumnResizeHandles(
+  columnsTwips: readonly number[],
+  heightTwips: number,
+): ColumnResizeHandle[] {
+  const handles: ColumnResizeHandle[] = [];
+  let cursor = 0;
+  for (let i = 0; i < columnsTwips.length - 1; i += 1) {
+    cursor += columnsTwips[i] ?? 0;
+    handles.push({
+      columnIndex: i,
+      originTwips: cursor,
+      heightTwips,
+    });
+  }
+  return handles;
+}

package/src/runtime/numbering-prefix.ts

@@ -1,4 +1,5 @@
 import type {
+  CanonicalRunFormatting,
   NumberingCatalog,
   NumberingLevelDefinition,
   ParagraphNode,
@@ -23,6 +24,7 @@ export interface NumberingPrefixResult {
   paragraphStyleId?: string;
   isLegalNumbering?: boolean;
   geometry: ResolvedNumberingGeometry;
+  markerRunProperties?: CanonicalRunFormatting;
 }
 
 export interface NumberingPrefixResolver {
@@ -90,6 +92,9 @@ export function createNumberingPrefixResolver(
         ? { paragraphStyleId: resolved.effectiveLevel.paragraphStyleId }
         : {}),
       ...(resolved.effectiveLevel.isLegalNumbering ? { isLegalNumbering: true } : {}),
+      ...(resolved.geometry.markerRunProperties
+        ? { markerRunProperties: resolved.geometry.markerRunProperties }
+        : {}),
       geometry: resolved.geometry,
     };
   }