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

package/src/hooks/auth/useVerifyOrgProjects.tsx

@@ -27,13 +27,20 @@ export function useVerifyOrgProjects(disabled = false, projectIds?: string[]): s
   const instance = useSanityInstance()
   const [error, setError] = useState<string | null>(null)
 
+  const isInactive = disabled || !projectIds || projectIds.length === 0
+
+  // Reset stale errors when verification turns off so the next activation
+  // doesn't briefly leak the previous result.
+  const [prevInactive, setPrevInactive] = useState(isInactive)
+  if (prevInactive !== isInactive) {
+    setPrevInactive(isInactive)
+    if (isInactive) setError(null)
+  }
+
   useEffect(() => {
-    if (disabled || !projectIds || projectIds.length === 0) {
-      if (error !== null) setError(null)
-      return
-    }
+    if (isInactive) return
 
-    const verificationObservable$ = observeOrganizationVerificationState(instance, projectIds)
+    const verificationObservable$ = observeOrganizationVerificationState(instance, projectIds!)
 
     const subscription = verificationObservable$.subscribe((result: OrgVerificationResult) => {
       setError(result.error)
@@ -42,7 +49,7 @@ export function useVerifyOrgProjects(disabled = false, projectIds?: string[]): s
     return () => {
       subscription.unsubscribe()
     }
-  }, [instance, disabled, error, projectIds])
+  }, [instance, isInactive, projectIds])
 
   return error
 }

package/src/hooks/client/useClient.test.tsx

@@ -6,10 +6,7 @@ import {useClient} from './useClient'
 
 describe('useClient', () => {
   const wrapper = ({children}: {children: React.ReactNode}) => (
-    <ResourceProvider
-      resource={{projectId: 'test-project', dataset: 'test-dataset'}}
-      fallback={null}
-    >
+    <ResourceProvider projectId="test-project" dataset="test-dataset" fallback={null}>
       {children}
     </ResourceProvider>
   )

package/src/hooks/client/useClient.ts

@@ -39,4 +39,5 @@ export const useClient = createStateSourceHook({
     }
     return getClientState(instance, options)
   },
+  getConfig: (options: ClientOptions) => options,
 })

package/src/hooks/comlink/useFrameConnection.test.tsx

@@ -4,7 +4,7 @@ import {beforeEach, describe, expect, it, vi} from 'vitest'
 import {act, renderHook} from '../../../test/test-utils'
 import {useFrameConnection} from './useFrameConnection'
 
-vi.mock(import('@sanity/sdk'), async (importOriginal) => {
+vi.mock(import('@sanity/sdk/comlink'), async (importOriginal) => {
   const actual = await importOriginal()
   return {
     ...actual,
@@ -14,7 +14,8 @@ vi.mock(import('@sanity/sdk'), async (importOriginal) => {
   }
 })
 
-const {getOrCreateChannel, getOrCreateController, releaseChannel} = await import('@sanity/sdk')
+const {getOrCreateChannel, getOrCreateController, releaseChannel} =
+  await import('@sanity/sdk/comlink')
 
 interface TestControllerMessage {
   type: 'TEST_MESSAGE'

package/src/hooks/comlink/useFrameConnection.ts

@@ -5,7 +5,7 @@ import {
   getOrCreateController,
   releaseChannel,
   type WindowMessage,
-} from '@sanity/sdk'
+} from '@sanity/sdk/comlink'
 import {useCallback, useEffect, useRef} from 'react'
 
 import {useSanityInstance} from '../context/useSanityInstance'

package/src/hooks/comlink/useWindowConnection.test.tsx

@@ -1,5 +1,6 @@
 import {type Message, type Node} from '@sanity/comlink'
-import {getNodeState, type NodeState, type StateSource} from '@sanity/sdk'
+import {type StateSource} from '@sanity/sdk'
+import {getNodeState, type NodeState} from '@sanity/sdk/comlink'
 import {screen} from '@testing-library/react'
 import {Suspense} from 'react'
 import {beforeEach, describe, expect, it, vi} from 'vitest'
@@ -7,8 +8,8 @@ import {beforeEach, describe, expect, it, vi} from 'vitest'
 import {render, renderHook} from '../../../test/test-utils'
 import {useWindowConnection} from './useWindowConnection'
 
-vi.mock('@sanity/sdk', async () => {
-  const actual = await vi.importActual('@sanity/sdk')
+vi.mock('@sanity/sdk/comlink', async () => {
+  const actual = await vi.importActual('@sanity/sdk/comlink')
   return {
     ...actual,
     getNodeState: vi.fn(),

package/src/hooks/comlink/useWindowConnection.ts

@@ -1,12 +1,11 @@
 import {type MessageData, type NodeInput} from '@sanity/comlink'
+import {type SanityInstance, type StateSource} from '@sanity/sdk'
 import {
   type FrameMessage,
   getNodeState,
   type NodeState,
-  type SanityInstance,
-  type StateSource,
   type WindowMessage,
-} from '@sanity/sdk'
+} from '@sanity/sdk/comlink'
 import {useCallback, useEffect, useRef} from 'react'
 import {filter, firstValueFrom} from 'rxjs'
 

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

@@ -0,0 +1,150 @@
+import {
+  createComment,
+  removeComment,
+  replyToComment,
+  setCommentStatus,
+  updateComment,
+} from '@sanity/sdk'
+import {renderHook} from '@testing-library/react'
+import {beforeEach, describe, expect, it, vi} from 'vitest'
+
+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')>()
+  return {
+    ...original,
+    createComment: vi.fn(),
+    replyToComment: vi.fn(),
+    updateComment: vi.fn(),
+    setCommentStatus: vi.fn(),
+    removeComment: vi.fn(),
+  }
+})
+
+const HANDLE = {documentId: 'doc-1', documentType: 'author'}
+
+/** Creates name a field, since a comment with no path is refused. */
+const CREATE = {...HANDLE, fieldPath: 'name'}
+
+// 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'}}
+
+/** Hoisted for the same reason as `RESOURCES`. */
+const RELEASE_PERSPECTIVE = {releaseName: 'summer'}
+
+function Wrapper({children}: {children: React.ReactNode}) {
+  return (
+    <ResourceProvider projectId="p" dataset="d" fallback={null}>
+      <ResourcesContext.Provider value={RESOURCES}>{children}</ResourcesContext.Provider>
+    </ResourceProvider>
+  )
+}
+
+function PerspectiveWrapper({children}: {children: React.ReactNode}) {
+  return (
+    <ResourceProvider projectId="p" dataset="d" perspective={RELEASE_PERSPECTIVE} fallback={null}>
+      <ResourcesContext.Provider value={RESOURCES}>{children}</ResourcesContext.Provider>
+    </ResourceProvider>
+  )
+}
+
+function setup(wrapper: typeof Wrapper = Wrapper) {
+  return renderHook(() => useCommentActions(), {wrapper})
+}
+
+describe('useCommentActions', () => {
+  beforeEach(() => {
+    vi.resetAllMocks()
+  })
+
+  it('keeps the callbacks stable across renders', () => {
+    const {result, rerender} = setup()
+    const first = result.current
+
+    rerender()
+
+    expect(result.current).toBe(first)
+  })
+
+  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.setCommentStatus({commentId: 'c1', status: 'resolved'})
+    result.current.removeComment({commentId: 'c1'})
+
+    expect(createComment).toHaveBeenCalledOnce()
+    expect(replyToComment).toHaveBeenCalledOnce()
+    expect(updateComment).toHaveBeenCalledOnce()
+    expect(setCommentStatus).toHaveBeenCalledOnce()
+    expect(removeComment).toHaveBeenCalledOnce()
+  })
+
+  it('fills in the resource from context', () => {
+    const {result} = setup()
+
+    result.current.createComment({...CREATE, message: null})
+
+    expect(createComment).toHaveBeenCalledWith(
+      expect.anything(),
+      expect.objectContaining({resource: {projectId: 'p', dataset: 'd'}}),
+    )
+  })
+
+  it('lets a call choose a different named resource', () => {
+    // Resolution happens per call, so one set of callbacks serves several
+    // resources.
+    const {result} = setup()
+
+    result.current.removeComment({commentId: 'c1', resourceName: 'other'})
+
+    expect(removeComment).toHaveBeenCalledWith(
+      expect.anything(),
+      expect.objectContaining({resource: {projectId: 'p2', dataset: 'd2'}}),
+    )
+  })
+
+  it('rejects a call naming a resource that is not in context', () => {
+    const {result} = setup()
+
+    expect(() => result.current.removeComment({commentId: 'c1', resourceName: 'missing'})).toThrow(
+      /no resource named "missing"/,
+    )
+  })
+
+  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.
+    const {result} = setup(PerspectiveWrapper)
+
+    result.current.createComment({...CREATE, message: null})
+    result.current.replyToComment({...HANDLE, parentCommentId: 'p1', message: null})
+
+    expect(createComment).toHaveBeenCalledWith(
+      expect.anything(),
+      expect.objectContaining({perspective: RELEASE_PERSPECTIVE}),
+    )
+    expect(replyToComment).toHaveBeenCalledWith(
+      expect.anything(),
+      expect.objectContaining({perspective: RELEASE_PERSPECTIVE}),
+    )
+  })
+
+  it('lets a call override the perspective from context', () => {
+    const {result} = setup(PerspectiveWrapper)
+
+    result.current.createComment({...CREATE, message: null, perspective: 'published'})
+
+    expect(createComment).toHaveBeenCalledWith(
+      expect.anything(),
+      expect.objectContaining({perspective: 'published'}),
+    )
+  })
+})

package/src/hooks/comments/useCommentActions.ts

@@ -0,0 +1,109 @@
+import {
+  type Comment,
+  createComment,
+  type CreateCommentOptions,
+  type DocumentResource,
+  type PerspectiveHandle,
+  removeComment,
+  type RemoveCommentOptions,
+  replyToComment,
+  type ReplyToCommentOptions,
+  setCommentStatus,
+  type SetCommentStatusOptions,
+  updateComment,
+  type UpdateCommentOptions,
+} from '@sanity/sdk'
+import {useContext, useMemo} from 'react'
+
+import {PerspectiveContext} from '../../context/PerspectiveContext'
+import {ResourcesContext} from '../../context/ResourcesContext'
+import {useSanityInstance} from '../context/useSanityInstance'
+import {
+  normalizeResourceOptions,
+  useEffectiveContextResource,
+  type WithResourceNameSupport,
+} from '../helpers/useNormalizedResourceOptions'
+import {trackHookUsage} from '../helpers/useTrackHookUsage'
+
+/**
+ * @public
+ * @category Types
+ */
+export interface CommentActions {
+  /** Starts a thread on a document, or on one of its 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>
+  /** 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>
+}
+
+type Resolvable = {
+  resource?: DocumentResource
+  resourceName?: string
+  projectId?: string
+  dataset?: string
+  perspective?: PerspectiveHandle['perspective']
+}
+
+/**
+ * Returns the five 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.
+ *
+ * Creating is the exception, and `replyToComment` counts as creating. A comment
+ * 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.
+ *
+ * @category Comments
+ * @function
+ * @returns The five write actions
+ *
+ * @example Resolve a thread
+ * ```tsx
+ * function ResolveButton({commentId}: {commentId: string}) {
+ *   const {setCommentStatus} = useCommentActions()
+ *
+ *   return (
+ *     <button onClick={() => setCommentStatus({commentId, status: 'resolved'})}>
+ *       Resolve
+ *     </button>
+ *   )
+ * }
+ * ```
+ *
+ * @public
+ */
+export function useCommentActions(): CommentActions {
+  const instance = useSanityInstance()
+  trackHookUsage(instance, 'useCommentActions')
+
+  const resources = useContext(ResourcesContext)
+  const contextResource = useEffectiveContextResource()
+  const contextPerspective = useContext(PerspectiveContext)
+
+  return useMemo(() => {
+    const resolve = <T extends Resolvable>(options: T) =>
+      normalizeResourceOptions(options, resources, contextResource, contextPerspective)
+
+    return {
+      createComment: (options) => createComment(instance, resolve(options)),
+      replyToComment: (options) => replyToComment(instance, resolve(options)),
+      updateComment: (options) => updateComment(instance, resolve(options)),
+      setCommentStatus: (options) => setCommentStatus(instance, resolve(options)),
+      removeComment: (options) => removeComment(instance, resolve(options)),
+    }
+  }, [contextPerspective, contextResource, instance, resources])
+}

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])
+}