@sanity/sdk-react 0.0.0-alpha.8 → 0.0.0-chore-react-18-compat.0

package/src/hooks/dashboard/useStudioWorkspacesByResourceId.test.tsx

@@ -0,0 +1,278 @@
+import {type Message, type Status} from '@sanity/comlink'
+import {renderHook, waitFor} from '@testing-library/react'
+import {describe, expect, it, vi} from 'vitest'
+
+import {useWindowConnection, type WindowConnection} from '../comlink/useWindowConnection'
+import {useStudioWorkspacesByResourceId} from './useStudioWorkspacesByResourceId'
+
+vi.mock('../comlink/useWindowConnection', () => ({
+  useWindowConnection: vi.fn(),
+}))
+
+const mockWorkspaceData = {
+  context: {
+    availableResources: [
+      {
+        projectId: 'project1',
+        workspaces: [
+          {
+            name: 'workspace1',
+            title: 'Workspace 1',
+            basePath: '/workspace1',
+            dataset: 'dataset1',
+            userApplicationId: 'user1',
+            url: 'https://test.sanity.studio',
+            _ref: 'user1-workspace1',
+          },
+          {
+            name: 'workspace2',
+            title: 'Workspace 2',
+            basePath: '/workspace2',
+            dataset: 'dataset1',
+            userApplicationId: 'user1',
+            url: 'https://test.sanity.studio',
+            _ref: 'user1-workspace2',
+          },
+        ],
+      },
+      {
+        projectId: 'project2',
+        workspaces: [
+          {
+            name: 'workspace3',
+            title: 'Workspace 3',
+            basePath: '/workspace3',
+            dataset: 'dataset2',
+            userApplicationId: 'user2',
+            url: 'https://test.sanity.studio',
+            _ref: 'user2-workspace3',
+          },
+        ],
+      },
+      {
+        // Project without workspaces
+        projectId: 'project3',
+        workspaces: [],
+      },
+    ],
+  },
+}
+
+describe('useStudioWorkspacesByResourceId', () => {
+  it('should return empty workspaces and connected=false when not connected', async () => {
+    // Create a mock that captures the onStatus callback
+    let capturedOnStatus: ((status: Status) => void) | undefined
+
+    vi.mocked(useWindowConnection).mockImplementation(({onStatus}) => {
+      capturedOnStatus = onStatus
+
+      return {
+        fetch: undefined,
+        sendMessage: vi.fn(),
+      } as unknown as WindowConnection<Message>
+    })
+
+    const {result} = renderHook(() => useStudioWorkspacesByResourceId())
+
+    // Call onStatus with 'idle' to simulate not connected
+    if (capturedOnStatus) capturedOnStatus('idle')
+
+    expect(result.current).toEqual({
+      workspacesByResourceId: {},
+      error: null,
+      isConnected: false,
+    })
+  })
+
+  it('should process workspaces into lookup by projectId:dataset', async () => {
+    const mockFetch = vi.fn().mockResolvedValue(mockWorkspaceData)
+    let capturedOnStatus: ((status: Status) => void) | undefined
+
+    vi.mocked(useWindowConnection).mockImplementation(({onStatus}) => {
+      capturedOnStatus = onStatus
+
+      return {
+        fetch: mockFetch,
+        sendMessage: vi.fn(),
+      } as unknown as WindowConnection<Message>
+    })
+
+    const {result} = renderHook(() => useStudioWorkspacesByResourceId())
+
+    // Call onStatus with 'connected' to simulate connected state
+    if (capturedOnStatus) capturedOnStatus('connected')
+
+    await waitFor(() => {
+      expect(result.current.workspacesByResourceId).toEqual({
+        'project1:dataset1': [
+          {
+            name: 'workspace1',
+            title: 'Workspace 1',
+            basePath: '/workspace1',
+            dataset: 'dataset1',
+            userApplicationId: 'user1',
+            url: 'https://test.sanity.studio',
+            _ref: 'user1-workspace1',
+          },
+          {
+            name: 'workspace2',
+            title: 'Workspace 2',
+            basePath: '/workspace2',
+            dataset: 'dataset1',
+            userApplicationId: 'user1',
+            url: 'https://test.sanity.studio',
+            _ref: 'user1-workspace2',
+          },
+        ],
+        'project2:dataset2': [
+          {
+            name: 'workspace3',
+            title: 'Workspace 3',
+            basePath: '/workspace3',
+            dataset: 'dataset2',
+            userApplicationId: 'user2',
+            url: 'https://test.sanity.studio',
+            _ref: 'user2-workspace3',
+          },
+        ],
+      })
+      expect(result.current.error).toBeNull()
+      expect(result.current.isConnected).toBe(true)
+    })
+
+    expect(mockFetch).toHaveBeenCalledWith(
+      'dashboard/v1/bridge/context',
+      undefined,
+      expect.any(Object),
+    )
+  })
+
+  it('should handle fetch errors', async () => {
+    const mockFetch = vi.fn().mockRejectedValue(new Error('Failed to fetch'))
+    let capturedOnStatus: ((status: Status) => void) | undefined
+
+    vi.mocked(useWindowConnection).mockImplementation(({onStatus}) => {
+      capturedOnStatus = onStatus
+
+      return {
+        fetch: mockFetch,
+        sendMessage: vi.fn(),
+      } as unknown as WindowConnection<Message>
+    })
+
+    const {result} = renderHook(() => useStudioWorkspacesByResourceId())
+
+    // Call onStatus with 'connected' to simulate connected state
+    if (capturedOnStatus) capturedOnStatus('connected')
+
+    await waitFor(() => {
+      expect(result.current.workspacesByResourceId).toEqual({})
+      expect(result.current.error).toBe('Failed to fetch workspaces')
+      expect(result.current.isConnected).toBe(true)
+    })
+  })
+
+  it('should handle AbortError silently', async () => {
+    const abortError = new Error('Aborted')
+    abortError.name = 'AbortError'
+    const mockFetch = vi.fn().mockRejectedValue(abortError)
+    let capturedOnStatus: ((status: Status) => void) | undefined
+
+    vi.mocked(useWindowConnection).mockImplementation(({onStatus}) => {
+      capturedOnStatus = onStatus
+
+      return {
+        fetch: mockFetch,
+        sendMessage: vi.fn(),
+      } as unknown as WindowConnection<Message>
+    })
+
+    const {result} = renderHook(() => useStudioWorkspacesByResourceId())
+
+    // Call onStatus with 'connected' to simulate connected state
+    if (capturedOnStatus) capturedOnStatus('connected')
+
+    await waitFor(() => {
+      expect(result.current.workspacesByResourceId).toEqual({})
+      expect(result.current.error).toBeNull()
+      expect(result.current.isConnected).toBe(true)
+    })
+  })
+
+  it('should handle projects without workspaces', async () => {
+    const mockFetch = vi.fn().mockResolvedValue({
+      context: {
+        availableResources: [
+          {
+            projectId: 'project1',
+            workspaces: [],
+          },
+        ],
+      },
+    })
+    let capturedOnStatus: ((status: Status) => void) | undefined
+
+    vi.mocked(useWindowConnection).mockImplementation(({onStatus}) => {
+      capturedOnStatus = onStatus
+
+      return {
+        fetch: mockFetch,
+        sendMessage: vi.fn(),
+      } as unknown as WindowConnection<Message>
+    })
+
+    const {result} = renderHook(() => useStudioWorkspacesByResourceId())
+
+    // Call onStatus with 'connected' to simulate connected state
+    if (capturedOnStatus) capturedOnStatus('connected')
+
+    await waitFor(() => {
+      expect(result.current.workspacesByResourceId).toEqual({})
+      expect(result.current.error).toBeNull()
+      expect(result.current.isConnected).toBe(true)
+    })
+  })
+
+  it('should handle projects without projectId', async () => {
+    const mockFetch = vi.fn().mockResolvedValue({
+      context: {
+        availableResources: [
+          {
+            workspaces: [
+              {
+                name: 'workspace1',
+                title: 'Workspace 1',
+                basePath: '/workspace1',
+                dataset: 'dataset1',
+                userApplicationId: 'user1',
+                url: 'https://test.sanity.studio',
+                _ref: 'user1-workspace1',
+              },
+            ],
+          },
+        ],
+      },
+    })
+    let capturedOnStatus: ((status: Status) => void) | undefined
+
+    vi.mocked(useWindowConnection).mockImplementation(({onStatus}) => {
+      capturedOnStatus = onStatus
+
+      return {
+        fetch: mockFetch,
+        sendMessage: vi.fn(),
+      } as unknown as WindowConnection<Message>
+    })
+
+    const {result} = renderHook(() => useStudioWorkspacesByResourceId())
+
+    // Call onStatus with 'connected' to simulate connected state
+    if (capturedOnStatus) capturedOnStatus('connected')
+
+    await waitFor(() => {
+      expect(result.current.workspacesByResourceId).toEqual({})
+      expect(result.current.error).toBeNull()
+      expect(result.current.isConnected).toBe(true)
+    })
+  })
+})

package/src/hooks/dashboard/useStudioWorkspacesByResourceId.ts

@@ -0,0 +1,92 @@
+import {type Status} from '@sanity/comlink'
+import {SDK_CHANNEL_NAME, SDK_NODE_NAME} from '@sanity/message-protocol'
+import {useEffect, useState} from 'react'
+
+import {useWindowConnection} from '../comlink/useWindowConnection'
+
+interface Workspace {
+  name: string
+  title: string
+  basePath: string
+  dataset: string
+  userApplicationId: string
+  url: string
+  _ref: string
+}
+
+interface WorkspacesByResourceId {
+  [key: string]: Workspace[] // key format: `${projectId}:${dataset}`
+}
+
+interface StudioWorkspacesResult {
+  workspacesByResourceId: WorkspacesByResourceId
+  error: string | null
+  isConnected: boolean
+}
+
+/**
+ * Hook that fetches studio workspaces and organizes them by projectId:dataset
+ * @internal
+ */
+export function useStudioWorkspacesByResourceId(): StudioWorkspacesResult {
+  const [workspacesByResourceId, setWorkspacesByResourceId] = useState<WorkspacesByResourceId>({})
+  const [status, setStatus] = useState<Status>('idle')
+  const [error, setError] = useState<string | null>(null)
+
+  const {fetch} = useWindowConnection({
+    name: SDK_NODE_NAME,
+    connectTo: SDK_CHANNEL_NAME,
+    onStatus: setStatus,
+  })
+
+  // Once computed, this should probably be in a store and poll for changes
+  // However, our stores are currently being refactored
+  useEffect(() => {
+    if (!fetch || status !== 'connected') return
+
+    async function fetchWorkspaces(signal: AbortSignal) {
+      try {
+        const data = await fetch<{
+          context: {availableResources: Array<{projectId: string; workspaces: Workspace[]}>}
+        }>('dashboard/v1/bridge/context', undefined, {signal})
+
+        const workspaceMap: WorkspacesByResourceId = {}
+
+        data.context.availableResources.forEach((resource) => {
+          if (!resource.projectId || !resource.workspaces?.length) return
+
+          resource.workspaces.forEach((workspace) => {
+            const key = `${resource.projectId}:${workspace.dataset}`
+            if (!workspaceMap[key]) {
+              workspaceMap[key] = []
+            }
+            workspaceMap[key].push(workspace)
+          })
+        })
+
+        setWorkspacesByResourceId(workspaceMap)
+        setError(null)
+      } catch (err: unknown) {
+        if (err instanceof Error) {
+          if (err.name === 'AbortError') {
+            return
+          }
+          setError('Failed to fetch workspaces')
+        }
+      }
+    }
+
+    const controller = new AbortController()
+    fetchWorkspaces(controller.signal)
+
+    return () => {
+      controller.abort()
+    }
+  }, [fetch, status])
+
+  return {
+    workspacesByResourceId,
+    error,
+    isConnected: status === 'connected',
+  }
+}

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