@sanity/sdk-react 0.0.0-alpha.9 → 0.0.0-rc.1

package/src/hooks/document/useApplyActions.test.ts

@@ -1,4 +1,4 @@
-import {applyActions, createDocument} from '@sanity/sdk'
+import {applyActions, createDocument, type ResourceId} from '@sanity/sdk'
 import {describe, it} from 'vitest'
 
 import {createCallbackHook} from '../helpers/createCallbackHook'
@@ -14,11 +14,12 @@ vi.mock('@sanity/sdk', async (importOriginal) => {
 describe('useApplyActions', () => {
   it('calls `createCallbackHook` with `applyActions`', async () => {
     const {useApplyActions} = await import('./useApplyActions')
-    expect(createCallbackHook).toHaveBeenCalledWith(applyActions)
+    const resourceId: ResourceId = 'project1.dataset1'
+    expect(createCallbackHook).not.toHaveBeenCalled()
 
     expect(applyActions).not.toHaveBeenCalled()
-    const apply = useApplyActions()
+    const apply = useApplyActions(resourceId)
     apply(createDocument({_type: 'author'}))
-    expect(applyActions).toHaveBeenCalled()
+    expect(applyActions).toHaveBeenCalledWith(createDocument({_type: 'author'}))
   })
 })

package/src/hooks/document/useApplyActions.ts

@@ -3,22 +3,72 @@ import {
   applyActions,
   type ApplyActionsOptions,
   type DocumentAction,
+  type ResourceId,
 } from '@sanity/sdk'
 import {type SanityDocument} from '@sanity/types'
 
 import {createCallbackHook} from '../helpers/createCallbackHook'
 
-/** @beta */
-export function useApplyActions(): <TDocument extends SanityDocument>(
+/**
+ *
+ * @beta
+ *
+ * Provides a callback for applying one or more actions to a document.
+ *
+ * @category Documents
+ * @param resourceId - The resource ID of the document to apply actions to. If not provided, the document will use the default resource.
+ * @returns A function that takes one more more {@link DocumentAction}s and returns a promise that resolves to an {@link ActionsResult}.
+ * @example Publish or unpublish a document
+ * ```
+ * import { publishDocument, unpublishDocument } from '@sanity/sdk'
+ * import { useApplyActions } from '@sanity/sdk-react'
+ *
+ * const apply = useApplyActions()
+ * const myDocument = { _id: 'my-document-id', _type: 'my-document-type' }
+ *
+ * return (
+ *   <button onClick={() => apply(publishDocument(myDocument))}>Publish</button>
+ *   <button onClick={() => apply(unpublishDocument(myDocument))}>Unpublish</button>
+ * )
+ * ```
+ *
+ * @example Create and publish a new document
+ * ```
+ * import { createDocument, publishDocument } from '@sanity/sdk'
+ * import { useApplyActions } from '@sanity/sdk-react'
+ *
+ * const apply = useApplyActions()
+ *
+ * const handleCreateAndPublish = () => {
+ *   const handle = { _id: window.crypto.randomUUID(), _type: 'my-document-type' }
+ *   apply([
+ *     createDocument(handle),
+ *     publishDocument(handle),
+ *   ])
+ * }
+ *
+ * return (
+ *   <button onClick={handleCreateAndPublish}>
+ *     I’m feeling lucky
+ *   </button>
+ * )
+ * ```
+ */
+export function useApplyActions(
+  resourceId?: ResourceId,
+): <TDocument extends SanityDocument>(
   action: DocumentAction<TDocument> | DocumentAction<TDocument>[],
   options?: ApplyActionsOptions,
 ) => Promise<ActionsResult<TDocument>>
+
 /** @beta */
-export function useApplyActions(): (
+export function useApplyActions(
+  resourceId?: ResourceId,
+): (
   action: DocumentAction | DocumentAction[],
   options?: ApplyActionsOptions,
 ) => Promise<ActionsResult> {
-  return _useApplyActions()
+  return _useApplyActions(resourceId)()
 }
 
-const _useApplyActions = createCallbackHook(applyActions)
+const _useApplyActions = (resourceId?: ResourceId) => createCallbackHook(applyActions, resourceId)

package/src/hooks/document/useDocument.test.ts

@@ -46,7 +46,7 @@ describe('useDocument hook', () => {
       subscribe,
     } as unknown as StateSource<unknown>)
 
-    const {result} = renderHook(() => useDocument('doc1'))
+    const {result} = renderHook(() => useDocument({_id: 'doc1', _type: 'book'}))
 
     expect(result.current).toEqual(doc)
     expect(getCurrent).toHaveBeenCalled()
@@ -69,7 +69,7 @@ describe('useDocument hook', () => {
     // Render the hook and capture the thrown promise.
     const {result} = renderHook(() => {
       try {
-        return useDocument('doc1')
+        return useDocument({_id: 'doc1', _type: 'book'})
       } catch (e) {
         return e
       }

package/src/hooks/document/useDocument.ts

@@ -1,38 +1,107 @@
 import {
   type DocumentHandle,
   getDocumentState,
+  getResourceId,
   type JsonMatch,
   type JsonMatchPath,
   resolveDocument,
 } from '@sanity/sdk'
 import {type SanityDocument} from '@sanity/types'
-import {useCallback, useMemo, useSyncExternalStore} from 'react'
 
-import {useSanityInstance} from '../context/useSanityInstance'
+import {createStateSourceHook} from '../helpers/createStateSourceHook'
 
-/** @beta */
+/**
+ * @beta
+ *
+ * ## useDocument(doc, path)
+ * Read and subscribe to nested values in a document
+ * @category Documents
+ * @param doc - The document to read state from. If you pass a `DocumentHandle` with a `resourceId` in the DocumentResourceId format (`document:projectId.dataset:documentId`)
+ * the document will be read from the specified Sanity project and dataset that is included in the handle. If no `resourceId` is provided, the default project and dataset from your `SanityApp` configuration will be used.
+ * @param path - The path to the nested value to read from
+ * @returns The value at the specified path
+ * @example
+ * ```tsx
+ * import {type DocumentHandle, useDocument} from '@sanity/sdk-react'
+ *
+ * function OrderLink({documentHandle}: {documentHandle: DocumentHandle}) {
+ *   const title = useDocument(documentHandle, 'title')
+ *   const id = useDocument(documentHandle, '_id')
+ *
+ *   return (
+ *     <a href=`/order/${id}`>Order {title} today!</a>
+ *   )
+ * }
+ * ```
+ *
+ */
 export function useDocument<
   TDocument extends SanityDocument,
   TPath extends JsonMatchPath<TDocument>,
->(doc: string | DocumentHandle<TDocument>, path: TPath): JsonMatch<TDocument, TPath> | undefined
-/** @beta */
+>(doc: DocumentHandle<TDocument>, path: TPath): JsonMatch<TDocument, TPath> | undefined
+
+/**
+ * @beta
+ * ## useDocument(doc)
+ * Read and subscribe to an entire document
+ * @param doc - The document to read state from
+ * @returns The document state as an object
+ * @example
+ * ```tsx
+ * import {type SanityDocument, type DocumentHandle, useDocument} from '@sanity/sdk-react'
+ *
+ * interface Book extends SanityDocument {
+ *   title: string
+ *   author: string
+ *   summary: string
+ * }
+ *
+ * function DocumentView({documentHandle}: {documentHandle: DocumentHandle}) {
+ *   const book = useDocument<Book>(documentHandle)
+ *
+ *   return (
+ *     <article>
+ *       <h1>{book?.title}</h1>
+ *       <address>By {book?.author}</address>
+ *
+ *       <h2>Summary</h2>
+ *       {book?.summary}
+ *
+ *       <h2>Order</h2>
+ *       <a href=`/order/${book._id}`>Order {book?.title} today!</a>
+ *     </article>
+ *   )
+ * }
+ * ```
+ *
+ */
 export function useDocument<TDocument extends SanityDocument>(
-  doc: string | DocumentHandle<TDocument>,
+  doc: DocumentHandle<TDocument>,
 ): TDocument | null
-/** @beta */
-export function useDocument(doc: string | DocumentHandle, path?: string): unknown {
-  const documentId = typeof doc === 'string' ? doc : doc._id
-  const instance = useSanityInstance()
-  const isDocumentReady = useCallback(
-    () => getDocumentState(instance, documentId).getCurrent() !== undefined,
-    [instance, documentId],
-  )
-  if (!isDocumentReady()) throw resolveDocument(instance, documentId)
-
-  const {subscribe, getCurrent} = useMemo(
-    () => getDocumentState(instance, documentId, path),
-    [documentId, instance, path],
-  )
 
-  return useSyncExternalStore(subscribe, getCurrent)
+/**
+ * @beta
+ * Reads and subscribes to a document’s realtime state, incorporating both local and remote changes.
+ * When called with a `path` argument, the hook will return the nested value’s state.
+ * When called without a `path` argument, the entire document’s state will be returned.
+ *
+ * @remarks
+ * `useDocument` is designed to be used within a realtime context in which local updates to documents
+ * need to be displayed before they are persisted to the remote copy. This can be useful within a collaborative
+ * or realtime editing interface where local changes need to be reflected immediately.
+ *
+ * However, this hook can be too resource intensive for applications where static document values simply
+ * need to be displayed (or when changes to documents don’t need to be reflected immediately);
+ * consider using `usePreview` or `useQuery` for these use cases instead. These hooks leverage the Sanity
+ * Live Content API to provide a more efficient way to read and subscribe to document state.
+ */
+export function useDocument(doc: DocumentHandle, path?: string): unknown {
+  return _useDocument(doc, path)
 }
+
+const _useDocument = createStateSourceHook<[doc: DocumentHandle, path?: string], unknown>({
+  getState: getDocumentState,
+  shouldSuspend: (instance, doc) => getDocumentState(instance, doc._id).getCurrent() === undefined,
+  suspender: resolveDocument,
+  getResourceId: (doc) => getResourceId(doc.resourceId),
+})

package/src/hooks/document/useDocumentEvent.test.ts

@@ -1,5 +1,10 @@
 // tests/useDocumentEvent.test.ts
-import {createSanityInstance, type DocumentEvent, subscribeDocumentEvents} from '@sanity/sdk'
+import {
+  createSanityInstance,
+  type DocumentEvent,
+  type DocumentHandle,
+  subscribeDocumentEvents,
+} from '@sanity/sdk'
 import {renderHook} from '@testing-library/react'
 import {beforeEach, describe, expect, it, vi} from 'vitest'
 
@@ -16,6 +21,11 @@ vi.mock('../context/useSanityInstance', () => ({
 }))
 
 const instance = createSanityInstance({projectId: 'p', dataset: 'd'})
+const docHandle: DocumentHandle = {
+  _id: 'doc1',
+  _type: 'book',
+  resourceId: 'document:p.d:doc1',
+}
 
 describe('useDocumentEvent hook', () => {
   beforeEach(() => {
@@ -28,7 +38,7 @@ describe('useDocumentEvent hook', () => {
     const unsubscribe = vi.fn()
     vi.mocked(subscribeDocumentEvents).mockReturnValue(unsubscribe)
 
-    renderHook(() => useDocumentEvent(handler))
+    renderHook(() => useDocumentEvent(handler, docHandle))
 
     expect(vi.mocked(subscribeDocumentEvents)).toHaveBeenCalledTimes(1)
     expect(vi.mocked(subscribeDocumentEvents).mock.calls[0][0]).toBe(instance)
@@ -46,7 +56,7 @@ describe('useDocumentEvent hook', () => {
     const unsubscribe = vi.fn()
     vi.mocked(subscribeDocumentEvents).mockReturnValue(unsubscribe)
 
-    const {unmount} = renderHook(() => useDocumentEvent(handler))
+    const {unmount} = renderHook(() => useDocumentEvent(handler, docHandle))
     unmount()
     expect(unsubscribe).toHaveBeenCalledTimes(1)
   })

package/src/hooks/document/useDocumentEvent.ts

@@ -1,10 +1,42 @@
-import {type DocumentEvent, subscribeDocumentEvents} from '@sanity/sdk'
+import {
+  type DocumentEvent,
+  type DocumentHandle,
+  getResourceId,
+  subscribeDocumentEvents,
+} from '@sanity/sdk'
 import {useCallback, useEffect, useInsertionEffect, useRef} from 'react'
 
 import {useSanityInstance} from '../context/useSanityInstance'
 
-/** @beta */
-export function useDocumentEvent(handler: (documentEvent: DocumentEvent) => void): void {
+/**
+ *
+ * @beta
+ *
+ * Subscribes an event handler to events in your application’s document store, such as document
+ * creation, deletion, and updates.
+ *
+ * @category Documents
+ * @param handler - The event handler to register.
+ * @param doc - The document to subscribe to events for. If you pass a `DocumentHandle` with a `resourceId` (in the format of `document:projectId.dataset:documentId`)
+ * the document will be read from the specified Sanity project and dataset that is included in the handle. If no `resourceId` is provided, the default project and dataset from your `SanityApp` configuration will be used.
+ * @example
+ * ```
+ * import {useDocumentEvent} from '@sanity/sdk-react'
+ * import {type DocumentEvent} from '@sanity/sdk'
+ *
+ * useDocumentEvent((event) => {
+ *   if (event.type === DocumentEvent.DocumentDeletedEvent) {
+ *     alert(`Document with ID ${event.documentId} deleted!`)
+ *   } else {
+ *     console.log(event)
+ *   }
+ * })
+ * ```
+ */
+export function useDocumentEvent(
+  handler: (documentEvent: DocumentEvent) => void,
+  doc: DocumentHandle,
+): void {
   const ref = useRef(handler)
 
   useInsertionEffect(() => {
@@ -15,7 +47,7 @@ export function useDocumentEvent(handler: (documentEvent: DocumentEvent) => void
     return ref.current(documentEvent)
   }, [])
 
-  const instance = useSanityInstance()
+  const instance = useSanityInstance(getResourceId(doc.resourceId))
   useEffect(() => {
     return subscribeDocumentEvents(instance, stableHandler)
   }, [instance, stableHandler])

package/src/hooks/document/useDocumentSyncStatus.test.ts

@@ -7,7 +7,7 @@ import {createStateSourceHook} from '../helpers/createStateSourceHook'
 vi.mock('../helpers/createStateSourceHook', () => ({createStateSourceHook: vi.fn(identity)}))
 vi.mock('@sanity/sdk', () => ({getDocumentSyncStatus: vi.fn()}))
 
-describe('useAuthToken', () => {
+describe('useDocumentSyncStatus', () => {
   it('calls `createStateSourceHook` with `getTokenState`', async () => {
     const {useDocumentSyncStatus} = await import('./useDocumentSyncStatus')
     expect(createStateSourceHook).toHaveBeenCalledWith(getDocumentSyncStatus)

package/src/hooks/document/useDocumentSyncStatus.ts

@@ -1,6 +1,30 @@
-import {getDocumentSyncStatus} from '@sanity/sdk'
+import {type DocumentHandle, getDocumentSyncStatus} from '@sanity/sdk'
 
 import {createStateSourceHook} from '../helpers/createStateSourceHook'
 
+type UseDocumentSyncStatus = {
+  /**
+   * Exposes the document’s sync status between local and remote document states.
+   *
+   * @category Documents
+   * @param doc - The document handle to get sync status for. If you pass a `DocumentHandle` with a `resourceId` (in the format of `document:projectId.dataset:documentId`)
+   * the document will be read from the specified Sanity project and dataset that is included in the handle. If no `resourceId` is provided, the default project and dataset from your `SanityApp` configuration will be used.
+   * @returns `true` if local changes are synced with remote, `false` if the changes are not synced, and `undefined` if the document is not found
+   * @example Disable a Save button when there are no changes to sync
+   * ```
+   * const myDocumentHandle = { _id: 'documentId', _type: 'documentType', resourceId: 'document:projectId:dataset:documentId' }
+   * const documentSynced = useDocumentSyncStatus(myDocumentHandle)
+   *
+   * return (
+   *   <button disabled={documentSynced}>
+   *     Save Changes
+   *   </button>
+   * )
+   * ```
+   */
+  (doc: DocumentHandle): boolean | undefined
+}
+
 /** @beta */
-export const useDocumentSyncStatus = createStateSourceHook(getDocumentSyncStatus)
+export const useDocumentSyncStatus: UseDocumentSyncStatus =
+  createStateSourceHook(getDocumentSyncStatus)

package/src/hooks/document/useEditDocument.test.ts

@@ -1,6 +1,7 @@
 // tests/useEditDocument.test.ts
 import {
   createSanityInstance,
+  type DocumentHandle,
   editDocument,
   getDocumentState,
   resolveDocument,
@@ -35,13 +36,19 @@ vi.mock('./useApplyActions', () => ({
 // Create a fake instance to be returned by useSanityInstance.
 const instance = createSanityInstance({projectId: 'p', dataset: 'd'})
 
-const doc: SanityDocument = {
+const doc = {
   _id: 'doc1',
   foo: 'bar',
   _type: 'book',
   _rev: 'tx0',
   _createdAt: '2025-02-06T00:11:00.000Z',
   _updatedAt: '2025-02-06T00:11:00.000Z',
+} satisfies SanityDocument
+
+const docHandle: DocumentHandle<SanityDocument> = {
+  _id: 'doc1',
+  _type: 'book',
+  resourceId: 'document:p.d:doc1',
 }
 
 describe('useEditDocument hook', () => {
@@ -61,10 +68,10 @@ describe('useEditDocument hook', () => {
     const apply = vi.fn().mockResolvedValue({transactionId: 'tx1'})
     vi.mocked(useApplyActions).mockReturnValue(apply)
 
-    const {result} = renderHook(() => useEditDocument('doc1', 'foo'))
+    const {result} = renderHook(() => useEditDocument(docHandle, 'foo'))
     const promise = result.current('newValue')
-    expect(editDocument).toHaveBeenCalledWith('doc1', {set: {foo: 'newValue'}})
-    expect(apply).toHaveBeenCalledWith(editDocument('doc1', {set: {foo: 'newValue'}}))
+    expect(editDocument).toHaveBeenCalledWith(docHandle, {set: {foo: 'newValue'}})
+    expect(apply).toHaveBeenCalledWith(editDocument(docHandle, {set: {foo: 'newValue'}}))
     const actionsResult = await promise
     expect(actionsResult).toEqual({transactionId: 'tx1'})
   })
@@ -82,13 +89,51 @@ describe('useEditDocument hook', () => {
     const apply = vi.fn().mockResolvedValue({transactionId: 'tx2'})
     vi.mocked(useApplyActions).mockReturnValue(apply)
 
-    const {result} = renderHook(() => useEditDocument('doc1'))
-    const promise = result.current({foo: 'baz', extra: 'old', _id: 'doc1'})
-    expect(apply).toHaveBeenCalledWith([editDocument('doc1', {set: {foo: 'baz'}})])
+    const {result} = renderHook(() => useEditDocument(docHandle))
+    const promise = result.current({...doc, foo: 'baz', extra: 'old', _id: 'doc1'})
+    expect(apply).toHaveBeenCalledWith([editDocument(docHandle, {set: {foo: 'baz'}})])
     const actionsResult = await promise
     expect(actionsResult).toEqual({transactionId: 'tx2'})
   })
 
+  it('applies a single edit action using an updater function for the given path', async () => {
+    const getCurrent = vi.fn().mockReturnValue(doc.foo)
+    const subscribe = vi.fn().mockReturnValue(vi.fn())
+    vi.mocked(getDocumentState).mockReturnValue({
+      getCurrent,
+      subscribe,
+    } as unknown as StateSource<SanityDocument>)
+
+    const apply = vi.fn().mockResolvedValue({transactionId: 'tx3'})
+    vi.mocked(useApplyActions).mockReturnValue(apply)
+
+    const {result} = renderHook(() => useEditDocument(docHandle, 'foo'))
+    const promise = result.current((prev: unknown) => `${prev}Updated`) // 'bar' becomes 'barUpdated'
+    expect(editDocument).toHaveBeenCalledWith(docHandle, {set: {foo: 'barUpdated'}})
+    expect(apply).toHaveBeenCalledWith(editDocument(docHandle, {set: {foo: 'barUpdated'}}))
+    const actionsResult = await promise
+    expect(actionsResult).toEqual({transactionId: 'tx3'})
+  })
+
+  it('applies edit actions using an updater function for the entire document', async () => {
+    const currentDoc = {...doc, foo: 'bar', extra: 'old'}
+    const getCurrent = vi.fn().mockReturnValue(currentDoc)
+    const subscribe = vi.fn().mockReturnValue(vi.fn())
+    vi.mocked(getDocumentState).mockReturnValue({
+      getCurrent,
+      subscribe,
+    } as unknown as StateSource<SanityDocument>)
+
+    const apply = vi.fn().mockResolvedValue({transactionId: 'tx4'})
+    vi.mocked(useApplyActions).mockReturnValue(apply)
+
+    const {result} = renderHook(() => useEditDocument(docHandle))
+    const promise = result.current((prevDoc) => ({...prevDoc, foo: 'baz'}))
+    expect(apply).toHaveBeenCalledWith([editDocument(docHandle, {set: {foo: 'baz'}})])
+    const actionsResult = await promise
+    expect(actionsResult).toEqual({transactionId: 'tx4'})
+  })
+
   it('throws an error if next value is not an object', () => {
     const getCurrent = vi.fn().mockReturnValue(doc)
     const subscribe = vi.fn().mockReturnValue(vi.fn())
@@ -100,8 +145,8 @@ describe('useEditDocument hook', () => {
     const fakeApply = vi.fn()
     vi.mocked(useApplyActions).mockReturnValue(fakeApply)
 
-    const {result} = renderHook(() => useEditDocument('doc1'))
-    expect(() => result.current('notAnObject' as unknown as Partial<SanityDocument>)).toThrowError(
+    const {result} = renderHook(() => useEditDocument(docHandle))
+    expect(() => result.current('notAnObject' as unknown as SanityDocument)).toThrowError(
       'No path was provided to `useEditDocument` and the value provided was not a document object.',
     )
   })
@@ -122,7 +167,7 @@ describe('useEditDocument hook', () => {
     // Render the hook and capture the thrown promise.
     const {result} = renderHook(() => {
       try {
-        return useEditDocument('doc1')
+        return useEditDocument(docHandle)
       } catch (e) {
         return e
       }