@sanity/sdk-react 3.11.0-next.20261029105031 → 3.11.0

package/src/hooks/comments/useCommentThreads.ts

@@ -1,74 +1,80 @@
+import {getDocumentCommentsOptionsKey, parseDocumentCommentsOptionsKey} from '@sanity/sdk/_internal'
 import {
   type CommentsOptions,
   type CommentThread,
+  getCommentsErrorState,
   getCommentThreadsState,
   resolveCommentThreads,
-} from '@sanity/sdk'
+} from '@sanity/sdk/collaboration'
 import {useMemo} from 'react'
 
 import {type WithResourceNameSupport} from '../helpers/useNormalizedResourceOptions'
 import {type CommentListSource, useCommentList} from './useCommentList'
 
 /**
- * @public
+ * @beta
  * @category Types
  * @category Comments
  */
 export interface UseCommentThreadsResult {
-  /** Newest thread first, each with its replies oldest first. */
+  /** Matching threads, newest first, each with its replies oldest first. */
   threads: CommentThread[]
   /** True while switching to a different document or filter. */
   isPending: boolean
+  /**
+   * Set when the threads have stopped following the server: the listener
+   * failed after they had loaded, so what you are reading is the list as it
+   * last stood rather than as it is. Clears when a listener comes back.
+   */
+  error?: unknown
 }
 
-const SOURCE: CommentListSource<CommentThread[]> = {
+const SOURCE: CommentListSource<CommentsOptions, CommentThread[]> = {
   getState: getCommentThreadsState,
+  getErrorState: getCommentsErrorState,
   resolve: resolveCommentThreads,
+  getKey: getDocumentCommentsOptionsKey,
+  parseKey: parseDocumentCommentsOptionsKey,
 }
 
 /**
- * Reads a document's comments grouped into threads.
+ * Reads a document's comment threads and keeps them up to date.
  *
- * A thread is one comment plus its replies. Its `status` and `fieldPath` come
- * from the first comment, so filtering by either selects whole threads rather
- * than stray replies.
+ * A thread carries its first comment plus its replies, and `status` and
+ * `fieldPath` come from that first comment, so filtering by either selects
+ * whole threads. Use {@link useComments} to read the same list flat, `scope` to
+ * say which of the document's comments to cover — by default it follows the
+ * perspective in view — and {@link useCommentsQuery} when the question is not
+ * "comments on this document".
  *
- * Unlike the Studio, every thread is returned. The Studio hides threads whose
- * field has left the schema or is hidden by a conditional, which it can do
- * because it has the schema to check against. Inspect `fieldPath` yourself if
- * your app needs to do the same.
+ * Suspends until the comments have loaded. Switching document or filter is a
+ * transition, so the previous list stays on screen and `isPending` goes true
+ * rather than the component suspending again.
  *
  * @category Comments
  * @function
- * @param options - The document to read, optionally narrowed by `fieldPath` or `status`
+ * @param options - The document to read, optionally narrowed by `fieldPath`, `status`, or `scope`
  * @returns The matching threads, and whether a switch is in flight
  *
- * @example Render the open threads on a document
+ * @example Count the open threads on a field
  * ```tsx
- * function Threads({documentId}: {documentId: string}) {
+ * function TitleCommentCount({documentId}: {documentId: string}) {
  *   const {threads} = useCommentThreads({
  *     documentId,
  *     documentType: 'article',
+ *     fieldPath: 'title',
  *     status: 'open',
  *   })
  *
- *   return (
- *     <ul>
- *       {threads.map((thread) => (
- *         <li key={thread.threadId}>
- *           {thread.fieldPath || 'Document'} — {thread.commentsCount} comments
- *         </li>
- *       ))}
- *     </ul>
- *   )
+ *   return <span>{threads.length}</span>
  * }
  * ```
  *
- * @public
+ * @beta
  */
 export function useCommentThreads(
   options: WithResourceNameSupport<CommentsOptions>,
 ): UseCommentThreadsResult {
-  const {value, isPending} = useCommentList('useCommentThreads', options, SOURCE)
-  return useMemo(() => ({threads: value, isPending}), [isPending, value])
+  const {value, isPending, error} = useCommentList('useCommentThreads', options, SOURCE)
+  return useMemo(() => ({threads: value, isPending, error}), [error, isPending, value])
 }

package/src/hooks/comments/useComments.test.tsx

@@ -1,48 +1,38 @@
+import {type StateSource} from '@sanity/sdk'
 import {
   type Comment,
   type CommentsOptions,
+  getCommentsErrorState,
   getCommentsState,
   resolveComments,
-  type StateSource,
-} from '@sanity/sdk'
+} from '@sanity/sdk/collaboration'
 import {act, render, screen} from '@testing-library/react'
 import {Suspense} from 'react'
 import {type Observable, Subject} from 'rxjs'
 import {beforeEach, describe, expect, it, vi} from 'vitest'
 
 import {ResourceProvider} from '../../context/ResourceProvider'
-import {ResourcesContext} from '../../context/ResourcesContext'
 import {useComments} from './useComments'
 
-vi.mock('@sanity/sdk', async (importOriginal) => {
-  const original = await importOriginal<typeof import('@sanity/sdk')>()
-  return {...original, getCommentsState: vi.fn(), resolveComments: vi.fn()}
+vi.mock('@sanity/sdk/collaboration', async (importOriginal) => {
+  const original = await importOriginal<typeof import('@sanity/sdk/collaboration')>()
+  return {
+    ...original,
+    getCommentsState: vi.fn(),
+    getCommentsErrorState: vi.fn(),
+    resolveComments: vi.fn(),
+  }
 })
 
 const HANDLE = {documentId: 'doc-1', documentType: 'author'}
 
-function comment(id: string): Comment {
-  return {
-    id,
-    createdAt: '2026-01-01T00:00:00Z',
-    authorId: 'user-1',
-    message: null,
-    threadId: 'thread-1',
-    status: 'open',
-    documentId: 'doc-1',
-    documentType: 'author',
-    fieldPath: '',
-    reactions: [],
-  }
+function comment(id: string) {
+  return {id, fieldPath: ''} as Comment
 }
 
 /**
- * Stands in for the store, one source per option set so a test can hold one
- * document loaded and another not.
- *
- * `getCurrent` must hand back the same array every call for a given option set.
- * Returning a fresh one sends `useSyncExternalStore` into a render loop, which
- * is why the store memoises its selectors.
+ * Stands in for the store. `getCurrent` must hand back the same array every
+ * call for a given option set, or `useSyncExternalStore` renders in a loop.
  */
 function mockSource(
   getCurrent: (options: CommentsOptions) => Comment[] | undefined,
@@ -61,29 +51,21 @@ function mockSource(
         },
       }) as StateSource<Comment[] | undefined>,
   )
+  vi.mocked(getCommentsErrorState).mockImplementation(
+    () =>
+      ({
+        getCurrent: () => undefined,
+        subscribe: vi.fn(() => () => {}),
+        get observable(): Observable<unknown> {
+          throw new Error('Not implemented')
+        },
+      }) as StateSource<unknown>,
+  )
 }
 
-/** Hoisted so the context value stays identical across renders. */
-const RELEASE_PERSPECTIVE = {releaseName: 'summer'}
-
 function Wrapper({children}: {children: React.ReactNode}) {
   return (
     <ResourceProvider projectId="p" dataset="d" fallback={<p>Loading…</p>}>
-      <ResourcesContext.Provider value={{other: {projectId: 'p2', dataset: 'd2'}}}>
-        <Suspense fallback={<p data-testid="suspended">Suspended</p>}>{children}</Suspense>
-      </ResourcesContext.Provider>
-    </ResourceProvider>
-  )
-}
-
-function PerspectiveWrapper({children}: {children: React.ReactNode}) {
-  return (
-    <ResourceProvider
-      projectId="p"
-      dataset="d"
-      perspective={RELEASE_PERSPECTIVE}
-      fallback={<p>Loading…</p>}
-    >
       <Suspense fallback={<p data-testid="suspended">Suspended</p>}>{children}</Suspense>
     </ResourceProvider>
   )
@@ -137,12 +119,17 @@ describe('useComments', () => {
     expect(screen.getByTestId('out').textContent).toBe('1')
   })
 
-  it('passes the field path and status through to the store', () => {
+  it('passes the field path, status, and scope through to the store', () => {
     const loaded: Comment[] = []
     mockSource(() => loaded)
 
     function TestComponent() {
-      useComments({...HANDLE, fieldPath: ['body', {_key: 'intro'}], status: 'resolved'})
+      useComments({
+        ...HANDLE,
+        fieldPath: ['body', {_key: 'intro'}],
+        status: 'resolved',
+        scope: 'all',
+      })
       return null
     }
 
@@ -154,89 +141,9 @@ describe('useComments', () => {
         documentId: 'doc-1',
         fieldPath: 'body[_key=="intro"]',
         status: 'resolved',
+        scope: 'all',
         resource: {projectId: 'p', dataset: 'd'},
       }),
     )
   })
-
-  it('resolves a named resource from context', () => {
-    const loaded: Comment[] = []
-    mockSource(() => loaded)
-
-    function TestComponent() {
-      useComments({...HANDLE, resourceName: 'other'})
-      return null
-    }
-
-    render(<TestComponent />, {wrapper: Wrapper})
-
-    expect(getCommentsState).toHaveBeenCalledWith(
-      expect.anything(),
-      expect.objectContaining({resource: {projectId: 'p2', dataset: 'd2'}}),
-    )
-  })
-
-  it('fills in the perspective from context', () => {
-    // Core turns a release perspective into `target.documentVersionId` and into
-    // the key the list is stored under, so dropping it here would read and
-    // write the wrong release with nothing to show that anything went wrong.
-    const loaded: Comment[] = []
-    mockSource(() => loaded)
-
-    function TestComponent() {
-      useComments(HANDLE)
-      return null
-    }
-
-    render(<TestComponent />, {wrapper: PerspectiveWrapper})
-
-    expect(getCommentsState).toHaveBeenCalledWith(
-      expect.anything(),
-      expect.objectContaining({perspective: RELEASE_PERSPECTIVE}),
-    )
-  })
-
-  it('keeps the previous list on screen while a different document loads', async () => {
-    const first = [comment('a')]
-    const second = [comment('b'), comment('c')]
-    // Only `doc-1` is loaded, so switching to `doc-2` has to suspend.
-    const byDocument: Record<string, Comment[] | undefined> = {'doc-1': first}
-    mockSource((options) => byDocument[options.documentId])
-
-    let settle: () => void = () => {}
-    vi.mocked(resolveComments).mockReturnValue(
-      new Promise<Comment[]>((resolve) => {
-        settle = () => resolve(second)
-      }),
-    )
-
-    function TestComponent({documentId}: {documentId: string}) {
-      const {comments, isPending} = useComments({...HANDLE, documentId})
-      return <div data-testid="out">{`${comments.length} ${isPending ? 'pending' : 'idle'}`}</div>
-    }
-
-    const {rerender} = render(<TestComponent documentId="doc-1" />, {wrapper: Wrapper})
-    expect(screen.getByTestId('out').textContent).toBe('1 idle')
-
-    await act(async () => {
-      rerender(<TestComponent documentId="doc-2" />)
-    })
-
-    // The swap happens inside a transition, so the render that suspends is
-    // thrown away rather than falling back: `doc-1` stays on screen and
-    // `isPending` is what reports the switch.
-    expect(screen.queryByTestId('suspended')).not.toBeInTheDocument()
-    expect(screen.getByTestId('out').textContent).toBe('1 pending')
-    expect(getCommentsState).toHaveBeenCalledWith(
-      expect.anything(),
-      expect.objectContaining({documentId: 'doc-2'}),
-    )
-
-    await act(async () => {
-      byDocument['doc-2'] = second
-      settle()
-    })
-
-    expect(screen.getByTestId('out').textContent).toBe('2 idle')
-  })
 })

package/src/hooks/comments/useComments.ts

@@ -1,11 +1,18 @@
-import {type Comment, type CommentsOptions, getCommentsState, resolveComments} from '@sanity/sdk'
+import {getDocumentCommentsOptionsKey, parseDocumentCommentsOptionsKey} from '@sanity/sdk/_internal'
+import {
+  type Comment,
+  type CommentsOptions,
+  getCommentsErrorState,
+  getCommentsState,
+  resolveComments,
+} from '@sanity/sdk/collaboration'
 import {useMemo} from 'react'
 
 import {type WithResourceNameSupport} from '../helpers/useNormalizedResourceOptions'
 import {type CommentListSource, useCommentList} from './useCommentList'
 
 /**
- * @public
+ * @beta
  * @category Types
  * @category Comments
  */
@@ -14,20 +21,32 @@ export interface UseCommentsResult {
   comments: Comment[]
   /** True while switching to a different document or filter. */
   isPending: boolean
+  /**
+   * Set when the comments have stopped following the server: the listener
+   * failed after they had loaded, so what you are reading is the list as it
+   * last stood rather than as it is. Clears when a listener comes back.
+   */
+  error?: unknown
 }
 
-const SOURCE: CommentListSource<Comment[]> = {
+const SOURCE: CommentListSource<CommentsOptions, Comment[]> = {
   getState: getCommentsState,
+  getErrorState: getCommentsErrorState,
   resolve: resolveComments,
+  getKey: getDocumentCommentsOptionsKey,
+  parseKey: parseDocumentCommentsOptionsKey,
 }
 
 /**
  * Reads a document's comments and keeps them up to date.
  *
- * Comments are shared with the Studio: they live in the project's comments
- * dataset, so a thread started here shows up there and the other way round. The
- * list is flat, replies included; reach for {@link useCommentThreads} to read it
- * grouped.
+ * The list is flat, replies included, which suits a count or a feed. Reach for
+ * {@link useCommentThreads} to read the same comments grouped, where a reply
+ * sits under the comment it answers and filtering by `status` or `fieldPath`
+ * selects whole threads rather than individual comments. Both read the same
+ * document and share a listener, so using them side by side costs nothing
+ * extra. {@link useCommentsQuery} covers anything that is not one document's
+ * comments.
  *
  * Suspends until the comments have loaded. Switching document or filter is a
  * transition, so the previous list stays on screen and `isPending` goes true
@@ -35,10 +54,10 @@ const SOURCE: CommentListSource<Comment[]> = {
  *
  * @category Comments
  * @function
- * @param options - The document to read, optionally narrowed by `fieldPath` or `status`
+ * @param options - The document to read, optionally narrowed by `fieldPath`, `status`, or `scope`
  * @returns The matching comments, and whether a switch is in flight
  *
- * @example Count the open threads on a field
+ * @example Count the open comments on a field
  * ```tsx
  * function TitleCommentCount({documentId}: {documentId: string}) {
  *   const {comments} = useComments({
@@ -52,9 +71,9 @@ const SOURCE: CommentListSource<Comment[]> = {
  * }
  * ```
  *
- * @public
+ * @beta
  */
 export function useComments(options: WithResourceNameSupport<CommentsOptions>): UseCommentsResult {
-  const {value, isPending} = useCommentList('useComments', options, SOURCE)
-  return useMemo(() => ({comments: value, isPending}), [isPending, value])
+  const {value, isPending, error} = useCommentList('useComments', options, SOURCE)
+  return useMemo(() => ({comments: value, isPending, error}), [error, isPending, value])
 }

package/src/hooks/comments/useCommentsQuery.test.tsx

@@ -0,0 +1,259 @@
+import {type StateSource} from '@sanity/sdk'
+import {
+  type Comment,
+  type CommentsQueryOptions,
+  getCommentsQueryErrorState,
+  getCommentsQueryState,
+  resolveCommentsQuery,
+} from '@sanity/sdk/collaboration'
+import {act, render, screen} from '@testing-library/react'
+import {Suspense} from 'react'
+import {type Observable, Subject} from 'rxjs'
+import {beforeEach, describe, expect, it, vi} from 'vitest'
+
+import {ResourceProvider} from '../../context/ResourceProvider'
+import {ResourcesContext} from '../../context/ResourcesContext'
+import {useCommentsQuery} from './useCommentsQuery'
+
+vi.mock('@sanity/sdk/collaboration', async (importOriginal) => {
+  const original = await importOriginal<typeof import('@sanity/sdk/collaboration')>()
+  return {
+    ...original,
+    getCommentsQueryState: vi.fn(),
+    getCommentsQueryErrorState: vi.fn(),
+    resolveCommentsQuery: vi.fn(),
+  }
+})
+
+function comment(id: string): Comment {
+  return {
+    id,
+    createdAt: '2026-01-01T00:00:00Z',
+    authorId: 'user-1',
+    message: [{_type: 'block', _key: 'b1', children: [{_type: 'span', text: 'hello'}]}],
+    threadId: 'thread-1',
+    status: 'open',
+    documentId: 'doc-1',
+    sourceDocumentId: 'doc-1',
+    documentType: 'author',
+    fieldPath: 'title',
+    reactions: [],
+  }
+}
+
+/** See the equivalent in `useCommentThreads.test.tsx` for why this is keyed. */
+function mockSource(
+  getCurrent: (options: CommentsQueryOptions) => Comment[] | undefined,
+  changed$?: Subject<void>,
+) {
+  vi.mocked(getCommentsQueryState).mockImplementation(
+    (_instance, options) =>
+      ({
+        getCurrent: () => getCurrent(options),
+        subscribe: vi.fn((cb?: () => void) => {
+          const subscription = changed$?.subscribe(() => cb?.())
+          return () => subscription?.unsubscribe()
+        }),
+        get observable(): Observable<Comment[] | undefined> {
+          throw new Error('Not implemented')
+        },
+      }) as StateSource<Comment[] | undefined>,
+  )
+  mockErrorSource(() => undefined)
+}
+
+/** The companion source, live by default. Call again to override. */
+function mockErrorSource(getCurrent: () => unknown, changed$?: Subject<void>) {
+  vi.mocked(getCommentsQueryErrorState).mockImplementation(
+    () =>
+      ({
+        getCurrent,
+        subscribe: vi.fn((cb?: () => void) => {
+          const subscription = changed$?.subscribe(() => cb?.())
+          return () => subscription?.unsubscribe()
+        }),
+        get observable(): Observable<unknown> {
+          throw new Error('Not implemented')
+        },
+      }) as StateSource<unknown>,
+  )
+}
+
+function Wrapper({children}: {children: React.ReactNode}) {
+  return (
+    <ResourceProvider projectId="p" dataset="d" fallback={<p>Loading…</p>}>
+      <ResourcesContext.Provider value={{other: {projectId: 'p2', dataset: 'd2'}}}>
+        <Suspense fallback={<p data-testid="suspended">Suspended</p>}>{children}</Suspense>
+      </ResourcesContext.Provider>
+    </ResourceProvider>
+  )
+}
+
+describe('useCommentsQuery', () => {
+  beforeEach(() => {
+    vi.resetAllMocks()
+  })
+
+  it('renders the comments once they are loaded', () => {
+    const loaded = [comment('a'), comment('b')]
+    mockSource(() => loaded)
+
+    function TestComponent() {
+      const {comments, isPending} = useCommentsQuery({filter: 'status == "open"'})
+      return <div data-testid="out">{`${comments.length} ${isPending ? 'pending' : 'idle'}`}</div>
+    }
+
+    render(<TestComponent />, {wrapper: Wrapper})
+
+    expect(screen.getByTestId('out').textContent).toBe('2 idle')
+  })
+
+  it('suspends until the first snapshot arrives', async () => {
+    const loaded = [comment('a')]
+    const ref: {current: Comment[] | undefined} = {current: undefined}
+    const changed$ = new Subject<void>()
+    mockSource(() => ref.current, changed$)
+
+    let settle: () => void = () => {}
+    vi.mocked(resolveCommentsQuery).mockReturnValue(
+      new Promise<Comment[]>((resolve) => {
+        settle = () => resolve(loaded)
+      }),
+    )
+
+    function TestComponent() {
+      const {comments} = useCommentsQuery({filter: 'status == "open"'})
+      return <div data-testid="out">{comments.length}</div>
+    }
+
+    render(<TestComponent />, {wrapper: Wrapper})
+    expect(screen.getByTestId('suspended')).toBeInTheDocument()
+
+    await act(async () => {
+      ref.current = loaded
+      settle()
+    })
+
+    expect(screen.getByTestId('out').textContent).toBe('1')
+  })
+
+  it('passes the filter and its params through to the store', () => {
+    const loaded: Comment[] = []
+    mockSource(() => loaded)
+
+    function TestComponent() {
+      useCommentsQuery({filter: '_system.createdBy == $userId', params: {userId: 'user-1'}})
+      return null
+    }
+
+    render(<TestComponent />, {wrapper: Wrapper})
+
+    expect(getCommentsQueryState).toHaveBeenCalledWith(
+      expect.anything(),
+      expect.objectContaining({
+        filter: '_system.createdBy == $userId',
+        params: {userId: 'user-1'},
+        resource: {projectId: 'p', dataset: 'd'},
+      }),
+    )
+  })
+
+  it('resolves a named resource from context', () => {
+    const loaded: Comment[] = []
+    mockSource(() => loaded)
+
+    function TestComponent() {
+      useCommentsQuery({filter: 'status == "open"', resourceName: 'other'})
+      return null
+    }
+
+    render(<TestComponent />, {wrapper: Wrapper})
+
+    expect(getCommentsQueryState).toHaveBeenCalledWith(
+      expect.anything(),
+      expect.objectContaining({resource: {projectId: 'p2', dataset: 'd2'}}),
+    )
+  })
+
+  it('re-reads when a param changes rather than only when the filter does', () => {
+    // The filter is a template and the params are what it means, so keying on
+    // the filter alone would leave a user's list showing another user's
+    // comments.
+    const loaded: Comment[] = []
+    mockSource(() => loaded)
+
+    function TestComponent({userId}: {userId: string}) {
+      useCommentsQuery({filter: '_system.createdBy == $userId', params: {userId}})
+      return null
+    }
+
+    const {rerender} = render(<TestComponent userId="user-1" />, {wrapper: Wrapper})
+    rerender(<TestComponent userId="user-2" />)
+
+    expect(getCommentsQueryState).toHaveBeenCalledWith(
+      expect.anything(),
+      expect.objectContaining({params: {userId: 'user-2'}}),
+    )
+  })
+
+  it('keeps the previous list on screen while a different filter loads', async () => {
+    const open = [comment('a')]
+    const resolved = [comment('b'), comment('c')]
+    const byFilter: Record<string, Comment[] | undefined> = {'status == "open"': open}
+    mockSource((options) => byFilter[options.filter])
+
+    let settle: () => void = () => {}
+    vi.mocked(resolveCommentsQuery).mockReturnValue(
+      new Promise<Comment[]>((resolve) => {
+        settle = () => resolve(resolved)
+      }),
+    )
+
+    function TestComponent({filter}: {filter: string}) {
+      const {comments, isPending} = useCommentsQuery({filter})
+      return <div data-testid="out">{`${comments.length} ${isPending ? 'pending' : 'idle'}`}</div>
+    }
+
+    const {rerender} = render(<TestComponent filter='status == "open"' />, {wrapper: Wrapper})
+    expect(screen.getByTestId('out').textContent).toBe('1 idle')
+
+    await act(async () => {
+      rerender(<TestComponent filter='status == "resolved"' />)
+    })
+
+    expect(screen.queryByTestId('suspended')).not.toBeInTheDocument()
+    expect(screen.getByTestId('out').textContent).toBe('1 pending')
+
+    await act(async () => {
+      byFilter['status == "resolved"'] = resolved
+      settle()
+    })
+
+    expect(screen.getByTestId('out').textContent).toBe('2 idle')
+  })
+
+  it('reports a listener that failed after the comments had loaded', async () => {
+    const loaded = [comment('a')]
+    mockSource(() => loaded)
+    const failure: {current: unknown} = {current: undefined}
+    const changed$ = new Subject<void>()
+    mockErrorSource(() => failure.current, changed$)
+
+    function TestComponent() {
+      const {comments, error} = useCommentsQuery({filter: 'status == "open"'})
+      return (
+        <div data-testid="out">{`${comments.length} ${error instanceof Error ? error.message : 'live'}`}</div>
+      )
+    }
+
+    render(<TestComponent />, {wrapper: Wrapper})
+    expect(screen.getByTestId('out').textContent).toBe('1 live')
+
+    await act(async () => {
+      failure.current = new Error('connection failed')
+      changed$.next()
+    })
+
+    expect(screen.getByTestId('out').textContent).toBe('1 connection failed')
+  })
+})