@sanity/sdk-react 3.0.0-rc.1 → 3.0.0-rc.2

package/src/hooks/comments/useCommentList.ts

@@ -0,0 +1,79 @@
+import {type CommentsOptions, type SanityInstance, type StateSource} from '@sanity/sdk'
+import {getCommentsOptionsKey, parseCommentsOptionsKey} from '@sanity/sdk/_internal'
+import {useEffect, useMemo, useRef, useState, useSyncExternalStore, useTransition} from 'react'
+
+import {useSanityInstance} from '../context/useSanityInstance'
+import {
+  useNormalizedResourceOptions,
+  type WithResourceNameSupport,
+} 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>
+}
+
+/**
+ * Shared body of {@link useComments} and {@link useCommentThreads}.
+ *
+ * Suspends until the first snapshot arrives. Changing documents or filters
+ * happens in a transition, so the list already on screen stays put and
+ * `isPending` reports the swap instead of the component suspending again. The
+ * previous read is aborted, which drops its listener when nothing else is
+ * reading it.
+ *
+ * @internal
+ */
+export function useCommentList<T>(
+  hookName: string,
+  options: WithResourceNameSupport<CommentsOptions>,
+  {getState, resolve}: CommentListSource<T>,
+): {value: T; isPending: boolean} {
+  const instance = useSanityInstance()
+  trackHookUsage(instance, hookName)
+
+  const normalized = useNormalizedResourceOptions(options)
+  const [isPending, startTransition] = useTransition()
+
+  const key = getCommentsOptionsKey(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())
+
+  useEffect(() => {
+    if (key === deferredKey) return
+
+    startTransition(() => {
+      if (!abortRef.current.signal.aborted) {
+        abortRef.current.abort()
+        abortRef.current = new AbortController()
+      }
+      setDeferredKey(key)
+    })
+  }, [deferredKey, key])
+
+  const deferred = useMemo(() => parseCommentsOptionsKey(deferredKey), [deferredKey])
+  const {getCurrent, subscribe} = useMemo(
+    () => getState(instance, deferred),
+    [deferred, getState, instance],
+  )
+
+  if (getCurrent() === undefined) {
+    // Reading the ref mid-render is safe here: React runs no effects for a
+    // render that suspends, so the signal captured now cannot be swapped
+    // underneath this pass.
+    const currentSignal = abortRef.current.signal
+
+    // eslint-disable-next-line react-hooks/refs -- intentional during a suspended render; see above
+    throw resolve(instance, {...deferred, signal: currentSignal})
+  }
+
+  // Not memoised: both callers destructure this immediately and memoise their
+  // own result object, so a stable identity here would never be observed.
+  return {value: useSyncExternalStore(subscribe, getCurrent) as T, isPending}
+}

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

@@ -0,0 +1,107 @@
+import {
+  type CommentThread,
+  getCommentThreadsState,
+  resolveCommentThreads,
+  type StateSource,
+} from '@sanity/sdk'
+import {act, render, screen} from '@testing-library/react'
+import {Suspense} from 'react'
+import {type Observable} from 'rxjs'
+import {beforeEach, describe, expect, it, vi} from 'vitest'
+
+import {ResourceProvider} from '../../context/ResourceProvider'
+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()}
+})
+
+const HANDLE = {documentId: 'doc-1', documentType: 'author'}
+
+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>)
+}
+
+function Wrapper({children}: {children: React.ReactNode}) {
+  return (
+    <ResourceProvider projectId="p" dataset="d" fallback={<p>Loading…</p>}>
+      <Suspense fallback={<p data-testid="suspended">Suspended</p>}>{children}</Suspense>
+    </ResourceProvider>
+  )
+}
+
+describe('useCommentThreads', () => {
+  beforeEach(() => {
+    vi.resetAllMocks()
+  })
+
+  it('renders the threads once they are loaded', () => {
+    const loaded = [thread('t1'), thread('t2')]
+    mockSource(() => loaded)
+
+    function TestComponent() {
+      const {threads, isPending} = useCommentThreads(HANDLE)
+      return <div data-testid="out">{`${threads.length} ${isPending ? 'pending' : 'idle'}`}</div>
+    }
+
+    render(<TestComponent />, {wrapper: Wrapper})
+
+    expect(screen.getByTestId('out').textContent).toBe('2 idle')
+  })
+
+  it('suspends until the threads are available', async () => {
+    const loaded = [thread('t1')]
+    const ref: {current: CommentThread[] | undefined} = {current: undefined}
+    mockSource(() => ref.current)
+
+    let settle: () => void = () => {}
+    vi.mocked(resolveCommentThreads).mockReturnValue(
+      new Promise<CommentThread[]>((resolve) => {
+        settle = () => resolve(loaded)
+      }),
+    )
+
+    function TestComponent() {
+      const {threads} = useCommentThreads(HANDLE)
+      return <div data-testid="out">{threads.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('narrows to one field when asked', () => {
+    const loaded: CommentThread[] = []
+    mockSource(() => loaded)
+
+    function TestComponent() {
+      useCommentThreads({...HANDLE, fieldPath: 'title'})
+      return null
+    }
+
+    render(<TestComponent />, {wrapper: Wrapper})
+
+    expect(getCommentThreadsState).toHaveBeenCalledWith(
+      expect.anything(),
+      expect.objectContaining({fieldPath: 'title'}),
+    )
+  })
+})

package/src/hooks/comments/useCommentThreads.ts

@@ -0,0 +1,73 @@
+import {
+  type CommentsOptions,
+  type CommentThread,
+  getCommentThreadsState,
+  resolveCommentThreads,
+} from '@sanity/sdk'
+import {useMemo} from 'react'
+
+import {type WithResourceNameSupport} from '../helpers/useNormalizedResourceOptions'
+import {type CommentListSource, useCommentList} from './useCommentList'
+
+/**
+ * @public
+ * @category Types
+ */
+export interface UseCommentThreadsResult {
+  /** Newest thread first, each with its replies oldest first. */
+  threads: CommentThread[]
+  /** True while switching to a different document or filter. */
+  isPending: boolean
+}
+
+const SOURCE: CommentListSource<CommentThread[]> = {
+  getState: getCommentThreadsState,
+  resolve: resolveCommentThreads,
+}
+
+/**
+ * Reads a document's comments grouped into threads.
+ *
+ * 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.
+ *
+ * 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.
+ *
+ * @category Comments
+ * @function
+ * @param options - The document to read, optionally narrowed by `fieldPath` or `status`
+ * @returns The matching threads, and whether a switch is in flight
+ *
+ * @example Render the open threads on a document
+ * ```tsx
+ * function Threads({documentId}: {documentId: string}) {
+ *   const {threads} = useCommentThreads({
+ *     documentId,
+ *     documentType: 'article',
+ *     status: 'open',
+ *   })
+ *
+ *   return (
+ *     <ul>
+ *       {threads.map((thread) => (
+ *         <li key={thread.threadId}>
+ *           {thread.fieldPath || 'Document'} — {thread.commentsCount} comments
+ *         </li>
+ *       ))}
+ *     </ul>
+ *   )
+ * }
+ * ```
+ *
+ * @public
+ */
+export function useCommentThreads(
+  options: WithResourceNameSupport<CommentsOptions>,
+): UseCommentThreadsResult {
+  const {value, isPending} = useCommentList('useCommentThreads', options, SOURCE)
+  return useMemo(() => ({threads: value, isPending}), [isPending, value])
+}

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

@@ -0,0 +1,242 @@
+import {
+  type Comment,
+  type CommentsOptions,
+  getCommentsState,
+  resolveComments,
+  type StateSource,
+} from '@sanity/sdk'
+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()}
+})
+
+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: [],
+  }
+}
+
+/**
+ * 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) => Comment[] | undefined,
+  changed$?: Subject<void>,
+) {
+  vi.mocked(getCommentsState).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>,
+  )
+}
+
+/** 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>
+  )
+}
+
+describe('useComments', () => {
+  beforeEach(() => {
+    vi.resetAllMocks()
+  })
+
+  it('renders the comments once they are loaded', () => {
+    const loaded = [comment('a'), comment('b')]
+    mockSource(() => loaded)
+
+    function TestComponent() {
+      const {comments, isPending} = useComments(HANDLE)
+      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(resolveComments).mockReturnValue(
+      new Promise<Comment[]>((resolve) => {
+        settle = () => resolve(loaded)
+      }),
+    )
+
+    function TestComponent() {
+      const {comments} = useComments(HANDLE)
+      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 field path and status through to the store', () => {
+    const loaded: Comment[] = []
+    mockSource(() => loaded)
+
+    function TestComponent() {
+      useComments({...HANDLE, fieldPath: ['body', {_key: 'intro'}], status: 'resolved'})
+      return null
+    }
+
+    render(<TestComponent />, {wrapper: Wrapper})
+
+    expect(getCommentsState).toHaveBeenCalledWith(
+      expect.anything(),
+      expect.objectContaining({
+        documentId: 'doc-1',
+        fieldPath: 'body[_key=="intro"]',
+        status: 'resolved',
+        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

@@ -0,0 +1,59 @@
+import {type Comment, type CommentsOptions, getCommentsState, resolveComments} from '@sanity/sdk'
+import {useMemo} from 'react'
+
+import {type WithResourceNameSupport} from '../helpers/useNormalizedResourceOptions'
+import {type CommentListSource, useCommentList} from './useCommentList'
+
+/**
+ * @public
+ * @category Types
+ */
+export interface UseCommentsResult {
+  /** Every matching comment, newest first, replies included. */
+  comments: Comment[]
+  /** True while switching to a different document or filter. */
+  isPending: boolean
+}
+
+const SOURCE: CommentListSource<Comment[]> = {
+  getState: getCommentsState,
+  resolve: resolveComments,
+}
+
+/**
+ * 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.
+ *
+ * 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`
+ * @returns The matching comments, and whether a switch is in flight
+ *
+ * @example Count the open threads on a field
+ * ```tsx
+ * function TitleCommentCount({documentId}: {documentId: string}) {
+ *   const {comments} = useComments({
+ *     documentId,
+ *     documentType: 'article',
+ *     fieldPath: 'title',
+ *     status: 'open',
+ *   })
+ *
+ *   return <span>{comments.length}</span>
+ * }
+ * ```
+ *
+ * @public
+ */
+export function useComments(options: WithResourceNameSupport<CommentsOptions>): UseCommentsResult {
+  const {value, isPending} = useCommentList('useComments', options, SOURCE)
+  return useMemo(() => ({comments: value, isPending}), [isPending, value])
+}

package/src/hooks/context/useSanityInstance.test.tsx

@@ -1,7 +1,7 @@
-import {createSanityInstance, type SanityConfig, type SanityInstance} from '@sanity/sdk'
+import {createSanityInstance, type SanityInstance} from '@sanity/sdk'
 import {renderHook} from '@testing-library/react'
 import {type ReactNode} from 'react'
-import {afterEach, beforeEach, describe, expect, it, vi} from 'vitest'
+import {describe, expect, it} from 'vitest'
 
 import {SanityInstanceContext} from '../../context/SanityInstanceContext'
 import {useSanityInstance} from './useSanityInstance'
@@ -49,56 +49,4 @@ describe('useSanityInstance', () => {
     // Should return the instance
     expect(result.current).toBe(instance)
   })
-
-  describe('deprecated config parameter', () => {
-    let warnSpy: ReturnType<typeof vi.spyOn>
-
-    beforeEach(() => {
-      warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {})
-    })
-
-    afterEach(() => {
-      warnSpy.mockRestore()
-    })
-
-    it('should return the current context instance regardless of config', () => {
-      const instance = createSanityInstance({projectId: 'test-project', dataset: 'test-dataset'})
-      const requestedConfig: SanityConfig = {projectId: 'test-project', dataset: 'test-dataset'}
-
-      const {result} = renderHook(() => useSanityInstance(requestedConfig), {
-        wrapper: createWrapper(instance),
-      })
-
-      expect(result.current).toBe(instance)
-    })
-
-    it('should throw if no instance in context even when config is provided', () => {
-      expect(() => {
-        renderHook(() => useSanityInstance({projectId: 'test'}), {
-          wrapper: createWrapper(null),
-        })
-      }).toThrow('SanityInstance context not found')
-    })
-
-    it('warns once when a config argument is passed', () => {
-      const instance = createSanityInstance({projectId: 'test-project', dataset: 'test-dataset'})
-      const {rerender} = renderHook(() => useSanityInstance({projectId: 'test-project'}), {
-        wrapper: createWrapper(instance),
-      })
-
-      expect(warnSpy).toHaveBeenCalledTimes(1)
-      expect(warnSpy).toHaveBeenCalledWith(expect.stringContaining('[useSanityInstance]'))
-
-      rerender()
-      rerender()
-      expect(warnSpy).toHaveBeenCalledTimes(1)
-    })
-
-    it('does not warn when no config is passed', () => {
-      const instance = createSanityInstance({projectId: 'test-project', dataset: 'test-dataset'})
-      renderHook(() => useSanityInstance(), {wrapper: createWrapper(instance)})
-
-      expect(warnSpy).not.toHaveBeenCalled()
-    })
-  })
 })

package/src/hooks/context/useSanityInstance.ts

@@ -1,17 +1,14 @@
-import {type SanityConfig, type SanityInstance} from '@sanity/sdk'
+import {type SanityInstance} from '@sanity/sdk'
 import {useContext} from 'react'
 
 import {SanityInstanceContext} from '../../context/SanityInstanceContext'
 
-const warnedCallers = new Set<string>()
-
 /**
  * Retrieves the current Sanity instance from context
  *
  * @public
  *
  * @category Platform
- * @param config - Deprecated. Formerly used to match against the instance hierarchy.
  * @returns The current Sanity instance
  *
  * @remarks
@@ -26,26 +23,7 @@ const warnedCallers = new Set<string>()
  *
  * @throws Error if no SanityInstance is found in context
  */
-export const useSanityInstance = (
-  /**
-   * @deprecated Passing a config to match against the instance hierarchy is deprecated.
-   * Use `useSanityInstance()` without arguments instead.
-   */
-  config?: SanityConfig,
-): SanityInstance => {
-  if (config !== undefined) {
-    const caller = new Error().stack?.split('\n')[2]?.trim() ?? 'unknown'
-    if (!warnedCallers.has(caller)) {
-      warnedCallers.add(caller)
-      // eslint-disable-next-line no-console
-      console.warn(
-        '[useSanityInstance] Passing a config argument is deprecated and has no effect. ' +
-          'SDK apps use a single instance for all resources, so the config argument is no longer needed. ' +
-          'Call useSanityInstance() without arguments instead, or useResource() to get your currently active resource.',
-      )
-    }
-  }
-
+export const useSanityInstance = (): SanityInstance => {
   const instance = useContext(SanityInstanceContext)
 
   if (!instance) {

package/src/hooks/dashboard/useManageFavorite.ts

@@ -9,10 +9,10 @@ import {
 import {
   type DocumentHandle,
   type FavoriteStatusResponse,
-  type FrameMessage,
   getFavoritesState,
   resolveFavoritesState,
 } from '@sanity/sdk'
+import {type FrameMessage} from '@sanity/sdk/comlink'
 import {useCallback, useMemo, useSyncExternalStore} from 'react'
 
 import {useWindowConnection} from '../comlink/useWindowConnection'