tiptap-markdown-react 0.6.2 → 0.7.0

package/README.md

@@ -114,6 +114,46 @@ export default async function Page() {
 }
 ```
 
+### 4. Comment anchoring (edit session only)
+
+Review / annotation workflows: pass decoded comment segments to the editor; the
+library maps them onto text ranges as `commentAnchor` marks, renders a block-left
+gutter, and reports clicks back to you. **Marks are session-only** — `getMarkdown()`
+strips them, undo history ignores them, and the read-only `MarkdownPreview` never
+renders them.
+
+```tsx
+const comments: CommentRef[] = [
+  {
+    commentId: 'c1',
+    author: 'agent',
+    segments: [{ exact: '寒武纪成立于2016年' }],
+    body: 'Add a source for this claim.',
+  },
+];
+
+<MarkdownWysiwygEditor
+  ref={ref}
+  initialMarkdown={md}
+  comments={comments}
+  activeCommentId={activeId}
+  onActiveCommentChange={setActiveId}
+  onCommentClick={({ commentIds, anchorEl }) => openPopover(commentIds[0], anchorEl)}
+/>
+```
+
+- **Ref methods**: `focusComment(id)` (active + scroll + cursor to range start),
+  `nextComment('next' | 'prev')`, `getCommentIds()`.
+- **Overlap**: multiple comments on the same text merge into one mark with
+  `data-comment-ids="1 2"`; clicks report all ids.
+- **Popover**: `CommentPopover` (Radix) anchors to the clicked mark; content is
+  host-owned (`renderComment`-style children).
+- **Guards**: paste / drop strips marks via `transformPasted`; anchor application
+  is excluded from undo history.
+- **Segments**: `CommentSegment[]` (`{ blockHash?, prefix?, exact, suffix? }`).
+  Capture them from a document with the same text model (see `commentMapper` /
+  `blockTextHash`) so re-anchoring is exact.
+
 ## Theming
 
 Override any of these CSS variables on an ancestor (e.g. `:root` or the editor container):
@@ -130,6 +170,11 @@ Override any of these CSS variables on an ancestor (e.g. `:root` or the editor c
 | `--tmr-min-height` | `420px` | Editor min height |
 | `--tmr-code-bg` | `#f4f4f4` | Inline code background |
 | `--tmr-table-header-bg` | `#f7f7f7` | Table header background |
+| `--tmr-comment-bg` | `rgba(255, 213, 79, 0.32)` | Comment mark background |
+| `--tmr-comment-bg-active` | `rgba(255, 183, 0, 0.55)` | Active comment mark background |
+| `--tmr-comment-ring` | `rgba(219, 171, 10, 0.55)` | Active mark / block outline ring |
+| `--tmr-comment-gutter-bg` | `#f4b400` | Gutter bubble background |
+| `--tmr-popover-bg` | `#fff` | CommentPopover background |
 
 ## API
 
@@ -138,6 +183,7 @@ Override any of these CSS variables on an ancestor (e.g. `:root` or the editor c
 | Prop | Type | Description |
 | --- | --- | --- |
 | `initialMarkdown` | `string` | Initial content (markdown). |
+| `editable` | `boolean` | `false` renders read-only with the **same** extensions/NodeViews/styles — interactive controls (code-block language dropdown, delete) collapse. Comments are ignored when `false`. Default `true`. |
 | `placeholder` | `string` | Placeholder for the empty document. |
 | `onEditorReady` | `(editor: Editor \| null) => void` | Get the Tiptap instance (for the toolbar). |
 | `onTocChange` | `(items: TocItem[]) => void` | Fires when headings change. |
@@ -147,7 +193,8 @@ Override any of these CSS variables on an ancestor (e.g. `:root` or the editor c
 | `codeBlockLabels` | `Partial<CodeBlockLabels>` | Localize the code block UI. |
 | `className` | `string` | Class on the scroll container. |
 
-Ref handle (`MarkdownWysiwygEditorHandle`): `getMarkdown()`, `getHTML()`, `getJSON()`, `getEditor()`.
+Ref handle (`MarkdownWysiwygEditorHandle`): `getMarkdown()`, `getHTML()`, `getJSON()`, `getEditor()`,
+`focusComment(id)`, `nextComment(dir?)`, `getCommentIds()`.
 
 #### Markdown in: paste, drop, import
 

package/dist/commentAnchor/CommentMark.d.ts

@@ -0,0 +1,29 @@
+import { Mark } from '@tiptap/core';
+/**
+ * 评论锚定 mark —— 仅存在于编辑会话内，导出 markdown 时剥离。
+ *
+ * - attrs.commentIds：string[]。ProseMirror 同一文本节点不能挂两个同名
+ *   mark，重叠评论由 commentMapper 合并成「区间 + commentIds[]」后一次性铺入。
+ * - renderMarkdown 返回空串 → getMarkdown() 输出纯文本，评论数据不落库。
+ * - 粘贴/拖拽拦截与 gutter / active 装饰见 commentAnchorPlugin（客户端）。
+ *   本模块保持纯 schema，server 入口可安全导入。
+ */
+declare module '@tiptap/core' {
+    interface Commands<ReturnType> {
+        commentAnchor: {
+            /** 按互不相交的区间 + commentIds 数组铺评论 mark（区间由 mergeCommentIntervals 产出）。 */
+            applyCommentAnchors: (intervals: CommentInterval[]) => ReturnType;
+            /** 清空全文档评论 mark（comments 刷新 / 退出编辑态前调用）。 */
+            clearCommentAnchors: () => ReturnType;
+        };
+    }
+}
+export interface CommentInterval {
+    from: number;
+    to: number;
+    commentIds: string[];
+}
+export interface CommentMarkOptions {
+    HTMLAttributes: Record<string, unknown>;
+}
+export declare const CommentMark: Mark<CommentMarkOptions, any>;

package/dist/commentAnchor/CommentPopover.d.ts

@@ -0,0 +1,18 @@
+import { ReactNode } from 'react';
+export interface CommentPopoverProps {
+    open: boolean;
+    onOpenChange?: (open: boolean) => void;
+    /** 被点击的 mark 元素（from onCommentClick 的 anchorEl）。 */
+    anchorEl: HTMLElement | null;
+    children: ReactNode;
+    side?: 'top' | 'bottom' | 'left' | 'right';
+    align?: 'start' | 'center' | 'end';
+    sideOffset?: number;
+}
+/**
+ * 评论浮层（Radix）。库只负责锚定与外观，内容由宿主通过 children 提供
+ * （典型：评论正文 + Resolve/Dismiss/Reopen 操作）。
+ * 锚点是点击 mark 的动态元素：渲染一个 fixed 1x1 span 挂在 anchorEl 的
+ * getBoundingClientRect 位置，Radix 以它为锚。
+ */
+export declare function CommentPopover({ open, onOpenChange, anchorEl, children, side, align, sideOffset, }: CommentPopoverProps): import("react").JSX.Element;

package/dist/commentAnchor/commentAnchor.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/commentAnchor/commentAnchorController.d.ts

@@ -0,0 +1,15 @@
+import { Editor } from '@tiptap/core';
+import { CommentRange } from './commentMapper';
+import { CommentRef } from './commentTypes';
+/** 先清后铺，幂等；无评论时清空全部 mark。 */
+export declare function applyCommentAnchorsToEditor(editor: Editor, comments: CommentRef[]): void;
+/** 文档顺序去重的 commentId 列表（gutter / 导航顺序）。 */
+export declare function collectCommentIds(editor: Editor): string[];
+export declare function commentRangesById(editor: Editor, commentId: string): CommentRange[];
+/**
+ * 聚焦某条评论：设置 active（mark/block 高亮）+ 滚动到第一个 mark + 光标落到
+ * 区间起点。找不到（outdated）时清空 active 并返回 false。
+ */
+export declare function focusComment(editor: Editor, commentId: string): boolean;
+/** 按文档顺序在评论间循环跳转（dir: next / prev）。 */
+export declare function nextComment(editor: Editor, dir?: 'next' | 'prev'): string | null;

package/dist/commentAnchor/commentAnchorPlugin.d.ts

@@ -0,0 +1,26 @@
+import { Slice, MarkType } from '@tiptap/pm/model';
+import { Extension } from '@tiptap/core';
+import { Plugin, PluginKey } from '@tiptap/pm/state';
+export declare const COMMENT_ACTIVE_META = "tmr:comment:active";
+export declare const COMMENT_CLICK_META = "tmr:comment:click";
+export declare const COMMENT_GUTTER_META = "tmr:comment:gutter";
+export interface CommentGutterPayload {
+    commentIds: string[];
+    pos: number;
+}
+export interface CommentAnchorPluginOptions {
+    /** 是否在 block 左缘渲染评论 gutter 气泡，默认 true。 */
+    showGutter?: boolean;
+}
+export interface CommentAnchorPluginState {
+    activeCommentId: string | null;
+}
+export declare const commentAnchorPluginKey: PluginKey<CommentAnchorPluginState>;
+/** 从 Slice 中剔除 commentAnchor mark（粘贴/拖拽守卫）。 */
+export declare function stripCommentAnchorMarks(slice: Slice, markType: MarkType): Slice;
+export declare function commentAnchorPlugin(options?: CommentAnchorPluginOptions): Plugin<CommentAnchorPluginState>;
+/**
+ * Tiptap Extension 包装：把评论锚定 Plugin 挂进 useEditor / Editor 的 extensions。
+ * 只读态（MarkdownPreview）不要注入本扩展 —— 评论是编辑会话专属。
+ */
+export declare function commentAnchorExtension(options?: CommentAnchorPluginOptions): Extension<any, any>;

package/dist/commentAnchor/commentMapper.d.ts

@@ -0,0 +1,40 @@
+import { Node } from '@tiptap/pm/model';
+import { CommentInterval } from './CommentMark';
+/**
+ * SPIKE 原型：把评论的 ref_content segments 映射到 ProseMirror doc 上的文本区间。
+ *
+ * 与旧 DOM textContent 匹配的区别：
+ * - 工作在文档模型上（无表格 wrapper 空白 / text node 碎片问题）；
+ * - 按顶层 block 作用域搜索，避免跨 block 误命中；
+ * - fallback 链与既有 anchorCommentsInDom 一致：hash → context → exact → prefix → outdated。
+ */
+export interface CommentSegment {
+    /** block 文本哈希（可选快路径；哈希算法见 blockTextHash，需与捕获端一致）。 */
+    blockHash?: string;
+    prefix?: string;
+    exact: string;
+    suffix?: string;
+}
+export interface CommentAnchorInput {
+    commentId: string;
+    segments: CommentSegment[];
+}
+export type CommentAnchorStatus = 'matched' | 'ambiguous' | 'partial' | 'outdated';
+export interface CommentRange {
+    from: number;
+    to: number;
+}
+export interface CommentAnchorResult {
+    commentId: string;
+    ranges: CommentRange[];
+    status: CommentAnchorStatus;
+}
+/** djb2 哈希（捕获端与消费端必须用同一个实现；invret 接入时对齐）。 */
+export declare function blockTextHash(text: string): string;
+/** 主入口：评论列表 → 每条的 doc 区间 + 状态。 */
+export declare function mapCommentAnchors(doc: Node, comments: CommentAnchorInput[]): CommentAnchorResult[];
+/** 把每条评论的区间合并成互不相交的 CommentInterval（重叠区间合并 commentIds）。 */
+export declare function mergeCommentIntervals(entries: Array<{
+    commentId: string;
+    ranges: CommentRange[];
+}>): CommentInterval[];

package/dist/commentAnchor/commentTypes.d.ts

@@ -0,0 +1,33 @@
+import { ReactNode } from 'react';
+import { CommentSegment } from './commentMapper';
+/** 宿主评论（已解码为 segments；ref_content 解码由宿主完成）。 */
+export interface CommentRef {
+    commentId: string;
+    /** 评论作者类型：agent / user（宿主用于配色等）。 */
+    author?: 'agent' | 'user';
+    /** 决议状态：open / resolved / dismissed。 */
+    state?: 'open' | 'resolved' | 'dismissed';
+    /** 与正文对齐的锚定片段（编辑器装载时映射为 mark 区间）。 */
+    segments: CommentSegment[];
+    /** 评论正文（宿主展示用，库不消费）。 */
+    body?: string;
+    user?: {
+        name?: string;
+        avatar?: string;
+    };
+}
+/** CommentPopover 内容插槽上下文。 */
+export interface RenderCommentContext {
+    comment: CommentRef;
+    /** 锚定的评论 id（多条重叠时取第一条）。 */
+    commentId: string;
+}
+export type RenderComment = (ctx: RenderCommentContext) => ReactNode;
+/** 编辑器内点击评论 mark / gutter 时上报给宿主的载荷。 */
+export interface CommentClickPayload {
+    commentIds: string[];
+    /** mark 元素（gutter 点击为 null）。 */
+    anchorEl: HTMLElement | null;
+    /** 点击位置的 doc 坐标。 */
+    pos: number;
+}

package/dist/components/CodeBlockView.d.ts

@@ -3,4 +3,4 @@ import { NodeViewProps } from '@tiptap/react';
  * 代码块自定义 NodeView：右上角语言选择器（Radix DropdownMenu，支持方向键导航）+ 删除。
  * 文案（Auto-detect / 删除标题）从扩展 options.codeBlockLabels 读取，缺省用英文默认。
  */
-export declare function CodeBlockView({ node, updateAttributes, deleteNode, extension, }: NodeViewProps): import("react").JSX.Element;
+export declare function CodeBlockView({ node, updateAttributes, deleteNode, extension, editor, }: NodeViewProps): import("react").JSX.Element;

package/dist/components/MarkdownWysiwygEditor.d.ts

@@ -1,6 +1,7 @@
 import { AnyExtension, Editor } from '@tiptap/react';
 import { SourceRef } from '../citationUtils';
 import { RenderCitation } from '../citationTypes';
+import { CommentClickPayload, CommentRef } from '../commentAnchor/commentTypes';
 import { CodeBlockLabels } from '../labels';
 import { TocItem } from '../toc/extractToc';
 export interface MarkdownWysiwygEditorHandle {
@@ -12,10 +13,22 @@ export interface MarkdownWysiwygEditorHandle {
     getJSON: () => Record<string, unknown>;
     /** 底层 Tiptap Editor 实例（可能为 null，未就绪时）。 */
     getEditor: () => Editor | null;
+    /** 聚焦评论：设 active + 滚动 + 光标落到区间起点。找不到返回 false。 */
+    focusComment: (commentId: string) => boolean;
+    /** 按文档顺序跳转评论（next / prev），返回目标 commentId。 */
+    nextComment: (dir?: 'next' | 'prev') => string | null;
+    /** 当前 doc 内已锚定的去重 commentId 列表（文档顺序）。 */
+    getCommentIds: () => string[];
 }
 export interface MarkdownWysiwygEditorProps {
     /** 初始 markdown 内容。 */
     initialMarkdown?: string;
+    /**
+     * 是否可编辑，默认 true。false = 只读渲染，与编辑态同源同路径：
+     * 同一套扩展 / NodeView / 样式，交互件（代码块语言选择、删除等）自动收起。
+     * 只读态不应用评论锚定（comments 被忽略），与 MarkdownPreview 语义一致。
+     */
+    editable?: boolean;
     /**
      * 初始脚注来源：按 index 对齐 `[^n]`，写入 citationRef 的 url/title。
      * 仅影响初始 content；后续插入请用 `insertMarkdown(editor, md, sources)`。
@@ -47,6 +60,20 @@ export interface MarkdownWysiwygEditorProps {
     codeBlockLabels?: Partial<CodeBlockLabels>;
     /** 附加到滚动容器的 class。 */
     className?: string;
+    /**
+     * 编辑态评论锚定：评论列表（含已解码 segments）。装载时映射为 commentAnchor
+     * mark 并高亮；markdown 导出自动剥离，只读态（MarkdownPreview）不渲染评论。
+     * 注意：数组引用变化会触发重新铺 mark，宿主应 memo 该数组。
+     */
+    comments?: CommentRef[];
+    /** 受控 active 评论 id（sidebar 联动）。null = 无 active。 */
+    activeCommentId?: string | null;
+    /** 编辑器内点击 mark / gutter 时回调。 */
+    onCommentClick?: (payload: CommentClickPayload) => void;
+    /** active 变化回调（点击 mark / gutter / nextComment 时）。 */
+    onActiveCommentChange?: (commentId: string | null) => void;
+    /** 是否在 block 左缘渲染评论 gutter 气泡，默认 true。 */
+    showCommentGutter?: boolean;
 }
 /**
  * 所见即所得 Markdown 编辑器（基于 Tiptap v3 + 官方 @tiptap/markdown）。