@beyondwork/docx-react-component 1.0.24 → 1.0.26-rc2

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@beyondwork/docx-react-component",
   "publisher": "beyondwork",
-  "version": "1.0.24",
+  "version": "1.0.26rc2",
   "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

@@ -1398,6 +1398,7 @@ export interface WordReviewEditorProps {
   loadSourcePolicy?: LoadSourcePolicy;
   readOnly?: boolean;
   reviewMode?: "editing" | "review";
+  suggestionsEnabled?: boolean;
   markupDisplay?: "clean" | "simple" | "all";
   showReviewPanel?: boolean;
   chromeVisibility?: Partial<WordReviewEditorChromeVisibility>;

package/src/core/commands/index.ts

@@ -1309,7 +1309,7 @@ function applySuggestingInsert(
   }
 
   if (isCollapsed) {
-    // Pure insertion at cursor: apply normally, then create insertion revision
+    // Pure insertion at cursor: apply normally, then create or extend an insertion revision.
     const result = insertText(state.document, selection, text, { timestamp: context.timestamp });
     const insertedFrom = from;
     const insertedTo = from + Array.from(text).length;
@@ -1321,25 +1321,53 @@ function applySuggestingInsert(
       result.mapping,
     );
 
-    // Create the revision with pre-mapping positions — it refers to content
-    // that was just inserted, so its anchors are already correct in the new document
-    const revision = createAuthoredRevision(
+    // If there is an authored insertion revision that ends exactly where this
+    // text was inserted (i.e. the cursor was at the end of a prior insertion),
+    // extend that revision to cover the new text rather than creating a new one.
+    // This groups consecutive keystrokes into a single tracked change.
+    const adjacentInsertion = findAdjacentAuthoredInsertion(
       reviewState.document.review.revisions,
-      "insertion",
       insertedFrom,
-      insertedTo,
-      authorId,
-      context.timestamp,
     );
 
+    let finalRevisionId: string;
+    let finalRevisions: Record<string, CanonicalRevisionRecord>;
+
+    if (adjacentInsertion && adjacentInsertion.anchor.kind === "range") {
+      const extended: CanonicalRevisionRecord = {
+        ...adjacentInsertion,
+        anchor: {
+          kind: "range",
+          range: { from: adjacentInsertion.anchor.range.from, to: insertedTo },
+          assoc: { start: 1, end: -1 },
+        },
+      };
+      finalRevisionId = extended.changeId;
+      finalRevisions = {
+        ...reviewState.document.review.revisions,
+        [extended.changeId]: extended,
+      };
+    } else {
+      const revision = createAuthoredRevision(
+        reviewState.document.review.revisions,
+        "insertion",
+        insertedFrom,
+        insertedTo,
+        authorId,
+        context.timestamp,
+      );
+      finalRevisionId = revision.changeId;
+      finalRevisions = {
+        ...reviewState.document.review.revisions,
+        [revision.changeId]: revision,
+      };
+    }
+
     const finalDocument: CanonicalDocumentEnvelope = {
       ...reviewState.document,
       review: {
         ...reviewState.document.review,
-        revisions: {
-          ...reviewState.document.review.revisions,
-          [revision.changeId]: revision,
-        },
+        revisions: finalRevisions,
       },
     };
 
@@ -1360,7 +1388,7 @@ function applySuggestingInsert(
         mapping: result.mapping,
         effects: {
           ...reviewState.effects,
-          revisionAuthored: { changeId: revision.changeId, kind: "insertion" },
+          revisionAuthored: { changeId: finalRevisionId, kind: "insertion" },
         },
       },
     );
@@ -1704,3 +1732,26 @@ function findOverlappingAuthoredDeletion(
   }
   return undefined;
 }
+
+/**
+ * Find an open authored insertion revision whose end position equals `cursorAt`.
+ * Used to extend an existing insertion when the user keeps typing at the same
+ * position rather than creating a new revision for every character.
+ */
+function findAdjacentAuthoredInsertion(
+  revisions: Record<string, CanonicalRevisionRecord>,
+  cursorAt: number,
+): CanonicalRevisionRecord | undefined {
+  for (const revision of Object.values(revisions)) {
+    if (
+      revision.kind === "insertion" &&
+      revision.status === "open" &&
+      revision.metadata?.source === "runtime" &&
+      revision.anchor.kind === "range" &&
+      revision.anchor.range.to === cursorAt
+    ) {
+      return revision;
+    }
+  }
+  return undefined;
+}

package/src/core/selection/review-anchors.ts

@@ -104,7 +104,6 @@ export function rangeStaysWithinSingleParagraph(
 }
 
 export function canCreateDocxCommentAnchor(
-  content: unknown,
   anchor: ReviewAnchor,
 ): boolean {
   if (anchor.kind !== "range") {
@@ -112,11 +111,7 @@ export function canCreateDocxCommentAnchor(
   }
 
   const normalized = normalizeRange(anchor.range);
-  if (normalized.from === normalized.to) {
-    return false;
-  }
-
-  return rangeStaysWithinSingleParagraph(content, normalized);
+  return normalized.from !== normalized.to;
 }
 
 function readSurfaceBlocks(

package/src/io/export/serialize-comments.ts

@@ -261,19 +261,25 @@ export function serializeCommentAnchorsIntoDocumentXml(
       continue;
     }
 
-    const paragraph = paragraphs.find(
+    const startParagraph = paragraphs.find(
       (candidate) =>
         anchor.range.from >= candidate.start &&
+        anchor.range.from <= candidate.end,
+    );
+
+    const endParagraph = paragraphs.find(
+      (candidate) =>
+        anchor.range.to >= candidate.start &&
         anchor.range.to <= candidate.end,
     );
 
-    if (!paragraph) {
+    if (!startParagraph || !endParagraph) {
       skippedCommentIds.push(thread.commentId);
       continue;
     }
 
-    const startIndex = paragraph.boundaries.get(anchor.range.from);
-    const endIndex = paragraph.boundaries.get(anchor.range.to);
+    const startIndex = startParagraph.boundaries.get(anchor.range.from);
+    const endIndex = endParagraph.boundaries.get(anchor.range.to);
 
     if (startIndex === undefined || endIndex === undefined) {
       skippedCommentIds.push(thread.commentId);

package/src/review/store/comment-remapping.ts

@@ -4,7 +4,6 @@ import {
   getAnchorRange,
   mapReviewAnchor,
   mappingTouchesAnchorContent,
-  rangeStaysWithinSingleParagraph,
   type ReviewAnchor,
 } from "../../core/selection/review-anchors.ts";
 import type { TransactionMapping } from "../../core/selection/mapping.ts";
@@ -28,7 +27,7 @@ export function remapCommentThreads(
   const comments = Object.fromEntries(
     Object.entries(options.comments).map(([commentId, comment]) => [
       commentId,
-      remapCommentThread(comment, options.mapping, options.nextContent),
+      remapCommentThread(comment, options.mapping),
     ]),
   );
   const detachedCommentIds = Object.values(comments)
@@ -45,14 +44,13 @@ export function remapCommentThreads(
 export function remapCommentThread(
   comment: CommentThreadRecord,
   mapping: TransactionMapping,
-  nextContent: unknown,
 ): CommentThreadRecord {
   if (comment.anchor.kind === "detached") {
     return comment;
   }
 
   const mappedAnchor = mapReviewAnchor(comment.anchor, mapping);
-  const anchor = normalizeCommentAnchor(comment.anchor, mappedAnchor, mapping, nextContent);
+  const anchor = normalizeCommentAnchor(comment.anchor, mappedAnchor, mapping);
 
   return {
     ...comment,
@@ -64,7 +62,6 @@ function normalizeCommentAnchor(
   previousAnchor: ReviewAnchor,
   mappedAnchor: ReviewAnchor,
   mapping: TransactionMapping,
-  nextContent: unknown,
 ): ReviewAnchor {
   if (mappedAnchor.kind === "detached") {
     return mappedAnchor;
@@ -83,13 +80,6 @@ function normalizeCommentAnchor(
     return detachReviewAnchor(previousRange, detachReason(mapping));
   }
 
-  if (
-    mappedAnchor.kind === "range" &&
-    !rangeStaysWithinSingleParagraph(nextContent, mappedAnchor.range)
-  ) {
-    return detachReviewAnchor(previousRange, "invalidatedByStructureChange");
-  }
-
   return mappedAnchor;
 }
 

package/src/runtime/document-runtime.ts

@@ -1160,9 +1160,9 @@ export function createDocumentRuntime(
       const selection = params.anchor
         ? createSelectionFromPublicAnchor(params.anchor)
         : state.selection;
-      if (!canCreateDocxCommentAnchor(state.document.content, anchor)) {
+      if (!canCreateDocxCommentAnchor(anchor)) {
         const message =
-          "DOCX comments must use a non-empty range that stays within a single paragraph.";
+          "DOCX comments must use a non-empty range.";
         emitError({
           errorId: createSessionId("comment-anchor", clock()),
           code: "validation_failed",

package/src/runtime/session-capabilities.ts

@@ -110,7 +110,7 @@ export function deriveCapabilities(
     activeStory.kind === "main" &&
     !snapshot.selection.isCollapsed &&
     Boolean(snapshot.surface) &&
-    canCreateDocxCommentAnchor(snapshot.surface, toRuntimeAnchor(snapshot.selection.activeRange));
+    canCreateDocxCommentAnchor(toRuntimeAnchor(snapshot.selection.activeRange));
   const canExport = isReady && !exportBlocked && !hasFatalError;
 
   // Revision capabilities

package/src/ui/WordReviewEditor.tsx

@@ -520,6 +520,7 @@ export const WordReviewEditor = forwardRef<WordReviewEditorRef, WordReviewEditor
       onWarning,
       readOnly = false,
       reviewMode = "review",
+      suggestionsEnabled = false,
       showReviewPanel = true,
       chromeVisibility,
     } = props;
@@ -693,6 +694,10 @@ export const WordReviewEditor = forwardRef<WordReviewEditorRef, WordReviewEditor
       activeRuntime.setViewMode(effectiveViewMode);
     }, [activeRuntime, effectiveViewMode]);
 
+    useEffect(() => {
+      activeRuntime.setDocumentMode(suggestionsEnabled ? "suggesting" : "editing");
+    }, [activeRuntime, suggestionsEnabled]);
+
     useEffect(() => {
       runtimeViewStateSeedRef.current = {
         workspaceMode: viewState.workspaceMode,
@@ -1707,6 +1712,7 @@ export const WordReviewEditor = forwardRef<WordReviewEditorRef, WordReviewEditor
         markupDisplay={liveMarkupDisplay}
         activeRevisionId={activeRevisionId}
         showTrackedChanges={showTrackedChanges}
+        suggestionsEnabled={suggestionsEnabled}
         mediaPreviews={mediaPreviews}
         isPageWorkspace={isPageWorkspace}
         workflowScopes={workflowScopeSnapshot?.scopes}

package/src/ui/editor-surface-controller.tsx

@@ -27,6 +27,7 @@ export interface EditorSurfaceControllerProps {
   markupDisplay: MarkupDisplay;
   activeRevisionId?: string;
   showTrackedChanges?: boolean;
+  suggestionsEnabled?: boolean;
   mediaPreviews?: Record<string, MediaPreviewDescriptor>;
   isPageWorkspace?: boolean;
   onSelectionToolbarAnchorChange?: (anchor: SelectionToolbarAnchor | null) => void;

package/src/ui-tailwind/editor-surface/pm-decorations.ts

@@ -211,10 +211,13 @@ export function buildDecorations(
   workflowBlockedReasons?: readonly WorkflowBlockedCommandReason[],
   activeWorkflowWorkItemId?: string | null,
   activeWorkflowScopeIds?: readonly string[],
+  suggestionsEnabled = false,
 ): DecorationSet {
   const decorations: Decoration[] = [];
   const railRangeCache = new Map<string, Array<{ from: number; to: number }>>();
   const activeScopeIds = new Set(activeWorkflowScopeIds ?? []);
+  // In suggestions mode, tracked changes are always shown regardless of the toggle.
+  const effectiveShowTracked = suggestionsEnabled ? true : showTrackedChanges;
 
   // Walk comment threads and create inline decorations
   if (commentModel) {
@@ -248,7 +251,7 @@ export function buildDecorations(
       // Always hide deletions in clean mode (final-text semantics).
       // This is the critical behavior: "hide tracked changes" must show
       // the document as if accepted, not show deleted text as kept text.
-      if (markupDisplay === "clean" && rev.kind === "deletion") {
+      if (markupDisplay === "clean" && rev.kind === "deletion" && !suggestionsEnabled) {
         const pmFrom = positionMap.runtimeToPm(rev.from);
         const pmTo = positionMap.runtimeToPm(rev.to);
         if (pmFrom < pmTo) {
@@ -263,7 +266,48 @@ export function buildDecorations(
       }
 
       // Skip visual styling when tracked changes display is off
-      if (!showTrackedChanges) continue;
+      if (!effectiveShowTracked) continue;
+
+      const pmFrom = positionMap.runtimeToPm(rev.from);
+      const pmTo = positionMap.runtimeToPm(rev.to);
+      if (pmFrom >= pmTo) continue;
+
+      if (suggestionsEnabled) {
+        if (rev.kind === "insertion") {
+          decorations.push(
+            Decoration.inline(pmFrom, pmTo, {
+              class: "text-insert",
+              "data-revision-id": rev.revisionId,
+            }),
+          );
+          decorations.push(
+            Decoration.widget(pmFrom, () => {
+              const el = document.createElement("span");
+              el.textContent = "[";
+              el.className = "text-insert";
+              el.setAttribute("contenteditable", "false");
+              return el;
+            }, { side: -1, key: `${rev.revisionId}-open` }),
+          );
+          decorations.push(
+            Decoration.widget(pmTo, () => {
+              const el = document.createElement("span");
+              el.textContent = "]";
+              el.className = "text-insert";
+              el.setAttribute("contenteditable", "false");
+              return el;
+            }, { side: 1, key: `${rev.revisionId}-close` }),
+          );
+        } else if (rev.kind === "deletion") {
+          decorations.push(
+            Decoration.inline(pmFrom, pmTo, {
+              class: "text-danger line-through decoration-danger/80 decoration-1",
+              "data-revision-id": rev.revisionId,
+            }),
+          );
+        }
+        continue;
+      }
 
       const cls = getRevisionHighlightClass(
         revisionModel,
@@ -273,16 +317,12 @@ export function buildDecorations(
       );
       if (!cls) continue;
 
-      const pmFrom = positionMap.runtimeToPm(rev.from);
-      const pmTo = positionMap.runtimeToPm(rev.to);
-      if (pmFrom < pmTo) {
-        decorations.push(
-          Decoration.inline(pmFrom, pmTo, {
-            class: cls,
-            "data-revision-id": rev.revisionId,
-          }),
-        );
-      }
+      decorations.push(
+        Decoration.inline(pmFrom, pmTo, {
+          class: cls,
+          "data-revision-id": rev.revisionId,
+        }),
+      );
     }
   }
 

package/src/ui-tailwind/editor-surface/surface-build-keys.ts

@@ -43,6 +43,7 @@ export function createSurfaceDecorationKey(input: {
   workflowBlockedSignature?: string;
   activeWorkflowWorkItemId?: string | null;
   activeWorkflowScopeIds?: readonly string[];
+  suggestionsEnabled?: boolean;
 }): string {
   return JSON.stringify({
     markupDisplay: input.markupDisplay,
@@ -55,5 +56,6 @@ export function createSurfaceDecorationKey(input: {
     workflowBlockedSignature: input.workflowBlockedSignature ?? null,
     activeWorkflowWorkItemId: input.activeWorkflowWorkItemId ?? null,
     activeWorkflowScopeIds: input.activeWorkflowScopeIds ?? [],
+    suggestionsEnabled: input.suggestionsEnabled ?? false,
   });
 }

package/src/ui-tailwind/editor-surface/tw-prosemirror-surface.tsx

@@ -75,6 +75,7 @@ export interface TwProseMirrorSurfaceProps {
   markupDisplay: MarkupDisplay;
   activeRevisionId?: string;
   showTrackedChanges?: boolean;
+  suggestionsEnabled?: boolean;
   /** When true, the surface renders inside the page workspace (vs canvas). */
   isPageWorkspace?: boolean;
   onFocus: FocusEventHandler<HTMLDivElement>;
@@ -204,6 +205,7 @@ export const TwProseMirrorSurface = forwardRef<
       }),
     [mediaPreviewKey, snapshot.activeStory, surface],
   );
+  const suggestionsEnabled = props.suggestionsEnabled === true;
   const decorationBuildKey = useMemo(
     () =>
       createSurfaceDecorationKey({
@@ -217,6 +219,7 @@ export const TwProseMirrorSurface = forwardRef<
         workflowBlockedSignature: createWorkflowBlockedSignature(props.workflowBlockedReasons),
         activeWorkflowWorkItemId: props.activeWorkflowWorkItemId ?? null,
         activeWorkflowScopeIds: props.activeWorkflowScopeIds ?? [],
+        suggestionsEnabled,
       }),
     [
       canEdit,
@@ -229,6 +232,7 @@ export const TwProseMirrorSurface = forwardRef<
       props.workflowScopes,
       showTrackedChanges,
       snapshot.comments.activeCommentId,
+      suggestionsEnabled,
     ],
   );
 
@@ -274,6 +278,7 @@ export const TwProseMirrorSurface = forwardRef<
         props.workflowBlockedReasons,
         props.activeWorkflowWorkItemId,
         props.activeWorkflowScopeIds,
+        suggestionsEnabled,
       );
       view.setProps({
         editable: () => canEdit,