@sanity/sdk-react 2.18.0 → 2.19.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sanity/sdk-react",
-  "version": "2.18.0",
+  "version": "2.19.0",
   "private": false,
   "description": "Sanity SDK React toolkit for Content OS",
   "keywords": [
@@ -44,19 +44,19 @@
     "access": "public"
   },
   "dependencies": {
-    "@sanity/client": "^7.23.1",
+    "@sanity/client": "^7.23.2",
     "@sanity/message-protocol": "^0.23.0",
-    "@sanity/types": "^6.2.0",
+    "@sanity/types": "^6.5.0",
     "groq": "3.88.1-typegen-experimental.0",
     "react-compiler-runtime": "^1.0.0",
     "react-error-boundary": "^6.1.2",
     "rxjs": "^7.8.2",
-    "@sanity/sdk": "2.18.0"
+    "@sanity/sdk": "2.19.0"
   },
   "devDependencies": {
     "@sanity/browserslist-config": "^1.0.5",
     "@sanity/comlink": "^4.0.1",
-    "@sanity/pkg-utils": "^10.5.8",
+    "@sanity/pkg-utils": "^10.9.2",
     "@testing-library/jest-dom": "^6.9.1",
     "@testing-library/react": "^16.3.2",
     "@types/node": "^24.13.3",
@@ -66,18 +66,18 @@
     "@vitest/coverage-v8": "^4.1.10",
     "babel-plugin-react-compiler": "^1.0.0",
     "eslint": "^10.6.0",
-    "groq-js": "^1.30.3",
+    "groq-js": "^2.0.0",
     "jsdom": "^29.1.1",
     "oxfmt": "^0.58.0",
     "react": "^19.2.7",
     "react-dom": "^19.2.7",
     "rollup-plugin-visualizer": "^7.0.1",
     "typescript": "^6.0.3",
-    "vite": "^8.1.4",
+    "vite": "^8.1.5",
     "vitest": "^4.1.10",
     "@repo/config-eslint": "0.0.0",
-    "@repo/config-test": "0.0.1",
     "@repo/package.bundle": "3.82.0",
+    "@repo/config-test": "0.0.1",
     "@repo/tsconfig": "0.0.1",
     "@repo/package.config": "0.0.1"
   },

package/src/_exports/sdk-react.ts

@@ -78,6 +78,11 @@ export {
   usePaginatedDocuments,
 } from '../hooks/paginatedDocuments/usePaginatedDocuments'
 export {usePresence} from '../hooks/presence/usePresence'
+export {
+  usePresenceForDocument,
+  type UsePresenceForDocumentOptions,
+} from '../hooks/presence/usePresenceForDocument'
+export {useReportPresence, type UseReportPresenceOptions} from '../hooks/presence/useReportPresence'
 export {
   useDocumentPreview,
   type useDocumentPreviewOptions,

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

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

@@ -0,0 +1,202 @@
+import {reportPresence} from '@sanity/sdk'
+import {act, renderHook} from '@testing-library/react'
+import {afterEach, beforeEach, describe, expect, it, vi} from 'vitest'
+
+import {ResourceProvider} from '../../context/ResourceProvider'
+import {useReportPresence} from './useReportPresence'
+
+vi.mock('@sanity/sdk', async (importOriginal) => {
+  const actual = await importOriginal<typeof import('@sanity/sdk')>()
+  return {
+    ...actual,
+    reportPresence: vi.fn(),
+  }
+})
+
+const reported = () => vi.mocked(reportPresence).mock.calls.map(([, params]) => params.locations)
+
+const wrapper = ({children}: {children: React.ReactNode}) => (
+  <ResourceProvider projectId="p" dataset="d" fallback={null}>
+    {children}
+  </ResourceProvider>
+)
+
+describe('useReportPresence', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+    vi.useFakeTimers()
+  })
+
+  afterEach(() => {
+    vi.useRealTimers()
+  })
+
+  it('reports the document with no path or selection keys when neither was given', () => {
+    renderHook(() => useReportPresence({documentId: 'doc-1', documentType: 'movie'}), {wrapper})
+
+    // Keys absent rather than set to `undefined`. The id stays unresolved here:
+    // core turns a perspective into a specific document id, so the read and write
+    // sides cannot drift apart.
+    expect(reported()).toEqual([[{documentId: 'doc-1'}]])
+  })
+
+  it('forwards an explicit perspective for core to resolve', () => {
+    renderHook(
+      () =>
+        useReportPresence({
+          documentId: 'doc-1',
+          documentType: 'movie',
+          perspective: {releaseName: 'autumn'},
+        }),
+      {wrapper},
+    )
+
+    expect(reported()[0][0]).toMatchObject({
+      documentId: 'doc-1',
+      perspective: {releaseName: 'autumn'},
+    })
+  })
+
+  it('forwards liveEdit, which core resolves to the published document', () => {
+    renderHook(
+      () => useReportPresence({documentId: 'doc-1', documentType: 'movie', liveEdit: true}),
+      {wrapper},
+    )
+
+    expect(reported()[0][0]).toMatchObject({documentId: 'doc-1', liveEdit: true})
+  })
+
+  it('picks up an ambient perspective from the provider', () => {
+    // The whole point of resolving after normalization: a perspective set once on
+    // `ResourceProvider` has to reach presence without every call site passing it.
+    const ambient = ({children}: {children: React.ReactNode}) => (
+      <ResourceProvider projectId="p" dataset="d" perspective="published" fallback={null}>
+        {children}
+      </ResourceProvider>
+    )
+
+    renderHook(() => useReportPresence({documentId: 'doc-1', documentType: 'movie'}), {
+      wrapper: ambient,
+    })
+
+    expect(reported()[0][0]).toMatchObject({documentId: 'doc-1', perspective: 'published'})
+  })
+
+  it('announces a field path', () => {
+    renderHook(
+      () => useReportPresence({documentId: 'doc-1', documentType: 'movie', path: ['title']}),
+      {wrapper},
+    )
+
+    expect(reported()[0][0].path).toEqual(['title'])
+  })
+
+  it('carries keyed segments and a selection', () => {
+    const path = ['body', {_key: 'b1'}, 'children', {_key: 's1'}, 'text']
+    const selection = {
+      anchor: {path: [{_key: 'b1'}, 'children', {_key: 's1'}], offset: 1},
+      focus: {path: [{_key: 'b1'}, 'children', {_key: 's1'}], offset: 4},
+    }
+
+    renderHook(
+      () => useReportPresence({documentId: 'doc-1', documentType: 'movie', path, selection}),
+      {wrapper},
+    )
+
+    expect(reported()[0][0].path).toEqual(path)
+    expect(reported()[0][0].selection).toEqual(selection)
+  })
+
+  it('does not re-announce when a caller passes fresh literals each render', () => {
+    const {rerender} = renderHook(
+      () =>
+        useReportPresence({
+          documentId: 'doc-1',
+          documentType: 'movie',
+          // A new array identity on every render, which is what real callers do.
+          path: ['title'],
+        }),
+      {wrapper},
+    )
+
+    rerender()
+    rerender()
+
+    expect(reported()).toHaveLength(1)
+  })
+
+  it('throttles a burst and announces the final position', () => {
+    const {rerender} = renderHook(
+      ({path}: {path: string[]}) =>
+        useReportPresence({documentId: 'doc-1', documentType: 'movie', path}),
+      {wrapper, initialProps: {path: ['a']}},
+    )
+
+    expect(reported()).toHaveLength(1)
+
+    rerender({path: ['b']})
+    rerender({path: ['c']})
+    expect(reported()).toHaveLength(1)
+
+    // Trailing edge, so the position the user actually settled on is the one sent.
+    act(() => {
+      vi.advanceTimersByTime(1000)
+    })
+    expect(reported()).toHaveLength(2)
+    expect(reported()[1][0].path).toEqual(['c'])
+  })
+
+  it('announces selections more often than field focus', () => {
+    const selectionAt = (offset: number) => ({
+      anchor: {path: [{_key: 'b1'}], offset},
+      focus: {path: [{_key: 'b1'}], offset},
+    })
+
+    const {rerender} = renderHook(
+      ({offset}: {offset: number}) =>
+        useReportPresence({
+          documentId: 'doc-1',
+          documentType: 'movie',
+          path: ['body'],
+          selection: selectionAt(offset),
+        }),
+      {wrapper, initialProps: {offset: 1}},
+    )
+
+    expect(reported()).toHaveLength(1)
+    rerender({offset: 2})
+
+    // Would still be pending at the 1000ms focus interval. A caret that lags a
+    // full second reads as broken, so selections use 250ms.
+    act(() => {
+      vi.advanceTimersByTime(250)
+    })
+    expect(reported()).toHaveLength(2)
+  })
+
+  it('clears its location on unmount, staying present but nowhere', () => {
+    const {unmount} = renderHook(
+      () => useReportPresence({documentId: 'doc-1', documentType: 'movie'}),
+      {wrapper},
+    )
+
+    unmount()
+
+    expect(reported().at(-1)).toEqual([])
+  })
+
+  it('does not clear on every location change, only on unmount', () => {
+    const {rerender} = renderHook(
+      ({path}: {path: string[]}) =>
+        useReportPresence({documentId: 'doc-1', documentType: 'movie', path}),
+      {wrapper, initialProps: {path: ['a']}},
+    )
+
+    rerender({path: ['b']})
+    act(() => {
+      vi.advanceTimersByTime(1000)
+    })
+
+    expect(reported().every((locations) => locations.length === 1)).toBe(true)
+  })
+})