@portone/docx-editor 0.5.1 → 0.6.0

package/CHANGELOG.md

@@ -1,5 +1,28 @@
 # @portone/docx-editor
 
+## 0.6.0
+
+### Minor Changes
+
+- [#131](https://github.com/portone-io/docx-editor/pull/131) [`5dd468a`](https://github.com/portone-io/docx-editor/commit/5dd468ae14d6210070ab6c8275d16e03b20cf64c) Thanks [@Deea222](https://github.com/Deea222)! - A comment now outlives the text it was written for, and a resolved one stops marking the page.
+  
+  Deleting commented text used to delete the comment and everything said under it. The thread now
+  stays. Trim the highlighted text - type over part of it, backspace through its edge - and the
+  comment follows what is left. Delete all of it and the comment comes back detached: no longer drawn
+  beside the page, since there is nothing to draw it next to, and listed under All comments marked
+  "Original content deleted". Cutting commented text leaves it behind the same way instead of dropping
+  it. Word has no detached state, so such a comment reaches the saved file as an ordinary comment
+  sitting where the deleted text was. Deleting a comment from its own Delete button still deletes it,
+  and undo and redo still take a deletion back and make it again.
+  
+  Resolving a thread now takes its highlight off the text, and reopening puts it back. Clicking a
+  resolved comment's card in All comments selects the text it was written about and scrolls it into
+  view, which `selectComment` now does for every caller.
+  
+  `documentComments` reports a new `anchored` field on every comment, `false` for one that no longer
+  marks a stretch of the document. Its existing fields are unchanged, so a panel of your own keeps
+  working and can read the new field to decide what a click on a card should do.
+
 ## 0.5.1
 
 ### Patch Changes

package/CONTRIBUTING.md

@@ -44,22 +44,28 @@ Run a specialized check when your change affects its area:
 pnpm test:package
 pnpm verify:package
 pnpm test:e2e
+pnpm bench
 ```
 
+A pull request that changes performance-sensitive code attaches its `pnpm bench` output to the description.
+
 [Testing](https://github.com/portone-io/docx-editor/blob/main/docs/testing.md) explains the scope and prerequisites of every check.
+CI runs `pnpm test:package` on every pull request in a separate job; it is not part of the local `pnpm check` command.
 
 A command added to `./commands` or `./table` needs a writer probe in `src/docx/__testing__/writerProbes.ts` with a `check` of its immediate effect, so its export is validated before another command can overwrite it, or an entry in `NOT_A_WRITER` giving the reason it reaches no writer.
 
 ## Changesets
 
-If you changed anything under `src/`, run `pnpm changeset` and commit the file it writes.
+If you changed production code under `src/`, run `pnpm changeset` and commit the file it writes.
 It becomes the CHANGELOG entry, so write it for someone reading release notes rather than the diff.
+Changes limited to tests, fixtures, scripts, or documentation do not need a changeset.
 
-The public API is the exported names and types of the four entry points - `.`, `./core`, `./commands`, and `./table` - together with the parts of the document model that [What a plugin may rely on](https://docx-editor.portone.io/docs/custom-controls#what-a-plugin-may-rely-on) calls stable.
+The public API is the exported names and types of the four entry points - `.`, `./core`, `./commands`, and `./table` - together with the parts of the document model that [What a plugin may rely on](https://docx-editor.portone.io/docs/editor-api/plugins-and-presets#what-a-plugin-may-rely-on) calls stable.
 An attr that page calls internal is not part of it, and neither is anything under `src/` that no entry point reaches.
 
 Choose `patch` unless the change adds to that surface, takes something out of it, or changes what a part of it means.
 Those are `minor` while the package is below 1.0.
+A diff to `src/schema/attrRoles.ts` is where to check this: a change to a stable document-model attr is `minor` even when the declaration reports do not change.
 A declaration added, removed, or rewritten in `etc/*.api.md` after running `pnpm api:update` is what that looks like; a line that only gains or loses an `(undocumented)` marker is not.
 Commit the regenerated report in the same commit as the changeset.
 

package/README.md

@@ -47,7 +47,7 @@ export function Editor({
 - Preserves document structures and package parts across edits, and records who wrote each comment.
 - Reads document styles, theme fonts, page layout, and CJK font information for display.
 
-See [Feature support](https://docx-editor.portone.io/docs/features) for the support matrix. Build [custom controls](https://docx-editor.portone.io/docs/custom-controls) or use [programmatic DOCX import and export](https://docx-editor.portone.io/docs/core).
+See [Feature support](https://docx-editor.portone.io/docs/features) for the support matrix. Build controls of your own with the [Editor API](https://docx-editor.portone.io/docs/editor-api) or use [programmatic DOCX import and export](https://docx-editor.portone.io/docs/core).
 
 The full [documentation](https://docx-editor.portone.io/docs) lives on the documentation site.
 

package/dist/DocxEditor.js

@@ -31,7 +31,7 @@ import { usePageLayout } from "./page/usePageLayout.js";
 import { editingProtection, protectionOf } from "./schema/protectionState.js";
 import { storyNodeOf } from "./schema/stories.js";
 import { editorClassNames } from "./styles/classNames.js";
-import { CommentsPanel } from "./ui/CommentsPanel.js";
+import { CommentsPanel, shownBesideThePage } from "./ui/CommentsPanel.js";
 import { LinkCard } from "./ui/LinkCard.js";
 import { LinkPanel } from "./ui/LinkPanel.js";
 import { NotesPanel } from "./ui/NotesPanel.js";
@@ -280,9 +280,9 @@ function DocxEditorSurface({
   const tableAnchor = live && !textAnchor ? tableMenuAnchor(live.state) : null;
   const linkAtCursor = live && !live.view.composing && !isLinkPanelOpen(live.state) ? activeLinkSpan(live.state) : null;
   const comments = live?.state === void 0 ? [] : commentProjection.read(live.state).comments;
-  const hasUnresolvedComments = comments.some((comment) => !comment.resolved);
+  const hasRailComments = comments.some(shownBesideThePage);
   const composerOpen = live !== null && isCommentComposerOpen(live.state);
-  const showComments = live !== null && (commentsOpen || composerOpen || hasUnresolvedComments);
+  const showComments = live !== null && (commentsOpen || composerOpen || hasRailComments);
   const commentsPanel = live && showComments && /* @__PURE__ */ jsx(
     CommentsPanel,
     {

package/dist/editor/commands/comments/editing.d.ts

@@ -41,5 +41,8 @@ export declare function removeCommentReply(commentId: string, replyId: string):
  * document without standing for anything.
  */
 export declare function removeComment(id: string): Command;
-/** Selects the text anchored by a comment, or places the caret at a point comment. */
+/**
+ * Selects the text a comment is anchored to and scrolls it into view. A comment marking no stretch
+ * - one written at a point, or one whose text was deleted - takes the caret to where it stands.
+ */
 export declare function selectComment(id: string): Command;

package/dist/editor/commands/comments/editing.js

@@ -342,9 +342,7 @@ function selectComment(id) {
     const comment = commentById(state, id);
     if (!comment) return false;
     dispatch?.(
-      state.tr.setSelection(
-        TextSelection.create(state.doc, comment.from, comment.to)
-      )
+      state.tr.setSelection(TextSelection.create(state.doc, comment.from, comment.to)).scrollIntoView()
     );
     return true;
   };

package/dist/editor/commands/comments/model.d.ts

@@ -42,6 +42,13 @@ export interface DocumentComment {
     readonly from: number;
     readonly to: number;
     readonly referencePos: number;
+    /**
+     * Whether the comment still marks a stretch of the document: both range markers stand, and the
+     * opening one stands before the closing one. A comment that lost both markers with the text an
+     * edit deleted is detached - `from` and `to` are then both where its reference stands - and is
+     * drawn nowhere on the page.
+     */
+    readonly anchored: boolean;
     readonly resolved: boolean;
     readonly replies: readonly DocumentCommentReply[];
 }

package/dist/editor/createEditor.js

@@ -26,6 +26,7 @@ import { imageFiles } from "./imageFiles.js";
 import { columnResize } from "./plugins/columnResize.js";
 import { commentComposer } from "./plugins/commentComposer.js";
 import { commentDecorations } from "./plugins/commentDecorations.js";
+import { commentRestoration } from "./plugins/commentRestoration.js";
 import {
   displayDerivation,
   withDerivedDisplay
@@ -96,6 +97,9 @@ function createEditorState(doc, options = {}) {
       // The list beside the page, the lookup the comment commands ask, and these ranges are the
       // one walk this plugin holds (`plugins/commentDecorations`)
       commentDecorations(),
+      // A comment outlives the text it was written for: an edit that sweeps its reference away has
+      // it put back where the deletion left, detached from the page (`plugins/commentRestoration`)
+      commentRestoration(),
       // What the notes under the page are, worked out from the document the same way
       noteProjection.plugin,
       // Adjacent text tabs still need separate DOM ranges for layout and pointer selection.

package/dist/editor/plugins/commentDecorations.js

@@ -34,7 +34,7 @@ function commentsIn(doc) {
     const id = stringAttr(node.attrs.id) ?? "";
     const start = markers.starts.get(id);
     const end = markers.ends.get(id);
-    const hasRange = start !== void 0 && end !== void 0 && start < end;
+    const anchored = start !== void 0 && end !== void 0 && start < end;
     const point = start ?? end ?? pos;
     return {
       id,
@@ -43,9 +43,10 @@ function commentsIn(doc) {
       initials: stringAttr(node.attrs.initials),
       date: stringAttr(node.attrs.date),
       text: bodyText(doc, id),
-      from: hasRange ? start + 1 : point,
-      to: hasRange ? end : point,
+      from: anchored ? start + 1 : point,
+      to: anchored ? end : point,
       referencePos: pos,
+      anchored,
       resolved: node.attrs.resolved === true,
       replies: repliesAttr(node.attrs.replies).map((reply) => ({
         id: reply.id,
@@ -69,7 +70,7 @@ function deriveComments(doc) {
     byId,
     decorations: DecorationSet.create(
       doc,
-      comments.filter((comment) => comment.from < comment.to).map(
+      comments.filter((comment) => !comment.resolved && comment.from < comment.to).map(
         (comment) => Decoration.inline(comment.from, comment.to, {
           class: editorClassNames.commentRange,
           "data-comment-id": comment.id

package/dist/editor/plugins/commentRestoration.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Keeps a comment when the text it was written for goes away.
+ *
+ * Deleting commented text is an edit of the body, not a decision about the thread, so a body edit
+ * that takes a comment's nodes away has them put back at the spots the edit left: the thread stays
+ * anchored where one range marker survived, detached where both went (`DocumentComment.anchored`).
+ *
+ * The comment's story (`docx/story`) tells such an edit from `removeComment`: a body deletion does
+ * not reach the story, so a comment is put back while its story stands, which only `removeComment`
+ * takes away. The cost is that a reference the comments part held no body for is never put back.
+ *
+ * A restoration is an ordinary transaction the guards judge (`editor/plugins/lockedContent`): the
+ * nodes take the nearest spot left open, and a document leaving none loses the comment. A range
+ * marker with no home takes its surviving counterpart down, so no export carries half a range.
+ *
+ * A restoration needs no deferral around an open IME composition: the nodes go in beside the
+ * composed text rather than rewriting it (`e2e/hangulComposition.spec.ts`).
+ */
+import { Plugin } from "prosemirror-state";
+export declare function commentRestoration(): Plugin;

package/dist/editor/plugins/commentRestoration.js

@@ -0,0 +1,168 @@
+// src/editor/plugins/commentRestoration.ts
+import {
+  Plugin,
+  TextSelection
+} from "prosemirror-state";
+import { storyKey, storyOf } from "../../docx/story.js";
+import { docxSchema } from "../../schema/index.js";
+import { editShut, transactionTouchesComments } from "../../schema/guards.js";
+import { stringAttr } from "../commands/comments/model.js";
+var NODE_FIELD = {
+  commentStart: "start",
+  commentEnd: "end",
+  commentReference: "reference"
+};
+var NODE_FIELDS = ["start", "end", "reference"];
+var MAPPING_SIDE = {
+  start: 1,
+  end: -1,
+  reference: -1
+};
+var NO_NODES = { start: null, end: null, reference: null };
+function commentNodesIn(doc) {
+  const found = /* @__PURE__ */ new Map();
+  doc.descendants((node, pos) => {
+    const field = NODE_FIELD[node.type.name];
+    if (field === void 0) return true;
+    const id = stringAttr(node.attrs.id);
+    if (id === null) return true;
+    const nodes = found.get(id) ?? { ...NO_NODES };
+    found.set(id, nodes);
+    if (nodes[field] === null) nodes[field] = { node, pos };
+    return true;
+  });
+  return found;
+}
+function inlineRanges(doc) {
+  const type = docxSchema.nodes.commentReference;
+  const ranges = [];
+  doc.descendants((node, pos) => {
+    if (!node.isTextblock) return true;
+    if (node.type.contentMatch.matchType(type) !== null) {
+      ranges.push({ from: pos + 1, to: pos + 1 + node.content.size });
+    }
+    return false;
+  });
+  return ranges;
+}
+function within(ranges, pos) {
+  return ranges.some((range) => pos >= range.from && pos <= range.to);
+}
+function* homes(ranges, wanted, caret) {
+  if (within(ranges, wanted)) yield wanted;
+  if (caret !== wanted && within(ranges, caret)) yield caret;
+  for (let index = ranges.length - 1; index >= 0; index -= 1) {
+    const range = ranges[index];
+    if (range !== void 0 && range.to < wanted) yield range.to;
+  }
+  for (const range of ranges) {
+    if (range.from > wanted) yield range.from;
+  }
+}
+function allowedHome(state, ranges, wanted, caret) {
+  for (const at of homes(ranges, wanted, caret)) {
+    if (!editShut(state, { kind: "insert", at })) return at;
+  }
+  return null;
+}
+function mappedThrough(transactions, pos, side) {
+  return transactions.reduce((at, tr) => tr.mapping.map(at, side), pos);
+}
+function restorable(node) {
+  return node.type.create(
+    node.attrs,
+    null,
+    node.marks.filter((mark) => mark.type === docxSchema.marks.run)
+  );
+}
+function planRestoration(transactions, oldState, newState) {
+  const before = commentNodesIn(oldState.doc);
+  const after = commentNodesIn(newState.doc);
+  const ranges = inlineRanges(newState.doc);
+  const caret = newState.selection.from;
+  const plan = { insertions: [], removals: [] };
+  for (const [id, was] of before) {
+    if (storyOf(newState.doc, storyKey("comment", id)) === null) continue;
+    const now = after.get(id) ?? NO_NODES;
+    for (const field of NODE_FIELDS) {
+      const lost = was[field];
+      if (lost === null || now[field] !== null) continue;
+      const counterpart = field === "start" ? now.end : field === "end" ? now.start : null;
+      if (field !== "reference" && counterpart === null) continue;
+      const at = allowedHome(
+        newState,
+        ranges,
+        mappedThrough(transactions, lost.pos, MAPPING_SIDE[field]),
+        caret
+      );
+      if (at !== null) {
+        plan.insertions.push({
+          node: restorable(lost.node),
+          at,
+          was: lost.pos
+        });
+      } else if (counterpart !== null && !markerShut(newState, counterpart)) {
+        plan.removals.push(counterpart);
+      }
+    }
+  }
+  return plan;
+}
+function markerShut(state, marker) {
+  return editShut(state, {
+    kind: "replace",
+    from: marker.pos,
+    to: marker.pos + marker.node.nodeSize
+  });
+}
+function pastCommentNodes(doc, pos, direction) {
+  let at = pos;
+  for (; ; ) {
+    const resolved = doc.resolve(at);
+    const next = direction < 0 ? resolved.nodeBefore : resolved.nodeAfter;
+    if (next === null || NODE_FIELD[next.type.name] === void 0) return at;
+    at += direction * next.nodeSize;
+  }
+}
+function withCaretPastMarkers(tr, oldState, newState) {
+  const { selection } = newState;
+  if (!(selection instanceof TextSelection) || !selection.empty) return tr;
+  if (!tr.doc.eq(oldState.doc)) return tr;
+  const direction = selection.from < oldState.selection.from ? -1 : 1;
+  return tr.setSelection(
+    TextSelection.create(
+      tr.doc,
+      pastCommentNodes(tr.doc, tr.selection.from, direction)
+    )
+  );
+}
+function restoration(transactions, oldState, newState) {
+  const plan = planRestoration(transactions, oldState, newState);
+  if (plan.insertions.length === 0 && plan.removals.length === 0) return null;
+  const tr = newState.tr;
+  for (const marker of [...plan.removals].sort(
+    (left, right) => right.pos - left.pos
+  )) {
+    tr.delete(marker.pos, marker.pos + marker.node.nodeSize);
+  }
+  const ordered = [...plan.insertions].sort(
+    (left, right) => left.at - right.at || left.was - right.was
+  );
+  for (const { node, at } of ordered) {
+    tr.insert(tr.mapping.map(at), node);
+  }
+  if (!tr.docChanged) return null;
+  return withCaretPastMarkers(tr, oldState, newState);
+}
+function commentRestoration() {
+  return new Plugin({
+    appendTransaction(transactions, oldState, newState) {
+      if (!transactions.some((tr) => tr.docChanged)) return null;
+      if (!transactions.some(transactionTouchesComments)) return null;
+      return restoration(transactions, oldState, newState);
+    }
+  });
+}
+export {
+  commentRestoration
+};

package/dist/styles/classNames.d.ts

@@ -140,6 +140,8 @@ export declare const editorClassNames: {
     readonly commentMeta: "docx-editor-comment-meta";
     readonly commentAuthor: "docx-editor-comment-author";
     readonly commentDate: "docx-editor-comment-date";
+    /** The note on a card whose comment lost the text it was written for */
+    readonly commentDetached: "docx-editor-comment-detached";
     readonly commentBody: "docx-editor-comment-body";
     readonly commentActions: "docx-editor-comment-actions";
     readonly commentPrimaryAction: "docx-editor-comment-primary-action";

package/dist/styles/classNames.js

@@ -136,6 +136,8 @@ var editorClassNames = {
   commentMeta: `${PREFIX}-comment-meta`,
   commentAuthor: `${PREFIX}-comment-author`,
   commentDate: `${PREFIX}-comment-date`,
+  /** The note on a card whose comment lost the text it was written for */
+  commentDetached: `${PREFIX}-comment-detached`,
   commentBody: `${PREFIX}-comment-body`,
   commentActions: `${PREFIX}-comment-actions`,
   commentPrimaryAction: `${PREFIX}-comment-primary-action`,

package/dist/styles.css

@@ -270,12 +270,15 @@
   margin-top: 2px;
 }
 
-button.docx-editor-comment-meta {
-  cursor: pointer;
+.docx-editor-comment-detached {
+  display: block;
+  margin-top: 2px;
+  color: #8a8a8a;
+  font-style: italic;
 }
 
-button.docx-editor-comment-meta:disabled {
-  cursor: default;
+button.docx-editor-comment-meta {
+  cursor: pointer;
 }
 
 .docx-editor-comment-body {

package/dist/ui/CommentsPanel.d.ts

@@ -1,7 +1,12 @@
 import type { EditorState } from "prosemirror-state";
 import type { EditorView } from "prosemirror-view";
 import { type ReactElement } from "react";
-import { type CommentAuthor } from "../editor/commands/commentCommands";
+import { type CommentAuthor, type DocumentComment } from "../editor/commands/commentCommands";
+/**
+ * Whether the rail beside the page carries this comment: the thread is unsettled, and the text it
+ * was written for is still there to draw it next to.
+ */
+export declare function shownBesideThePage(comment: DocumentComment): boolean;
 export interface CommentsPanelProps {
     view: EditorView;
     state: EditorState;

package/dist/ui/CommentsPanel.js

@@ -43,6 +43,19 @@ function run(view, command) {
 }
 var REFUSED_COMMENT = "This comment could not be added. The text it was written for may have been changed or locked since.";
 var REFUSED_REPLY = "This reply could not be added. The comment it answers may have been changed or deleted since.";
+var DETACHED_LABEL = "Original content deleted";
+function shownBesideThePage(comment) {
+  return !comment.resolved && comment.anchored;
+}
+function CommentIdentity({
+  comment
+}) {
+  const date = shownDate(comment.date);
+  return /* @__PURE__ */ jsxs(Fragment, { children: [
+    /* @__PURE__ */ jsx("span", { className: editorClassNames.commentAuthor, children: comment.author ?? "Unknown author" }),
+    date && /* @__PURE__ */ jsx("span", { className: editorClassNames.commentDate, children: date })
+  ] });
+}
 function sameTarget(left, right) {
   return left?.commentId === right.commentId && left.replyId === right.replyId;
 }
@@ -74,7 +87,7 @@ function CommentsPanel({
       if (Number.isNaN(leftTime)) return 1;
       if (Number.isNaN(rightTime)) return -1;
       return rightTime - leftTime;
-    }) : comments.filter((comment) => !comment.resolved),
+    }) : comments.filter(shownBesideThePage),
     [allCommentsOpen, comments]
   );
   const { positions, canvasHeight } = useCommentRailLayout({
@@ -158,22 +171,26 @@ function CommentsPanel({
                   {
                     className: editorClassNames.commentPosition,
                     "data-resolved": comment.resolved ? "true" : void 0,
+                    "data-detached": comment.anchored ? void 0 : "true",
                     "data-comment-position": comment.id,
                     style: allCommentsOpen ? void 0 : { top: `${positions.get(comment.id) ?? 64}px` },
                     children: /* @__PURE__ */ jsxs("div", { className: editorClassNames.commentCard, children: [
                       /* @__PURE__ */ jsxs("div", { className: editorClassNames.commentHeader, children: [
-                        /* @__PURE__ */ jsxs(
+                        comment.anchored ? /* @__PURE__ */ jsx(
                           "button",
                           {
                             type: "button",
                             className: editorClassNames.commentMeta,
                             onClick: () => run(view, selectComment(comment.id)),
-                            disabled: comment.resolved,
-                            children: [
-                              /* @__PURE__ */ jsx("span", { className: editorClassNames.commentAuthor, children: comment.author ?? "Unknown author" }),
-                              shownDate(comment.date) && /* @__PURE__ */ jsx("span", { className: editorClassNames.commentDate, children: shownDate(comment.date) })
-                            ]
+                            children: /* @__PURE__ */ jsx(CommentIdentity, { comment })
                           }
+                        ) : (
+                          // Nothing on the page to go to, so the identity is text rather than a button:
+                          // a click here leaves the caret and the scroll where the reader left them
+                          /* @__PURE__ */ jsxs("div", { className: editorClassNames.commentMeta, children: [
+                            /* @__PURE__ */ jsx(CommentIdentity, { comment }),
+                            /* @__PURE__ */ jsx("span", { className: editorClassNames.commentDetached, children: DETACHED_LABEL })
+                          ] })
                         ),
                         writer !== null && !rootEditing && /* @__PURE__ */ jsxs("div", { className: editorClassNames.commentIconActions, children: [
                           rootOwned && !comment.resolved && /* @__PURE__ */ jsx(
@@ -361,5 +378,6 @@ function CommentsPanel({
   );
 }
 export {
-  CommentsPanel
+  CommentsPanel,
+  shownBesideThePage
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@portone/docx-editor",
-  "version": "0.5.1",
+  "version": "0.6.0",
   "description": "A simple DOCX editor for React, built directly on OOXML.",
   "license": "Apache-2.0",
   "type": "module",
@@ -107,6 +107,7 @@
     "build:demo": "vite build --config demo/vite.config.ts",
     "dev:site": "pnpm --filter @portone/docx-editor-site dev",
     "build:site": "pnpm --filter @portone/docx-editor-site build",
+    "bench": "vitest run --config vitest.bench.config.ts --disableConsoleIntercept",
     "check": "pnpm lint && pnpm typecheck && pnpm test && pnpm test:fixtures && pnpm test:site-release && pnpm test:release && pnpm check:demo-library",
     "typecheck": "tsc --noEmit && tsc --noEmit -p e2e && tsc --noEmit -p demo && pnpm --filter @portone/docx-editor-site typecheck",
     "lint": "pnpm biome check . --diagnostic-level=error",