@ai-matrx/office 0.8.21 → 0.8.23

package/dist/docs.d.cts

@@ -785,4 +785,55 @@ declare function documentBodyWriteHandler(deps: {
     assertWritable: (whatItBlocks: string) => void;
 }): DocumentBodyWriteHandler;
 
-export { type BodyEdit, type BodyText, CARET_HEARTBEAT_MS, CARET_MAX_RANGES, CARET_STALE_MS, type CaretRange, type CreateDocumentArgs, DOCUMENT_BODY_MAX_LENGTH, DOCUMENT_DESCRIPTION_MAX_LENGTH, DOCUMENT_NAME_MAX_LENGTH, DOCUMENT_SAVE_DELAY_MS, type DocsHostPorts, type DocsSupabase, type DocumentAwareness, type DocumentBodyPort, type DocumentBodyWriteHandler, type DocumentCollabBase, type DocumentCollabFactory, type DocumentCollabHandle, DocumentModel, type DocumentModelDeps, type DocumentOtFactory, type DocumentOtHandle, type DocumentSnapshotData, type DocumentViewPort, EMOJI_GROUPS, type Glyph, MIN_FIT_ZOOM, type ParkedDocumentEditor, type PublishedCaret, type RemoteCaret, RemoteCaretBook, SPECIAL_GROUPS, type SaveDocumentSnapshotArgs, bodyTextOf, configureDocsHost, copyDocument, createDocument, deleteDocument, discardFailedDocument, documentBodyWriteHandler, documentSourceLabel, fitZoomRatio, getDocsHost, getDocument, getLatestDocumentSnapshot, listAccessibleDocuments, listDocumentSnapshots, listTrashedDocuments, moveDocument, movePeerRangesThroughBodyEdit, moveRangesThroughBodyEdit, planBodyEdit, publishedCaretFromSelection, renameDocument, restoreDocument, sanitizeUniverDocSnapshot, saveDocumentSnapshot, searchSymbols, updateDocumentDescription, validateDocumentBody, validateDocumentDescription, validateDocumentName, writeBodyText };
+/**
+ * Comment anchors in a document (COLLAB-DESIGN §8, unit C9).
+ *
+ * A comment points at its passage through a CUSTOM RANGE in the document body (`rangeType` COMMENT, `rangeId` =
+ * the anchor id). The range is part of the document, so it travels in the same `rich-text-editing` ops as the
+ * text and moves through every concurrent edit with our transform (C0: custom ranges pass against every family;
+ * Univer's own comment DECORATIONS do not, and are never used). The thread itself (messages, author, resolved)
+ * lives in the platform's one comment store, `platform.comments`, as a `part_anchor` whose `part_key` is
+ * `anchor:<id>` and whose `label` is the quoted text when the comment was made.
+ *
+ * A thread whose anchor no longer appears in the body had all of its text removed: it is ORPHANED and shown as
+ * "text removed", never dropped.
+ */
+
+/** The custom-range type our anchors use. Univer draws no style for it; the highlight is ours. */
+declare const COMMENT_ANCHOR_RANGE_TYPE = CustomRangeType.COMMENT;
+/** `part_anchor.part_key` prefix of a comment anchored inside a Doc or a Sheet. */
+declare const COMMENT_ANCHOR_PART_PREFIX = "anchor:";
+/** The quoted text kept on the thread (the `part_anchor.label` limit). */
+declare const COMMENT_ANCHOR_LABEL_MAX = 200;
+/** A fresh anchor id: 16 random base-36 characters (custom-range ids are plain strings). */
+declare function newCommentAnchorId(): string;
+declare function commentAnchorPartKey(anchorId: string): string;
+/** The anchor id a `part_anchor` names, or null when it is not one of ours. */
+declare function anchorIdOfPartAnchor(anchor: unknown): string | null;
+/** The `part_anchor` a new thread on this anchor carries. */
+declare function commentPartAnchor(anchorId: string, quote: string): {
+    __kind: "part_anchor";
+    part_key: string;
+    label?: string;
+};
+/** Where one anchor sits in the body now: `[start, end)` in body offsets, and the text it covers. */
+interface CommentAnchorSpan {
+    id: string;
+    start: number;
+    end: number;
+    text: string;
+}
+/**
+ * Every comment anchor in a body, by id. A range Univer split into pieces (text inserted inside it, a paragraph
+ * break) is one anchor from its first piece's start to its last piece's end. Univer's `endIndex` is inclusive.
+ */
+declare function commentAnchorsOf(body: unknown): Map<string, CommentAnchorSpan>;
+/** The `rich-text-editing` actions that anchor `[start, end)` of the body to `anchorId` (null when it cannot). */
+declare function addCommentAnchorActions(body: unknown, start: number, end: number, anchorId: string): unknown[] | null;
+/**
+ * The `rich-text-editing` actions that take one anchor out of the body (a draft the person cancelled), keeping
+ * its text. Null when the anchor is not there.
+ */
+declare function removeCommentAnchorActions(documentDataModel: unknown, anchorId: string): unknown[] | null;
+
+export { type BodyEdit, type BodyText, CARET_HEARTBEAT_MS, CARET_MAX_RANGES, CARET_STALE_MS, COMMENT_ANCHOR_LABEL_MAX, COMMENT_ANCHOR_PART_PREFIX, COMMENT_ANCHOR_RANGE_TYPE, type CaretRange, type CommentAnchorSpan, type CreateDocumentArgs, DOCUMENT_BODY_MAX_LENGTH, DOCUMENT_DESCRIPTION_MAX_LENGTH, DOCUMENT_NAME_MAX_LENGTH, DOCUMENT_SAVE_DELAY_MS, type DocsHostPorts, type DocsSupabase, type DocumentAwareness, type DocumentBodyPort, type DocumentBodyWriteHandler, type DocumentCollabBase, type DocumentCollabFactory, type DocumentCollabHandle, DocumentModel, type DocumentModelDeps, type DocumentOtFactory, type DocumentOtHandle, type DocumentSnapshotData, type DocumentViewPort, EMOJI_GROUPS, type Glyph, MIN_FIT_ZOOM, type ParkedDocumentEditor, type PublishedCaret, type RemoteCaret, RemoteCaretBook, SPECIAL_GROUPS, type SaveDocumentSnapshotArgs, addCommentAnchorActions, anchorIdOfPartAnchor, bodyTextOf, commentAnchorPartKey, commentAnchorsOf, commentPartAnchor, configureDocsHost, copyDocument, createDocument, deleteDocument, discardFailedDocument, documentBodyWriteHandler, documentSourceLabel, fitZoomRatio, getDocsHost, getDocument, getLatestDocumentSnapshot, listAccessibleDocuments, listDocumentSnapshots, listTrashedDocuments, moveDocument, movePeerRangesThroughBodyEdit, moveRangesThroughBodyEdit, newCommentAnchorId, planBodyEdit, publishedCaretFromSelection, removeCommentAnchorActions, renameDocument, restoreDocument, sanitizeUniverDocSnapshot, saveDocumentSnapshot, searchSymbols, updateDocumentDescription, validateDocumentBody, validateDocumentDescription, validateDocumentName, writeBodyText };

package/dist/docs.d.ts

@@ -785,4 +785,55 @@ declare function documentBodyWriteHandler(deps: {
     assertWritable: (whatItBlocks: string) => void;
 }): DocumentBodyWriteHandler;
 
-export { type BodyEdit, type BodyText, CARET_HEARTBEAT_MS, CARET_MAX_RANGES, CARET_STALE_MS, type CaretRange, type CreateDocumentArgs, DOCUMENT_BODY_MAX_LENGTH, DOCUMENT_DESCRIPTION_MAX_LENGTH, DOCUMENT_NAME_MAX_LENGTH, DOCUMENT_SAVE_DELAY_MS, type DocsHostPorts, type DocsSupabase, type DocumentAwareness, type DocumentBodyPort, type DocumentBodyWriteHandler, type DocumentCollabBase, type DocumentCollabFactory, type DocumentCollabHandle, DocumentModel, type DocumentModelDeps, type DocumentOtFactory, type DocumentOtHandle, type DocumentSnapshotData, type DocumentViewPort, EMOJI_GROUPS, type Glyph, MIN_FIT_ZOOM, type ParkedDocumentEditor, type PublishedCaret, type RemoteCaret, RemoteCaretBook, SPECIAL_GROUPS, type SaveDocumentSnapshotArgs, bodyTextOf, configureDocsHost, copyDocument, createDocument, deleteDocument, discardFailedDocument, documentBodyWriteHandler, documentSourceLabel, fitZoomRatio, getDocsHost, getDocument, getLatestDocumentSnapshot, listAccessibleDocuments, listDocumentSnapshots, listTrashedDocuments, moveDocument, movePeerRangesThroughBodyEdit, moveRangesThroughBodyEdit, planBodyEdit, publishedCaretFromSelection, renameDocument, restoreDocument, sanitizeUniverDocSnapshot, saveDocumentSnapshot, searchSymbols, updateDocumentDescription, validateDocumentBody, validateDocumentDescription, validateDocumentName, writeBodyText };
+/**
+ * Comment anchors in a document (COLLAB-DESIGN §8, unit C9).
+ *
+ * A comment points at its passage through a CUSTOM RANGE in the document body (`rangeType` COMMENT, `rangeId` =
+ * the anchor id). The range is part of the document, so it travels in the same `rich-text-editing` ops as the
+ * text and moves through every concurrent edit with our transform (C0: custom ranges pass against every family;
+ * Univer's own comment DECORATIONS do not, and are never used). The thread itself (messages, author, resolved)
+ * lives in the platform's one comment store, `platform.comments`, as a `part_anchor` whose `part_key` is
+ * `anchor:<id>` and whose `label` is the quoted text when the comment was made.
+ *
+ * A thread whose anchor no longer appears in the body had all of its text removed: it is ORPHANED and shown as
+ * "text removed", never dropped.
+ */
+
+/** The custom-range type our anchors use. Univer draws no style for it; the highlight is ours. */
+declare const COMMENT_ANCHOR_RANGE_TYPE = CustomRangeType.COMMENT;
+/** `part_anchor.part_key` prefix of a comment anchored inside a Doc or a Sheet. */
+declare const COMMENT_ANCHOR_PART_PREFIX = "anchor:";
+/** The quoted text kept on the thread (the `part_anchor.label` limit). */
+declare const COMMENT_ANCHOR_LABEL_MAX = 200;
+/** A fresh anchor id: 16 random base-36 characters (custom-range ids are plain strings). */
+declare function newCommentAnchorId(): string;
+declare function commentAnchorPartKey(anchorId: string): string;
+/** The anchor id a `part_anchor` names, or null when it is not one of ours. */
+declare function anchorIdOfPartAnchor(anchor: unknown): string | null;
+/** The `part_anchor` a new thread on this anchor carries. */
+declare function commentPartAnchor(anchorId: string, quote: string): {
+    __kind: "part_anchor";
+    part_key: string;
+    label?: string;
+};
+/** Where one anchor sits in the body now: `[start, end)` in body offsets, and the text it covers. */
+interface CommentAnchorSpan {
+    id: string;
+    start: number;
+    end: number;
+    text: string;
+}
+/**
+ * Every comment anchor in a body, by id. A range Univer split into pieces (text inserted inside it, a paragraph
+ * break) is one anchor from its first piece's start to its last piece's end. Univer's `endIndex` is inclusive.
+ */
+declare function commentAnchorsOf(body: unknown): Map<string, CommentAnchorSpan>;
+/** The `rich-text-editing` actions that anchor `[start, end)` of the body to `anchorId` (null when it cannot). */
+declare function addCommentAnchorActions(body: unknown, start: number, end: number, anchorId: string): unknown[] | null;
+/**
+ * The `rich-text-editing` actions that take one anchor out of the body (a draft the person cancelled), keeping
+ * its text. Null when the anchor is not there.
+ */
+declare function removeCommentAnchorActions(documentDataModel: unknown, anchorId: string): unknown[] | null;
+
+export { type BodyEdit, type BodyText, CARET_HEARTBEAT_MS, CARET_MAX_RANGES, CARET_STALE_MS, COMMENT_ANCHOR_LABEL_MAX, COMMENT_ANCHOR_PART_PREFIX, COMMENT_ANCHOR_RANGE_TYPE, type CaretRange, type CommentAnchorSpan, type CreateDocumentArgs, DOCUMENT_BODY_MAX_LENGTH, DOCUMENT_DESCRIPTION_MAX_LENGTH, DOCUMENT_NAME_MAX_LENGTH, DOCUMENT_SAVE_DELAY_MS, type DocsHostPorts, type DocsSupabase, type DocumentAwareness, type DocumentBodyPort, type DocumentBodyWriteHandler, type DocumentCollabBase, type DocumentCollabFactory, type DocumentCollabHandle, DocumentModel, type DocumentModelDeps, type DocumentOtFactory, type DocumentOtHandle, type DocumentSnapshotData, type DocumentViewPort, EMOJI_GROUPS, type Glyph, MIN_FIT_ZOOM, type ParkedDocumentEditor, type PublishedCaret, type RemoteCaret, RemoteCaretBook, SPECIAL_GROUPS, type SaveDocumentSnapshotArgs, addCommentAnchorActions, anchorIdOfPartAnchor, bodyTextOf, commentAnchorPartKey, commentAnchorsOf, commentPartAnchor, configureDocsHost, copyDocument, createDocument, deleteDocument, discardFailedDocument, documentBodyWriteHandler, documentSourceLabel, fitZoomRatio, getDocsHost, getDocument, getLatestDocumentSnapshot, listAccessibleDocuments, listDocumentSnapshots, listTrashedDocuments, moveDocument, movePeerRangesThroughBodyEdit, moveRangesThroughBodyEdit, newCommentAnchorId, planBodyEdit, publishedCaretFromSelection, removeCommentAnchorActions, renameDocument, restoreDocument, sanitizeUniverDocSnapshot, saveDocumentSnapshot, searchSymbols, updateDocumentDescription, validateDocumentBody, validateDocumentDescription, validateDocumentName, writeBodyText };

package/dist/docs.js

@@ -959,10 +959,76 @@ var RemoteCaretBook = class {
     return out;
   }
 };
+
+// src/docs/comment-anchors.ts
+import { BuildTextUtils, CustomRangeType, JSONX } from "@univerjs/core";
+var COMMENT_ANCHOR_RANGE_TYPE = CustomRangeType.COMMENT;
+var COMMENT_ANCHOR_PART_PREFIX = "anchor:";
+var COMMENT_ANCHOR_LABEL_MAX = 200;
+var ID_ALPHABET = "abcdefghijklmnopqrstuvwxyz0123456789";
+function newCommentAnchorId() {
+  const bytes = new Uint8Array(16);
+  globalThis.crypto.getRandomValues(bytes);
+  let out = "c";
+  for (const b of bytes) out += ID_ALPHABET[b % ID_ALPHABET.length];
+  return out;
+}
+function commentAnchorPartKey(anchorId) {
+  return `${COMMENT_ANCHOR_PART_PREFIX}${anchorId}`;
+}
+function anchorIdOfPartAnchor(anchor) {
+  if (!anchor || typeof anchor !== "object") return null;
+  const a = anchor;
+  if (a.__kind !== "part_anchor" || typeof a.part_key !== "string") return null;
+  if (!a.part_key.startsWith(COMMENT_ANCHOR_PART_PREFIX)) return null;
+  const id = a.part_key.slice(COMMENT_ANCHOR_PART_PREFIX.length);
+  return id.length > 0 ? id : null;
+}
+function commentPartAnchor(anchorId, quote) {
+  const label = quote.replace(/\s+/g, " ").trim().slice(0, COMMENT_ANCHOR_LABEL_MAX);
+  return { __kind: "part_anchor", part_key: commentAnchorPartKey(anchorId), ...label ? { label } : {} };
+}
+var CONTROL = /[\u0000-\u001f\u007f]/g;
+function commentAnchorsOf(body) {
+  const out = /* @__PURE__ */ new Map();
+  const b = body ?? {};
+  const stream = typeof b.dataStream === "string" ? b.dataStream : "";
+  for (const r of b.customRanges ?? []) {
+    if (!r || r.rangeType !== COMMENT_ANCHOR_RANGE_TYPE || typeof r.rangeId !== "string") continue;
+    const start = r.startIndex;
+    const end = r.endIndex + 1;
+    if (!(end > start)) continue;
+    const had = out.get(r.rangeId);
+    const s2 = had ? Math.min(had.start, start) : start;
+    const e2 = had ? Math.max(had.end, end) : end;
+    out.set(r.rangeId, { id: r.rangeId, start: s2, end: e2, text: "" });
+  }
+  for (const span of out.values()) span.text = stream.slice(span.start, span.end).replace(CONTROL, " ");
+  return out;
+}
+function addCommentAnchorActions(body, start, end, anchorId) {
+  if (!(end > start) || start < 0) return null;
+  const textX = BuildTextUtils.customRange.add({
+    body,
+    ranges: [{ startOffset: start, endOffset: end, collapsed: false }],
+    rangeId: anchorId,
+    rangeType: COMMENT_ANCHOR_RANGE_TYPE
+  });
+  if (!textX) return null;
+  return JSONX.getInstance().editOp(textX.serialize(), ["body"]);
+}
+function removeCommentAnchorActions(documentDataModel, anchorId) {
+  const textX = BuildTextUtils.customRange.delete({ documentDataModel, rangeId: anchorId });
+  if (!textX) return null;
+  return JSONX.getInstance().editOp(textX.serialize(), ["body"]);
+}
 export {
   CARET_HEARTBEAT_MS,
   CARET_MAX_RANGES,
   CARET_STALE_MS,
+  COMMENT_ANCHOR_LABEL_MAX,
+  COMMENT_ANCHOR_PART_PREFIX,
+  COMMENT_ANCHOR_RANGE_TYPE,
   DOCUMENT_BODY_MAX_LENGTH,
   DOCUMENT_DESCRIPTION_MAX_LENGTH,
   DOCUMENT_NAME_MAX_LENGTH,
@@ -972,7 +1038,12 @@ export {
   MIN_FIT_ZOOM,
   RemoteCaretBook,
   SPECIAL_GROUPS,
+  addCommentAnchorActions,
+  anchorIdOfPartAnchor,
   bodyTextOf,
+  commentAnchorPartKey,
+  commentAnchorsOf,
+  commentPartAnchor,
   configureDocsHost,
   copyDocument,
   createDocument,
@@ -990,8 +1061,10 @@ export {
   moveDocument,
   movePeerRangesThroughBodyEdit,
   moveRangesThroughBodyEdit,
+  newCommentAnchorId,
   planBodyEdit,
   publishedCaretFromSelection,
+  removeCommentAnchorActions,
   renameDocument,
   restoreDocument,
   sanitizeUniverDocSnapshot,