feat(ui): add ui.comments.reply for thread replies (SD-2817) (#3035)

Wraps editor.doc.comments.create({ parentCommentId, text }). Replies
inherit the parent's anchor, so callers don't pass a target — the
doc-api adapter resolves it from the parent. Returns a NO_OP receipt
on empty/whitespace text, matching the doc-api contract for top-level
comments.

Drops the useSuperDocHost() reach from the BYO-UI demo's reply
composer; the typed ui.comments.reply() call is now the canonical
path. Routes through the same routed editor as createFromSelection /
createFromCapture so a header-focused composer posts in the header
story.

Author: caio-pizzol

demos/build-your-own-ui/src/components/ActivitySidebar.tsx

@@ -1,9 +1,7 @@
 import { useEffect, useMemo, useRef, useState } from 'react';
-import type { SuperDoc } from 'superdoc';
 import type { CommentsListResult, TrackChangeInfo } from 'superdoc/ui';
 import {
   useSuperDocComments,
-  useSuperDocHost,
   useSuperDocSelection,
   useSuperDocTrackChanges,
   useSuperDocUI,
@@ -271,7 +269,6 @@ function CommentBody({
   replies?: ActivityItem[];
   ui: NonNullable<ReturnType<typeof useSuperDocUI>>;
 }) {
-  const host = useSuperDocHost() as SuperDoc | null;
   const [replyOpen, setReplyOpen] = useState(false);
   const [replyText, setReplyText] = useState('');
   const [replying, setReplying] = useState(false);
@@ -294,17 +291,15 @@ function CommentBody({
   };
 
   const postReply = () => {
-    const editor = host?.activeEditor;
-    const commentsApi = editor?.doc?.comments;
-    if (!commentsApi || typeof commentsApi.create !== 'function' || !replyText.trim()) return;
+    if (!replyText.trim()) return;
     setReplying(true);
     try {
-      // Reply uses the doc-api `create({ parentCommentId, text })`
-      // path. `ui.comments` doesn't yet expose a typed `reply()`
-      // method (filed as a follow-up under SD-2817); the `host`
-      // surface is the documented escape hatch until then.
-      commentsApi.create({ parentCommentId: comment.id, text: replyText.trim() });
-      cancelReply();
+      const receipt = ui.comments.reply(comment.id, { text: replyText.trim() });
+      if (receipt.success) {
+        cancelReply();
+      } else {
+        console.error('[ActivitySidebar] reply rejected', receipt);
+      }
     } catch (err) {
       console.error('[ActivitySidebar] reply failed', err);
     } finally {
@@ -359,7 +354,7 @@ function CommentBody({
             <button onClick={cancelReply}>Cancel</button>
             <button
               className="primary"
-              disabled={!host || replying || !replyText.trim()}
+              disabled={replying || !replyText.trim()}
               onClick={postReply}
             >
               {replying ? 'Posting…' : 'Reply'}
@@ -376,9 +371,7 @@ function CommentBody({
           <>
             <button onClick={() => ui.comments.resolve(comment.id)}>Resolve</button>
             {!replyOpen && (
-              <button disabled={!host} onClick={openReply}>
-                Reply
-              </button>
+              <button onClick={openReply}>Reply</button>
             )}
           </>
         )}

packages/super-editor/src/ui/comments.test.ts

@@ -379,6 +379,77 @@ describe('ui.comments — actions route through editor.doc.*', () => {
     ui.destroy();
   });
 
+  it('reply forwards to comments.create with parentCommentId set and no target', () => {
+    const { superdoc, mocks } = makeStubs();
+    const ui = createSuperDocUI({ superdoc });
+
+    const receipt = ui.comments.reply('c-parent', { text: 'thanks!' });
+
+    expect(receipt.success).toBe(true);
+    expect(mocks.create).toHaveBeenCalledWith({ parentCommentId: 'c-parent', text: 'thanks!' });
+    // Reply must NOT carry a `target` — the doc-api adapter resolves
+    // the parent's anchor itself. Sending one would either be ignored
+    // or, worse, override the inherited address.
+    expect(mocks.create.mock.calls[0]?.[0]).not.toHaveProperty('target');
+
+    ui.destroy();
+  });
+
+  it('reply returns a NO_OP receipt when text is empty or whitespace-only', () => {
+    const { superdoc, mocks } = makeStubs();
+    const ui = createSuperDocUI({ superdoc });
+
+    const empty = ui.comments.reply('c-parent', { text: '' });
+    expect(empty.success).toBe(false);
+
+    const whitespace = ui.comments.reply('c-parent', { text: '   \n\t' });
+    expect(whitespace.success).toBe(false);
+
+    expect(mocks.create).not.toHaveBeenCalled();
+
+    ui.destroy();
+  });
+
+  it('reply refreshes the comments snapshot synchronously after the post', async () => {
+    const { superdoc } = makeStubs({
+      comments: [{ id: 'c-parent', commentId: 'c-parent', text: 'parent' }],
+    });
+    const ui = createSuperDocUI({ superdoc });
+
+    expect(ui.comments.getSnapshot().items).toHaveLength(1);
+
+    // Stub mutates list as if a reply was just persisted.
+    superdoc.setComments([
+      { id: 'c-parent', commentId: 'c-parent', text: 'parent' },
+      { id: 'c-reply', commentId: 'c-reply', text: 'thanks', parentCommentId: 'c-parent' },
+    ]);
+    ui.comments.reply('c-parent', { text: 'thanks' });
+
+    // refreshAndNotify should already have re-read the cache.
+    expect(ui.comments.getSnapshot().items.map((i) => i.id)).toEqual(['c-parent', 'c-reply']);
+
+    ui.destroy();
+  });
+
+  it('reply routes through the routed editor (header / footer focus stays scoped)', () => {
+    // Same posture as createFromSelection / createFromCapture: replies
+    // go through `resolveRoutedEditor` so a header-focused composer
+    // posts in the header story, not the body. Mirrors the doc-api
+    // contract: `comments.create` is story-scoped on the routed editor.
+    const { superdoc, mocks } = makeStubs();
+    const ui = createSuperDocUI({ superdoc });
+
+    ui.comments.reply('c-parent', { text: 'in scope' });
+
+    expect(mocks.create).toHaveBeenCalledTimes(1);
+    expect(mocks.create.mock.calls[0]?.[0]).toMatchObject({
+      parentCommentId: 'c-parent',
+      text: 'in scope',
+    });
+
+    ui.destroy();
+  });
+
   it('resolve forwards to comments.patch({ commentId, status: "resolved" })', () => {
     const { superdoc, mocks } = makeStubs();
     const ui = createSuperDocUI({ superdoc });

packages/super-editor/src/ui/create-super-doc-ui.ts

@@ -1171,6 +1171,27 @@ export function createSuperDocUI(options: SuperDocUIOptions): SuperDocUI {
       refreshAndNotify();
       return receipt;
     },
+    reply(parentCommentId, { text }) {
+      // Reply uses the same `create` operation as a top-level comment;
+      // discrimination is `parentCommentId` set vs absent. Replies
+      // inherit the parent's anchor, so callers don't pass a target —
+      // the doc-api adapter resolves the parent's positional address
+      // and stamps it on the new comment.
+      const trimmed = typeof text === 'string' ? text.trim() : '';
+      if (!trimmed) {
+        return {
+          success: false,
+          failure: { code: 'NO_OP', message: 'ui.comments.reply: text is empty.' },
+        };
+      }
+      const api = requireDocComments();
+      const receipt = (api.create as (input: unknown, options?: unknown) => Receipt).call(api, {
+        parentCommentId,
+        text,
+      });
+      refreshAndNotify();
+      return receipt;
+    },
     resolve(commentId) {
       const api = requireDocComments();
       const receipt = (api.patch as (input: unknown, options?: unknown) => Receipt).call(api, {

packages/super-editor/src/ui/types.ts

@@ -912,6 +912,21 @@ export interface CommentsHandle {
    * lacks a positional target.
    */
   createFromCapture(capture: SelectionCapture, input: { text: string }): import('@superdoc/document-api').Receipt;
+  /**
+   * Post a reply to an existing thread. Routes through
+   * `editor.doc.comments.create({ parentCommentId, text })`; the
+   * reply inherits the parent's anchor, so callers don't pass a
+   * target. The next `useSuperDocComments()` snapshot includes the
+   * reply with `parentCommentId` set, which sidebars can group under
+   * the thread root.
+   *
+   * Returns a `NO_OP` receipt when `text` is empty or whitespace-only,
+   * matching the doc-api's text-required contract for top-level
+   * comments. Returns a failure receipt when the parent id has been
+   * deleted between the time the user opened the reply composer and
+   * pressed Send.
+   */
+  reply(parentCommentId: string, input: { text: string }): import('@superdoc/document-api').Receipt;
   /** Resolve a comment via `editor.doc.comments.patch`. */
   resolve(commentId: string): import('@superdoc/document-api').Receipt;
   /**