@beyondwork/docx-react-component 1.0.85 → 1.0.87

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@beyondwork/docx-react-component",
   "publisher": "beyondwork",
-  "version": "1.0.85",
+  "version": "1.0.87",
   "description": "Embeddable React Word (docx) editor with review, comments, tracked changes, and round-trip OOXML fidelity.",
   "type": "module",
   "sideEffects": [

package/src/api/public-types.ts

@@ -921,12 +921,22 @@ export interface UpdateFieldsResult {
 
 /** Options for runtime-backed TOC refresh. */
 export interface TocRefreshOptions {
+  /** Specific TOC region to update. Defaults to the first/all supported regions depending on mode. */
+  tocId?: string;
+  /** Preserve imported cached rows for visual parity, or regenerate from headings. Defaults to regenerate. */
+  mode?: "preserveCached" | "regenerate";
   /** Maximum heading outline level to include (1–9, default 3). */
   maxLevel?: number;
 }
 
 /** Result of a TOC refresh operation. */
 export interface TocRefreshResult {
+  /** TOC region affected when the document has a first-class TOC region. */
+  tocId?: string;
+  /** Update mode used by the runtime. */
+  mode?: "preserveCached" | "regenerate";
+  /** Region freshness after the operation. */
+  status?: "current" | "stale" | "missing";
   /** Number of TOC entries generated from heading structure. */
   entryCount: number;
   /** Heading entries that populated the TOC. */
@@ -934,6 +944,8 @@ export interface TocRefreshResult {
     level: number;
     text: string;
     pageIndex: number;
+    pageText?: string;
+    source?: "cached" | "generated";
   }>;
 }
 
@@ -986,15 +998,30 @@ export interface TocEntrySnapshot {
   level: number;
   text: string;
   pageIndex?: number;
+  pageText?: string;
+  source?: "cached" | "generated";
   anchor?: EditorAnchorProjection;
   bookmarkName?: string;
   headingId?: string;
 }
 
+export interface TocRegionSnapshot {
+  tocId: string;
+  status: "current" | "stale";
+  sourceFieldIndex: number;
+  instruction: string;
+  cachedEntryCount: number;
+  generatedEntryCount: number;
+}
+
 export interface TocSnapshot {
   status: "current" | "stale" | "missing";
+  tocId?: string;
   sourceFieldIndex?: number;
   instruction?: string;
+  source?: "cached" | "generated";
+  regionCount?: number;
+  regions?: TocRegionSnapshot[];
   entries: TocEntrySnapshot[];
 }
 
@@ -2580,6 +2607,13 @@ export interface AddScopeResult {
 export interface ExportDocxOptions {
   fileName?: string;
   reason?: string;
+  /**
+   * Controls the browser download fallback used by the mounted
+   * `WordReviewEditor` ref when no host/datastore `saveExport` adapter is
+   * present. Defaults to `true`. Set to `false` to receive exported bytes
+   * without triggering an anchor download.
+   */
+  download?: boolean;
   /**
    * @experimental Lane 7c Slice 7c.4 (v2.0.0) — opt-in for Strict-flavor
    * OOXML export (ECMA-376 / ISO 29500-1 Strict, namespaces under
@@ -3595,6 +3629,8 @@ export type WordReviewEditorEvent =
   | {
       type: "toc_auto_refreshed";
       documentId: string;
+      tocId?: string;
+      regionCount?: number;
       entryCount: number;
       trigger: TocRefreshTrigger;
     }
@@ -5802,6 +5838,13 @@ export type TextCommandAckKind =
   | "rejected"
   | "structural-divergence";
 
+export type TextCommandRefreshClass =
+  | "selection-only"
+  | "local-text-equivalent"
+  | "surface-only"
+  | "full-projection"
+  | "blocked";
+
 export interface ScopeTagTouch {
   /** Tag family: "comment" | "revision" | "field" | "bookmark" | "sdt" | "opaque" | custom string. */
   tagType: string;
@@ -5827,6 +5870,12 @@ export interface ScopeTagTouch {
  */
 export interface TextCommandAck {
   kind: TextCommandAckKind;
+  /**
+   * Narrow post-ack refresh tier for editors that separate the typing hot
+   * path from broader projection work. Older runtimes may omit this; callers
+   * should derive a conservative tier from `kind` when absent.
+   */
+  refreshClass?: TextCommandRefreshClass;
   /** Opaque id echoed back from the predicted op. Undefined for canonical callers. */
   opId?: string;
   /** Revision token of the document AFTER commit. Empty string when `kind === "rejected"`. */

package/src/api/v3/ui/chrome-composition.ts

@@ -29,10 +29,7 @@ import type {
   WordReviewEditorChromePreset,
   WordReviewEditorChromeVisibility,
 } from "../../public-types";
-import {
-  resolveChromePresetOptions,
-  resolveChromeVisibilityForPreset,
-} from "./chrome-preset-model";
+import { resolveChromeVisibilityForPreset } from "./chrome-preset-model";
 
 /**
  * Pure breakpoint resolver — inlined at layer 10 so chrome composition does
@@ -285,11 +282,6 @@ export function resolveChromeComposition(
   input: ChromeCompositionInput,
 ): ChromeComposition {
   const mode = deriveMode(input);
-  const options = resolveChromePresetOptions(
-    input.chromePreset,
-    input.chromeOptions,
-    input.role,
-  );
   const visibility = resolveChromeVisibilityForPreset({
     chromePreset: input.chromePreset,
     chromeOptions: input.chromeOptions,
@@ -300,8 +292,7 @@ export function resolveChromeComposition(
   const density: ChromeDensity = input.density ?? "standard";
   const pinnedRailTabs: ReadonlySet<EditorRailTab> =
     input.pinnedRailTabs ?? new Set<EditorRailTab>();
-  const railOpen =
-    input.railOpen ?? (options.showReviewRail && visibility.reviewRail);
+  const railOpen = input.railOpen ?? false;
   const visibleTabs = resolveVisibleRailTabs(
     railOpen,
     diagnosticsSignal,

package/src/api/v3/ui/chrome.ts

@@ -277,10 +277,9 @@ export function createChromeFamily(ctx: UiApiContext) {
   // isolation pattern as U9 overlay-visibility).
   //
   // `activeRailTabSet` distinguishes "user explicitly set activeRailTab"
-  // (including to `null`, meaning "close the rail") from "user hasn't
-  // expressed an opinion" (composer picks a mode-default). Without this
-  // flag, getComposition would force `null` for every caller that
-  // previously relied on the composer's mode-appropriate default.
+  // (including to `null`) from "user hasn't expressed an opinion".
+  // Without this flag, getComposition would force `null` for every caller
+  // that relies on the composer's closed-by-default rail posture.
   let activeRailTab: EditorRailTab | null = null;
   let activeRailTabSet = false;
   const pinnedRailTabs = new Set<EditorRailTab>();
@@ -354,10 +353,9 @@ export function createChromeFamily(ctx: UiApiContext) {
       // caller can override `activeRailTab` / `pinnedRailTabs` via input;
       // when omitted AND the UI API's internal state has been set,
       // internal state fills in. When the caller omits AND internal state
-      // is untouched (the initial-mount path), the composer's mode-default
-      // kicks in (e.g. rail open on "advanced" preset picks a default
-      // active tab per mode). This preserves back-compat for callers that
-      // never interacted with rail-state methods.
+      // is untouched (the initial-mount path), the composer keeps the rail
+      // closed. Mounted workspaces pass `railOpen` from their local toggle
+      // state when the user opens the rail.
       const merged: ChromeCompositionInput = {
         ...input,
         ...(input.activeRailTab !== undefined

package/src/index.ts

@@ -203,6 +203,7 @@ export type {
   DocumentOutlineHeadingSnapshot,
   DocumentOutlineSnapshot,
   TocEntrySnapshot,
+  TocRegionSnapshot,
   TocSnapshot,
   DocumentSectionSnapshot,
   SnapshotRefreshInvalidateTarget,
@@ -255,6 +256,10 @@ export type {
   WorkflowBlockedCommandReason,
   WorkflowScopeSnapshot,
   InteractionGuardSnapshot,
+  TextCommandAckKind,
+  TextCommandRefreshClass,
+  TextCommandAck,
+  ScopeTagTouch,
   WorkflowMarkupKind,
   WorkflowMarkupBase,
   WorkflowHighlightMarkup,

package/src/io/export/serialize-main-document.ts

@@ -1,8 +1,10 @@
 import type {
   AltChunkNode,
+  BlockNode,
   BorderSpec,
   CustomXmlNode,
   DocumentRootNode,
+  FieldNode,
   FootnoteProperties,
   InlineNode,
   LegacyFormFieldNode,
@@ -97,6 +99,8 @@ interface SerializationState {
   usedBookmarkIds: Set<string>;
   scopeBookmarkIds: Map<string, string>;
   nextScopeBookmarkId: number;
+  /** Number of paragraph-range TOC fields reconstructed during serialization. */
+  tocRegionExportCount: number;
 }
 
 interface InlineSerializationResult {
@@ -216,6 +220,7 @@ export function serializeMainDocument(
     usedBookmarkIds: collectNumericBookmarkIds(content),
     scopeBookmarkIds: new Map<string, string>(),
     nextScopeBookmarkId: 100000,
+    tocRegionExportCount: 0,
   };
   const suffix = `</w:body>\n</w:document>`;
   const bodyPieces: string[] = [];
@@ -228,8 +233,43 @@ export function serializeMainDocument(
   let paragraphIndex = -1;
   let previousWasParagraph = false;
 
-  for (const block of content.children) {
+  for (let blockIndex = 0; blockIndex < content.children.length; blockIndex += 1) {
+    const block = content.children[blockIndex]!;
     if (block.type === "paragraph") {
+      const tocField = findSerializableTocField(block);
+      if (tocField && startsSerializableTocRegion(content.children, blockIndex)) {
+        const startIndex = blockIndex;
+        const endIndex = findSerializableTocRegionEnd(content.children, startIndex);
+        state.tocRegionExportCount += 1;
+        for (let regionIndex = startIndex; regionIndex <= endIndex; regionIndex += 1) {
+          const paragraph = content.children[regionIndex];
+          if (paragraph?.type !== "paragraph") continue;
+          if (previousWasParagraph) {
+            cursor += 1;
+          }
+          paragraphIndex += 1;
+          const serializedParagraph = serializeParagraphWithTocBoundary(
+            paragraph,
+            state,
+            cursor,
+            paragraphIndex,
+            tocField,
+            regionIndex === startIndex,
+            regionIndex === endIndex,
+          );
+          const bodyRelativeOffset = bodyLength;
+          bodyPieces.push(serializedParagraph.xml);
+          bodyLength += serializedParagraph.xml.length;
+          paragraphBoundaries.push(
+            offsetParagraphBoundary(serializedParagraph.boundary, bodyRelativeOffset),
+          );
+          cursor = serializedParagraph.nextCursor;
+          previousWasParagraph = true;
+        }
+        blockIndex = endIndex;
+        continue;
+      }
+
       if (previousWasParagraph) {
         cursor += 1;
       }
@@ -365,6 +405,7 @@ export function serializeMainDocument(
         blockKindCounts,
         documentXmlBytes: documentXml.length,
         relationshipCount: state.relationships.length,
+        tocRegionExportCount: state.tocRegionExportCount,
         ms: serializePerformanceNow() - started,
       },
     });
@@ -412,12 +453,94 @@ function serializeTableCellNode(
   state: SerializationState,
 ): string {
   const propertiesXml = buildCellPropertiesXml(cell);
-  const blocksXml = cell.children
-    .map((child) => serializeBlockNode(child, state))
-    .join("");
+  const blocksXml = serializeBlockSequence(cell.children, state);
   return `<w:tc>${propertiesXml}${blocksXml || "<w:p/>"}</w:tc>`;
 }
 
+function serializeBlockSequence(
+  blocks: readonly BlockNode[],
+  state: SerializationState,
+): string {
+  const pieces: string[] = [];
+  for (let index = 0; index < blocks.length; index += 1) {
+    const block = blocks[index];
+    if (!block) continue;
+    if (block?.type === "paragraph") {
+      const tocField = findSerializableTocField(block);
+      if (tocField && startsSerializableTocRegion(blocks, index)) {
+        const endIndex = findSerializableTocRegionEnd(blocks, index);
+        state.tocRegionExportCount += 1;
+        for (let regionIndex = index; regionIndex <= endIndex; regionIndex += 1) {
+          const paragraph = blocks[regionIndex];
+          if (paragraph?.type !== "paragraph") continue;
+          pieces.push(
+            serializeTableCellParagraphWithTocBoundary(
+              paragraph,
+              state,
+              tocField,
+              regionIndex === index,
+              regionIndex === endIndex,
+            ),
+          );
+        }
+        index = endIndex;
+        continue;
+      }
+    }
+    pieces.push(serializeBlockNode(block, state));
+  }
+  return pieces.join("");
+}
+
+function findSerializableTocField(paragraph: ParagraphNode): FieldNode | undefined {
+  return paragraph.children.find(
+    (child): child is FieldNode => child.type === "field" && child.fieldFamily === "TOC",
+  );
+}
+
+function startsSerializableTocRegion(blocks: readonly BlockNode[], index: number): boolean {
+  const current = blocks[index];
+  if (current?.type === "paragraph" && isSerializableTocParagraphStyle(current.styleId)) {
+    return true;
+  }
+  const next = blocks[index + 1];
+  return next?.type === "paragraph" && isSerializableTocParagraphStyle(next.styleId);
+}
+
+function findSerializableTocRegionEnd(blocks: readonly BlockNode[], startIndex: number): number {
+  let endIndex = startIndex;
+  while (endIndex + 1 < blocks.length) {
+    const next = blocks[endIndex + 1];
+    if (next?.type !== "paragraph" || !isSerializableTocParagraphStyle(next.styleId)) {
+      break;
+    }
+    endIndex += 1;
+  }
+  return endIndex;
+}
+
+function isSerializableTocParagraphStyle(styleId: string | undefined): boolean {
+  return /^TOC\d+$/u.test(styleId ?? "");
+}
+
+function stripSerializableTocField(children: readonly InlineNode[]): InlineNode[] {
+  return children.filter(
+    (child) => !(child.type === "field" && child.fieldFamily === "TOC"),
+  );
+}
+
+function serializeTocFieldBeginXml(field: FieldNode): string {
+  return (
+    `<w:r><w:fldChar w:fldCharType="begin"/></w:r>` +
+    `<w:r><w:instrText xml:space="preserve"> ${escapeXml(field.instruction)} </w:instrText></w:r>` +
+    `<w:r><w:fldChar w:fldCharType="separate"/></w:r>`
+  );
+}
+
+function serializeTocFieldEndXml(): string {
+  return `<w:r><w:fldChar w:fldCharType="end"/></w:r>`;
+}
+
 function serializeBlockNode(
   block: DocumentRootNode["children"][number],
   state: SerializationState,
@@ -463,7 +586,7 @@ function serializeSdtNode(
   state: SerializationState,
 ): string {
   const propertiesXml = block.properties.propertiesXml ?? buildSdtPropertiesXml(block);
-  const childrenXml = block.children.map((child) => serializeBlockNode(child, state)).join("") || "<w:p/>";
+  const childrenXml = serializeBlockSequence(block.children, state) || "<w:p/>";
   return `<w:sdt>${propertiesXml}<w:sdtContent>${childrenXml}</w:sdtContent></w:sdt>`;
 }
 
@@ -482,7 +605,7 @@ function serializeCustomXmlNode(
     attrs.push(`w:element="${escapeXmlAttribute(block.element)}"`);
   }
   const attrXml = attrs.length > 0 ? ` ${attrs.join(" ")}` : "";
-  const childrenXml = block.children.map((child) => serializeBlockNode(child, state)).join("");
+  const childrenXml = serializeBlockSequence(block.children, state);
   return `<w:customXml${attrXml}>${childrenXml || "<w:p/>"}</w:customXml>`;
 }
 
@@ -559,6 +682,27 @@ function serializeTableCellParagraph(
   return xml;
 }
 
+function serializeTableCellParagraphWithTocBoundary(
+  paragraph: ParagraphNode,
+  state: SerializationState,
+  tocField: FieldNode,
+  isFirst: boolean,
+  isLast: boolean,
+): string {
+  let xml = buildParagraphOpenTag(paragraph, state);
+  const paragraphPropertiesXml = buildParagraphPropertiesXml(paragraph);
+  if (paragraphPropertiesXml.length > 0) {
+    xml += paragraphPropertiesXml;
+  }
+  const children = stripSerializableTocField(paragraph.children);
+  const childrenXml = children.map((child) => serializeTableInlineNode(child, state)).join("");
+  xml += isFirst ? serializeTocFieldBeginXml(tocField) : "";
+  xml += childrenXml || "<w:r><w:t></w:t></w:r>";
+  xml += isLast ? serializeTocFieldEndXml() : "";
+  xml += "</w:p>";
+  return xml;
+}
+
 /**
  * A.7: build the paragraph opening tag. When the canonical paragraph
  * carries a preserved `wordExtensionIds`, re-emit `w14:paraId` /
@@ -991,6 +1135,71 @@ function serializeParagraph(
   };
 }
 
+function serializeParagraphWithTocBoundary(
+  paragraph: ParagraphNode,
+  state: SerializationState,
+  cursor: number,
+  paragraphIndex: number,
+  tocField: FieldNode,
+  isFirst: boolean,
+  isLast: boolean,
+): ParagraphSerializationResult {
+  let xml = buildParagraphOpenTag(paragraph, state);
+  const boundaries = new Map<number, number>();
+  const paragraphStart = 0;
+  const paragraphStartTagEnd = xml.length;
+  boundaries.set(cursor, paragraphStartTagEnd);
+
+  let paragraphPropertiesStart: number | undefined;
+  let paragraphPropertiesEnd: number | undefined;
+
+  const paragraphPropertiesXml = buildParagraphPropertiesXml(paragraph);
+  if (paragraphPropertiesXml.length > 0) {
+    paragraphPropertiesStart = xml.length;
+    xml += paragraphPropertiesXml;
+    paragraphPropertiesEnd = xml.length;
+  }
+
+  if (isFirst) {
+    xml += serializeTocFieldBeginXml(tocField);
+  }
+  const strippedChildren = stripSerializableTocField(paragraph.children);
+  const children = serializeParagraphChildren(strippedChildren, state, cursor, xml.length);
+  xml += children.xml;
+  const contentEmpty = children.xml.length === 0;
+  if (contentEmpty) {
+    xml += "<w:r><w:t></w:t></w:r>";
+  }
+  if (isLast) {
+    xml += serializeTocFieldEndXml();
+  }
+  const paragraphEndTagStart = xml.length;
+  xml += "</w:p>";
+
+  if (!children.boundaries.has(children.cursor)) {
+    children.boundaries.set(children.cursor, paragraphEndTagStart);
+  }
+
+  return {
+    xml,
+    nextCursor: children.cursor,
+    boundary: {
+      paragraphIndex,
+      start: cursor,
+      end: children.cursor,
+      boundaries: children.boundaries,
+      paragraphStart,
+      paragraphStartTagEnd,
+      paragraphEndTagStart,
+      paragraphEnd: xml.length,
+      ...(paragraphPropertiesStart !== undefined
+        ? { paragraphPropertiesStart }
+        : {}),
+      ...(paragraphPropertiesEnd !== undefined ? { paragraphPropertiesEnd } : {}),
+    },
+  };
+}
+
 function serializeParagraphChildren(
   children: InlineNode[],
   state: SerializationState,

package/src/io/ooxml/parse-drawing.ts

@@ -6,6 +6,7 @@ import type { DrawingFrameNode, AnchorGeometry } from "../../model/canonical-doc
 import { parseAnchorGeometry } from "./parse-anchor.ts";
 import { parsePicture } from "./parse-picture.ts";
 import { parseShapeContent, type TxbxBlockParser } from "./parse-shapes.ts";
+import { parseChartSpace } from "./chart/parse-chart-space.ts";
 import {
   type XmlElementNode,
   findFirstChild,
@@ -203,7 +204,14 @@ function resolveContent(
     return { type: "opaque", rawXml };
   }
   if (uri === CHART_GRAPHIC_URI || uri === CHART_GRAPHIC_URI_ALT) {
-    return { type: "chart_preview", rawXml };
+    const chartRelId = extractChartRelId(graphicData);
+    const chartXml = chartRelId ? opts.chartPartLookup?.(chartRelId) : undefined;
+    const parsedData = chartXml ? parseChartSpace(chartXml) : undefined;
+    return {
+      type: "chart_preview",
+      rawXml,
+      ...(parsedData ? { parsedData } : {}),
+    };
   }
   if (uri === SMARTART_GRAPHIC_URI || uri === SMARTART_GRAPHIC_URI_ALT) {
     return { type: "smartart_preview", rawXml };
@@ -223,6 +231,12 @@ function resolveContent(
   return { type: "opaque", rawXml };
 }
 
+function extractChartRelId(graphicData: XmlElementNode | undefined): string | null {
+  if (!graphicData) return null;
+  const chart = findFirstDescendant(graphicData, "chart");
+  return chart?.attributes["r:id"] ?? chart?.attributes.id ?? null;
+}
+
 // Phase 6 — XML parser helpers imported from ./_mini-xml.ts (previously
 // duplicated inline across four files). See that module for B4 throw-on-
 // unterminated-tag contract and entity-decoding implementation.