@beyondwork/docx-react-component 1.0.86 → 1.0.88

package/src/model/canonical-document.ts

@@ -1339,6 +1339,9 @@ export type PreserveOnlyFieldFamily =
   | "SEQ"
   | "INDEX"
   | "TC"
+  | "FORMTEXT"
+  | "FORMCHECKBOX"
+  | "FORMDROPDOWN"
   | "FORMULA"
   | "UNKNOWN";
 
@@ -1424,6 +1427,8 @@ export interface FieldRegistry {
   supported: FieldRegistryEntry[];
   /** Preserve-only field instances cataloged for round-trip safety. */
   preserveOnly: FieldRegistryEntry[];
+  /** First-class TOC regions, including cached field-result rows and generated heading rows. */
+  tocRegions?: TocRegion[];
   /** Generated TOC structure extracted from heading-driven TOC fields. */
   tocStructure?: TocStructure;
 }
@@ -1464,6 +1469,78 @@ export interface TocStructure {
   status: "current" | "stale";
 }
 
+export interface TocInstructionModel {
+  /** The raw TOC field instruction (e.g. "TOC \\o \"1-3\" \\h"). */
+  raw: string;
+  /** Heading level range selected by \\o, or defaulted to 1-9. */
+  outlineRange: { from: number; to: number };
+  /** \\h — result entries should hyperlink to their anchors. */
+  hyperlink?: boolean;
+  /** \\z — hide tab leader and page numbers in web layout. */
+  hidePageNumbersInWeb?: boolean;
+  /** \\u — include paragraphs with outline levels. */
+  useOutlineLevels?: boolean;
+  /** \\t "Style,Level,..." — style-driven TOC mapping. */
+  styleMap?: TocStyleMapEntry[];
+  /** \\b bookmark — bound source content to a bookmark. */
+  bookmarkName?: string;
+  /** \\c identifier — table-of-figures / sequence identifier. */
+  sequenceIdentifier?: string;
+  /** \\f identifier — TC-entry identifier. */
+  tcIdentifier?: string;
+  /** \\p separator — custom entry/page separator. */
+  entryPageSeparator?: string;
+  /** \\d separator — custom sequence separator. */
+  sequenceSeparator?: string;
+  /** \\n optional range — omit page numbers. */
+  omitPageNumbers?: true | { from: number; to: number };
+  /** Switches parsed but not yet semantically implemented. */
+  unsupportedSwitches?: string[];
+}
+
+export interface TocStyleMapEntry {
+  styleName: string;
+  level: number;
+}
+
+export interface TocCachedEntry {
+  /** Text extracted from the cached field-result row before the page-number tab. */
+  text: string;
+  /** TOC level inferred from TOC1/TOC2/etc. paragraph style. */
+  level: number;
+  /** Paragraph index of the cached result row in document order. */
+  paragraphIndex: number;
+  /** Style ID of the cached result paragraph, if available. */
+  styleId?: string;
+  /** Bookmark/hyperlink anchor used by the cached result row, if present. */
+  bookmarkName?: string;
+  /** Page label extracted from the cached field result. */
+  pageText?: string;
+  /** Full visible row text, including tabs/page labels. */
+  displayText: string;
+}
+
+export interface TocRegion {
+  /** Stable document-order id for this imported TOC region. */
+  tocId: string;
+  /** Source TOC field index in FieldRegistry.supported. */
+  sourceFieldIndex: number;
+  /** Parsed instruction metadata and switches. */
+  instruction: TocInstructionModel;
+  /** Inclusive paragraph range containing the cached/generated result rows. */
+  resultRange: { fromParagraphIndex: number; toParagraphIndex: number };
+  /** Parent container kind where the region was found. */
+  parentKind: "body" | "sdt" | "custom_xml" | "table_cell";
+  /** Structural path to the parent block sequence, for diagnostics. */
+  sourcePath: string;
+  /** Cached rows imported from the DOCX field result. */
+  cachedEntries: TocCachedEntry[];
+  /** Heading-derived rows generated from the canonical document. */
+  generatedEntries: TocEntry[];
+  /** Whether cached entries match the generated heading model. */
+  status: "current" | "stale";
+}
+
 export interface TocEntry {
   /** Heading text. */
   text: string;
@@ -2009,8 +2086,8 @@ export interface DrawingFrameNode {
   content:
     | PictureContent
     | ShapeContent
-    | { type: "chart_preview"; rawXml: string }
-    | { type: "smartart_preview"; rawXml: string }
+    | ChartPreviewNode
+    | SmartArtPreviewNode
     | { type: "opaque"; rawXml: string };
 }
 
@@ -4069,6 +4146,9 @@ const PRESERVE_ONLY_FIELD_FAMILIES: ReadonlySet<PreserveOnlyFieldFamily> = new S
   "SEQ",
   "INDEX",
   "TC",
+  "FORMTEXT",
+  "FORMCHECKBOX",
+  "FORMDROPDOWN",
   "FORMULA",
   "UNKNOWN",
 ]);
@@ -4123,6 +4203,16 @@ function validateFieldRegistry(
   if (record.tocStructure !== undefined) {
     validateTocStructure(record.tocStructure, `${path}.tocStructure`, issues);
   }
+
+  if (record.tocRegions !== undefined) {
+    if (!Array.isArray(record.tocRegions)) {
+      issues.push({ path: `${path}.tocRegions`, message: "tocRegions must be an array." });
+    } else {
+      record.tocRegions.forEach((region, index) => {
+        validateTocRegion(region, `${path}.tocRegions[${index}]`, issues);
+      });
+    }
+  }
 }
 
 function validateFieldRegistryEntry(
@@ -4265,6 +4355,91 @@ function validateTocStructure(
   }
 }
 
+function validateTocRegion(
+  value: unknown,
+  path: string,
+  issues: ModelValidationIssue[],
+): void {
+  const record = asPlainObject(value, path, issues);
+  if (!record) {
+    return;
+  }
+
+  expectString(record.tocId, `${path}.tocId`, issues);
+  if (!Number.isInteger(record.sourceFieldIndex) || (record.sourceFieldIndex as number) < 0) {
+    issues.push({
+      path: `${path}.sourceFieldIndex`,
+      message: "sourceFieldIndex must be a non-negative integer.",
+    });
+  }
+
+  const instruction = asPlainObject(record.instruction, `${path}.instruction`, issues);
+  if (instruction) {
+    expectString(instruction.raw, `${path}.instruction.raw`, issues);
+    const outlineRange = asPlainObject(
+      instruction.outlineRange,
+      `${path}.instruction.outlineRange`,
+      issues,
+    );
+    if (outlineRange) {
+      if (!Number.isInteger(outlineRange.from) || (outlineRange.from as number) < 1) {
+        issues.push({
+          path: `${path}.instruction.outlineRange.from`,
+          message: "outlineRange.from must be an integer >= 1.",
+        });
+      }
+      if (!Number.isInteger(outlineRange.to) || (outlineRange.to as number) < 1) {
+        issues.push({
+          path: `${path}.instruction.outlineRange.to`,
+          message: "outlineRange.to must be an integer >= 1.",
+        });
+      }
+    }
+  }
+
+  const resultRange = asPlainObject(record.resultRange, `${path}.resultRange`, issues);
+  if (resultRange) {
+    if (!Number.isInteger(resultRange.fromParagraphIndex)) {
+      issues.push({
+        path: `${path}.resultRange.fromParagraphIndex`,
+        message: "fromParagraphIndex must be an integer.",
+      });
+    }
+    if (!Number.isInteger(resultRange.toParagraphIndex)) {
+      issues.push({
+        path: `${path}.resultRange.toParagraphIndex`,
+        message: "toParagraphIndex must be an integer.",
+      });
+    }
+  }
+
+  if (
+    record.parentKind !== "body" &&
+    record.parentKind !== "sdt" &&
+    record.parentKind !== "custom_xml" &&
+    record.parentKind !== "table_cell"
+  ) {
+    issues.push({
+      path: `${path}.parentKind`,
+      message: "parentKind must be body, sdt, custom_xml, or table_cell.",
+    });
+  }
+  expectString(record.sourcePath, `${path}.sourcePath`, issues);
+
+  if (!Array.isArray(record.cachedEntries)) {
+    issues.push({ path: `${path}.cachedEntries`, message: "cachedEntries must be an array." });
+  }
+  if (!Array.isArray(record.generatedEntries)) {
+    issues.push({ path: `${path}.generatedEntries`, message: "generatedEntries must be an array." });
+  }
+  if (record.status !== "current" && record.status !== "stale") {
+    issues.push({
+      path: `${path}.status`,
+      message: "status must be 'current' or 'stale'.",
+    });
+  }
+}
+
 function validateCanonicalFontTable(
   value: unknown,
   path: string,

package/src/model/layout/page-layout-snapshot.ts

@@ -38,6 +38,8 @@ export interface PageLayoutSnapshot {
     start?: number;
     chapterStyle?: string;
     chapterSeparator?: string;
+    /** Runtime-derived chapter marker for chapter-prefixed PAGE/PAGEREF display. */
+    chapterNumber?: string;
   };
   lineNumbering?: {
     countBy?: number;

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

@@ -90,6 +90,12 @@ export interface BuildPageGraphInput {
   >;
   /** Optional per-page line boxes. */
   lineBoxes?: ReadonlyMap<string, RuntimeLineBox[]>;
+  /**
+   * Optional per-page line boxes keyed by pageIndex. This mirrors
+   * `fragmentsByPageIndex` for callers that cannot know graph-internal
+   * `page-${revision}-${index}` ids before `buildPageGraph` runs.
+   */
+  lineBoxesByPageIndex?: ReadonlyMap<number, RuntimeLineBox[]>;
   /** Optional per-page note allocations keyed by graph-assigned pageId. */
   noteAllocations?: ReadonlyMap<string, RuntimeNoteAllocation[]>;
   /**

package/src/preservation/store.ts

@@ -163,11 +163,10 @@ export function describeStructuredWrapperBlock(
 ): OpaqueFragmentDescriptor | null {
   if (block.type === "sdt") {
     if (isTocContentControl(block)) {
-      return {
-        featureKey: "content-controls",
-        label: "TOC content control",
-        detail: "TOC content control remains a wrapper-heavy template structure and read-only.",
-      };
+      // CCEP SOW templates wrap the visible cached TOC result paragraphs in a
+      // docPartObj SDT. Collapsing that wrapper hides LibreOffice-visible
+      // content, so keep the wrapper in the surface tree and project children.
+      return null;
     }
     if (block.properties.sdtType === "docPartObj") {
       // coord-02 §11 P0 — a Template content control that wraps a

package/src/runtime/document-outline.ts

@@ -211,6 +211,62 @@ export function createTocSnapshot(
   navigation?: DocumentNavigationSnapshot,
 ): TocSnapshot | null {
   const registry = document.fieldRegistry;
+  const tocRegions = registry?.tocRegions ?? [];
+  const primaryRegion = tocRegions[0];
+  if (primaryRegion) {
+    const resolvedNavigation =
+      navigation ?? createDocumentNavigationSnapshot(document, 0, MAIN_STORY_TARGET);
+    const headingRefs = buildHeadingRefs(document, resolvedNavigation);
+    const useCachedEntries = primaryRegion.cachedEntries.length > 0;
+    const entries: TocEntrySnapshot[] = (useCachedEntries
+      ? primaryRegion.cachedEntries
+      : primaryRegion.generatedEntries
+    ).map((entry, index) => {
+      const pageText = useCachedEntries
+        ? primaryRegion.cachedEntries[index]?.pageText
+        : undefined;
+      const heading = useCachedEntries
+        ? resolveHeadingForCachedTocEntry(entry, headingRefs)
+        : resolveHeadingForTocEntry(primaryRegion.generatedEntries[index]!, headingRefs);
+      const bookmarkName =
+        entry.bookmarkName ??
+        headingRefs.find((ref) => ref.heading.headingId === heading?.headingId)?.bookmarkName;
+      return {
+        tocEntryId: `${primaryRegion.tocId}-entry-${index}`,
+        level: entry.level,
+        text: entry.text,
+        source: useCachedEntries ? "cached" : "generated",
+        ...(pageText ? { pageText } : {}),
+        ...(heading
+          ? {
+              pageIndex: heading.pageIndex,
+              anchor: createPublicRangeAnchor(heading.offset, heading.offset),
+              headingId: heading.headingId,
+            }
+          : {}),
+        ...(bookmarkName ? { bookmarkName } : {}),
+      };
+    });
+
+    return {
+      status: primaryRegion.status,
+      tocId: primaryRegion.tocId,
+      sourceFieldIndex: primaryRegion.sourceFieldIndex,
+      instruction: primaryRegion.instruction.raw,
+      source: useCachedEntries ? "cached" : "generated",
+      regionCount: tocRegions.length,
+      regions: tocRegions.map((region) => ({
+        tocId: region.tocId,
+        status: region.status,
+        sourceFieldIndex: region.sourceFieldIndex,
+        instruction: region.instruction.raw,
+        cachedEntryCount: region.cachedEntries.length,
+        generatedEntryCount: region.generatedEntries.length,
+      })),
+      entries,
+    };
+  }
+
   const tocStructure = registry?.tocStructure;
   const fallbackFields = document.fieldRegistry?.supported ?? [];
   const tocFieldIndex = tocStructure
@@ -331,6 +387,30 @@ function resolveHeadingForTocEntry(
   return paragraphMatch?.heading;
 }
 
+function resolveHeadingForCachedTocEntry(
+  entry: { text: string; bookmarkName?: string },
+  headingRefs: ReadonlyArray<{
+    heading: DocumentHeadingSnapshot;
+    paragraphIndex?: number;
+    bookmarkName?: string;
+  }>,
+): DocumentHeadingSnapshot | undefined {
+  if (entry.bookmarkName) {
+    const bookmarkMatch = headingRefs.find((ref) => ref.bookmarkName === entry.bookmarkName);
+    if (bookmarkMatch) {
+      return bookmarkMatch.heading;
+    }
+  }
+  const normalizedEntryText = normalizeTocSnapshotText(entry.text);
+  return headingRefs.find(
+    (ref) => normalizeTocSnapshotText(ref.heading.text) === normalizedEntryText,
+  )?.heading;
+}
+
+function normalizeTocSnapshotText(text: string): string {
+  return text.replace(/\s+/gu, " ").trim();
+}
+
 function findFirstTocField(blocks: readonly BlockNode[]): Extract<InlineNode, { type: "field" }> | undefined {
   for (const block of blocks) {
     if (block.type === "paragraph") {