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

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

package/src/hooks/presence/useReportPresence.ts

@@ -0,0 +1,170 @@
+import {
+  isMediaLibraryResource,
+  type PresenceSelection,
+  reportPresence,
+  type ReportPresenceOptions,
+} from '@sanity/sdk'
+import {type Path} from '@sanity/types'
+import {useEffect, useMemo, useRef} from 'react'
+
+import {type DocumentHandle} from '../../config/handles'
+import {useSanityInstance} from '../context/useSanityInstance'
+import {useNormalizedResourceOptions} from '../helpers/useNormalizedResourceOptions'
+import {trackHookUsage} from '../helpers/useTrackHookUsage'
+
+/**
+ * Field focus moves at human speed, so a second between announcements is plenty.
+ */
+const FOCUS_THROTTLE_MS = 1000
+
+/**
+ * A caret that trails a second behind reads as broken rather than as latency, so
+ * reporting a `selection` announces more often. The Studio uses a flat 1000ms for
+ * both, which is why its remote carets feel sluggish.
+ */
+const SELECTION_THROTTLE_MS = 250
+
+/** @beta */
+export interface UseReportPresenceOptions extends DocumentHandle {
+  /**
+   * The focused field path. Omit it for document-level presence. Keyed and numeric
+   * segments are supported, so array items and Portable Text spans can be
+   * addressed.
+   */
+  path?: Path
+
+  /** The Portable Text caret, when the focused field is a Portable Text field. */
+  selection?: PresenceSelection
+
+  /** Overrides the throttle interval. Mainly useful in tests. */
+  throttleMs?: number
+}
+
+/**
+ * Announces that the current user is in a document, so that other clients in the
+ * same project and dataset can show them.
+ *
+ * Writing presence is opt-in. Reading it with `usePresenceForDocument` or
+ * `usePresence` never announces anything, and this hook is the only thing that
+ * makes an app visible to others. That includes the Studio, which shares the same
+ * presence room and will show these users in its navbar and field indicators.
+ *
+ * Announcements are throttled, collapsed over a short window, and then repeated
+ * every 30 seconds while the user is idle. That repeat is what tells peers the
+ * session is still alive, so the intended usage is to mount this hook for as long
+ * as the user is in the document. On unmount the location is cleared, leaving the
+ * user present in the app but not in any particular document.
+ *
+ * The perspective decides which specific document is reported: the draft under
+ * `drafts`, the published document under `published`, a version under a release.
+ * It is taken from `ResourceProvider` unless you pass one on the handle. That
+ * matters for interoperability, because the Studio's field indicators compare the
+ * exact id its form is on, so a mismatch shows your user at document level while
+ * never lighting up a field.
+ *
+ * Presence is scoped to a single project and dataset. It is not a list of everyone
+ * signed in to your organization.
+ *
+ * @example Document-level presence
+ * ```tsx
+ * function DocumentEditor({documentId, documentType}: DocumentHandle) {
+ *   useReportPresence({documentId, documentType})
+ *   return <Editor />
+ * }
+ * ```
+ *
+ * @example Presence in a release version
+ * ```tsx
+ * // The document id stays plain; the perspective selects the version.
+ * useReportPresence({documentId, documentType, perspective: {releaseName: 'autumn'}})
+ * ```
+ *
+ * @example Field-level presence
+ * ```tsx
+ * function TitleField({documentId, documentType}: DocumentHandle) {
+ *   const [focused, setFocused] = useState(false)
+ *   useReportPresence({documentId, documentType, path: focused ? ['title'] : undefined})
+ *   return <input onFocus={() => setFocused(true)} onBlur={() => setFocused(false)} />
+ * }
+ * ```
+ *
+ * @beta
+ */
+export function useReportPresence(options: UseReportPresenceOptions): void {
+  const {path, selection, throttleMs, ...handle} = options
+
+  const normalizedOptions = useNormalizedResourceOptions(handle)
+  if (normalizedOptions.resource && isMediaLibraryResource(normalizedOptions.resource)) {
+    throw new Error(
+      'useReportPresence() does not support media library resources. Presence tracking requires a canvas or dataset resource.',
+    )
+  }
+
+  const sanityInstance = useSanityInstance()
+  trackHookUsage(sanityInstance, 'useReportPresence')
+
+  const {resource, perspective} = normalizedOptions
+  const {documentId, liveEdit} = options
+
+  const interval = throttleMs ?? (selection ? SELECTION_THROTTLE_MS : FOCUS_THROTTLE_MS)
+
+  // Compared by value, because callers write `path={['title']}` inline and a fresh
+  // array identity every render must not mean a fresh announcement every render.
+  const locationKey = useMemo(
+    () =>
+      JSON.stringify([documentId, path ?? [], selection ?? null, perspective ?? null, liveEdit]),
+    [documentId, path, selection, perspective, liveEdit],
+  )
+
+  // Rebuilt from the key rather than from the props, so the effect below can
+  // depend on it honestly instead of suppressing the exhaustive-deps rule.
+  const location = useMemo<ReportPresenceOptions>(() => {
+    const [id, parsedPath, parsedSelection, parsedPerspective, parsedLiveEdit] = JSON.parse(
+      locationKey,
+    ) as [string, Path, PresenceSelection, ReportPresenceOptions['perspective'] | null, boolean?]
+    return {
+      documentId: id,
+      // Forwarded rather than resolved here: core turns the perspective into the
+      // specific document id, so the read and write sides cannot drift apart.
+      ...(parsedPerspective ? {perspective: parsedPerspective} : {}),
+      ...(parsedLiveEdit ? {liveEdit: parsedLiveEdit} : {}),
+      ...(parsedPath.length > 0 ? {path: parsedPath} : {}),
+      ...(parsedSelection ? {selection: parsedSelection} : {}),
+    }
+  }, [locationKey])
+
+  const lastSentAt = useRef(0)
+  const pending = useRef<ReturnType<typeof setTimeout> | undefined>(undefined)
+
+  useEffect(() => {
+    // Captured in this effect's closure rather than read from a ref, so nothing is
+    // written during render. A newer location re-runs the effect, which clears the
+    // pending timeout below and schedules the newer value instead.
+    const send = () => {
+      lastSentAt.current = Date.now()
+      reportPresence(sanityInstance, {
+        ...(resource ? {resource} : {}),
+        locations: [location],
+      })
+    }
+
+    const elapsed = Date.now() - lastSentAt.current
+    if (elapsed >= interval) {
+      send()
+    } else {
+      // Trailing edge, so the position the user settled on is the one announced.
+      clearTimeout(pending.current)
+      pending.current = setTimeout(send, interval - elapsed)
+    }
+
+    return () => clearTimeout(pending.current)
+  }, [location, interval, sanityInstance, resource])
+
+  // Kept separate from the throttled effect so it runs on unmount only, rather
+  // than every time the reported location changes.
+  useEffect(() => {
+    return () => {
+      reportPresence(sanityInstance, {...(resource ? {resource} : {}), locations: []})
+    }
+  }, [sanityInstance, resource])
+}

package/src/hooks/preview/useDocumentPreview.test.tsx

@@ -11,7 +11,6 @@ vi.mock('../projection/useDocumentProjection')
 const mockDocument: DocumentHandle = {
   documentId: 'doc1',
   documentType: 'exampleType',
-  resource: {projectId: 'p', dataset: 'd'},
 }
 
 describe('useDocumentPreview', () => {

package/src/hooks/preview/useDocumentPreview.tsx

@@ -1,14 +1,11 @@
-import {
-  PREVIEW_PROJECTION,
-  type PreviewQueryResult,
-  type PreviewValue,
-  transformProjectionToPreview,
-} from '@sanity/sdk'
+import {type PreviewQueryResult, type PreviewValue} from '@sanity/sdk'
+import {PREVIEW_PROJECTION, transformProjectionToPreview} from '@sanity/sdk/_internal'
 import {useMemo} from 'react'
 
 import {type DocumentHandle} from '../../config/handles'
 import {useSanityInstance} from '../context/useSanityInstance'
 import {useNormalizedResourceOptions} from '../helpers/useNormalizedResourceOptions'
+import {trackHookUsage} from '../helpers/useTrackHookUsage'
 import {useDocumentProjection} from '../projection/useDocumentProjection'
 
 /**
@@ -60,9 +57,9 @@ export interface useDocumentPreviewResults {
  *
  * @example Combining with useDocuments to render a collection of document previews
  * ```
- * // PreviewComponent.tsx
- * export default function PreviewComponent(docHandle: DocumentHandle) {
- *   const { data: { title, subtitle, media }, isPending } = useDocumentPreview(docHandle)
+ * // PreviewComponent.jsx
+ * export default function PreviewComponent({ document }) {
+ *   const { data: { title, subtitle, media }, isPending } = useDocumentPreview({ document })
  *   return (
  *     <article style={{ opacity: isPending ? 0.5 : 1}}>
  *       {media?.type === 'image-asset' ? <img src={media.url} alt='' /> : ''}
@@ -72,16 +69,16 @@ export interface useDocumentPreviewResults {
  *   )
  * }
  *
- * // DocumentList.tsx
- * const { data } = useDocuments({ documentType: 'movie' })
+ * // DocumentList.jsx
+ * const { data } = useDocuments({ filter: '_type == "movie"' })
  * return (
  *   <div>
  *     <h1>Movies</h1>
  *     <ul>
  *       {data.map(movie => (
- *         <li key={movie.documentId}>
+ *         <li key={movie._id}>
  *           <Suspense fallback='Loading…'>
- *             <PreviewComponent {...movie} />
+ *             <PreviewComponent document={movie} />
  *           </Suspense>
  *         </li>
  *       ))}
@@ -95,6 +92,7 @@ export function useDocumentPreview({
   ...docHandle
 }: useDocumentPreviewOptions): useDocumentPreviewResults {
   const instance = useSanityInstance()
+  trackHookUsage(instance, 'useDocumentPreview')
   const normalizedDocHandle = useNormalizedResourceOptions(docHandle)
 
   // Use the projection hook with the fixed preview projection
@@ -108,7 +106,7 @@ export function useDocumentPreview({
   // Keep this non-null assumption aligned with useDocumentPreviewResults.data.
   const previewValue = useMemo(
     () =>
-      transformProjectionToPreview(instance, normalizedDocHandle.resource, projectionResult.data),
+      transformProjectionToPreview(instance, projectionResult.data, normalizedDocHandle.resource),
     [projectionResult.data, instance, normalizedDocHandle.resource],
   )