@beyondwork/docx-react-component 1.0.13 → 1.0.14

package/package.json

@@ -1,9 +1,8 @@
 {
   "name": "@beyondwork/docx-react-component",
   "publisher": "beyondwork",
-  "version": "1.0.13",
+  "version": "1.0.14",
   "description": "Embeddable React Word (docx) editor with review, comments, tracked changes, and round-trip OOXML fidelity.",
-  "packageManager": "pnpm@10.30.3",
   "type": "module",
   "sideEffects": [
     "**/*.css"
@@ -46,29 +45,6 @@
     "./package.json": "./package.json"
   },
   "types": "./src/index.ts",
-  "scripts": {
-    "build": "tsup",
-    "test": "bash scripts/run-workspace-tests.sh",
-    "test:repo": "node scripts/run-repo-tests.mjs core",
-    "test:repo:all": "node scripts/run-repo-tests.mjs all",
-    "test:repo:optional": "node scripts/run-repo-tests.mjs optional",
-    "test:wcag-audit": "node scripts/run-repo-tests.mjs wcag-audit",
-    "test:harness": "pnpm --filter @docx-react-component/react-word-editor-harness test",
-    "lint": "pnpm run lint:no-authored-js && pnpm run lint:tsgo && pnpm run lint:tsgo:harness",
-    "lint:no-authored-js": "bash scripts/check-no-authored-js.sh",
-    "lint:tsgo": "tsgo --noEmit -p tsconfig.build.json",
-    "lint:tsgo:harness": "pnpm --filter @docx-react-component/react-word-editor-harness lint:tsgo",
-    "context7:api-check": "bash scripts/context7-export-env.sh run bash scripts/context7-api-check.sh",
-    "wave:doctor": "bash scripts/context7-export-env.sh run pnpm exec wave doctor --json",
-    "wave:dry-run": "bash scripts/context7-export-env.sh run pnpm exec wave launch --lane main --dry-run --no-dashboard",
-    "wave:launch": "bash scripts/context7-export-env.sh run pnpm exec wave launch --lane main",
-    "wave:launch:managed": "bash scripts/wave-launch.sh",
-    "wave:status": "bash scripts/wave-status.sh",
-    "wave:watch": "bash scripts/wave-watch.sh --follow",
-    "wave:dashboard:current": "bash scripts/wave-dashboard-attach.sh current",
-    "wave:dashboard:global": "bash scripts/wave-dashboard-attach.sh global",
-    "harness:dev": "pnpm --filter @docx-react-component/react-word-editor-harness dev"
-  },
   "keywords": [
     "docx",
     "word",
@@ -131,14 +107,27 @@
     "tsup": "^8.3.0",
     "tsx": "^4.21.0"
   },
-  "pnpm": {
-    "onlyBuiltDependencies": [
-      "esbuild",
-      "sharp"
-    ],
-    "overrides": {
-      "react": "19.2.4",
-      "react-dom": "19.2.4"
-    }
+  "scripts": {
+    "build": "tsup",
+    "test": "bash scripts/run-workspace-tests.sh",
+    "test:repo": "node scripts/run-repo-tests.mjs core",
+    "test:repo:all": "node scripts/run-repo-tests.mjs all",
+    "test:repo:optional": "node scripts/run-repo-tests.mjs optional",
+    "test:wcag-audit": "node scripts/run-repo-tests.mjs wcag-audit",
+    "test:harness": "pnpm --filter @docx-react-component/react-word-editor-harness test",
+    "lint": "pnpm run lint:no-authored-js && pnpm run lint:tsgo && pnpm run lint:tsgo:harness",
+    "lint:no-authored-js": "bash scripts/check-no-authored-js.sh",
+    "lint:tsgo": "tsgo --noEmit -p tsconfig.build.json",
+    "lint:tsgo:harness": "pnpm --filter @docx-react-component/react-word-editor-harness lint:tsgo",
+    "context7:api-check": "bash scripts/context7-export-env.sh run bash scripts/context7-api-check.sh",
+    "wave:doctor": "bash scripts/context7-export-env.sh run pnpm exec wave doctor --json",
+    "wave:dry-run": "bash scripts/context7-export-env.sh run pnpm exec wave launch --lane main --dry-run --no-dashboard",
+    "wave:launch": "bash scripts/context7-export-env.sh run pnpm exec wave launch --lane main",
+    "wave:launch:managed": "bash scripts/wave-launch.sh",
+    "wave:status": "bash scripts/wave-status.sh",
+    "wave:watch": "bash scripts/wave-watch.sh --follow",
+    "wave:dashboard:current": "bash scripts/wave-dashboard-attach.sh current",
+    "wave:dashboard:global": "bash scripts/wave-dashboard-attach.sh global",
+    "harness:dev": "pnpm --filter @docx-react-component/react-word-editor-harness dev"
   }
 }

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

@@ -76,6 +76,16 @@ export function rangeStaysWithinSingleParagraph(
     return true;
   }
 
+  const surfaceBlocks = readSurfaceBlocks(content);
+  if (surfaceBlocks) {
+    return surfaceBlocks.some(
+      (block) =>
+        block.kind === "paragraph" &&
+        normalized.from >= block.from &&
+        normalized.to <= block.to,
+    );
+  }
+
   const story = parseTextStory(content);
   const upperBound = Math.min(normalized.to, story.units.length);
 
@@ -92,3 +102,82 @@ export function rangeStaysWithinSingleParagraph(
 
   return true;
 }
+
+export function canCreateDocxCommentAnchor(
+  content: unknown,
+  anchor: ReviewAnchor,
+): boolean {
+  if (anchor.kind !== "range") {
+    return false;
+  }
+
+  const normalized = normalizeRange(anchor.range);
+  if (normalized.from === normalized.to) {
+    return false;
+  }
+
+  return rangeStaysWithinSingleParagraph(content, normalized);
+}
+
+function readSurfaceBlocks(
+  content: unknown,
+): Array<{ kind: string; from: number; to: number }> | undefined {
+  if (!content || typeof content !== "object" || !("blocks" in content)) {
+    return undefined;
+  }
+
+  const blocks = (content as { blocks?: unknown }).blocks;
+  if (!Array.isArray(blocks)) {
+    return undefined;
+  }
+
+  const normalized = flattenSurfaceBlocks(blocks);
+
+  return normalized.length > 0 ? normalized : undefined;
+}
+
+function flattenSurfaceBlocks(
+  blocks: unknown[],
+): Array<{ kind: string; from: number; to: number }> {
+  const flattened: Array<{ kind: string; from: number; to: number }> = [];
+
+  for (const block of blocks) {
+    if (
+      !block ||
+      typeof block !== "object" ||
+      typeof (block as { kind?: unknown }).kind !== "string" ||
+      typeof (block as { from?: unknown }).from !== "number" ||
+      typeof (block as { to?: unknown }).to !== "number"
+    ) {
+      continue;
+    }
+
+    flattened.push({
+      kind: (block as { kind: string }).kind,
+      from: (block as { from: number }).from,
+      to: (block as { to: number }).to,
+    });
+
+    if (
+      (block as { kind: string }).kind === "table" &&
+      Array.isArray((block as { rows?: unknown }).rows)
+    ) {
+      for (const row of (block as { rows: Array<{ cells?: unknown[] }> }).rows) {
+        for (const cell of row.cells ?? []) {
+          if (cell && typeof cell === "object" && Array.isArray((cell as { content?: unknown[] }).content)) {
+            flattened.push(...flattenSurfaceBlocks((cell as { content: unknown[] }).content));
+          }
+        }
+      }
+    }
+
+    if (
+      (block as { kind: string }).kind === "sdt_block" &&
+      Array.isArray((block as { children?: unknown[] }).children)
+    ) {
+      flattened.push(...flattenSurfaceBlocks((block as { children: unknown[] }).children));
+    }
+  }
+
+  return flattened;
+}

package/src/runtime/document-runtime.ts

@@ -41,6 +41,7 @@ import {
   createRangeAnchor,
   type EditorAnchorProjection as InternalEditorAnchorProjection,
 } from "../core/selection/mapping.ts";
+import { canCreateDocxCommentAnchor } from "../core/selection/review-anchors.ts";
 import { createCommentSidebarProjection } from "../review/store/comment-store.ts";
 import { createCommentStoreFromRuntimeComments } from "../review/store/runtime-comment-store.ts";
 import {
@@ -212,6 +213,18 @@ export function createDocumentRuntime(
       const anchor = params.anchor
         ? toInternalAnchorProjection(params.anchor)
         : state.selection.activeRange;
+      if (!canCreateDocxCommentAnchor(state.document.content, anchor)) {
+        const message =
+          "DOCX comments must use a non-empty range that stays within a single paragraph.";
+        emitError({
+          errorId: createSessionId("comment-anchor", clock()),
+          code: "validation_failed",
+          isFatal: false,
+          message,
+          source: "runtime",
+        });
+        throw new Error(message);
+      }
       const authorId = params.authorId ?? options.defaultAuthorId ?? "unknown";
       const createdAt = clock();
       const entries: CommentEntryRecord[] = [

package/src/runtime/session-capabilities.ts

@@ -1,4 +1,10 @@
 import type { RuntimeRenderSnapshot } from "../api/public-types";
+import {
+  createDetachedAnchor,
+  createNodeAnchor,
+  createRangeAnchor,
+} from "../core/selection/mapping.ts";
+import { canCreateDocxCommentAnchor } from "../core/selection/review-anchors";
 
 /**
  * Session capabilities derived from the runtime snapshot.
@@ -80,7 +86,11 @@ export function deriveCapabilities(
   const canEdit = isReady && !isReadOnly && !hasFatalError;
   const canUndo = snapshot.commandState.canUndo && canEdit;
   const canRedo = snapshot.commandState.canRedo && canEdit;
-  const canAddComment = canEdit && !snapshot.selection.isCollapsed;
+  const canAddComment =
+    canEdit &&
+    !snapshot.selection.isCollapsed &&
+    Boolean(snapshot.surface) &&
+    canCreateDocxCommentAnchor(snapshot.surface, toRuntimeAnchor(snapshot.selection.activeRange));
   const canExport = isReady && !exportBlocked && !hasFatalError;
 
   // Revision capabilities
@@ -136,3 +146,14 @@ export function deriveCapabilities(
     hasFatalError,
   };
 }
+
+function toRuntimeAnchor(anchor: RuntimeRenderSnapshot["selection"]["activeRange"]) {
+  switch (anchor.kind) {
+    case "range":
+      return createRangeAnchor(anchor.from, anchor.to, anchor.assoc);
+    case "node":
+      return createNodeAnchor(anchor.at, anchor.assoc);
+    case "detached":
+      return createDetachedAnchor(anchor.lastKnownRange, anchor.reason);
+  }
+}

package/src/ui/WordReviewEditor.tsx

@@ -958,12 +958,16 @@ export const WordReviewEditor = forwardRef<WordReviewEditorRef, WordReviewEditor
     }
 
     function addReviewComment(): void {
-      activeRuntime.addComment({
-        anchor: snapshot.selection.activeRange,
-        body: "New review comment",
-        authorId: currentUser.userId,
-      });
-      setActiveRailTab("comments");
+      try {
+        activeRuntime.addComment({
+          anchor: snapshot.selection.activeRange,
+          body: "New review comment",
+          authorId: currentUser.userId,
+        });
+        setActiveRailTab("comments");
+      } catch {
+        // Runtime already emitted a concrete export-safety error for invalid anchors.
+      }
     }
 
     function exportCurrentDocument(): void {
@@ -991,6 +995,10 @@ export const WordReviewEditor = forwardRef<WordReviewEditorRef, WordReviewEditor
       ? derivedCapabilities
       : { ...derivedCapabilities, reviewRailVisible: false };
     const diagnosticsModeMessage = getDiagnosticsModeMessage(loadError ?? snapshot.fatalError);
+    const addCommentDisabledReason =
+      !capabilities.canAddComment && !snapshot.selection.isCollapsed
+        ? "Select text within one paragraph to add a DOCX comment."
+        : undefined;
     const accessibilityInstructionsId = `${documentId}-accessibility-instructions`;
     const accessibilityStatusId = `${documentId}-accessibility-status`;
     const accessibilityAlertId = `${documentId}-accessibility-alert`;
@@ -1147,6 +1155,7 @@ export const WordReviewEditor = forwardRef<WordReviewEditorRef, WordReviewEditor
           activeRevisionId={activeRevisionId}
           showTrackedChanges={showTrackedChanges}
           selectionPreview={selectionPreview}
+          addCommentDisabledReason={addCommentDisabledReason}
           onViewModeChange={setViewMode}
           onActiveRailTabChange={setActiveRailTab}
           onShowTrackedChangesChange={setShowTrackedChanges}

package/src/ui-tailwind/chrome/tw-selection-toolbar.tsx

@@ -5,6 +5,8 @@ import { MessageSquare } from "lucide-react";
 export interface TwSelectionToolbarProps {
   selectionPreview: string;
   readOnly: boolean;
+  canAddComment?: boolean;
+  disabledReason?: string;
   onAddComment?: () => void;
 }
 
@@ -12,6 +14,10 @@ const focusRingClass =
   "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-accent focus-visible:ring-offset-2 focus-visible:ring-offset-canvas";
 
 export function TwSelectionToolbar(props: TwSelectionToolbarProps) {
+  const addCommentDisabled = props.readOnly || props.canAddComment === false;
+  const tooltipLabel = addCommentDisabled
+    ? props.disabledReason ?? "Select text within one paragraph to add a DOCX comment"
+    : "Add comment";
   return (
     <div className="mb-6 inline-flex items-center gap-1 rounded-lg bg-canvas shadow-lg ring-1 ring-border p-1">
       <Tooltip.Root>
@@ -19,7 +25,7 @@ export function TwSelectionToolbar(props: TwSelectionToolbarProps) {
           <button
             type="button"
             aria-label="Comment"
-            disabled={props.readOnly}
+            disabled={addCommentDisabled}
             onClick={props.onAddComment}
             className={`inline-flex h-7 w-7 items-center justify-center rounded-md transition-colors text-accent hover:bg-accent-soft disabled:opacity-30 disabled:cursor-not-allowed ${focusRingClass}`}
           >
@@ -31,7 +37,7 @@ export function TwSelectionToolbar(props: TwSelectionToolbarProps) {
             className="rounded-md bg-primary px-2 py-1 text-xs text-white shadow-md z-50"
             sideOffset={6}
           >
-            Add comment
+            {tooltipLabel}
           </Tooltip.Content>
         </Tooltip.Portal>
       </Tooltip.Root>

package/src/ui-tailwind/tw-review-workspace.tsx

@@ -27,6 +27,7 @@ export interface TwReviewWorkspaceProps {
   activeRevisionId?: string;
   showTrackedChanges: boolean;
   selectionPreview?: string | null;
+  addCommentDisabledReason?: string;
   onViewModeChange: (value: ViewMode) => void;
   onActiveRailTabChange: (value: ReviewRailTab) => void;
   onShowTrackedChangesChange: (show: boolean) => void;
@@ -92,6 +93,8 @@ export function TwReviewWorkspace(props: TwReviewWorkspaceProps) {
                     <TwSelectionToolbar
                       selectionPreview={props.selectionPreview}
                       readOnly={snapshot.readOnly}
+                      canAddComment={props.capabilities?.canAddComment}
+                      disabledReason={props.addCommentDisabledReason}
                       onAddComment={props.onAddComment}
                     />
                   </div>