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

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

@@ -1,10 +1,13 @@
 import {
+  addReaction,
   createComment,
   removeComment,
+  removeReaction,
   replyToComment,
   setCommentStatus,
   updateComment,
-} from '@sanity/sdk'
+  updateCommentAnchor,
+} from '@sanity/sdk/collaboration'
 import {renderHook} from '@testing-library/react'
 import {beforeEach, describe, expect, it, vi} from 'vitest'
 
@@ -12,15 +15,18 @@ import {ResourceProvider} from '../../context/ResourceProvider'
 import {ResourcesContext} from '../../context/ResourcesContext'
 import {useCommentActions} from './useCommentActions'
 
-vi.mock('@sanity/sdk', async (importOriginal) => {
-  const original = await importOriginal<typeof import('@sanity/sdk')>()
+vi.mock('@sanity/sdk/collaboration', async (importOriginal) => {
+  const original = await importOriginal<typeof import('@sanity/sdk/collaboration')>()
   return {
     ...original,
     createComment: vi.fn(),
     replyToComment: vi.fn(),
     updateComment: vi.fn(),
+    updateCommentAnchor: vi.fn(),
     setCommentStatus: vi.fn(),
     removeComment: vi.fn(),
+    addReaction: vi.fn(),
+    removeReaction: vi.fn(),
   }
 })
 
@@ -29,6 +35,14 @@ const HANDLE = {documentId: 'doc-1', documentType: 'author'}
 /** Creates name a field, since a comment with no path is refused. */
 const CREATE = {...HANDLE, fieldPath: 'name'}
 
+const MESSAGE = [{_type: 'block', _key: 'b1', children: [{_type: 'span', text: 'hi'}]}]
+
+const ANCHOR = {
+  type: 'portable-text',
+  start: {_key: 'b1', offset: 0},
+  end: {_key: 'b1', offset: 5},
+} as const
+
 // Hoisted: an inline object here would be a new value on every render, and the
 // callbacks are memoised against it.
 const RESOURCES = {other: {projectId: 'p2', dataset: 'd2'}}
@@ -73,23 +87,29 @@ describe('useCommentActions', () => {
   it('forwards each action to the store', () => {
     const {result} = setup()
 
-    result.current.createComment({...CREATE, message: null})
-    result.current.replyToComment({...HANDLE, parentCommentId: 'p1', message: null})
-    result.current.updateComment({commentId: 'c1', message: null})
+    result.current.createComment({...CREATE, message: MESSAGE})
+    result.current.replyToComment({...HANDLE, parentCommentId: 'p1', message: MESSAGE})
+    result.current.updateComment({commentId: 'c1', message: MESSAGE})
+    result.current.updateCommentAnchor({commentId: 'c1', anchor: ANCHOR})
     result.current.setCommentStatus({commentId: 'c1', status: 'resolved'})
     result.current.removeComment({commentId: 'c1'})
+    result.current.addReaction({commentId: 'c1', shortName: ':+1:'})
+    result.current.removeReaction({commentId: 'c1', shortName: ':+1:'})
 
     expect(createComment).toHaveBeenCalledOnce()
     expect(replyToComment).toHaveBeenCalledOnce()
     expect(updateComment).toHaveBeenCalledOnce()
+    expect(updateCommentAnchor).toHaveBeenCalledOnce()
     expect(setCommentStatus).toHaveBeenCalledOnce()
     expect(removeComment).toHaveBeenCalledOnce()
+    expect(addReaction).toHaveBeenCalledOnce()
+    expect(removeReaction).toHaveBeenCalledOnce()
   })
 
   it('fills in the resource from context', () => {
     const {result} = setup()
 
-    result.current.createComment({...CREATE, message: null})
+    result.current.createComment({...CREATE, message: MESSAGE})
 
     expect(createComment).toHaveBeenCalledWith(
       expect.anything(),
@@ -119,13 +139,13 @@ describe('useCommentActions', () => {
   })
 
   it('fills in the perspective from context', () => {
-    // Core turns a release perspective into `target.documentVersionId`, so
-    // losing it here files the comment against the wrong release and nothing
-    // reports an error.
+    // Core turns a release perspective into the source document id the comment
+    // is written against, so losing it here files the comment against the wrong
+    // release and nothing reports an error.
     const {result} = setup(PerspectiveWrapper)
 
-    result.current.createComment({...CREATE, message: null})
-    result.current.replyToComment({...HANDLE, parentCommentId: 'p1', message: null})
+    result.current.createComment({...CREATE, message: MESSAGE})
+    result.current.replyToComment({...HANDLE, parentCommentId: 'p1', message: MESSAGE})
 
     expect(createComment).toHaveBeenCalledWith(
       expect.anything(),
@@ -140,7 +160,7 @@ describe('useCommentActions', () => {
   it('lets a call override the perspective from context', () => {
     const {result} = setup(PerspectiveWrapper)
 
-    result.current.createComment({...CREATE, message: null, perspective: 'published'})
+    result.current.createComment({...CREATE, message: MESSAGE, perspective: 'published'})
 
     expect(createComment).toHaveBeenCalledWith(
       expect.anything(),

package/src/hooks/comments/useCommentActions.ts

@@ -1,18 +1,22 @@
+import {type DocumentResource, type PerspectiveHandle} from '@sanity/sdk'
 import {
+  addReaction,
   type Comment,
   createComment,
   type CreateCommentOptions,
-  type DocumentResource,
-  type PerspectiveHandle,
+  type ReactionOptions,
   removeComment,
   type RemoveCommentOptions,
+  removeReaction,
   replyToComment,
   type ReplyToCommentOptions,
   setCommentStatus,
   type SetCommentStatusOptions,
   updateComment,
+  updateCommentAnchor,
+  type UpdateCommentAnchorOptions,
   type UpdateCommentOptions,
-} from '@sanity/sdk'
+} from '@sanity/sdk/collaboration'
 import {useContext, useMemo} from 'react'
 
 import {PerspectiveContext} from '../../context/PerspectiveContext'
@@ -26,21 +30,31 @@ import {
 import {trackHookUsage} from '../helpers/useTrackHookUsage'
 
 /**
- * @public
+ * @beta
  * @category Types
  * @category Comments
  */
 export interface CommentActions {
-  /** Starts a thread on a document, or on one of its fields. */
+  /** Starts a thread on one of a document's fields. */
   createComment: (options: WithResourceNameSupport<CreateCommentOptions>) => Promise<Comment>
   /** Adds a reply to an existing thread. */
   replyToComment: (options: WithResourceNameSupport<ReplyToCommentOptions>) => Promise<Comment>
   /** Rewrites a comment's message. */
   updateComment: (options: WithResourceNameSupport<UpdateCommentOptions>) => Promise<void>
+  /**
+   * Re-anchors a comment to a different run of text, without marking it edited.
+   */
+  updateCommentAnchor: (
+    options: WithResourceNameSupport<UpdateCommentAnchorOptions>,
+  ) => Promise<void>
   /** Resolves or reopens a thread. Pass the thread's first comment. */
   setCommentStatus: (options: WithResourceNameSupport<SetCommentStatusOptions>) => Promise<void>
   /** Deletes a comment, and its replies when it starts a thread. */
   removeComment: (options: WithResourceNameSupport<RemoveCommentOptions>) => Promise<void>
+  /** Adds the current user's reaction to a comment. */
+  addReaction: (options: WithResourceNameSupport<ReactionOptions>) => Promise<void>
+  /** Removes the current user's reaction from a comment. */
+  removeReaction: (options: WithResourceNameSupport<ReactionOptions>) => Promise<void>
 }
 
 type Resolvable = {
@@ -52,25 +66,28 @@ type Resolvable = {
 }
 
 /**
- * Returns the five comment write actions, bound to the current instance.
+ * Returns the comment write actions, bound to the current instance.
  *
  * Each writes optimistically: the change shows immediately and is rolled back
  * if the server rejects it, so an app can render straight from
- * {@link useComments} without tracking pending state itself.
+ * {@link useCommentThreads} without tracking pending state itself.
  *
  * Creating is the exception, and `replyToComment` counts as creating. A comment
- * that fails to post stays on screen carrying `_state.createError` rather than
+ * that fails to post stays on screen carrying `state.createError` rather than
  * disappearing, so passing the same `commentId` again retries it instead of
  * losing what someone typed.
  *
  * The resource is resolved when an action is called rather than when the hook
  * runs, so one set of callbacks works across several resources. Pass `resource`
  * or `resourceName` per call to choose; otherwise the surrounding
- * `ResourceProvider` decides.
+ * `ResourceProvider` decides. The organization the comments live in is
+ * resolved per call as well: the one the Dashboard opened the app in, else
+ * `organizationId` on the Sanity config, else the organization owning the
+ * resource's project. It cannot be passed on the call.
  *
  * @category Comments
  * @function
- * @returns The five write actions
+ * @returns The write actions
  *
  * @example Resolve a thread
  * ```tsx
@@ -85,7 +102,7 @@ type Resolvable = {
  * }
  * ```
  *
- * @public
+ * @beta
  */
 export function useCommentActions(): CommentActions {
   const instance = useSanityInstance()
@@ -103,8 +120,11 @@ export function useCommentActions(): CommentActions {
       createComment: (options) => createComment(instance, resolve(options)),
       replyToComment: (options) => replyToComment(instance, resolve(options)),
       updateComment: (options) => updateComment(instance, resolve(options)),
+      updateCommentAnchor: (options) => updateCommentAnchor(instance, resolve(options)),
       setCommentStatus: (options) => setCommentStatus(instance, resolve(options)),
       removeComment: (options) => removeComment(instance, resolve(options)),
+      addReaction: (options) => addReaction(instance, resolve(options)),
+      removeReaction: (options) => removeReaction(instance, resolve(options)),
     }
   }, [contextPerspective, contextResource, instance, resources])
 }

package/src/hooks/comments/useCommentList.ts

@@ -1,5 +1,4 @@
-import {type CommentsOptions, type SanityInstance, type StateSource} from '@sanity/sdk'
-import {getCommentsOptionsKey, parseCommentsOptionsKey} from '@sanity/sdk/_internal'
+import {type DocumentResource, type SanityInstance, type StateSource} from '@sanity/sdk'
 import {useEffect, useMemo, useRef, useState, useSyncExternalStore, useTransition} from 'react'
 
 import {useSanityInstance} from '../context/useSanityInstance'
@@ -9,17 +8,22 @@ import {
 } from '../helpers/useNormalizedResourceOptions'
 import {trackHookUsage} from '../helpers/useTrackHookUsage'
 
-/** The pair of core functions backing one read hook. */
-export interface CommentListSource<T> {
-  getState: (instance: SanityInstance, options: CommentsOptions) => StateSource<T | undefined>
-  resolve: (
-    instance: SanityInstance,
-    options: CommentsOptions & {signal?: AbortSignal},
-  ) => Promise<T>
+/**
+ * The core functions backing one read hook, plus the option-key pair that keeps
+ * its state source steady across renders.
+ *
+ * @internal
+ */
+export interface CommentListSource<TOptions, TValue> {
+  getState: (instance: SanityInstance, options: TOptions) => StateSource<TValue | undefined>
+  getErrorState: (instance: SanityInstance, options: TOptions) => StateSource<unknown>
+  resolve: (instance: SanityInstance, options: TOptions & {signal?: AbortSignal}) => Promise<TValue>
+  getKey: (options: TOptions) => string
+  parseKey: (key: string) => TOptions
 }
 
 /**
- * Shared body of {@link useComments} and {@link useCommentThreads}.
+ * Shared body of the comment read hooks.
  *
  * Suspends until the first snapshot arrives. Changing documents or filters
  * happens in a transition, so the list already on screen stays put and
@@ -27,20 +31,23 @@ export interface CommentListSource<T> {
  * previous read is aborted, which drops its listener when nothing else is
  * reading it.
  *
+ * A listener that fails after the list has loaded is reported through `error`
+ * rather than thrown: the list stays on screen, frozen as it last stood.
+ *
  * @internal
  */
-export function useCommentList<T>(
+export function useCommentList<TOptions extends {resource?: DocumentResource}, TValue>(
   hookName: string,
-  options: WithResourceNameSupport<CommentsOptions>,
-  {getState, resolve}: CommentListSource<T>,
-): {value: T; isPending: boolean} {
+  options: WithResourceNameSupport<TOptions>,
+  {getState, getErrorState, resolve, getKey, parseKey}: CommentListSource<TOptions, TValue>,
+): {value: TValue; isPending: boolean; error: unknown} {
   const instance = useSanityInstance()
   trackHookUsage(instance, hookName)
 
-  const normalized = useNormalizedResourceOptions(options)
+  const normalized = useNormalizedResourceOptions(options) as TOptions
   const [isPending, startTransition] = useTransition()
 
-  const key = getCommentsOptionsKey(normalized)
+  const key = getKey(normalized)
   // Held one render behind `key`, so the swap can happen inside a transition.
   const [deferredKey, setDeferredKey] = useState(key)
   const abortRef = useRef<AbortController>(new AbortController())
@@ -57,11 +64,15 @@ export function useCommentList<T>(
     })
   }, [deferredKey, key])
 
-  const deferred = useMemo(() => parseCommentsOptionsKey(deferredKey), [deferredKey])
+  const deferred = useMemo(() => parseKey(deferredKey), [deferredKey, parseKey])
   const {getCurrent, subscribe} = useMemo(
     () => getState(instance, deferred),
     [deferred, getState, instance],
   )
+  const errorSource = useMemo(
+    () => getErrorState(instance, deferred),
+    [deferred, getErrorState, instance],
+  )
 
   if (getCurrent() === undefined) {
     // Reading the ref mid-render is safe here: React runs no effects for a
@@ -73,7 +84,11 @@ export function useCommentList<T>(
     throw resolve(instance, {...deferred, signal: currentSignal})
   }
 
-  // Not memoised: both callers destructure this immediately and memoise their
+  // Not memoised: every caller destructures this immediately and memoises its
   // own result object, so a stable identity here would never be observed.
-  return {value: useSyncExternalStore(subscribe, getCurrent) as T, isPending}
+  return {
+    value: useSyncExternalStore(subscribe, getCurrent) as TValue,
+    isPending,
+    error: useSyncExternalStore(errorSource.subscribe, errorSource.getCurrent),
+  }
 }

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

@@ -1,20 +1,28 @@
+import {type StateSource} from '@sanity/sdk'
 import {
+  type CommentsOptions,
   type CommentThread,
+  getCommentsErrorState,
   getCommentThreadsState,
   resolveCommentThreads,
-  type StateSource,
-} from '@sanity/sdk'
+} from '@sanity/sdk/collaboration'
 import {act, render, screen} from '@testing-library/react'
 import {Suspense} from 'react'
-import {type Observable} from 'rxjs'
+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 {useCommentThreads} from './useCommentThreads'
 
-vi.mock('@sanity/sdk', async (importOriginal) => {
-  const original = await importOriginal<typeof import('@sanity/sdk')>()
-  return {...original, getCommentThreadsState: vi.fn(), resolveCommentThreads: vi.fn()}
+vi.mock('@sanity/sdk/collaboration', async (importOriginal) => {
+  const original = await importOriginal<typeof import('@sanity/sdk/collaboration')>()
+  return {
+    ...original,
+    getCommentThreadsState: vi.fn(),
+    getCommentsErrorState: vi.fn(),
+    resolveCommentThreads: vi.fn(),
+  }
 })
 
 const HANDLE = {documentId: 'doc-1', documentType: 'author'}
@@ -23,19 +31,72 @@ function thread(threadId: string) {
   return {threadId, commentsCount: 2, fieldPath: ''} as CommentThread
 }
 
-function mockSource(getCurrent: () => CommentThread[] | undefined) {
-  vi.mocked(getCommentThreadsState).mockReturnValue({
-    getCurrent,
-    subscribe: vi.fn(() => () => {}),
-    get observable(): Observable<CommentThread[] | undefined> {
-      throw new Error('Not implemented')
-    },
-  } as StateSource<CommentThread[] | undefined>)
+/**
+ * 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.
+ */
+function mockSource(
+  getCurrent: (options: CommentsOptions) => CommentThread[] | undefined,
+  changed$?: Subject<void>,
+) {
+  vi.mocked(getCommentThreadsState).mockImplementation(
+    (_instance, options) =>
+      ({
+        getCurrent: () => getCurrent(options),
+        subscribe: vi.fn((cb?: () => void) => {
+          const subscription = changed$?.subscribe(() => cb?.())
+          return () => subscription?.unsubscribe()
+        }),
+        get observable(): Observable<CommentThread[] | undefined> {
+          throw new Error('Not implemented')
+        },
+      }) as StateSource<CommentThread[] | undefined>,
+  )
+  mockErrorSource(() => undefined)
 }
 
+/** The companion source, live by default. Call again to override. */
+function mockErrorSource(getCurrent: () => unknown, changed$?: Subject<void>) {
+  vi.mocked(getCommentsErrorState).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>,
+  )
+}
+
+/** 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>
   )
@@ -60,10 +121,11 @@ describe('useCommentThreads', () => {
     expect(screen.getByTestId('out').textContent).toBe('2 idle')
   })
 
-  it('suspends until the threads are available', async () => {
+  it('suspends until the first snapshot arrives', async () => {
     const loaded = [thread('t1')]
     const ref: {current: CommentThread[] | undefined} = {current: undefined}
-    mockSource(() => ref.current)
+    const changed$ = new Subject<void>()
+    mockSource(() => ref.current, changed$)
 
     let settle: () => void = () => {}
     vi.mocked(resolveCommentThreads).mockReturnValue(
@@ -88,12 +150,40 @@ describe('useCommentThreads', () => {
     expect(screen.getByTestId('out').textContent).toBe('1')
   })
 
-  it('narrows to one field when asked', () => {
+  it('passes the field path, status, and scope through to the store', () => {
+    const loaded: CommentThread[] = []
+    mockSource(() => loaded)
+
+    function TestComponent() {
+      useCommentThreads({
+        ...HANDLE,
+        fieldPath: ['body', {_key: 'intro'}],
+        status: 'resolved',
+        scope: 'all',
+      })
+      return null
+    }
+
+    render(<TestComponent />, {wrapper: Wrapper})
+
+    expect(getCommentThreadsState).toHaveBeenCalledWith(
+      expect.anything(),
+      expect.objectContaining({
+        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: CommentThread[] = []
     mockSource(() => loaded)
 
     function TestComponent() {
-      useCommentThreads({...HANDLE, fieldPath: 'title'})
+      useCommentThreads({...HANDLE, resourceName: 'other'})
       return null
     }
 
@@ -101,7 +191,105 @@ describe('useCommentThreads', () => {
 
     expect(getCommentThreadsState).toHaveBeenCalledWith(
       expect.anything(),
-      expect.objectContaining({fieldPath: 'title'}),
+      expect.objectContaining({resource: {projectId: 'p2', dataset: 'd2'}}),
+    )
+  })
+
+  it('fills in the perspective from context', () => {
+    // The perspective decides which comments the default `scope` covers, so
+    // dropping it here would quietly read a release's comments as if they were
+    // the draft's.
+    const loaded: CommentThread[] = []
+    mockSource(() => loaded)
+
+    function TestComponent() {
+      useCommentThreads(HANDLE)
+      return null
+    }
+
+    render(<TestComponent />, {wrapper: PerspectiveWrapper})
+
+    expect(getCommentThreadsState).toHaveBeenCalledWith(
+      expect.anything(),
+      expect.objectContaining({perspective: RELEASE_PERSPECTIVE}),
+    )
+  })
+
+  it('keeps the previous list on screen while a different document loads', async () => {
+    const first = [thread('t1')]
+    const second = [thread('t2'), thread('t3')]
+    // Only `doc-1` is loaded, so switching to `doc-2` has to suspend.
+    const byDocument: Record<string, CommentThread[] | undefined> = {'doc-1': first}
+    mockSource((options) => byDocument[options.documentId])
+
+    let settle: () => void = () => {}
+    vi.mocked(resolveCommentThreads).mockReturnValue(
+      new Promise<CommentThread[]>((resolve) => {
+        settle = () => resolve(second)
+      }),
+    )
+
+    function TestComponent({documentId}: {documentId: string}) {
+      const {threads, isPending} = useCommentThreads({...HANDLE, documentId})
+      return <div data-testid="out">{`${threads.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(getCommentThreadsState).toHaveBeenCalledWith(
+      expect.anything(),
+      expect.objectContaining({documentId: 'doc-2'}),
     )
+
+    await act(async () => {
+      byDocument['doc-2'] = second
+      settle()
+    })
+
+    expect(screen.getByTestId('out').textContent).toBe('2 idle')
+  })
+
+  it('reports a listener that failed after the threads had loaded', async () => {
+    const loaded = [thread('t1')]
+    mockSource(() => loaded)
+    const failure: {current: unknown} = {current: undefined}
+    const changed$ = new Subject<void>()
+    mockErrorSource(() => failure.current, changed$)
+
+    function TestComponent() {
+      const {threads, error} = useCommentThreads(HANDLE)
+      return (
+        <div data-testid="out">{`${threads.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()
+    })
+
+    // The threads are still on screen; only their claim to being current is
+    // withdrawn.
+    expect(screen.getByTestId('out').textContent).toBe('1 connection failed')
+
+    await act(async () => {
+      failure.current = undefined
+      changed$.next()
+    })
+
+    expect(screen.getByTestId('out').textContent).toBe('1 live')
   })
 })