@sanity/sdk-react 0.0.0-alpha.2 → 0.0.0-alpha.21

package/src/hooks/datasets/useDatasets.ts

@@ -0,0 +1,40 @@
+import {type DatasetsResponse} from '@sanity/client'
+import {getDatasetsState, resolveDatasets, type SanityInstance, type StateSource} from '@sanity/sdk'
+
+import {createStateSourceHook} from '../helpers/createStateSourceHook'
+
+type UseDatasets = {
+  /**
+   *
+   * Returns metadata for each dataset the current user has access to.
+   *
+   * @category Datasets
+   * @returns The metadata for your the datasets
+   *
+   * @example
+   * ```tsx
+   * const datasets = useDatasets()
+   *
+   * return (
+   *   <select>
+   *     {datasets.map((dataset) => (
+   *       <option key={dataset.name}>{dataset.name}</option>
+   *     ))}
+   *   </select>
+   * )
+   * ```
+   *
+   */
+  (): DatasetsResponse
+}
+
+/**
+ * @public
+ * @function
+ */
+export const useDatasets: UseDatasets = createStateSourceHook({
+  // remove `undefined` since we're suspending when that is the case
+  getState: getDatasetsState as (instance: SanityInstance) => StateSource<DatasetsResponse>,
+  shouldSuspend: (instance) => getDatasetsState(instance).getCurrent() === undefined,
+  suspender: resolveDatasets,
+})

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

@@ -0,0 +1,25 @@
+import {applyDocumentActions, createDocument, type ResourceId} from '@sanity/sdk'
+import {describe, it} from 'vitest'
+
+import {createCallbackHook} from '../helpers/createCallbackHook'
+
+vi.mock('../helpers/createCallbackHook', () => ({
+  createCallbackHook: vi.fn((cb) => () => cb),
+}))
+vi.mock('@sanity/sdk', async (importOriginal) => {
+  const original = await importOriginal<typeof import('@sanity/sdk')>()
+  return {...original, applyDocumentActions: vi.fn()}
+})
+
+describe('useApplyDocumentActions', () => {
+  it('calls `createCallbackHook` with `applyDocumentActions`', async () => {
+    const {useApplyDocumentActions} = await import('./useApplyDocumentActions')
+    const resourceId: ResourceId = 'project1.dataset1'
+    expect(createCallbackHook).not.toHaveBeenCalled()
+
+    expect(applyDocumentActions).not.toHaveBeenCalled()
+    const apply = useApplyDocumentActions(resourceId)
+    apply(createDocument({_type: 'author'}))
+    expect(applyDocumentActions).toHaveBeenCalledWith(createDocument({_type: 'author'}))
+  })
+})

package/src/hooks/document/useApplyDocumentActions.ts

@@ -0,0 +1,75 @@
+import {
+  type ActionsResult,
+  applyDocumentActions,
+  type ApplyDocumentActionsOptions,
+  type DocumentAction,
+  type ResourceId,
+} from '@sanity/sdk'
+import {type SanityDocument} from '@sanity/types'
+
+import {createCallbackHook} from '../helpers/createCallbackHook'
+
+/**
+ *
+ * @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 { useApplyDocumentActions } from '@sanity/sdk-react'
+ *
+ * const apply = useApplyDocumentActions()
+ * 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 { useApplyDocumentActions } from '@sanity/sdk-react'
+ *
+ * const apply = useApplyDocumentActions()
+ *
+ * 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 useApplyDocumentActions(
+  resourceId?: ResourceId,
+): <TDocument extends SanityDocument>(
+  action: DocumentAction<TDocument> | DocumentAction<TDocument>[],
+  options?: ApplyDocumentActionsOptions,
+) => Promise<ActionsResult<TDocument>>
+
+/** @beta */
+export function useApplyDocumentActions(
+  resourceId?: ResourceId,
+): (
+  action: DocumentAction | DocumentAction[],
+  options?: ApplyDocumentActionsOptions,
+) => Promise<ActionsResult> {
+  return _useApplyDocumentActions(resourceId)()
+}
+
+const _useApplyDocumentActions = (resourceId?: ResourceId) =>
+  createCallbackHook(applyDocumentActions, resourceId)

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

@@ -0,0 +1,81 @@
+// tests/useDocument.test.ts
+import {
+  createSanityInstance,
+  getDocumentState,
+  resolveDocument,
+  type StateSource,
+} from '@sanity/sdk'
+import {type SanityDocument} from '@sanity/types'
+import {renderHook} from '@testing-library/react'
+import {beforeEach, describe, expect, it, vi} from 'vitest'
+
+import {useSanityInstance} from '../context/useSanityInstance'
+import {useDocument} from './useDocument'
+
+vi.mock('@sanity/sdk', async (importOriginal) => {
+  const original = await importOriginal<typeof import('@sanity/sdk')>()
+  return {...original, getDocumentState: vi.fn(), resolveDocument: vi.fn()}
+})
+
+vi.mock('../context/useSanityInstance', () => ({
+  useSanityInstance: vi.fn(),
+}))
+
+// Create a fake instance to be returned by useSanityInstance.
+const instance = createSanityInstance({projectId: 'p', dataset: 'd'})
+const doc: SanityDocument = {
+  _id: 'doc1',
+  foo: 'bar',
+  _type: 'book',
+  _rev: 'tx0',
+  _createdAt: '2025-02-06T00:11:00.000Z',
+  _updatedAt: '2025-02-06T00:11:00.000Z',
+}
+
+describe('useDocument hook', () => {
+  beforeEach(() => {
+    vi.resetAllMocks()
+    vi.mocked(useSanityInstance).mockReturnValue(instance)
+  })
+
+  it('returns the current document when ready (without a path)', () => {
+    const getCurrent = vi.fn().mockReturnValue(doc)
+    const subscribe = vi.fn().mockReturnValue(vi.fn())
+    vi.mocked(getDocumentState).mockReturnValue({
+      getCurrent,
+      subscribe,
+    } as unknown as StateSource<unknown>)
+
+    const {result} = renderHook(() => useDocument({_id: 'doc1', _type: 'book'}))
+
+    expect(result.current).toEqual(doc)
+    expect(getCurrent).toHaveBeenCalled()
+    expect(subscribe).toHaveBeenCalled()
+  })
+
+  it('throws a promise (suspends) when the document is not ready', () => {
+    const getCurrent = vi.fn().mockReturnValue(undefined)
+    const subscribe = vi.fn().mockReturnValue(vi.fn())
+    vi.mocked(getDocumentState).mockReturnValue({
+      getCurrent,
+      subscribe,
+    } as unknown as StateSource<unknown>)
+
+    const resolveDocPromise = Promise.resolve(doc)
+
+    // Also, simulate resolveDocument to return a known promise.
+    vi.mocked(resolveDocument).mockReturnValue(resolveDocPromise)
+
+    // Render the hook and capture the thrown promise.
+    const {result} = renderHook(() => {
+      try {
+        return useDocument({_id: 'doc1', _type: 'book'})
+      } catch (e) {
+        return e
+      }
+    })
+
+    // When the document is not ready, the hook throws the promise from resolveDocument.
+    expect(result.current).toBe(resolveDocPromise)
+  })
+})

package/src/hooks/document/useDocument.ts

@@ -0,0 +1,107 @@
+import {
+  type DocumentHandle,
+  getDocumentState,
+  getResourceId,
+  type JsonMatch,
+  type JsonMatchPath,
+  resolveDocument,
+} from '@sanity/sdk'
+import {type SanityDocument} from '@sanity/types'
+
+import {createStateSourceHook} from '../helpers/createStateSourceHook'
+
+/**
+ * @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: 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: DocumentHandle<TDocument>,
+): TDocument | null
+
+/**
+ * @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

@@ -0,0 +1,63 @@
+// tests/useDocumentEvent.test.ts
+import {
+  createSanityInstance,
+  type DocumentEvent,
+  type DocumentHandle,
+  subscribeDocumentEvents,
+} from '@sanity/sdk'
+import {renderHook} from '@testing-library/react'
+import {beforeEach, describe, expect, it, vi} from 'vitest'
+
+import {useSanityInstance} from '../context/useSanityInstance'
+import {useDocumentEvent} from './useDocumentEvent'
+
+vi.mock('@sanity/sdk', async (importOriginal) => {
+  const original = await importOriginal<typeof import('@sanity/sdk')>()
+  return {...original, subscribeDocumentEvents: vi.fn()}
+})
+
+vi.mock('../context/useSanityInstance', () => ({
+  useSanityInstance: vi.fn(),
+}))
+
+const instance = createSanityInstance({projectId: 'p', dataset: 'd'})
+const docHandle: DocumentHandle = {
+  _id: 'doc1',
+  _type: 'book',
+  resourceId: 'document:p.d:doc1',
+}
+
+describe('useDocumentEvent hook', () => {
+  beforeEach(() => {
+    vi.resetAllMocks()
+    vi.mocked(useSanityInstance).mockReturnValue(instance)
+  })
+
+  it('calls subscribeDocumentEvents with instance and a stable handler', () => {
+    const handler = vi.fn()
+    const unsubscribe = vi.fn()
+    vi.mocked(subscribeDocumentEvents).mockReturnValue(unsubscribe)
+
+    renderHook(() => useDocumentEvent(handler, docHandle))
+
+    expect(vi.mocked(subscribeDocumentEvents)).toHaveBeenCalledTimes(1)
+    expect(vi.mocked(subscribeDocumentEvents).mock.calls[0][0]).toBe(instance)
+
+    const stableHandler = vi.mocked(subscribeDocumentEvents).mock.calls[0][1]
+    expect(typeof stableHandler).toBe('function')
+
+    const event = {type: 'edited', documentId: 'doc1', outgoing: {}} as DocumentEvent
+    stableHandler(event)
+    expect(handler).toHaveBeenCalledWith(event)
+  })
+
+  it('calls the unsubscribe function on unmount', () => {
+    const handler = vi.fn()
+    const unsubscribe = vi.fn()
+    vi.mocked(subscribeDocumentEvents).mockReturnValue(unsubscribe)
+
+    const {unmount} = renderHook(() => useDocumentEvent(handler, docHandle))
+    unmount()
+    expect(unsubscribe).toHaveBeenCalledTimes(1)
+  })
+})

package/src/hooks/document/useDocumentEvent.ts

@@ -0,0 +1,54 @@
+import {
+  type DocumentEvent,
+  type DocumentHandle,
+  getResourceId,
+  subscribeDocumentEvents,
+} from '@sanity/sdk'
+import {useCallback, useEffect, useInsertionEffect, useRef} from 'react'
+
+import {useSanityInstance} from '../context/useSanityInstance'
+
+/**
+ *
+ * @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(() => {
+    ref.current = handler
+  })
+
+  const stableHandler = useCallback((documentEvent: DocumentEvent) => {
+    return ref.current(documentEvent)
+  }, [])
+
+  const instance = useSanityInstance(getResourceId(doc.resourceId))
+  useEffect(() => {
+    return subscribeDocumentEvents(instance, stableHandler)
+  }, [instance, stableHandler])
+}

package/src/hooks/document/useDocumentPermissions.ts

@@ -0,0 +1,84 @@
+import {
+  type DocumentAction,
+  type DocumentPermissionsResult,
+  getPermissionsState,
+  getResourceId,
+} from '@sanity/sdk'
+import {useCallback, useMemo, useSyncExternalStore} from 'react'
+import {filter, firstValueFrom} from 'rxjs'
+
+import {useSanityInstance} from '../context/useSanityInstance'
+
+/**
+ *
+ * @beta
+ *
+ * Check if the current user has the specified permissions for the given document actions.
+ *
+ * @category Permissions
+ * @param actions - One more more calls to a particular document action function for a given document
+ * @returns An object that specifies whether the action is allowed; if the action is not allowed, an explanatory message and list of reasons is also provided.
+ *
+ * @example Checking for permission to publish a document
+ * ```ts
+ * import {useDocumentPermissions, useApplyDocumentActions} from '@sanity/sdk-react'
+ * import {publishDocument} from '@sanity/sdk'
+ *
+ * export function PublishButton({doc}: {doc: DocumentHandle}) {
+ *   const publishPermissions = useDocumentPermissions(publishDocument(doc))
+ *   const applyAction = useApplyDocumentActions()
+ *
+ *   return (
+ *     <>
+ *       <button
+ *         disabled={!publishPermissions.allowed}
+ *         onClick={() => applyAction(publishDocument(doc))}
+ *         popoverTarget={`${publishPermissions.allowed ? undefined : 'publishButtonPopover'}`}
+ *       >
+ *         Publish
+ *       </button>
+ *       {!publishPermissions.allowed && (
+ *         <div popover id="publishButtonPopover">
+ *           {publishPermissions.message}
+ *         </div>
+ *       )}
+ *     </>
+ *   )
+ * }
+ * ```
+ */
+export function useDocumentPermissions(
+  actions: DocumentAction | DocumentAction[],
+): DocumentPermissionsResult {
+  // if actions is an array, we need to check each action to see if the resourceId is the same
+  if (Array.isArray(actions)) {
+    const resourceIds = actions.map((action) => action.resourceId)
+    const uniqueResourceIds = new Set(resourceIds)
+    if (uniqueResourceIds.size !== 1) {
+      throw new Error('All actions must have the same resourceId')
+    }
+  }
+  const resourceId = Array.isArray(actions)
+    ? getResourceId(actions[0].resourceId)
+    : getResourceId(actions.resourceId)
+
+  const instance = useSanityInstance(resourceId)
+  const isDocumentReady = useCallback(
+    () => getPermissionsState(instance, actions).getCurrent() !== undefined,
+    [actions, instance],
+  )
+  if (!isDocumentReady()) {
+    throw firstValueFrom(
+      getPermissionsState(instance, actions).observable.pipe(
+        filter((result) => result !== undefined),
+      ),
+    )
+  }
+
+  const {subscribe, getCurrent} = useMemo(
+    () => getPermissionsState(instance, actions),
+    [actions, instance],
+  )
+
+  return useSyncExternalStore(subscribe, getCurrent) as DocumentPermissionsResult
+}

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

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

package/src/hooks/document/useDocumentSyncStatus.ts

@@ -0,0 +1,33 @@
+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
+ * @function
+ */
+export const useDocumentSyncStatus: UseDocumentSyncStatus =
+  createStateSourceHook(getDocumentSyncStatus)