@beyondwork/docx-react-component 1.0.21 → 1.0.22

package/README.md

@@ -135,3 +135,685 @@ Shared platform and planned xlsx docs:
 This repo is not trying to become a generic office clone.
 
 It is building fidelity-first office-document runtimes with explicit preservation and calm, reviewable UI.
+
+## Using the package
+
+### WordReviewEditor
+
+`WordReviewEditor` is a React component for loading, editing, and exporting `.docx` files with full comment and tracked-change (redline) support. It is exported from `@beyondwork/docx-react-component`.
+
+### Installation
+
+```tsx
+import {
+  WordReviewEditor,
+  type WordReviewEditorRef,
+  type WordReviewEditorProps,
+  type WordReviewEditorEvent,
+} from "@beyondwork/docx-react-component";
+```
+
+### Basic mount
+
+```tsx
+import { useRef } from "react";
+import { WordReviewEditor, type WordReviewEditorRef } from "@beyondwork/docx-react-component";
+
+export function MyEditor({ docxBytes }: { docxBytes: Uint8Array }) {
+  const editorRef = useRef<WordReviewEditorRef>(null);
+
+  return (
+    <WordReviewEditor
+      ref={editorRef}
+      documentId="doc-001"
+      currentUser={{ userId: "u1", displayName: "Alice" }}
+      initialDocx={docxBytes}
+      onEvent={(event) => console.log(event)}
+    />
+  );
+}
+```
+
+---
+
+### Props reference
+
+| Prop | Type | Description |
+|---|---|---|
+| `documentId` | `string` | **Required.** Stable identifier for this document. |
+| `currentUser` | `EditorUser` | **Required.** The user performing edits and adding comments. |
+| `initialDocx` | `Uint8Array \| ArrayBuffer` | Raw `.docx` bytes to load on first mount. |
+| `initialSessionState` | `EditorSessionState` | Previously saved session state to restore. |
+| `initialSnapshot` | `PersistedEditorSnapshot` | Previously saved snapshot to restore. |
+| `externalDocSource` | `ExternalDocumentSource` | Alternative source with explicit `kind` (`"docx"`, `"session"`, `"snapshot"`). |
+| `readOnly` | `boolean` | When `true`, all editing commands are disabled. |
+| `reviewMode` | `"editing" \| "review"` | Shell layout hint — affects toolbar/panel arrangement but not editing authority. |
+| `markupDisplay` | `"clean" \| "simple" \| "all"` | Controls tracked-change visibility. |
+| `showReviewPanel` | `boolean` | Shows or hides the right-side comment and tracked-change panel. |
+| `autosave` | `AutosaveConfig` | Enables automatic saving. |
+| `hostAdapter` | `EditorHostAdapter` | Callbacks for `load`, `saveSession`, `saveExport`. |
+| `datastore` | `EditorDatastoreAdapter` | Alternative persistence adapter with `load`, `saveSnapshot`. |
+| `onEvent` | `(event: WordReviewEditorEvent) => void` | Unified event handler (see [Events](#events)). |
+| `onWarning` | `(warning: EditorWarning) => void` | Fired for non-fatal warnings. |
+| `onError` | `(error: EditorError) => void` | Fired for fatal errors. |
+
+#### EditorUser
+
+```ts
+interface EditorUser {
+  userId: string;
+  displayName: string;
+  email?: string;
+  avatarUrl?: string;
+}
+```
+
+#### AutosaveConfig
+
+```ts
+interface AutosaveConfig {
+  enabled?: boolean;
+  debounceMs?: number; // default: 2000
+}
+```
+
+---
+
+### Show / hide UI regions
+
+#### Review panel
+
+The right-side panel lists comment threads and tracked changes.
+
+```tsx
+<WordReviewEditor showReviewPanel={false} ... />  // hide panel
+<WordReviewEditor showReviewPanel={true}  ... />  // show panel (default)
+```
+
+#### Tracked-change display mode
+
+`markupDisplay` controls how tracked changes appear in the document body.
+
+| Value | Behaviour |
+|---|---|
+| `"clean"` | Show the accepted version — insertions visible, deletions hidden. |
+| `"simple"` | Show a simplified view of changes without inline markup. |
+| `"all"` | Show all insertion and deletion marks inline (Word's "Show Markup" mode). |
+
+```tsx
+<WordReviewEditor markupDisplay="clean" ... />
+```
+
+You can also change the display mode at runtime:
+
+```ts
+// no ref method for markupDisplay — pass as a prop; React re-renders propagate the change.
+```
+
+#### Document mode
+
+`DocumentMode` controls editing authority, not just appearance.
+
+| Mode | Effect |
+|---|---|
+| `"editing"` | Edits are applied directly (no tracking). |
+| `"suggesting"` | Every edit is automatically wrapped in a tracked change. |
+| `"viewing"` | Document is read-only regardless of the `readOnly` prop. |
+
+Set via ref:
+
+```ts
+editorRef.current.setDocumentMode("suggesting");
+```
+
+Or pass `reviewMode="review"` as a prop to start in a review-friendly shell layout (the component internally maps this to `"suggesting"` document mode).
+
+#### Read-only mode
+
+```tsx
+<WordReviewEditor readOnly={true} ... />
+```
+
+All editing, commenting, and tracked-change commands are blocked. The toolbar is still rendered but all buttons are disabled.
+
+#### Workspace layout
+
+```ts
+editorRef.current.setWorkspaceMode("canvas"); // continuous scroll
+editorRef.current.setWorkspaceMode("page");   // paginated view
+```
+
+---
+
+### Imperative ref
+
+Obtain the ref via `useRef<WordReviewEditorRef>()`:
+
+```tsx
+const editorRef = useRef<WordReviewEditorRef>(null);
+<WordReviewEditor ref={editorRef} ... />
+
+// then:
+editorRef.current?.addComment({ body: "Needs revision" });
+```
+
+---
+
+### Comment operations
+
+#### Add a comment
+
+```ts
+addComment(params: AddCommentParams): string
+// returns the new commentId
+```
+
+```ts
+interface AddCommentParams {
+  anchor?: EditorAnchorProjection; // defaults to the current selection
+  body?: string;
+  authorId?: string;               // defaults to currentUser.userId
+}
+```
+
+**Important**: if you want the comment to land on a specific text selection, capture the anchor *before* opening any draft UI (e.g. a modal or popover), because opening a modal typically collapses the editor selection.
+
+```ts
+// 1. Capture anchor while text is still selected
+const snapshot = editorRef.current.getRenderSnapshot();
+const anchor = snapshot.selection.activeRange;
+
+// 2. Open your draft UI, let user type a message...
+// 3. On submit:
+const commentId = editorRef.current.addComment({ anchor, body: draftText });
+```
+
+#### Resolve a comment
+
+```ts
+editorRef.current.resolveComment(commentId);
+```
+
+Marks the thread as resolved. The comment remains in the document and can be exported; it is moved to the resolved list in the sidebar.
+
+#### Reopen a resolved comment
+
+```ts
+editorRef.current.reopenComment(commentId);
+```
+
+#### Delete a comment permanently
+
+```ts
+editorRef.current.deleteComment(commentId);
+```
+
+Removes the comment entirely. Use this to clean up failed or unwanted drafts.
+
+#### Add a reply to an existing thread
+
+```ts
+editorRef.current.addCommentReply(commentId, "Reply text here");
+```
+
+#### Edit a comment body
+
+```ts
+editorRef.current.editCommentBody(commentId, "Updated text");
+```
+
+#### Scroll to a comment
+
+```ts
+editorRef.current.scrollToComment(commentId);
+```
+
+#### Open (focus) a comment in the sidebar
+
+```ts
+editorRef.current.openComment(commentId);
+```
+
+#### Get all comments
+
+```ts
+const sidebar: CommentSidebarSnapshot = editorRef.current.getComments();
+```
+
+```ts
+interface CommentSidebarSnapshot {
+  activeCommentId?: string;
+  openCommentIds: string[];
+  resolvedCommentIds: string[];
+  detachedCommentIds: string[];
+  totalCount: number;
+  threads: CommentSidebarThreadSnapshot[];
+}
+
+interface CommentSidebarThreadSnapshot {
+  commentId: string;
+  status: "open" | "resolved" | "detached";
+  anchor: EditorAnchorProjection;
+  excerpt: string;               // the anchored text snippet
+  entries: CommentSidebarThreadEntrySnapshot[];
+  entryCount: number;
+  createdAt: string;             // ISO 8601
+  createdBy: string;             // userId
+  resolvedAt?: string;
+  resolvedBy?: string;
+}
+```
+
+#### Detached comments
+
+A comment becomes **detached** when the text it was anchored to is deleted. Detached comments:
+
+- Still appear in `sidebar.detachedCommentIds` and have `status: "detached"`.
+- Have `anchor.kind === "detached"` with a `lastKnownRange` and a `reason` (`"deleted"`, `"invalidatedByStructureChange"`, or `"importAmbiguity"`).
+- Do **not** block DOCX export.
+- Can be resolved, reopened, or deleted via the same methods above.
+
+---
+
+### Tracked-change operations
+
+#### Get all tracked changes
+
+```ts
+const changes: TrackedChangesSnapshot = editorRef.current.getTrackedChanges();
+```
+
+```ts
+interface TrackedChangesSnapshot {
+  pendingChangeIds: string[];
+  acceptedChangeIds: string[];
+  rejectedChangeIds: string[];
+  detachedChangeIds: string[];
+  actionableChangeIds: string[];
+  preserveOnlyChangeIds: string[];
+  totalCount: number;
+  revisions: TrackedChangeEntrySnapshot[];
+}
+
+interface TrackedChangeEntrySnapshot {
+  revisionId: string;
+  kind: "insertion" | "deletion" | "formatting" | "move" | "property-change";
+  status: "active" | "accepted" | "rejected" | "detached";
+  actionability: "actionable" | "preserve-only";
+  canAccept: boolean;
+  canReject: boolean;
+  anchor: EditorAnchorProjection;
+  anchorLabel: string;
+  excerpt?: string;
+  detail?: string;
+  authorId: string;
+  createdAt: string;
+}
+```
+
+`preserve-only` revisions (`formatting`, `move`) can be displayed but cannot be individually accepted or rejected through the API.
+
+#### Accept a single change
+
+```ts
+editorRef.current.acceptChange(revisionId);
+```
+
+#### Reject a single change
+
+```ts
+editorRef.current.rejectChange(revisionId);
+```
+
+#### Accept all pending changes
+
+```ts
+editorRef.current.acceptAllChanges();
+```
+
+#### Reject all pending changes
+
+```ts
+editorRef.current.rejectAllChanges();
+```
+
+#### Scroll to a tracked change
+
+```ts
+editorRef.current.scrollToRevision(revisionId);
+```
+
+---
+
+### Export
+
+```ts
+const result = await editorRef.current.exportDocx({ fileName: "output.docx" });
+// result.bytes is the Uint8Array of the .docx file
+```
+
+Export will throw if any non-detached comment no longer maps to a serializable range in the document. To diagnose, check `getComments().threads` for entries where `status !== "detached"` but whose `anchor.kind` is unexpected.
+
+---
+
+### Events
+
+All events are dispatched through the single `onEvent` prop. The `type` discriminator narrows the payload.
+
+```tsx
+<WordReviewEditor
+  onEvent={(event) => {
+    if (event.type === "comment_added") {
+      console.log("New comment:", event.commentId);
+    }
+  }}
+/>
+```
+
+#### `ready`
+
+Fired once after the document finishes loading and the editor is interactive.
+
+```ts
+{
+  type: "ready";
+  documentId: string;
+  sessionId: string;
+  source: "docx" | "session" | "snapshot";
+  stats: DocumentStats;          // storyLength, commentCount, revisionCount
+  compatibility: CompatibilityReport;
+  comments: CommentSidebarSnapshot;
+  trackedChanges: TrackedChangesSnapshot;
+}
+```
+
+#### `comment_added`
+
+Fired when a new comment thread is created (via `addComment` or the toolbar).
+
+```ts
+{
+  type: "comment_added";
+  documentId: string;
+  commentId: string;
+  anchor: EditorAnchorProjection;
+}
+```
+
+#### `comment_resolved`
+
+Fired when a comment is resolved (via `resolveComment` or the sidebar).
+
+```ts
+{
+  type: "comment_resolved";
+  documentId: string;
+  commentId: string;
+}
+```
+
+There is no separate `comment_removed` event — deletions are silent. Query `getComments()` after a `dirty_changed` event if you need to detect deletions.
+
+#### `change_accepted`
+
+Fired when a tracked change is accepted.
+
+```ts
+{
+  type: "change_accepted";
+  documentId: string;
+  changeId: string;
+}
+```
+
+#### `change_rejected`
+
+Fired when a tracked change is rejected.
+
+```ts
+{
+  type: "change_rejected";
+  documentId: string;
+  changeId: string;
+}
+```
+
+#### `selection_changed`
+
+Fired whenever the editor cursor or selection changes.
+
+```ts
+{
+  type: "selection_changed";
+  documentId: string;
+  selection: SelectionSnapshot;
+}
+
+interface SelectionSnapshot {
+  anchor: number;
+  head: number;
+  isCollapsed: boolean;
+  activeRange: EditorAnchorProjection;
+  storyTarget?: EditorStoryTarget;
+}
+```
+
+Use `selection.activeRange` as the `anchor` argument to `addComment` — but capture it *before* opening any modal UI.
+
+#### `dirty_changed`
+
+Fired when the document transitions between clean and dirty (unsaved) states.
+
+```ts
+{
+  type: "dirty_changed";
+  documentId: string;
+  isDirty: boolean;
+}
+```
+
+#### `story_changed`
+
+Fired when the user navigates between document stories (e.g. main body → header/footer).
+
+```ts
+{
+  type: "story_changed";
+  documentId: string;
+  activeStory: EditorStoryTarget;
+}
+```
+
+#### `export_completed`
+
+Fired after a successful `exportDocx` call, after the host `saveExport` callback (if any) has resolved.
+
+```ts
+{
+  type: "export_completed";
+  documentId: string;
+  result: ExportResult;   // result.bytes, result.fileName, result.mimeType
+}
+```
+
+#### `session_saved`
+
+Fired after the host `saveSession` callback resolves.
+
+```ts
+{
+  type: "session_saved";
+  documentId: string;
+  sessionState: EditorSessionState;
+  savedAt: string;
+  isAutosave: boolean;
+}
+```
+
+#### `snapshot_saved`
+
+Fired after the datastore `saveSnapshot` callback resolves.
+
+```ts
+{
+  type: "snapshot_saved";
+  documentId: string;
+  snapshot: PersistedEditorSnapshot;
+  isAutosave: boolean;
+}
+```
+
+#### `autosave_state`
+
+Fired when the autosave lifecycle transitions.
+
+```ts
+{
+  type: "autosave_state";
+  documentId: string;
+  state: "idle" | "pending" | "saving" | "saved" | "error";
+}
+```
+
+#### `warning_added` / `warning_cleared`
+
+Non-fatal import or rendering warnings.
+
+```ts
+{ type: "warning_added";   documentId: string; warning: EditorWarning; }
+{ type: "warning_cleared"; documentId: string; warningId: string; code: EditorWarningCode; }
+```
+
+#### `error`
+
+Fatal editor error. The editor may be in an unrecoverable state after this event.
+
+```ts
+{
+  type: "error";
+  documentId: string;
+  error: EditorError;    // error.code, error.message, error.isFatal
+}
+```
+
+#### Workflow events
+
+These events relate to the optional workflow overlay feature.
+
+```ts
+{ type: "workflow_overlay_changed";          documentId: string; snapshot: WorkflowScopeSnapshot; }
+{ type: "workflow_active_work_item_changed"; documentId: string; activeWorkItemId: string | null; }
+{ type: "command_blocked";                   documentId: string; command: string; reasons: WorkflowBlockedCommandReason[]; }
+```
+
+---
+
+### Key types
+
+#### EditorAnchorProjection
+
+Describes a position or range in the document. Returned by `selection.activeRange` and stored on comments/revisions.
+
+```ts
+type EditorAnchorProjection =
+  | { kind: "range";    from: number; to: number; assoc: { start: -1|1; end: -1|1 } }
+  | { kind: "node";     at: number;  assoc: -1|1 }
+  | { kind: "detached"; lastKnownRange: { from: number; to: number };
+      reason: "deleted" | "invalidatedByStructureChange" | "importAmbiguity" };
+```
+
+A `"range"` anchor is required for `addComment` if the document contains tables or the selection spans multiple characters. The `from`/`to` positions are in the editor's internal runtime coordinate space — always capture them from `getRenderSnapshot().selection.activeRange`, never construct them manually.
+
+#### DocumentMode
+
+```ts
+type DocumentMode = "editing" | "suggesting" | "viewing";
+```
+
+#### WorkspaceMode
+
+```ts
+type WorkspaceMode = "canvas" | "page";
+```
+
+---
+
+### Common patterns
+
+#### Full add-comment flow with custom UI
+
+```tsx
+function CommentButton({ editorRef }: { editorRef: React.RefObject<WordReviewEditorRef> }) {
+  const [draft, setDraft] = useState<{ anchor: EditorAnchorProjection; text: string } | null>(null);
+
+  function openDraft() {
+    // Capture anchor BEFORE the modal steals focus from the editor
+    const snapshot = editorRef.current?.getRenderSnapshot();
+    if (!snapshot) return;
+    const anchor = snapshot.selection.activeRange;
+    if (anchor.kind !== "range" || anchor.from === anchor.to) return;
+    setDraft({ anchor, text: "" });
+  }
+
+  function submit() {
+    if (!draft) return;
+    editorRef.current?.addComment({ anchor: draft.anchor, body: draft.text });
+    setDraft(null);
+  }
+
+  return (
+    <>
+      <button onClick={openDraft}>Comment</button>
+      {draft && (
+        <dialog open>
+          <textarea value={draft.text} onChange={(e) => setDraft({ ...draft, text: e.target.value })} />
+          <button onClick={submit}>Add</button>
+          <button onClick={() => setDraft(null)}>Cancel</button>
+        </dialog>
+      )}
+    </>
+  );
+}
+```
+
+#### Listen for comment and review-change events
+
+```tsx
+<WordReviewEditor
+  onEvent={(event) => {
+    switch (event.type) {
+      case "comment_added":
+        console.log("comment added:", event.commentId, event.anchor);
+        break;
+      case "comment_resolved":
+        console.log("comment resolved:", event.commentId);
+        break;
+      case "change_accepted":
+        console.log("change accepted:", event.changeId);
+        break;
+      case "change_rejected":
+        console.log("change rejected:", event.changeId);
+        break;
+    }
+  }}
+/>
+```
+
+#### Resolve all open comments programmatically
+
+```ts
+const { threads } = editorRef.current.getComments();
+for (const thread of threads) {
+  if (thread.status === "open") {
+    editorRef.current.resolveComment(thread.commentId);
+  }
+}
+```
+
+#### Accept or reject all actionable changes
+
+```ts
+editorRef.current.acceptAllChanges();
+// or
+editorRef.current.rejectAllChanges();
+```

package/package.json

@@ -1,9 +1,8 @@
 {
   "name": "@beyondwork/docx-react-component",
   "publisher": "beyondwork",
-  "version": "1.0.21",
+  "version": "1.0.22",
   "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"
@@ -89,30 +88,6 @@
     "./ui-tailwind/theme/editor-theme.css": "./src/ui-tailwind/theme/editor-theme.css"
   },
   "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:docs-contracts && pnpm run lint:tsgo && pnpm run lint:tsgo:harness",
-    "lint:docs-contracts": "bash scripts/check-reference-load-contract.sh",
-    "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",
@@ -175,14 +150,28 @@
     "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:docs-contracts && pnpm run lint:tsgo && pnpm run lint:tsgo:harness",
+    "lint:docs-contracts": "bash scripts/check-reference-load-contract.sh",
+    "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"
   }
-}
+}