@sanity/sdk-react 0.0.0-alpha.8 → 0.0.0-rc.0

package/src/hooks/comlink/useManageFavorite.ts

@@ -0,0 +1,98 @@
+import {type Events, SDK_CHANNEL_NAME, SDK_NODE_NAME} from '@sanity/message-protocol'
+import {type DocumentHandle, type FrameMessage} from '@sanity/sdk'
+import {useCallback, useState} from 'react'
+
+import {useWindowConnection} from './useWindowConnection'
+
+// should we import this whole type from the message protocol?
+
+interface ManageFavorite {
+  favorite: () => void
+  unfavorite: () => void
+  isFavorited: boolean
+  isConnected: boolean
+}
+
+/**
+ * @beta
+ *
+ * ## useManageFavorite
+ * This hook provides functionality to add and remove documents from favorites,
+ * and tracks the current favorite status of the document.
+ * @category Core UI Communication
+ * @param documentHandle - The document handle containing document ID and type, like `{_id: '123', _type: 'book'}`
+ * @returns An object containing:
+ * - `favorite` - Function to add document to favorites
+ * - `unfavorite` - Function to remove document from favorites
+ * - `isFavorited` - Boolean indicating if document is currently favorited
+ * - `isConnected` - Boolean indicating if connection to Core UI is established
+ *
+ * @example
+ * ```tsx
+ * function MyDocumentAction(props: DocumentActionProps) {
+ *   const {_id, _type} = props
+ *   const {favorite, unfavorite, isFavorited, isConnected} = useManageFavorite({
+ *     _id,
+ *     _type
+ *   })
+ *
+ *   return (
+ *     <Button
+ *       disabled={!isConnected}
+ *       onClick={() => isFavorited ? unfavorite() : favorite()}
+ *       text={isFavorited ? 'Remove from favorites' : 'Add to favorites'}
+ *     />
+ *   )
+ * }
+ * ```
+ */
+export function useManageFavorite({_id, _type}: DocumentHandle): ManageFavorite {
+  const [isFavorited, setIsFavorited] = useState(false) // should load this from a comlink fetch
+  const {sendMessage, status} = useWindowConnection<Events.FavoriteMessage, FrameMessage>({
+    name: SDK_NODE_NAME,
+    connectTo: SDK_CHANNEL_NAME,
+  })
+
+  const handleFavoriteAction = useCallback(
+    (action: 'added' | 'removed', setFavoriteState: boolean) => {
+      if (!_id || !_type) return
+
+      try {
+        const message: Events.FavoriteMessage = {
+          type: 'core/v1/events/favorite',
+          data: {
+            eventType: action,
+            documentId: _id,
+            documentType: _type,
+          },
+        }
+
+        sendMessage(message.type, message.data)
+        setIsFavorited(setFavoriteState)
+      } catch (err) {
+        const error = err instanceof Error ? err : new Error('Failed to update favorite status')
+        // eslint-disable-next-line no-console
+        console.error(
+          `Failed to ${action === 'added' ? 'favorite' : 'unfavorite'} document:`,
+          error,
+        )
+        throw error
+      }
+    },
+    [_id, _type, sendMessage],
+  )
+
+  const favorite = useCallback(() => handleFavoriteAction('added', true), [handleFavoriteAction])
+
+  const unfavorite = useCallback(
+    () => handleFavoriteAction('removed', false),
+    [handleFavoriteAction],
+  )
+
+  return {
+    favorite,
+    unfavorite,
+    isFavorited,
+    isConnected: status === 'connected',
+  }
+}

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

@@ -0,0 +1,77 @@
+import {type Message, type Node, type Status} from '@sanity/comlink'
+import {getOrCreateNode} from '@sanity/sdk'
+import {beforeEach, describe, expect, it, vi} from 'vitest'
+
+import {act, renderHook} from '../../../test/test-utils'
+import {useRecordDocumentHistoryEvent} from './useRecordDocumentHistoryEvent'
+
+vi.mock(import('@sanity/sdk'), async (importOriginal) => {
+  const actual = await importOriginal()
+  return {
+    ...actual,
+    getOrCreateNode: vi.fn(),
+    releaseNode: vi.fn(),
+  }
+})
+
+describe('useRecordDocumentHistoryEvent', () => {
+  let node: Node<Message, Message>
+  let statusCallback: ((status: Status) => void) | null = null
+
+  const mockDocumentHandle = {
+    _id: 'mock-id',
+    _type: 'mock-type',
+  }
+
+  function createMockNode() {
+    return {
+      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)
+  })
+
+  it('should initialize with correct connection status', () => {
+    const {result} = renderHook(() => useRecordDocumentHistoryEvent(mockDocumentHandle))
+
+    expect(result.current.isConnected).toBe(false)
+
+    act(() => {
+      statusCallback?.('connected')
+    })
+
+    expect(result.current.isConnected).toBe(true)
+  })
+
+  it('should send correct message when recording events', () => {
+    const {result} = renderHook(() => useRecordDocumentHistoryEvent(mockDocumentHandle))
+
+    result.current.recordEvent('viewed')
+
+    expect(node.post).toHaveBeenCalledWith('core/v1/events/history', {
+      eventType: 'viewed',
+      documentId: 'mock-id',
+      documentType: 'mock-type',
+    })
+  })
+
+  it('should handle errors when sending messages', () => {
+    vi.mocked(node.post).mockImplementation(() => {
+      throw new Error('Failed to send message')
+    })
+
+    const {result} = renderHook(() => useRecordDocumentHistoryEvent(mockDocumentHandle))
+
+    expect(() => result.current.recordEvent('viewed')).toThrow('Failed to send message')
+  })
+})

package/src/hooks/comlink/useRecordDocumentHistoryEvent.ts

@@ -0,0 +1,75 @@
+import {type Events, SDK_CHANNEL_NAME, SDK_NODE_NAME} from '@sanity/message-protocol'
+import {type DocumentHandle, type FrameMessage} from '@sanity/sdk'
+import {useCallback} from 'react'
+
+import {useWindowConnection} from './useWindowConnection'
+
+interface DocumentInteractionHistory {
+  recordEvent: (eventType: 'viewed' | 'edited' | 'created' | 'deleted') => void
+  isConnected: boolean
+}
+
+/**
+ * @public
+ * Hook for managing document interaction history in Sanity Studio.
+ * This hook provides functionality to record document interactions.
+ * @param documentHandle - The document handle containing document ID and type, like `{_id: '123', _type: 'book'}`
+ * @returns An object containing:
+ * - `recordEvent` - Function to record document interactions
+ * - `isConnected` - Boolean indicating if connection to Studio is established
+ *
+ * @example
+ * ```tsx
+ * function MyDocumentAction(props: DocumentActionProps) {
+ *   const {_id, _type} = props
+ *   const {recordEvent, isConnected} = useRecordDocumentHistoryEvent({
+ *     _id,
+ *     _type
+ *   })
+ *
+ *   return (
+ *     <Button
+ *       disabled={!isConnected}
+ *       onClick={() => recordEvent('viewed')}
+ *       text={'Viewed'}
+ *     />
+ *   )
+ * }
+ * ```
+ */
+export function useRecordDocumentHistoryEvent({
+  _id,
+  _type,
+}: DocumentHandle): DocumentInteractionHistory {
+  const {sendMessage, status} = useWindowConnection<Events.HistoryMessage, FrameMessage>({
+    name: SDK_NODE_NAME,
+    connectTo: SDK_CHANNEL_NAME,
+  })
+
+  const recordEvent = useCallback(
+    (eventType: 'viewed' | 'edited' | 'created' | 'deleted') => {
+      try {
+        const message: Events.HistoryMessage = {
+          type: 'core/v1/events/history',
+          data: {
+            eventType,
+            documentId: _id,
+            documentType: _type,
+          },
+        }
+
+        sendMessage(message.type, message.data)
+      } catch (error) {
+        // eslint-disable-next-line no-console
+        console.error('Failed to record history event:', error)
+        throw error
+      }
+    },
+    [_id, _type, sendMessage],
+  )
+
+  return {
+    recordEvent,
+    isConnected: status === 'connected',
+  }
+}

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.test.tsx

@@ -11,7 +11,7 @@ describe('useSanityInstance', () => {
 
   it('returns sanity instance when used within provider', () => {
     const wrapper = ({children}: {children: React.ReactNode}) => (
-      <SanityProvider sanityInstance={sanityInstance}>{children}</SanityProvider>
+      <SanityProvider sanityInstances={[sanityInstance]}>{children}</SanityProvider>
     )
 
     const {result} = renderHook(() => useSanityInstance(), {wrapper})

package/src/hooks/context/useSanityInstance.ts

@@ -1,23 +1,39 @@
 import {type SanityInstance} from '@sanity/sdk'
 import {useContext} from 'react'
 
-import {SanityInstanceContext} from '../../context/SanityProvider'
+import {SanityInstanceContext} from '../../context/SanityInstanceContext'
 
 /**
  * `useSanityInstance` returns the current Sanity instance from the application context.
  * This must be called from within a `SanityProvider` component.
- * @public
+ * @internal
+ *
+ * @param resourceId - The resourceId of the Sanity instance to return (optional)
  * @returns The current Sanity instance
  * @example
  * ```tsx
- * const instance = useSanityInstance()
+ * const instance = useSanityInstance('abc123.production')
  * ```
  */
-export const useSanityInstance = (): SanityInstance => {
+export const useSanityInstance = (resourceId?: string): SanityInstance => {
   const sanityInstance = useContext(SanityInstanceContext)
   if (!sanityInstance) {
     throw new Error('useSanityInstance must be called from within the SanityProvider')
   }
+  if (sanityInstance.length === 0) {
+    throw new Error('No Sanity instances found')
+  }
+  if (sanityInstance.length === 1 || !resourceId) {
+    return sanityInstance[0]
+  }
 
-  return sanityInstance
+  if (!resourceId) {
+    throw new Error('resourceId is required when there are multiple Sanity instances')
+  }
+
+  const instance = sanityInstance.find((inst) => inst.identity.resourceId === resourceId)
+  if (!instance) {
+    throw new Error(`Sanity instance with resourceId ${resourceId} not found`)
+  }
+  return instance
 }

package/src/hooks/datasets/useDatasets.ts

@@ -0,0 +1,37 @@
+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 in your organization.
+   *
+   * @category Datasets
+   * @returns The metadata for your organization's datasets
+   *
+   * @example
+   * ```tsx
+   * const datasets = useDatasets()
+   *
+   * return (
+   *   <select>
+   *     {datasets.map((dataset) => (
+   *       <option key={dataset.name}>{dataset.name}</option>
+   *     ))}
+   *   </select>
+   * )
+   * ```
+   *
+   */
+  (): DatasetsResponse
+}
+
+/** @public */
+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/useApplyActions.test.ts

@@ -0,0 +1,25 @@
+import {applyActions, 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, applyActions: vi.fn()}
+})
+
+describe('useApplyActions', () => {
+  it('calls `createCallbackHook` with `applyActions`', async () => {
+    const {useApplyActions} = await import('./useApplyActions')
+    const resourceId: ResourceId = 'project1.dataset1'
+    expect(createCallbackHook).not.toHaveBeenCalled()
+
+    expect(applyActions).not.toHaveBeenCalled()
+    const apply = useApplyActions(resourceId)
+    apply(createDocument({_type: 'author'}))
+    expect(applyActions).toHaveBeenCalledWith(createDocument({_type: 'author'}))
+  })
+})

package/src/hooks/document/useApplyActions.ts

@@ -0,0 +1,74 @@
+import {
+  type ActionsResult,
+  applyActions,
+  type ApplyActionsOptions,
+  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 { 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(
+  resourceId?: ResourceId,
+): (
+  action: DocumentAction | DocumentAction[],
+  options?: ApplyActionsOptions,
+) => Promise<ActionsResult> {
+  return _useApplyActions(resourceId)()
+}
+
+const _useApplyActions = (resourceId?: ResourceId) => createCallbackHook(applyActions, 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)
+  })
+})