@sanity/sdk-react 0.0.0-rc.0 → 0.0.0-rc.2

package/src/hooks/dashboard/useNavigateToStudioDocument.ts

@@ -0,0 +1,123 @@
+import {type Status} from '@sanity/comlink'
+import {SDK_CHANNEL_NAME, SDK_NODE_NAME} from '@sanity/message-protocol'
+import {type DocumentHandle} from '@sanity/sdk'
+import {useCallback, useState} from 'react'
+
+import {useWindowConnection} from '../comlink/useWindowConnection'
+import {useStudioWorkspacesByResourceId} from './useStudioWorkspacesByResourceId'
+
+interface NavigateToResourceMessage {
+  type: 'dashboard/v1/bridge/navigate-to-resource'
+  data: {
+    /**
+     * Resource ID
+     */
+    resourceId: string
+    /**
+     * Resource type
+     * @example 'application' | 'studio'
+     */
+    resourceType: string
+    /**
+     * Path within the resource to navigate to.
+     */
+    path?: string
+  }
+}
+
+interface NavigateToStudioResult {
+  navigateToStudioDocument: () => void
+  isConnected: boolean
+}
+
+/**
+ * @public
+ * Hook that provides a function to navigate to a studio document.
+ * Currently, requires a document handle with a resourceId.
+ * That resourceId is currently formatted like: `document:projectId.dataset:documentId`
+ * If the hook you used to retrieve the document handle doesn't provide a resourceId like this,
+ * you can construct it according to the above format with the document handle's _id.
+ *
+ * This will only work if you have deployed a studio with a workspace
+ * with this projectId / dataset combination.
+ * It may be able to take a custom URL in the future.
+ *
+ * This will likely change in the future.
+ * @param documentHandle - The document handle containing document ID, type, and resource ID
+ * @returns An object containing:
+ * - navigateToStudioDocument - Function that when called will navigate to the studio document
+ * - isConnected - Boolean indicating if connection to Dashboard is established
+ *
+ * @example
+ * ```ts
+ * import {navigateToStudioDocument, type DocumentHandle} from '@sanity/sdk'
+ *
+ * function MyComponent({documentHandle}: {documentHandle: DocumentHandle}) {
+ *   const {navigateToStudioDocument, isConnected} = useNavigateToStudioDocument(documentHandle)
+ *
+ *   return (
+ *     <button onClick={navigateToStudioDocument} disabled={!isConnected}>
+ *       Navigate to Studio Document
+ *     </button>
+ *   )
+ * }
+ * ```
+ */
+export function useNavigateToStudioDocument(
+  documentHandle: DocumentHandle,
+): NavigateToStudioResult {
+  const {workspacesByResourceId, isConnected: workspacesConnected} =
+    useStudioWorkspacesByResourceId()
+  const [status, setStatus] = useState<Status>('idle')
+  const {sendMessage} = useWindowConnection<NavigateToResourceMessage, never>({
+    name: SDK_NODE_NAME,
+    connectTo: SDK_CHANNEL_NAME,
+    onStatus: setStatus,
+  })
+
+  const navigateToStudioDocument = useCallback(() => {
+    if (!workspacesConnected || status !== 'connected' || !documentHandle.resourceId) {
+      return
+    }
+
+    // Extract projectId and dataset from the resourceId (current format: document:projectId.dataset:documentId)
+    const [, projectAndDataset] = documentHandle.resourceId.split(':')
+    const [projectId, dataset] = projectAndDataset.split('.')
+    if (!projectId || !dataset) {
+      return
+    }
+
+    // Find the workspace for this document
+    const workspaces = workspacesByResourceId[`${projectId}:${dataset}`]
+    if (!workspaces?.length) {
+      // eslint-disable-next-line no-console
+      console.warn('No workspace found for document', documentHandle.resourceId)
+      return
+    }
+
+    if (workspaces.length > 1) {
+      // eslint-disable-next-line no-console
+      console.warn('Multiple workspaces found for document', documentHandle.resourceId)
+      // eslint-disable-next-line no-console
+      console.warn('Using the first one', workspaces[0])
+    }
+
+    const workspace = workspaces[0]
+
+    const message: NavigateToResourceMessage = {
+      type: 'dashboard/v1/bridge/navigate-to-resource',
+      data: {
+        resourceId: workspace._ref,
+        resourceType: 'studio',
+        path: `/intent/edit/id=${documentHandle._id};type=${documentHandle._type}`,
+      },
+    }
+
+    sendMessage(message.type, message.data)
+  }, [documentHandle, workspacesConnected, status, sendMessage, workspacesByResourceId])
+
+  return {
+    navigateToStudioDocument,
+    isConnected: workspacesConnected && status === 'connected',
+  }
+}

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

@@ -6,10 +6,10 @@ import {createStateSourceHook} from '../helpers/createStateSourceHook'
 type UseDatasets = {
   /**
    *
-   * Returns metadata for each dataset in your organization.
+   * Returns metadata for each dataset the current user has access to.
    *
    * @category Datasets
-   * @returns The metadata for your organization's datasets
+   * @returns The metadata for your the datasets
    *
    * @example
    * ```tsx
@@ -28,7 +28,10 @@ type UseDatasets = {
   (): DatasetsResponse
 }
 
-/** @public */
+/**
+ * @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>,

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/{useApplyActions.ts → useApplyDocumentActions.ts}

@@ -1,7 +1,7 @@
 import {
   type ActionsResult,
-  applyActions,
-  type ApplyActionsOptions,
+  applyDocumentActions,
+  type ApplyDocumentActionsOptions,
   type DocumentAction,
   type ResourceId,
 } from '@sanity/sdk'
@@ -21,9 +21,9 @@ import {createCallbackHook} from '../helpers/createCallbackHook'
  * @example Publish or unpublish a document
  * ```
  * import { publishDocument, unpublishDocument } from '@sanity/sdk'
- * import { useApplyActions } from '@sanity/sdk-react'
+ * import { useApplyDocumentActions } from '@sanity/sdk-react'
  *
- * const apply = useApplyActions()
+ * const apply = useApplyDocumentActions()
  * const myDocument = { _id: 'my-document-id', _type: 'my-document-type' }
  *
  * return (
@@ -35,9 +35,9 @@ import {createCallbackHook} from '../helpers/createCallbackHook'
  * @example Create and publish a new document
  * ```
  * import { createDocument, publishDocument } from '@sanity/sdk'
- * import { useApplyActions } from '@sanity/sdk-react'
+ * import { useApplyDocumentActions } from '@sanity/sdk-react'
  *
- * const apply = useApplyActions()
+ * const apply = useApplyDocumentActions()
  *
  * const handleCreateAndPublish = () => {
  *   const handle = { _id: window.crypto.randomUUID(), _type: 'my-document-type' }
@@ -54,21 +54,22 @@ import {createCallbackHook} from '../helpers/createCallbackHook'
  * )
  * ```
  */
-export function useApplyActions(
+export function useApplyDocumentActions(
   resourceId?: ResourceId,
 ): <TDocument extends SanityDocument>(
   action: DocumentAction<TDocument> | DocumentAction<TDocument>[],
-  options?: ApplyActionsOptions,
+  options?: ApplyDocumentActionsOptions,
 ) => Promise<ActionsResult<TDocument>>
 
 /** @beta */
-export function useApplyActions(
+export function useApplyDocumentActions(
   resourceId?: ResourceId,
 ): (
   action: DocumentAction | DocumentAction[],
-  options?: ApplyActionsOptions,
+  options?: ApplyDocumentActionsOptions,
 ) => Promise<ActionsResult> {
-  return _useApplyActions(resourceId)()
+  return _useApplyDocumentActions(resourceId)()
 }
 
-const _useApplyActions = (resourceId?: ResourceId) => createCallbackHook(applyActions, resourceId)
+const _useApplyDocumentActions = (resourceId?: ResourceId) =>
+  createCallbackHook(applyDocumentActions, resourceId)

package/src/hooks/document/{usePermissions.ts → useDocumentPermissions.ts}

@@ -1,8 +1,8 @@
 import {
   type DocumentAction,
+  type DocumentPermissionsResult,
   getPermissionsState,
   getResourceId,
-  type PermissionsResult,
 } from '@sanity/sdk'
 import {useCallback, useMemo, useSyncExternalStore} from 'react'
 import {filter, firstValueFrom} from 'rxjs'
@@ -21,25 +21,25 @@ import {useSanityInstance} from '../context/useSanityInstance'
  *
  * @example Checking for permission to publish a document
  * ```ts
- * import {usePermissions, useApplyActions} from '@sanity/sdk-react'
+ * import {useDocumentPermissions, useApplyDocumentActions} from '@sanity/sdk-react'
  * import {publishDocument} from '@sanity/sdk'
  *
  * export function PublishButton({doc}: {doc: DocumentHandle}) {
- *   const canPublish = usePermissions(publishDocument(doc))
- *   const applyAction = useApplyActions()
+ *   const publishPermissions = useDocumentPermissions(publishDocument(doc))
+ *   const applyAction = useApplyDocumentActions()
  *
  *   return (
  *     <>
  *       <button
- *         disabled={!canPublish.allowed}
+ *         disabled={!publishPermissions.allowed}
  *         onClick={() => applyAction(publishDocument(doc))}
- *         popoverTarget={`${canPublish.allowed ? undefined : 'publishButtonPopover'}`}
+ *         popoverTarget={`${publishPermissions.allowed ? undefined : 'publishButtonPopover'}`}
  *       >
  *         Publish
  *       </button>
- *       {!canPublish.allowed && (
+ *       {!publishPermissions.allowed && (
  *         <div popover id="publishButtonPopover">
- *           {canPublish.message}
+ *           {publishPermissions.message}
  *         </div>
  *       )}
  *     </>
@@ -47,7 +47,9 @@ import {useSanityInstance} from '../context/useSanityInstance'
  * }
  * ```
  */
-export function usePermissions(actions: DocumentAction | DocumentAction[]): PermissionsResult {
+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)
@@ -78,5 +80,5 @@ export function usePermissions(actions: DocumentAction | DocumentAction[]): Perm
     [actions, instance],
   )
 
-  return useSyncExternalStore(subscribe, getCurrent) as PermissionsResult
+  return useSyncExternalStore(subscribe, getCurrent) as DocumentPermissionsResult
 }

package/src/hooks/document/useDocumentSyncStatus.ts

@@ -25,6 +25,9 @@ type UseDocumentSyncStatus = {
   (doc: DocumentHandle): boolean | undefined
 }
 
-/** @beta */
+/**
+ * @beta
+ * @function
+ */
 export const useDocumentSyncStatus: UseDocumentSyncStatus =
   createStateSourceHook(getDocumentSyncStatus)