@sanity/sdk-react 0.0.0-alpha.11 → 0.0.0-alpha.12

package/src/hooks/comlink/useWindowConnection.test.ts

@@ -1,8 +1,8 @@
-import {type Message, type Node} from '@sanity/comlink'
+import {type Message, type Node, type Status} from '@sanity/comlink'
 import {getOrCreateNode, releaseNode} from '@sanity/sdk'
 import {beforeEach, describe, expect, it, vi} from 'vitest'
 
-import {renderHook} from '../../../test/test-utils'
+import {act, renderHook} from '../../../test/test-utils'
 import {useWindowConnection} from './useWindowConnection'
 
 vi.mock(import('@sanity/sdk'), async (importOriginal) => {
@@ -26,24 +26,55 @@ interface AnotherMessage {
 
 type TestMessages = TestMessage | AnotherMessage
 
-function createMockNode() {
-  return {
-    // return unsubscribe function
-    on: vi.fn(() => () => {}),
-    post: vi.fn(),
-    stop: vi.fn(),
-  } as unknown as Node<Message, Message>
-}
-
 describe('useWindowConnection', () => {
   let node: Node<Message, Message>
+  let statusCallback: ((status: Status) => void) | null = null
+
+  function createMockNode() {
+    return {
+      // return unsubscribe function
+      on: vi.fn(() => () => {}),
+      post: vi.fn(),
+      stop: vi.fn(),
+      onStatus: vi.fn((callback) => {
+        statusCallback = callback
+        return () => {}
+      }),
+    } as unknown as Node<Message, Message>
+  }
 
   beforeEach(() => {
+    statusCallback = null
     node = createMockNode()
-
     vi.mocked(getOrCreateNode).mockReturnValue(node as unknown as Node<Message, Message>)
   })
 
+  it('should initialize with idle status', () => {
+    const {result} = renderHook(() =>
+      useWindowConnection<TestMessages, TestMessages>({
+        name: 'test',
+        connectTo: 'window',
+      }),
+    )
+
+    expect(result.current.status).toBe('idle')
+  })
+
+  it('should update status to connected when node connects', async () => {
+    const {result} = renderHook(() =>
+      useWindowConnection<TestMessages, TestMessages>({
+        name: 'test',
+        connectTo: 'window',
+      }),
+    )
+
+    expect(result.current.status).toBe('idle')
+    act(() => {
+      statusCallback?.('connected')
+    })
+    expect(result.current.status).toBe('connected')
+  })
+
   it('should register message handlers', () => {
     const mockHandler = vi.fn()
     const mockData = {someData: 'test'}

package/src/hooks/comlink/useWindowConnection.ts

@@ -1,5 +1,6 @@
+import {type Status} from '@sanity/comlink'
 import {type FrameMessage, getOrCreateNode, releaseNode, type WindowMessage} from '@sanity/sdk'
-import {useCallback, useEffect, useMemo} from 'react'
+import {useCallback, useEffect, useMemo, useState} from 'react'
 
 import {useSanityInstance} from '../context/useSanityInstance'
 
@@ -27,6 +28,7 @@ export interface WindowConnection<TMessage extends WindowMessage> {
     type: TType,
     data?: Extract<TMessage, {type: TType}>['data'],
   ) => void
+  status: Status
 }
 
 /**
@@ -38,12 +40,21 @@ export function useWindowConnection<
 >(options: UseWindowConnectionOptions<TFrameMessage>): WindowConnection<TWindowMessage> {
   const {name, onMessage, connectTo} = options
   const instance = useSanityInstance()
+  const [status, setStatus] = useState<Status>('idle')
 
   const node = useMemo(
     () => getOrCreateNode(instance, {name, connectTo}),
     [instance, name, connectTo],
   )
 
+  useEffect(() => {
+    const unsubscribe = node.onStatus((newStatus) => {
+      setStatus(newStatus)
+    })
+
+    return unsubscribe
+  }, [node, instance, name])
+
   useEffect(() => {
     if (!onMessage) return
 
@@ -78,5 +89,6 @@ export function useWindowConnection<
 
   return {
     sendMessage,
+    status,
   }
 }

package/src/hooks/context/useSanityInstance.ts

@@ -6,7 +6,7 @@ import {SanityInstanceContext} from '../../context/SanityProvider'
 /**
  * `useSanityInstance` returns the current Sanity instance from the application context.
  * This must be called from within a `SanityProvider` component.
- * @public
+ * @internal
  * @returns The current Sanity instance
  * @example
  * ```tsx

package/src/hooks/document/useApplyActions.ts

@@ -8,11 +8,55 @@ import {type SanityDocument} from '@sanity/types'
 
 import {createCallbackHook} from '../helpers/createCallbackHook'
 
-/** @beta */
+/**
+ *
+ * @beta
+ *
+ * Provides a callback for applying one or more actions to a document.
+ *
+ * @category Documents
+ * @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(): <TDocument extends SanityDocument>(
   action: DocumentAction<TDocument> | DocumentAction<TDocument>[],
   options?: ApplyActionsOptions,
 ) => Promise<ActionsResult<TDocument>>
+
 /** @beta */
 export function useApplyActions(): (
   action: DocumentAction | DocumentAction[],

package/src/hooks/document/useDocument.ts

@@ -10,16 +10,90 @@ import {useCallback, useMemo, useSyncExternalStore} from 'react'
 
 import {useSanityInstance} from '../context/useSanityInstance'
 
-/** @beta */
+/**
+ * @beta
+ *
+ * ## useDocument(doc, path)
+ * Read and subscribe to nested values in a document
+ * @category Documents
+ * @param doc - The document to read state from
+ * @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 */
+
+/**
+ * @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>,
 ): TDocument | null
-/** @beta */
+
+/**
+ * @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: string | DocumentHandle, path?: string): unknown {
   const documentId = typeof doc === 'string' ? doc : doc._id
   const instance = useSanityInstance()

package/src/hooks/document/useDocumentEvent.ts

@@ -3,7 +3,29 @@ import {useCallback, useEffect, useInsertionEffect, useRef} from 'react'
 
 import {useSanityInstance} from '../context/useSanityInstance'
 
-/** @beta */
+/**
+ *
+ * @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.
+ * @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): void {
   const ref = useRef(handler)
 

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,29 @@
-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
+   * @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' }
+   * 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.ts

@@ -17,7 +17,52 @@ const ignoredKeys = ['_id', '_type', '_createdAt', '_updatedAt', '_rev']
 
 type Updater<TValue> = TValue | ((nextValue: TValue) => TValue)
 
-/** @beta */
+/**
+ *
+ * @beta
+ *
+ * ## useEditDocument(doc, path)
+ * Edit a nested value within a document
+ *
+ * @category Documents
+ * @param doc - The document to be edited; either as a document handle or the document’s ID a string
+ * @param path - The path to the nested value to be edited
+ * @returns A function to update the nested value. Accepts either a new value, or an updater function that exposes the previous value and returns a new value.
+ * @example Update a document’s name by providing the new value directly
+ * ```
+ * const handle = { _id: 'documentId', _type: 'documentType' }
+ * const name = useDocument(handle, 'name')
+ * const editName = useEditDocument(handle, 'name')
+ *
+ * function handleNameChange(event: React.ChangeEvent<HTMLInputElement>) {
+ *   editName(event.target.value)
+ * }
+ *
+ * return (
+ *   <input type='text' value={name} onChange={handleNameChange} />
+ * )
+ * ```
+ *
+ * @example Update a count on a document by providing an updater function
+ * ```
+ * const handle = { _id: 'documentId', _type: 'documentType' }
+ * const count = useDocument(handle, 'count')
+ * const editCount = useEditDocument(handle, 'count')
+ *
+ * function incrementCount() {
+ *   editCount(previousCount => previousCount + 1)
+ * }
+ *
+ * return (
+ *   <>
+ *     <button onClick={incrementCount}>
+ *       Increment
+ *     </button>
+ *     Current count: {count}
+ *   </>
+ * )
+ * ```
+ */
 export function useEditDocument<
   TDocument extends SanityDocument,
   TPath extends JsonMatchPath<TDocument>,
@@ -25,11 +70,81 @@ export function useEditDocument<
   doc: string | DocumentHandle<TDocument>,
   path: TPath,
 ): (nextValue: Updater<JsonMatch<TDocument, TPath>>) => Promise<ActionsResult<TDocument>>
-/** @beta */
+
+/**
+ *
+ * @beta
+ *
+ * ## useEditDocument(doc)
+ * Edit an entire document
+ * @param doc - The document to be edited; either as a document handle or the document’s ID a string
+ * @returns A function to update the document state. Accepts either a new document state, or an updater function that exposes the previous document state and returns the new document state.
+ * @example
+ * ```
+ * const myDocumentHandle = { _id: 'documentId', _type: 'documentType' }
+ *
+ * const myDocument = useDocument(myDocumentHandle)
+ * const { title, price } = myDocument
+ *
+ * const editMyDocument = useEditDocument(myDocumentHandle)
+ *
+ * function handleFieldChange(e: React.ChangeEvent<HTMLInputElement>) {
+ *   const {name, value} = e.currentTarget
+ *   // Use an updater function to update the document state based on the previous state
+ *   editMyDocument(previousDocument => ({
+ *     ...previousDocument,
+ *     [name]: value
+ *   }))
+ * }
+ *
+ * function handleSaleChange(e: React.ChangeEvent<HTMLInputElement>) {
+ *   const { checked } = e.currentTarget
+ *   if (checked) {
+ *     // Use an updater function to add a new salePrice field;
+ *     // set it at a 20% discount off the normal price
+ *     editMyDocument(previousDocument => ({
+ *       ...previousDocument,
+ *       salePrice: previousDocument.price * 0.8,
+ *     }))
+ *   } else {
+ *     // Get the document state without the salePrice field
+ *     const { salePrice, ...rest } = myDocument
+ *     // Update the document state to remove the salePrice field
+ *     editMyDocument(rest)
+ *   }
+ * }
+ *
+ * return (
+ *   <>
+ *     <form onSubmit={e => e.preventDefault()}>
+ *       <input name='title' type='text' value={title} onChange={handleFieldChange} />
+ *       <input name='price' type='number' value={price} onChange={handleFieldChange} />
+ *       <input
+ *         name='salePrice'
+ *         type='checkbox'
+ *         checked={Object(myDocument).hasOwnProperty('salePrice')}
+ *         onChange={handleSaleChange}
+ *       />
+ *     </form>
+ *     <pre><code>
+ *       {JSON.stringify(myDocument, null, 2)}
+ *     </code></pre>
+ *   </>
+ * )
+ * ```
+ */
 export function useEditDocument<TDocument extends SanityDocument>(
   doc: string | DocumentHandle<TDocument>,
 ): (nextValue: Updater<TDocument>) => Promise<ActionsResult<TDocument>>
-/** @beta */
+
+/**
+ *
+ * @beta
+ *
+ * Enables editing of a document’s state.
+ * When called with a `path` argument, the hook will return a function for updating a nested value.
+ * When called without a `path` argument, the hook will return a function for updating the entire document.
+ */
 export function useEditDocument(
   doc: string | DocumentHandle,
   path?: string,

package/src/hooks/document/usePermissions.ts

@@ -0,0 +1,28 @@
+import {type DocumentAction, getPermissionsState, type PermissionsResult} from '@sanity/sdk'
+import {useCallback, useMemo, useSyncExternalStore} from 'react'
+import {filter, firstValueFrom} from 'rxjs'
+
+import {useSanityInstance} from '../context/useSanityInstance'
+
+/** @beta */
+export function usePermissions(actions: DocumentAction | DocumentAction[]): PermissionsResult {
+  const instance = useSanityInstance()
+  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 PermissionsResult
+}

package/src/hooks/documentCollection/useDocuments.ts

@@ -5,8 +5,10 @@ import {useSanityInstance} from '../context/useSanityInstance'
 
 /**
  * @public
+ * A live collection of {@link DocumentHandle}s, along with metadata about the collection and a function for loading more of them.
+ * @category Types
  */
-export interface DocumentCollection {
+export interface DocumentHandleCollection {
   /** Retrieve more documents matching the provided options */
   loadMore: () => void
   /** The retrieved document handles of the documents matching the provided options */
@@ -31,13 +33,19 @@ const STABLE_EMPTY = {
 /**
  * @public
  *
- * The `useDocuments` hook retrieves and provides access to a live collection of documents, optionally filtered, sorted, and matched to a given Content Lake perspective.
- * Because the returned document collection is live, the results will update in real time until the component invoking the hook is unmounted.
+ * Retrieves and provides access to a live collection of {@link DocumentHandle}s, with an optional filter and sort applied.
+ * The returned document handles are canonical — that is, they refer to the document in its current state, whether draft, published, or within a release or perspective.
+ * Because the returned document handle collection is live, the results will update in real time until the component invoking the hook is unmounted.
  *
+ * @remarks
+ * {@link DocumentHandle}s are used by many other hooks (such as {@link usePreview}, {@link useDocument}, and {@link useEditDocument})
+ * to work with documents in various ways without the entire document needing to be fetched upfront.
+ *
+ * @category Documents
  * @param options - Options for narrowing and sorting the document collection
- * @returns The collection of documents matching the provided options (if any), as well as properties describing the collection and a function to load more.
+ * @returns The collection of document handles matching the provided options (if any), as well as properties describing the collection and a function to load more.
  *
- * @example Retrieving all documents of type 'movie'
+ * @example Retrieving document handles for all documents of type 'movie'
  * ```
  * const { results, isPending } = useDocuments({ filter: '_type == "movie"' })
  *
@@ -54,7 +62,7 @@ const STABLE_EMPTY = {
  * )
  * ```
  *
- * @example Retrieving all movies released since 1980, sorted by director’s last name
+ * @example Retrieving document handles for all movies released since 1980, sorted by director’s last name
  * ```
  * const { results } = useDocuments({
  *   filter: '_type == "movie" && releaseDate >= "1980-01-01"',
@@ -79,7 +87,7 @@ const STABLE_EMPTY = {
  * )
  * ```
  */
-export function useDocuments(options: DocumentListOptions = {}): DocumentCollection {
+export function useDocuments(options: DocumentListOptions = {}): DocumentHandleCollection {
   const instance = useSanityInstance()
 
   // NOTE: useState is used because it guaranteed to return a stable reference

package/src/hooks/preview/usePreview.tsx

@@ -5,7 +5,8 @@ import {distinctUntilChanged, EMPTY, Observable, startWith, switchMap} from 'rxj
 import {useSanityInstance} from '../context/useSanityInstance'
 
 /**
- * @alpha
+ * @beta
+ * @category Types
  */
 export interface UsePreviewOptions {
   document: DocumentHandle
@@ -13,7 +14,8 @@ export interface UsePreviewOptions {
 }
 
 /**
- * @alpha
+ * @beta
+ * @category Types
  */
 export interface UsePreviewResults {
   /** The results of resolving the document’s preview values */
@@ -23,13 +25,14 @@ export interface UsePreviewResults {
 }
 
 /**
- * @alpha
+ * @beta
  *
- * The `usePreview` hook takes a document (via a `DocumentHandle`) and returns its resolved preview values,
+ * Returns the preview values of a document (specified via a `DocumentHandle`),
  * including the document’s `title`, `subtitle`, `media`, and `status`. These values are live and will update in realtime.
  * To reduce unnecessary network requests for resolving the preview values, an optional `ref` can be passed to the hook so that preview
  * resolution will only occur if the `ref` is intersecting the current viewport.
  *
+ * @category Documents
  * @param options - The document handle for the document you want to resolve preview values for, and an optional ref
  * @returns The preview values for the given document and a boolean to indicate whether the resolution is pending
  *