tiptop-editor 2.1.0 → 2.2.0

package/README.md

@@ -412,6 +412,229 @@ Example:
 }
 ```
 
+## Comments
+
+The package ships a full inline and block comment system designed for **review / view mode**. Comments are stored entirely in the calling app — the package exposes hooks and callbacks so you can persist and sync with your own API.
+
+### Comment types
+
+| Type | What it annotates | How it looks |
+|------|------------------|--------------|
+| `inline` | A selected text range | Yellow underline highlight on the text |
+| `node` | An entire block (paragraph, heading, …) | Left amber border on the block |
+
+### Quick setup
+
+Wrap the editor in `CommentsProvider`, pass `showCommentMenu: true` and `editable: false` to put the editor into view mode, then render your own comment drawer next to it.
+
+```tsx
+import { TiptopEditor, CommentsProvider, useComments, useCommentActions } from 'tiptop-editor'
+import { Dropdown, Label } from '@heroui/react'
+import { MessageSquarePlus } from 'lucide-react'
+import { useTiptopEditor } from 'tiptop-editor'
+
+// Optional: lets users add block-level comments from the drag-handle menu
+function NodeCommentButton() {
+  const editor = useTiptopEditor()
+  const comments = useComments()
+
+  if (!editor || !comments) return null
+
+  return (
+    <Dropdown.Section>
+      <Dropdown.Item
+        id="add_node_comment"
+        textValue="Add comment"
+        onPress={() => {
+          comments.setPendingComment({
+            id: crypto.randomUUID(),
+            type: 'node',
+            nodePos: editor.state.selection.from,
+          })
+        }}
+      >
+        <MessageSquarePlus size={16} />
+        <Label>Add comment</Label>
+      </Dropdown.Item>
+    </Dropdown.Section>
+  )
+}
+
+export function ReviewPage() {
+  return (
+    <CommentsProvider>
+      <div style={{ display: 'flex' }}>
+        <TiptopEditor
+          editorOptions={{
+            content: '<p>Document content…</p>',
+            immediatelyRender: false,
+            editable: false,
+            showCommentMenu: true,
+          }}
+          slots={{
+            dragHandleDropdown: <NodeCommentButton />,
+          }}
+        />
+        {/* Your own drawer component here — see "Building a custom comment drawer" below */}
+      </div>
+    </CommentsProvider>
+  )
+}
+```
+
+> `showCommentMenu: true` registers the `CommentMark` and `NodeCommentExtension` Tiptap extensions and renders the floating "Add comment" button that appears on text selection.
+
+### Persisting comments with your API
+
+`CommentsProvider` accepts an `onCommentsChange` callback that fires whenever the comment list changes. Use it to sync with your backend.
+
+```tsx
+import { useState } from 'react'
+import { CommentsProvider, TiptopEditor } from 'tiptop-editor'
+import type { TiptopComment } from 'tiptop-editor'
+
+export function ReviewPage() {
+  const [initialComments] = useState<TiptopComment[]>([
+    // Comments loaded from your API on mount
+  ])
+
+  const handleCommentsChange = async (comments: TiptopComment[]) => {
+    await fetch('/api/documents/123/comments', {
+      method: 'PUT',
+      body: JSON.stringify(comments),
+    })
+  }
+
+  return (
+    <CommentsProvider
+      initialComments={initialComments}
+      onCommentsChange={handleCommentsChange}
+    >
+      <div style={{ display: 'flex' }}>
+        <TiptopEditor
+          editorOptions={{
+            content: '<p>…</p>',
+            editable: false,
+            showCommentMenu: true,
+            immediatelyRender: false,
+          }}
+        />
+        {/* Your own drawer here */}
+      </div>
+    </CommentsProvider>
+  )
+}
+```
+
+`onCommentsChange` receives the full updated array after every add, resolve, reply, or delete. It fires synchronously after the state update — debounce or batch API calls on your side as needed.
+
+### Loading existing comments
+
+Pass your persisted comments as `initialComments` to `CommentsProvider`. The comment marks in the editor HTML already carry a `data-comment-id` attribute, so the sidebar threads reconnect automatically as long as the IDs match.
+
+> The editor content (HTML string with mark attributes) and the comments array are two separate things to persist. Store both and restore both — the HTML goes into `editorOptions.content`, the comments go into `initialComments`.
+
+### Reading comment state programmatically
+
+Use `useComments()` anywhere inside `CommentsProvider` to read or mutate the comment state directly.
+
+```tsx
+import { useComments } from 'tiptop-editor'
+
+function CommentCount() {
+  const comments = useComments()
+  if (!comments) return null
+
+  const open = comments.comments.filter(c => !c.resolved).length
+  return <span>{open} open comment{open !== 1 ? 's' : ''}</span>
+}
+```
+
+Available values and actions from `useComments()`:
+
+| Name | Type | Description |
+|------|------|-------------|
+| `comments` | `TiptopComment[]` | All comments (open and resolved) |
+| `activeCommentId` | `string \| null` | ID of the currently focused comment |
+| `pendingComment` | `PendingComment \| null` | Comment being drafted (not yet submitted) |
+| `addComment` | `(id, type, content, author?) => void` | Finalize a pending comment |
+| `removeComment` | `(id) => void` | Delete a comment from the context (use `useCommentActions().remove` to also strip the editor mark) |
+| `resolveComment` | `(id) => void` | Mark as resolved in the context (use `useCommentActions().resolve` to also strip the editor mark) |
+| `replyToComment` | `(commentId, content, author?) => void` | Append a reply |
+| `setActiveCommentId` | `(id \| null) => void` | Highlight a comment thread |
+| `setPendingComment` | `(PendingComment \| null) => void` | Open the new-comment form |
+| `getComment` | `(id) => TiptopComment \| undefined` | Look up a single comment |
+
+### Building a custom comment drawer
+
+The package does not ship a styled sidebar — you build your own. The only non-obvious part is that resolving or deleting a comment requires two coordinated steps: removing the mark from the editor **and** updating the context. The `useCommentActions` hook handles both so you don't have to.
+
+```tsx
+import {
+  TiptopEditor,
+  CommentsProvider,
+  useComments,
+  useCommentActions,
+} from 'tiptop-editor'
+
+function MyCommentDrawer() {
+  const ctx = useComments()
+  const { submit, resolve, remove } = useCommentActions()
+
+  if (!ctx) return null
+  const { comments, pendingComment, activeCommentId, setActiveCommentId } = ctx
+
+  return (
+    <aside>
+      {/* New comment form — shown when the user clicks "Add comment" */}
+      {pendingComment && (
+        <form onSubmit={e => {
+          e.preventDefault()
+          const text = new FormData(e.currentTarget).get('comment') as string
+          submit(pendingComment, text)
+        }}>
+          <textarea name="comment" placeholder="Add a comment…" autoFocus />
+          <button type="submit">Save</button>
+          <button type="button" onClick={() => ctx.setPendingComment(null)}>Cancel</button>
+        </form>
+      )}
+
+      {/* Comment threads */}
+      {comments.map(comment => (
+        <div
+          key={comment.id}
+          data-active={activeCommentId === comment.id || undefined}
+          onClick={() => setActiveCommentId(comment.id)}
+        >
+          <p>{comment.content}</p>
+          <button onClick={e => { e.stopPropagation(); resolve(comment.id) }}>Resolve</button>
+          <button onClick={e => { e.stopPropagation(); remove(comment.id) }}>Delete</button>
+        </div>
+      ))}
+    </aside>
+  )
+}
+
+export function ReviewPage() {
+  return (
+    <CommentsProvider onCommentsChange={comments => saveToApi(comments)}>
+      <div style={{ display: 'flex' }}>
+        <TiptopEditor editorOptions={{ editable: false, showCommentMenu: true, immediatelyRender: false }} />
+        <MyCommentDrawer />
+      </div>
+    </CommentsProvider>
+  )
+}
+```
+
+`useCommentActions` provides three methods:
+
+| Method | Description |
+|--------|-------------|
+| `submit(pending, content, author?)` | Applies the pending comment to the editor (adds the mark/attribute) and registers it in the context |
+| `resolve(commentId)` | Removes the mark/attribute from the editor and marks the comment as resolved |
+| `remove(commentId)` | Removes the mark/attribute from the editor and deletes the comment from the context |
+
 ## Notes
 
 - If you use SSR, keep `immediatelyRender: false`.

package/dist/components/comment/CommentButton.d.ts

@@ -0,0 +1,7 @@
+/**
+ * A button meant to be placed in the `selectionMenuAppend` slot.
+ * When pressed it snapshots the current text selection and opens
+ * the comment sidebar so the user can type a new inline comment.
+ */
+declare const CommentButton: () => import("react/jsx-runtime").JSX.Element | null;
+export default CommentButton;

package/dist/components/comment/CommentSelectionMenu.d.ts

@@ -0,0 +1,10 @@
+import { Editor } from '@tiptap/react';
+/**
+ * Bubble menu that appears on text selection only when the editor is in
+ * view / review mode (`editable: false`). Rendered automatically by
+ * `TiptopEditor` when `showCommentMenu: true` is set.
+ */
+declare const CommentSelectionMenu: ({ editor }: {
+    editor: Editor;
+}) => import("react/jsx-runtime").JSX.Element | null;
+export default CommentSelectionMenu;

package/dist/components/comment/CommentsContext.d.ts

@@ -0,0 +1,11 @@
+import { ReactNode } from 'react';
+import { TiptopComment } from '../../types';
+interface CommentsProviderProps {
+    children: ReactNode;
+    /** Pre-populate the comment list (e.g. data fetched from your API on mount). */
+    initialComments?: TiptopComment[];
+    /** Called whenever the comments array changes. Use this to persist or sync externally. */
+    onCommentsChange?: (comments: TiptopComment[]) => void;
+}
+export declare const CommentsProvider: ({ children, initialComments, onCommentsChange }: CommentsProviderProps) => import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/components/comment/context.d.ts

@@ -0,0 +1,2 @@
+import { CommentsContextValue } from '../../types';
+export declare const CommentsContext: import('react').Context<CommentsContextValue | null>;

package/dist/components/comment/useCommentActions.d.ts

@@ -0,0 +1,13 @@
+import { PendingComment } from '../../types';
+/**
+ * Returns coordinated comment actions that keep the editor marks and the
+ * CommentsContext in sync. Use this when building a custom comment UI instead
+ * of reimplementing the editor↔context coordination yourself.
+ *
+ * Must be called inside both a `CommentsProvider` and a `TiptopEditor` tree.
+ */
+export declare const useCommentActions: () => {
+    submit: (pending: PendingComment, content: string, author?: string) => void;
+    resolve: (commentId: string) => void;
+    remove: (commentId: string) => void;
+};

package/dist/components/comment/useComments.d.ts

@@ -0,0 +1,7 @@
+import { CommentsContextValue } from '../../types';
+/**
+ * Returns the comments context value, or `null` if no `CommentsProvider`
+ * is present in the tree. Components that depend on comments should
+ * guard against `null` and render nothing when it's absent.
+ */
+export declare const useComments: () => CommentsContextValue | null;

package/dist/components/editor/TiptopEditor.stories.d.ts

@@ -17,3 +17,4 @@ export declare const Frameless: Story;
 export declare const WithSlots: Story;
 export declare const ViewMode: Story;
 export declare const WithDragHandleSlot: Story;
+export declare const WithComments: Story;

package/dist/extensions/comment/CommentMark.d.ts

@@ -0,0 +1,23 @@
+import { Mark } from '@tiptap/core';
+declare module '@tiptap/core' {
+    interface Commands<ReturnType> {
+        comment: {
+            /**
+             * Apply a comment mark to a specific text range.
+             * The range must be provided explicitly so the mark can be applied
+             * even after the editor selection has moved (e.g. after the user
+             * has focused a sidebar input).
+             */
+            setComment: (commentId: string, range: {
+                from: number;
+                to: number;
+            }) => ReturnType;
+            /**
+             * Remove a comment mark by its commentId, searching the whole document.
+             */
+            unsetComment: (commentId: string) => ReturnType;
+        };
+    }
+}
+declare const CommentMark: Mark<any, any>;
+export default CommentMark;

package/dist/extensions/comment/NodeCommentExtension.d.ts

@@ -0,0 +1,17 @@
+import { Extension } from '@tiptap/core';
+declare module '@tiptap/core' {
+    interface Commands<ReturnType> {
+        nodeComment: {
+            /**
+             * Set a comment on the block node at the given ProseMirror position.
+             */
+            setNodeComment: (commentId: string, nodePos: number) => ReturnType;
+            /**
+             * Remove the comment from every block node that carries the given commentId.
+             */
+            unsetNodeComment: (commentId: string) => ReturnType;
+        };
+    }
+}
+declare const NodeCommentExtension: Extension<any, any>;
+export default NodeCommentExtension;

package/dist/index.d.ts

@@ -2,3 +2,9 @@ export { default as TiptopEditor } from './components/editor/TiptopEditor';
 export { TiptopEditorContext, useTiptopEditor } from './components/editor/TiptopEditorContext';
 export { getDocumentMap, applyTargetedUpdate, applyTargetedUpdates } from './helpers';
 export * from './types';
+export { CommentsProvider } from './components/comment/CommentsContext';
+export { useComments } from './components/comment/useComments';
+export { useCommentActions } from './components/comment/useCommentActions';
+export { default as CommentSelectionMenu } from './components/comment/CommentSelectionMenu';
+export { default as CommentMark } from './extensions/comment/CommentMark';
+export { default as NodeCommentExtension } from './extensions/comment/NodeCommentExtension';