@beyondwork/docx-react-component 1.0.58 → 1.0.59

package/src/api/scope-metadata-resolver-types.ts

@@ -84,5 +84,11 @@ export interface ScopeMetadataResolver {
     version: number;
   }>;
 
+  /**
+   * Release a ref that is no longer needed (called when toggling a
+   * scope from `"external"` back to `"internal"`). Optional — hosts
+   * that don't need cleanup may omit it. Rejections are surfaced as
+   * non-fatal warnings; the scope continues to function internally.
+   */
   delete?(ref: ScopeMetadataStorageRef): Promise<void>;
 }

package/src/compare/diff-engine.ts

@@ -523,6 +523,7 @@ function getInlineLength(node: InlineNode): number {
     case "wordart":
     case "vml_shape":
     case "drawing_frame":
+    case "ole_embed":
       return 1;
   }
 }
@@ -584,6 +585,8 @@ function getInlineDisplayText(node: InlineNode): string {
       return node.text ?? "[VML Shape]";
     case "drawing_frame":
       return node.content.type === "picture" ? "[Image]" : "[Drawing]";
+    case "ole_embed":
+      return "[Embedded object]";
   }
 }
 

package/src/core/commands/formatting-commands.ts

@@ -1041,6 +1041,7 @@ function inlineNodeLength(node: InlineNode): number {
     case "wordart":
     case "vml_shape":
     case "drawing_frame":
+    case "ole_embed":
       return 1;
     case "field":
       return node.children.reduce<number>(

package/src/core/commands/index.ts

@@ -8,6 +8,7 @@ import {
   type SelectionSnapshot,
 } from "../state/editor-state.ts";
 import {
+  anchorUnaffectedByMapping,
   areAnchorsEqual,
   createDetachedAnchor,
   createEmptyMapping,
@@ -89,6 +90,14 @@ import {
   setHeaderFooterLinkAtSectionIndex,
 } from "./section-layout-commands.ts";
 import { insertPageBreak, insertTable } from "./text-commands.ts";
+// NOTE: This file imports `editLayer` from `runtime/edit-ops/index.ts`,
+// which in turn imports command primitives from `./text-commands.ts`. That
+// is a **diamond** dependency (A → B, A → C, B → C), NOT a module-level
+// cycle — `text-commands.ts` does not re-enter `core/commands/index.ts`
+// or `runtime/edit-ops/`. Verified 2026-04-20 by static DFS; see
+// docs/plans/architecture-lane.md §F3. Keep it this way — don't add
+// imports from `runtime/` that route through this file, as that could
+// introduce a real cycle.
 import { editLayer } from "../../runtime/edit-ops/index.ts";
 import { structureLayer } from "../../runtime/structure-ops/index.ts";
 import type { TableSelectionDescriptor } from "../../runtime/table-commands.ts";
@@ -411,6 +420,14 @@ export type EditorCommand =
 export interface TransactionEffects {
   warningsAdded: EditorWarning[];
   warningsCleared: Array<{ warningId: string; code: EditorWarning["code"] }>;
+  /**
+   * Fire-and-forget warnings emitted by the `notify` loop as `warning_added`
+   * events + `onWarning` callbacks, but NOT written to `state.warnings` or
+   * `CompatibilityReport.warnings`. Used for no-op diagnostic signaling such
+   * as `review_target_not_found` — the host should be told an op was
+   * skipped without accumulating a persistent entry every time.
+   */
+  transientWarnings?: EditorWarning[];
   commentAdded?: { commentId: string; anchor: EditorAnchorProjection };
   commentResolved?: { commentId: string };
   commentReopened?: { commentId: string };
@@ -800,6 +817,16 @@ export function executeEditorCommand(
         return createTransaction(state, {
           historyBoundary: "skip",
           markDirty: false,
+          effects: {
+            transientWarnings: [
+              reviewTargetNotFoundWarning(
+                "resolveComment",
+                command.commentId,
+                "comment_unknown",
+                "unknown commentId",
+              ),
+            ],
+          },
         });
       }
 
@@ -847,8 +874,38 @@ export function executeEditorCommand(
     }
     case "comment.reopen": {
       const existingThread = state.document.review.comments[command.commentId];
-      if (!existingThread || existingThread.status === "detached") {
-        return createTransaction(state, { historyBoundary: "skip", markDirty: false });
+      if (!existingThread) {
+        return createTransaction(state, {
+          historyBoundary: "skip",
+          markDirty: false,
+          effects: {
+            transientWarnings: [
+              reviewTargetNotFoundWarning(
+                "reopenComment",
+                command.commentId,
+                "comment_unknown",
+                "unknown commentId",
+              ),
+            ],
+          },
+        });
+      }
+      if (existingThread.status === "detached") {
+        return createTransaction(state, {
+          historyBoundary: "skip",
+          markDirty: false,
+          effects: {
+            transientWarnings: [
+              reviewTargetNotFoundWarning(
+                "reopenComment",
+                command.commentId,
+                "comment_detached",
+                "thread is detached",
+                { status: "detached" },
+              ),
+            ],
+          },
+        });
       }
       const reopenedComments = {
         ...state.document.review.comments,
@@ -880,11 +937,38 @@ export function executeEditorCommand(
     case "comment.add-reply": {
       const threadForReply = state.document.review.comments[command.commentId];
       if (!threadForReply) {
-        return createTransaction(state, { historyBoundary: "skip", markDirty: false });
+        return createTransaction(state, {
+          historyBoundary: "skip",
+          markDirty: false,
+          effects: {
+            transientWarnings: [
+              reviewTargetNotFoundWarning(
+                "addCommentReply",
+                command.commentId,
+                "comment_unknown",
+                "unknown commentId",
+              ),
+            ],
+          },
+        });
       }
       // Block reply on resolved or detached threads (must reopen first)
       if (threadForReply.status === "resolved" || threadForReply.status === "detached") {
-        return createTransaction(state, { historyBoundary: "skip", markDirty: false });
+        return createTransaction(state, {
+          historyBoundary: "skip",
+          markDirty: false,
+          effects: {
+            transientWarnings: [
+              reviewTargetNotFoundWarning(
+                "addCommentReply",
+                command.commentId,
+                "comment_status",
+                `thread is ${threadForReply.status}`,
+                { status: threadForReply.status },
+              ),
+            ],
+          },
+        });
       }
       const entryId = `${command.commentId}-entry-${(threadForReply.entries?.length ?? 0) + 1}`;
       const newEntry = {
@@ -919,8 +1003,37 @@ export function executeEditorCommand(
     }
     case "comment.edit-body": {
       const threadToEdit = state.document.review.comments[command.commentId];
-      if (!threadToEdit || !threadToEdit.entries?.length) {
-        return createTransaction(state, { historyBoundary: "skip", markDirty: false });
+      if (!threadToEdit) {
+        return createTransaction(state, {
+          historyBoundary: "skip",
+          markDirty: false,
+          effects: {
+            transientWarnings: [
+              reviewTargetNotFoundWarning(
+                "editCommentBody",
+                command.commentId,
+                "comment_unknown",
+                "unknown commentId",
+              ),
+            ],
+          },
+        });
+      }
+      if (!threadToEdit.entries?.length) {
+        return createTransaction(state, {
+          historyBoundary: "skip",
+          markDirty: false,
+          effects: {
+            transientWarnings: [
+              reviewTargetNotFoundWarning(
+                "editCommentBody",
+                command.commentId,
+                "comment_no_entries",
+                "thread has no entries to edit",
+              ),
+            ],
+          },
+        });
       }
       const editedEntries = [...threadToEdit.entries];
       editedEntries[0] = { ...editedEntries[0], body: command.body };
@@ -1443,6 +1556,9 @@ function createTransaction(
     effects: {
       warningsAdded: options.effects?.warningsAdded ?? [],
       warningsCleared: options.effects?.warningsCleared ?? [],
+      ...(options.effects?.transientWarnings
+        ? { transientWarnings: options.effects.transientWarnings }
+        : {}),
       commentAdded: options.effects?.commentAdded,
       commentResolved: options.effects?.commentResolved,
       changeAccepted: options.effects?.changeAccepted,
@@ -1453,6 +1569,71 @@ function createTransaction(
   };
 }
 
+/**
+ * Classify why `applyReviewCommand` produced no applied outcome so hosts can
+ * branch on `details.reason`. Inspects the pre-command revision store.
+ */
+function classifyReviewSkipReason(
+  store: RevisionStore,
+  command: ReviewCommand,
+): { reason: string; message: string; extraDetails?: Record<string, unknown> } {
+  if (command.type === "review.accept-all-revisions" || command.type === "review.reject-all-revisions") {
+    return {
+      reason: "no_actionable_revisions",
+      message: "no actionable revisions to apply",
+    };
+  }
+  const existing = store.revisions[command.revisionId];
+  if (!existing) {
+    return { reason: "revision_unknown", message: "unknown revisionId" };
+  }
+  if (existing.status === "detached") {
+    return {
+      reason: "revision_detached",
+      message: "revision anchor is detached",
+      extraDetails: { status: "detached" },
+    };
+  }
+  if (existing.status === "accepted" || existing.status === "rejected") {
+    return {
+      reason: "revision_status",
+      message: `revision is already ${existing.status}`,
+      extraDetails: { status: existing.status },
+    };
+  }
+  return {
+    reason: "revision_preserve_only",
+    message: "revision is preserve-only and cannot be accepted or rejected",
+    extraDetails: { kind: existing.kind },
+  };
+}
+
+/**
+ * Build a fire-and-forget `review_target_not_found` warning for a review op
+ * whose target id was unknown, resolved, detached, or preserve-only. Emitted
+ * via `effects.transientWarnings` — surfaces on `onWarning` + `warning_added`
+ * event without accumulating in `state.warnings` or `CompatibilityReport`.
+ *
+ * `reason` is a machine-readable code consumers can branch on; `message`
+ * is the human-readable string that lands on `EditorWarning.message`.
+ */
+function reviewTargetNotFoundWarning(
+  op: string,
+  targetId: string,
+  reason: string,
+  message: string,
+  extraDetails?: Record<string, unknown>,
+): EditorWarning {
+  return {
+    warningId: `review-target-not-found-${op}-${targetId}-${Date.now()}`,
+    code: "review_target_not_found",
+    severity: "info",
+    message: `${op}("${targetId}") skipped: ${message}.`,
+    source: "review",
+    details: { op, targetId, reason, ...(extraDetails ?? {}) },
+  };
+}
+
 function normalizeSelection(selection: SelectionSnapshot): SelectionSnapshot {
   const activeRange = normalizeSelectionAnchor(
     selection.activeRange,
@@ -1673,10 +1854,11 @@ function applyReviewCommand(
     });
   }
 
+  const priorStore = createRevisionStoreFromState(state);
   const result = applyRevisionRuntimeCommand({
     state: {
       document: state.document,
-      store: createRevisionStoreFromState(state),
+      store: priorStore,
     },
     command,
     timestamp,
@@ -1684,9 +1866,27 @@ function applyReviewCommand(
   const hasAppliedOutcome = result.outcomes.some((outcome) => outcome.kind === "applied");
 
   if (!hasAppliedOutcome) {
+    const op =
+      command.type === "review.accept-revision"
+        ? "acceptChange"
+        : command.type === "review.reject-revision"
+          ? "rejectChange"
+          : command.type === "review.accept-all-revisions"
+            ? "acceptAllChanges"
+            : "rejectAllChanges";
+    const targetId =
+      command.type === "review.accept-revision" || command.type === "review.reject-revision"
+        ? command.revisionId
+        : "*";
+    const { reason, message, extraDetails } = classifyReviewSkipReason(priorStore, command);
     return createTransaction(state, {
       historyBoundary: "skip",
       markDirty: false,
+      effects: {
+        transientWarnings: [
+          reviewTargetNotFoundWarning(op, targetId, reason, message, extraDetails),
+        ],
+      },
     });
   }
 
@@ -1781,15 +1981,24 @@ function remapReviewStateAfterContentChange(
     nextContent: nextDocument.content,
     existingWarnings: mappedWarnings,
   });
-  const revisions = Object.fromEntries(
-    Object.entries(nextDocument.review.revisions).map(([changeId, revision]) => [
-      changeId,
-      {
-        ...revision,
-        anchor: mapAnchor(revision.anchor, mapping),
-      },
-    ]),
-  );
+  // Remap revision anchors through the mapping. Most revisions are outside the
+  // edited range and don't need new objects — skip allocation for those and
+  // only rebuild the record when at least one anchor actually moved.
+  const sourceRevisions = nextDocument.review.revisions;
+  let revisions = sourceRevisions;
+  if (mapping.steps.length > 0) {
+    let changed = false;
+    const remappedEntries = Object.entries(sourceRevisions).map(([changeId, revision]) => {
+      if (anchorUnaffectedByMapping(revision.anchor, mapping)) {
+        return [changeId, revision] as const;
+      }
+      changed = true;
+      return [changeId, { ...revision, anchor: mapAnchor(revision.anchor, mapping) }] as const;
+    });
+    if (changed) {
+      revisions = Object.fromEntries(remappedEntries);
+    }
+  }
   const activeCommentId =
     state.runtime.activeCommentId &&
     remappedComments.comments[state.runtime.activeCommentId]

package/src/core/commands/legacy-form-field-commands.ts

@@ -0,0 +1,181 @@
+import type {
+  BlockNode,
+  DocumentRootNode,
+  FieldNode,
+  InlineNode,
+  LegacyFormFieldNode,
+  ParagraphNode,
+  TableCellNode,
+  TableNode,
+  TableRowNode,
+} from "../../model/canonical-document.ts";
+
+/**
+ * Any document shape that carries a `DocumentRootNode` on a `content` field.
+ * `CanonicalDocumentEnvelope`, `NormalizedTextDocument`, and the editor
+ * state snapshot all match this shape structurally.
+ */
+export interface DocWithContent {
+  content: DocumentRootNode;
+}
+
+/**
+ * Phase V.a — update a legacy form field value by name.
+ *
+ * For each `FieldNode` in the document whose `legacyFormField.name` matches
+ * the supplied name, the relevant typed field is updated:
+ *
+ *   kind="textInput"  → `textInput.default = value` (value must be string)
+ *   kind="checkBox"   → `checkBox.checked = value` (value must be boolean)
+ *   kind="ddList"     → `ddList.default = value` (value must be numeric
+ *                       index into `ddList.listEntry`)
+ *
+ * The node is marked `mutated: true` so the serializer regenerates the
+ * `<w:ffData>` XML from the typed fields (via `regenerateFFDataRawXml`)
+ * instead of emitting the preserved `rawXml` verbatim.
+ *
+ * Walk covers body, tables, SDT/customXml wrappers. Headers and footers are
+ * owned by their own document parts; call `setLegacyFormFieldValue` on
+ * those parts separately if the host needs to mutate them.
+ *
+ * If no field matches the name, the document is returned unchanged.
+ */
+export function setLegacyFormFieldValue<D extends DocWithContent>(
+  document: D,
+  fieldName: string,
+  value: string | boolean | number,
+): D {
+  const nextChildren = document.content.children.map((child) =>
+    rewriteBlock(child, fieldName, value),
+  );
+
+  if (arraysShallowEqual(nextChildren, document.content.children)) {
+    return document;
+  }
+
+  return {
+    ...document,
+    content: { ...document.content, children: nextChildren },
+  };
+}
+
+function rewriteBlock(
+  block: BlockNode,
+  fieldName: string,
+  value: string | boolean | number,
+): BlockNode {
+  if (block.type === "paragraph") {
+    return rewriteParagraph(block, fieldName, value);
+  }
+  if (block.type === "table") {
+    return rewriteTable(block, fieldName, value);
+  }
+  if (block.type === "sdt" || block.type === "custom_xml") {
+    const nextChildren = block.children.map((c) => rewriteBlock(c, fieldName, value));
+    if (arraysShallowEqual(nextChildren, block.children)) return block;
+    return { ...block, children: nextChildren };
+  }
+  return block;
+}
+
+function rewriteParagraph(
+  paragraph: ParagraphNode,
+  fieldName: string,
+  value: string | boolean | number,
+): ParagraphNode {
+  const nextChildren = paragraph.children.map((inline) =>
+    rewriteInline(inline, fieldName, value),
+  );
+  if (arraysShallowEqual(nextChildren, paragraph.children)) return paragraph;
+  return { ...paragraph, children: nextChildren };
+}
+
+function rewriteInline(
+  inline: InlineNode,
+  fieldName: string,
+  value: string | boolean | number,
+): InlineNode {
+  if (inline.type !== "field") return inline;
+  const field = inline as FieldNode;
+  const lff = field.legacyFormField;
+  if (!lff || lff.name !== fieldName) return inline;
+
+  const nextLff = applyValueToLegacyFormField(lff, value);
+  if (nextLff === lff) return inline;
+  return { ...field, legacyFormField: nextLff };
+}
+
+function applyValueToLegacyFormField(
+  lff: LegacyFormFieldNode,
+  value: string | boolean | number,
+): LegacyFormFieldNode {
+  switch (lff.kind) {
+    case "textInput": {
+      if (typeof value !== "string") return lff;
+      const currentDefault = lff.textInput?.default;
+      if (currentDefault === value) return lff;
+      return {
+        ...lff,
+        textInput: { ...(lff.textInput ?? {}), default: value },
+        mutated: true,
+      };
+    }
+    case "checkBox": {
+      if (typeof value !== "boolean") return lff;
+      if (lff.checkBox?.checked === value) return lff;
+      return {
+        ...lff,
+        checkBox: { ...(lff.checkBox ?? {}), checked: value },
+        mutated: true,
+      };
+    }
+    case "ddList": {
+      if (typeof value !== "number") return lff;
+      if (lff.ddList?.default === value) return lff;
+      return {
+        ...lff,
+        ddList: { ...(lff.ddList ?? {}), default: value },
+        mutated: true,
+      };
+    }
+  }
+}
+
+function rewriteTable(
+  table: TableNode,
+  fieldName: string,
+  value: string | boolean | number,
+): TableNode {
+  const nextRows = table.rows.map((row) => rewriteRow(row, fieldName, value));
+  if (arraysShallowEqual(nextRows, table.rows)) return table;
+  return { ...table, rows: nextRows };
+}
+
+function rewriteRow(
+  row: TableRowNode,
+  fieldName: string,
+  value: string | boolean | number,
+): TableRowNode {
+  const nextCells = row.cells.map((cell) => rewriteCell(cell, fieldName, value));
+  if (arraysShallowEqual(nextCells, row.cells)) return row;
+  return { ...row, cells: nextCells };
+}
+
+function rewriteCell(
+  cell: TableCellNode,
+  fieldName: string,
+  value: string | boolean | number,
+): TableCellNode {
+  const nextChildren = cell.children.map((child) => rewriteBlock(child, fieldName, value));
+  if (arraysShallowEqual(nextChildren, cell.children)) return cell;
+  return { ...cell, children: nextChildren };
+}
+
+function arraysShallowEqual<T>(a: readonly T[], b: readonly T[]): boolean {
+  if (a === b) return true;
+  if (a.length !== b.length) return false;
+  for (let i = 0; i < a.length; i += 1) {
+    if (a[i] !== b[i]) return false;
+  }
+  return true;
+}