@sanity/sdk-react 2.18.0 → 2.20.0

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/presence/usePresence.ts

@@ -7,7 +7,20 @@ import {useNormalizedResourceOptions} from '../helpers/useNormalizedResourceOpti
 import {trackHookUsage} from '../helpers/useTrackHookUsage'
 
 /**
- * A hook for subscribing to presence information for the current project or Canvas.
+ * Every participant in the current project and dataset, or Canvas.
+ *
+ * Reading presence never announces anything. Call `useReportPresence` to make the
+ * current user visible to others, including to the Studio, which shares the same
+ * presence room.
+ *
+ * This returns everyone in the whole resource and leaves the filtering to you.
+ * Prefer `usePresenceForDocument` when you care about one document: it scopes and
+ * flattens the result for rendering. Note that participants are counted by session,
+ * so one person in two tabs appears twice.
+ *
+ * Presence is scoped to a single project and dataset. It is not a list of everyone
+ * signed in to your organization.
+ *
  * @public
  */
 export function usePresence(options: ResourceHandle = {}): {

package/src/hooks/presence/usePresenceForDocument.test.tsx

@@ -0,0 +1,141 @@
+import {type DocumentPresence, getDocumentPresence} from '@sanity/sdk'
+import {act, renderHook} from '@testing-library/react'
+import {beforeEach, describe, expect, it, vi} from 'vitest'
+
+import {ResourceProvider} from '../../context/ResourceProvider'
+import {usePresenceForDocument} from './usePresenceForDocument'
+
+vi.mock('@sanity/sdk', async (importOriginal) => {
+  const actual = await importOriginal<typeof import('@sanity/sdk')>()
+  return {...actual, getDocumentPresence: vi.fn()}
+})
+
+const entry = (sessionId: string): DocumentPresence =>
+  ({
+    sessionId,
+    documentId: 'movie-1',
+    path: ['title'],
+    lastActiveAt: '2026-07-30T12:00:00Z',
+    user: {sanityUserId: 'u1', profile: {id: 'u1'}, memberships: []},
+  }) as unknown as DocumentPresence
+
+/** A minimal StateSource stand-in whose value can be pushed. */
+function createSource(initial: DocumentPresence[]) {
+  let current = initial
+  const listeners = new Set<() => void>()
+  return {
+    source: {
+      getCurrent: () => current,
+      subscribe: (cb: () => void) => {
+        listeners.add(cb)
+        return () => listeners.delete(cb)
+      },
+    },
+    push: (next: DocumentPresence[]) => {
+      current = next
+      listeners.forEach((cb) => cb())
+    },
+  }
+}
+
+const wrapper = ({children}: {children: React.ReactNode}) => (
+  <ResourceProvider projectId="p" dataset="d" fallback={null}>
+    {children}
+  </ResourceProvider>
+)
+
+describe('usePresenceForDocument', () => {
+  beforeEach(() => {
+    // Without this, `mock.calls[0]` is whatever the previous test did.
+    vi.clearAllMocks()
+  })
+
+  it('returns presence and updates when the store changes', () => {
+    const {source, push} = createSource([entry('s1')])
+    vi.mocked(getDocumentPresence).mockReturnValue(source as never)
+
+    const {result} = renderHook(
+      () => usePresenceForDocument({documentId: 'movie-1', documentType: 'movie'}),
+      {wrapper},
+    )
+
+    expect(result.current.presence).toHaveLength(1)
+
+    act(() => push([entry('s1'), entry('s2')]))
+    expect(result.current.presence).toHaveLength(2)
+  })
+
+  it('passes the document, path, and excludeVersions through', () => {
+    const {source} = createSource([])
+    vi.mocked(getDocumentPresence).mockReturnValue(source as never)
+
+    renderHook(
+      () =>
+        usePresenceForDocument({
+          documentId: 'drafts.movie-1',
+          documentType: 'movie',
+          path: ['cast', {_key: 'm1'}],
+          excludeVersions: true,
+        }),
+      {wrapper},
+    )
+
+    // Already a draft id, so resolution leaves it alone.
+    expect(vi.mocked(getDocumentPresence).mock.calls[0][1]).toMatchObject({
+      documentId: 'drafts.movie-1',
+      path: ['cast', {_key: 'm1'}],
+      excludeVersions: true,
+    })
+  })
+
+  it('reads the same id useReportPresence writes, or reads never match writes', () => {
+    const {source} = createSource([])
+    vi.mocked(getDocumentPresence).mockReturnValue(source as never)
+
+    // Forwarded unresolved, exactly as `useReportPresence` forwards it, so core
+    // resolves both the same way. If these diverged, field-level presence would
+    // silently never match.
+    renderHook(
+      () =>
+        usePresenceForDocument({
+          documentId: 'movie-1',
+          documentType: 'movie',
+          perspective: 'published',
+        }),
+      {wrapper},
+    )
+
+    expect(vi.mocked(getDocumentPresence).mock.calls[0][1]).toMatchObject({
+      documentId: 'movie-1',
+      perspective: 'published',
+    })
+  })
+
+  it('does not rebuild the source when a caller passes a fresh path each render', () => {
+    const {source} = createSource([])
+    vi.mocked(getDocumentPresence).mockReturnValue(source as never)
+
+    const {rerender} = renderHook(
+      // A new array identity every render, which is what real callers write.
+      () => usePresenceForDocument({documentId: 'movie-1', documentType: 'movie', path: ['title']}),
+      {wrapper},
+    )
+
+    rerender()
+    rerender()
+
+    expect(vi.mocked(getDocumentPresence)).toHaveBeenCalledTimes(1)
+  })
+
+  it('returns an empty array rather than undefined before anything arrives', () => {
+    const {source} = createSource(undefined as unknown as DocumentPresence[])
+    vi.mocked(getDocumentPresence).mockReturnValue(source as never)
+
+    const {result} = renderHook(
+      () => usePresenceForDocument({documentId: 'movie-1', documentType: 'movie'}),
+      {wrapper},
+    )
+
+    expect(result.current.presence).toEqual([])
+  })
+})

package/src/hooks/presence/usePresenceForDocument.ts

@@ -0,0 +1,104 @@
+import {type DocumentPresence, getDocumentPresence, isMediaLibraryResource} from '@sanity/sdk'
+import {type Path} from '@sanity/types'
+import {useCallback, useMemo, useSyncExternalStore} from 'react'
+
+import {type DocumentHandle} from '../../config/handles'
+import {useSanityInstance} from '../context/useSanityInstance'
+import {useNormalizedResourceOptions} from '../helpers/useNormalizedResourceOptions'
+import {trackHookUsage} from '../helpers/useTrackHookUsage'
+
+/** @beta */
+export interface UsePresenceForDocumentOptions extends DocumentHandle {
+  /**
+   * Narrows to participants at or below this field path, which is what a field
+   * indicator wants. Omit it for everyone in the document.
+   */
+  path?: Path
+
+  /**
+   * By default a draft, its published version, and any release versions count as
+   * the same document, which is what document lists want. Set this to compare ids
+   * exactly, so that a draft and a release version do not bleed into each other.
+   */
+  excludeVersions?: boolean
+}
+
+/**
+ * Who else is in a document, flattened to one entry per participant per location
+ * so it can be rendered straight against a field.
+ *
+ * Reading presence never announces anything. Use `useReportPresence` to make the
+ * current user visible to others.
+ *
+ * Prefer this over `usePresence` when you care about one document: `usePresence`
+ * returns every participant in the whole project and dataset, leaving the filtering
+ * to you.
+ *
+ * Resolves the document through its perspective exactly as `useReportPresence` does,
+ * so reads match writes. Participants are counted by session, so one person in two
+ * tabs appears twice.
+ *
+ * @example Avatars on a document
+ * ```tsx
+ * const {presence} = usePresenceForDocument({documentId, documentType})
+ * return presence.map((p) => <Avatar key={p.sessionId} user={p.user} />)
+ * ```
+ *
+ * @example Avatars on a single field
+ * ```tsx
+ * const {presence} = usePresenceForDocument({
+ *   documentId,
+ *   documentType,
+ *   path: ['title'],
+ *   excludeVersions: true,
+ * })
+ * ```
+ *
+ * @beta
+ */
+export function usePresenceForDocument(options: UsePresenceForDocumentOptions): {
+  presence: DocumentPresence[]
+} {
+  const {path, excludeVersions, ...handle} = options
+
+  const normalizedOptions = useNormalizedResourceOptions(handle)
+  if (normalizedOptions.resource && isMediaLibraryResource(normalizedOptions.resource)) {
+    throw new Error(
+      'usePresenceForDocument() does not support media library resources. Presence tracking requires a canvas or dataset resource.',
+    )
+  }
+
+  const sanityInstance = useSanityInstance()
+  trackHookUsage(sanityInstance, 'usePresenceForDocument')
+
+  const {resource, perspective} = normalizedOptions
+  const {documentId, liveEdit} = options
+
+  // Serialized so a caller passing a fresh `path` array each render does not
+  // rebuild the state source every render.
+  const pathKey = useMemo(() => JSON.stringify(path ?? null), [path])
+
+  const source = useMemo(
+    () =>
+      getDocumentPresence(sanityInstance, {
+        ...(resource ? {resource} : {}),
+        documentId,
+        // Forwarded, not resolved here, so this matches what `useReportPresence`
+        // sends. Core owns turning a perspective into a specific document id.
+        ...(perspective ? {perspective} : {}),
+        ...(liveEdit ? {liveEdit} : {}),
+        ...(pathKey === 'null' ? {} : {path: JSON.parse(pathKey) as Path}),
+        ...(excludeVersions === undefined ? {} : {excludeVersions}),
+      }),
+    [sanityInstance, resource, documentId, perspective, liveEdit, pathKey, excludeVersions],
+  )
+
+  const subscribe = useCallback((callback: () => void) => source.subscribe(callback), [source])
+  const presence = useSyncExternalStore(
+    subscribe,
+    () => source.getCurrent(),
+    () => source.getCurrent(),
+  )
+
+  return {presence: presence || []}
+}