@sanity/sdk-react 0.0.0-alpha.3 → 0.0.0-alpha.30

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

@@ -0,0 +1,291 @@
+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 {useStudioWorkspacesByProjectIdDataset} from './useStudioWorkspacesByProjectIdDataset'
+
+vi.mock('../comlink/useWindowConnection', () => ({
+  useWindowConnection: vi.fn(),
+}))
+
+const mockWorkspaceData = {
+  context: {
+    availableResources: [
+      {
+        id: 'user1-workspace1',
+        projectId: 'project1',
+        dataset: 'dataset1',
+        name: 'workspace1',
+        title: 'Workspace 1',
+        basePath: '/workspace1',
+        userApplicationId: 'user1',
+        url: 'https://test1.sanity.studio',
+        type: 'studio',
+      },
+      {
+        id: 'user1-workspace2',
+        projectId: 'project1',
+        dataset: 'dataset1',
+        name: 'workspace2',
+        title: 'Workspace 2',
+        basePath: '/workspace2',
+        userApplicationId: 'user1',
+        url: 'https://test2.sanity.studio',
+        type: 'studio',
+      },
+      {
+        id: 'user2-workspace3',
+        projectId: 'project2',
+        dataset: 'dataset2',
+        name: 'workspace3',
+        title: 'Workspace 3',
+        basePath: '/workspace3',
+        userApplicationId: 'user2',
+        url: 'https://test3.sanity.studio',
+        type: 'studio',
+      },
+    ],
+  },
+}
+
+describe('useStudioWorkspacesByResourceId', () => {
+  afterEach(() => {
+    vi.clearAllMocks()
+  })
+
+  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(() => useStudioWorkspacesByProjectIdDataset())
+
+    // Call onStatus with 'idle' to simulate not connected
+    if (capturedOnStatus) capturedOnStatus('idle')
+
+    expect(result.current).toEqual({
+      workspacesByProjectIdAndDataset: {},
+      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(() => useStudioWorkspacesByProjectIdDataset())
+
+    // Call onStatus with 'connected' to simulate connected state
+    if (capturedOnStatus) capturedOnStatus('connected')
+
+    await waitFor(() => {
+      expect(result.current.workspacesByProjectIdAndDataset).toEqual({
+        'project1:dataset1': [
+          {
+            id: 'user1-workspace1',
+            projectId: 'project1',
+            dataset: 'dataset1',
+            name: 'workspace1',
+            title: 'Workspace 1',
+            basePath: '/workspace1',
+            userApplicationId: 'user1',
+            url: 'https://test1.sanity.studio',
+            type: 'studio',
+          },
+          {
+            id: 'user1-workspace2',
+            projectId: 'project1',
+            dataset: 'dataset1',
+            name: 'workspace2',
+            title: 'Workspace 2',
+            basePath: '/workspace2',
+            userApplicationId: 'user1',
+            url: 'https://test2.sanity.studio',
+            type: 'studio',
+          },
+        ],
+        'project2:dataset2': [
+          {
+            id: 'user2-workspace3',
+            projectId: 'project2',
+            dataset: 'dataset2',
+            name: 'workspace3',
+            title: 'Workspace 3',
+            basePath: '/workspace3',
+            userApplicationId: 'user2',
+            url: 'https://test3.sanity.studio',
+            type: 'studio',
+          },
+        ],
+      })
+      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(() => useStudioWorkspacesByProjectIdDataset())
+
+    // Call onStatus with 'connected' to simulate connected state
+    if (capturedOnStatus) capturedOnStatus('connected')
+
+    await waitFor(() => {
+      expect(result.current.workspacesByProjectIdAndDataset).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(() => useStudioWorkspacesByProjectIdDataset())
+
+    // Call onStatus with 'connected' to simulate connected state
+    if (capturedOnStatus) capturedOnStatus('connected')
+
+    await waitFor(() => {
+      expect(result.current.workspacesByProjectIdAndDataset).toEqual({})
+      expect(result.current.error).toBeNull()
+      expect(result.current.isConnected).toBe(true)
+    })
+  })
+
+  it('should filter non-studio resources and handle resources without projectId/dataset', async () => {
+    const mockDataWithMixedResources = {
+      context: {
+        availableResources: [
+          {
+            id: 'studio1',
+            projectId: 'project1',
+            dataset: 'dataset1',
+            name: 'workspace1',
+            title: 'Workspace 1',
+            basePath: '/workspace1',
+            userApplicationId: 'user1',
+            url: 'https://test1.sanity.studio',
+            type: 'studio',
+          },
+          {
+            id: 'non-studio',
+            projectId: 'project2',
+            dataset: 'dataset2',
+            name: 'non-studio',
+            title: 'Non Studio Resource',
+            basePath: '/non-studio',
+            userApplicationId: 'user2',
+            url: 'https://test2.sanity.studio',
+            type: 'other',
+          },
+          {
+            id: 'studio-no-project',
+            name: 'incomplete-workspace',
+            title: 'Incomplete Workspace',
+            basePath: '/incomplete',
+            userApplicationId: 'user3',
+            url: 'https://test3.sanity.studio',
+            type: 'studio',
+          },
+          {
+            id: 'studio-no-dataset',
+            projectId: 'project3',
+            name: 'no-dataset-workspace',
+            title: 'No Dataset Workspace',
+            basePath: '/no-dataset',
+            userApplicationId: 'user4',
+            url: 'https://test4.sanity.studio',
+            type: 'studio',
+          },
+        ],
+      },
+    }
+
+    const mockFetch = vi.fn().mockResolvedValue(mockDataWithMixedResources)
+    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(() => useStudioWorkspacesByProjectIdDataset())
+
+    // Call onStatus with 'connected' to simulate connected state
+    if (capturedOnStatus) capturedOnStatus('connected')
+
+    await waitFor(() => {
+      // Should only include the studio resource with valid projectId and dataset
+      expect(result.current.workspacesByProjectIdAndDataset['project1:dataset1']).toHaveLength(1)
+      expect(result.current.workspacesByProjectIdAndDataset['project1:dataset1'][0].id).toBe(
+        'studio1',
+      )
+
+      // Should not include the non-studio resource
+      expect(result.current.workspacesByProjectIdAndDataset['project2:dataset2']).toBeUndefined()
+
+      // Should group resources without projectId or dataset under NO_PROJECT_ID:NO_DATASET
+      expect(
+        result.current.workspacesByProjectIdAndDataset['NO_PROJECT_ID:NO_DATASET'],
+      ).toHaveLength(2)
+      expect(
+        result.current.workspacesByProjectIdAndDataset['NO_PROJECT_ID:NO_DATASET'].map((r) => r.id),
+      ).toEqual(['studio-no-project', 'studio-no-dataset'])
+
+      expect(result.current.error).toBeNull()
+      expect(result.current.isConnected).toBe(true)
+    })
+  })
+})

package/src/hooks/dashboard/useStudioWorkspacesByProjectIdDataset.ts

@@ -0,0 +1,101 @@
+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'
+
+export interface DashboardResource {
+  id: string
+  name: string
+  title: string
+  basePath: string
+  projectId: string
+  dataset: string
+  type: string
+  userApplicationId: string
+  url: string
+}
+
+interface WorkspacesByProjectIdDataset {
+  [key: `${string}:${string}`]: DashboardResource[] // key format: `${projectId}:${dataset}`
+}
+
+interface StudioWorkspacesResult {
+  workspacesByProjectIdAndDataset: WorkspacesByProjectIdDataset
+  error: string | null
+  isConnected: boolean
+}
+
+/**
+ * Hook that fetches studio workspaces and organizes them by projectId:dataset
+ * @internal
+ */
+export function useStudioWorkspacesByProjectIdDataset(): StudioWorkspacesResult {
+  const [workspacesByProjectIdAndDataset, setWorkspacesByProjectIdAndDataset] =
+    useState<WorkspacesByProjectIdDataset>({})
+  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<DashboardResource>}
+        }>('dashboard/v1/bridge/context', undefined, {signal})
+
+        const workspaceMap: WorkspacesByProjectIdDataset = {}
+        const noProjectIdAndDataset: DashboardResource[] = []
+
+        data.context.availableResources.forEach((resource) => {
+          if (resource.type !== 'studio') return
+          if (!resource.projectId || !resource.dataset) {
+            noProjectIdAndDataset.push(resource)
+            return
+          }
+          const key = `${resource.projectId}:${resource.dataset}` as const
+          if (!workspaceMap[key]) {
+            workspaceMap[key] = []
+          }
+          workspaceMap[key].push(resource)
+        })
+
+        if (noProjectIdAndDataset.length > 0) {
+          workspaceMap['NO_PROJECT_ID:NO_DATASET'] = noProjectIdAndDataset
+        }
+
+        setWorkspacesByProjectIdAndDataset(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 {
+    workspacesByProjectIdAndDataset,
+    error,
+    isConnected: status === 'connected',
+  }
+}

package/src/hooks/datasets/useDatasets.test.ts

@@ -0,0 +1,80 @@
+import {getDatasetsState, type ProjectHandle, type SanityInstance} from '@sanity/sdk'
+import {beforeEach, describe, expect, it, vi} from 'vitest'
+
+import {createStateSourceHook} from '../helpers/createStateSourceHook'
+
+// Mock dependencies
+vi.mock('@sanity/sdk', () => ({
+  getDatasetsState: vi.fn(() => ({
+    getCurrent: vi.fn(() => undefined), // Mocking getCurrent to satisfy the call within shouldSuspend
+  })),
+  resolveDatasets: vi.fn(),
+}))
+vi.mock('../helpers/createStateSourceHook', () => ({
+  createStateSourceHook: vi.fn(),
+}))
+
+describe('useDatasets', () => {
+  // Use beforeEach to reset modules and ensure mocks are fresh for each test
+  beforeEach(() => {
+    vi.resetModules()
+    // Re-mock dependencies for each test after resetModules
+    vi.mock('@sanity/sdk', () => ({
+      getDatasetsState: vi.fn(() => ({
+        getCurrent: vi.fn(() => undefined),
+      })),
+      resolveDatasets: vi.fn(),
+    }))
+    vi.mock('../helpers/createStateSourceHook', () => ({
+      createStateSourceHook: vi.fn(),
+    }))
+  })
+
+  it('should call createStateSourceHook with correct arguments on import', async () => {
+    // Dynamically import the hook *after* mocks are set up and modules reset
+    await import('./useDatasets')
+
+    // Check if createStateSourceHook was called during the module evaluation (import)
+    expect(createStateSourceHook).toHaveBeenCalled()
+    expect(createStateSourceHook).toHaveBeenCalledWith(
+      expect.objectContaining({
+        getState: expect.any(Function),
+        shouldSuspend: expect.any(Function),
+        suspender: expect.any(Function), // Actual function reference doesn't matter here as it's mocked
+        getConfig: expect.any(Function), // Actual function reference doesn't matter here
+      }),
+    )
+  })
+
+  it('shouldSuspend should call getDatasetsState and getCurrent', async () => {
+    // Dynamically import the hook *after* mocks are set up and modules reset
+    await import('./useDatasets')
+
+    // Get the arguments passed to createStateSourceHook
+    // Need to ensure createStateSourceHook mock is correctly typed for access
+    const mockCreateStateSourceHook = createStateSourceHook as ReturnType<typeof vi.fn>
+    expect(mockCreateStateSourceHook.mock.calls.length).toBeGreaterThan(0)
+    const createStateSourceHookArgs = mockCreateStateSourceHook.mock.calls[0][0]
+    const shouldSuspend = createStateSourceHookArgs.shouldSuspend
+
+    // Mock instance and projectHandle for the test call
+    const mockInstance = {} as SanityInstance // Use specific type
+    const mockProjectHandle = {} as ProjectHandle // Use specific type
+
+    // Call the shouldSuspend function
+    const result = shouldSuspend(mockInstance, mockProjectHandle)
+
+    // Assert that getDatasetsState was called with the correct arguments
+    // Need to ensure getDatasetsState mock is correctly typed for access
+    const mockGetDatasetsState = getDatasetsState as ReturnType<typeof vi.fn>
+    expect(mockGetDatasetsState).toHaveBeenCalledWith(mockInstance, mockProjectHandle)
+
+    // Assert that getCurrent was called on the result of getDatasetsState
+    expect(mockGetDatasetsState.mock.results.length).toBeGreaterThan(0)
+    const getDatasetsStateMockResult = mockGetDatasetsState.mock.results[0].value
+    expect(getDatasetsStateMockResult.getCurrent).toHaveBeenCalled()
+
+    // Assert the result of shouldSuspend based on the mocked getCurrent value
+    expect(result).toBe(true) // Since getCurrent is mocked to return undefined
+  })
+})

package/src/hooks/datasets/useDatasets.ts

@@ -0,0 +1,52 @@
+import {type DatasetsResponse} from '@sanity/client'
+import {
+  getDatasetsState,
+  type ProjectHandle,
+  resolveDatasets,
+  type SanityInstance,
+  type StateSource,
+} from '@sanity/sdk'
+import {identity} from 'rxjs'
+
+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({
+  getState: getDatasetsState as (
+    instance: SanityInstance,
+    projectHandle?: ProjectHandle,
+  ) => StateSource<DatasetsResponse>,
+  shouldSuspend: (instance, projectHandle?: ProjectHandle) =>
+    // remove `undefined` since we're suspending when that is the case
+    getDatasetsState(instance, projectHandle).getCurrent() === undefined,
+  suspender: resolveDatasets,
+  getConfig: identity as (projectHandle?: ProjectHandle) => ProjectHandle,
+})

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

@@ -0,0 +1,20 @@
+import {applyDocumentActions} 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 `applyActions`', async () => {
+    expect(createCallbackHook).not.toHaveBeenCalled()
+    await import('./useApplyDocumentActions')
+    expect(createCallbackHook).toHaveBeenCalledWith(applyDocumentActions)
+  })
+})

package/src/hooks/document/useApplyDocumentActions.ts

@@ -0,0 +1,124 @@
+import {
+  type ActionsResult,
+  applyDocumentActions,
+  type ApplyDocumentActionsOptions,
+  type DocumentAction,
+} from '@sanity/sdk'
+import {type SanityDocumentResult} from 'groq'
+
+import {createCallbackHook} from '../helpers/createCallbackHook'
+// this import is used in an `{@link useEditDocument}`
+// eslint-disable-next-line unused-imports/no-unused-imports, import/consistent-type-specifier-style
+import type {useEditDocument} from './useEditDocument'
+
+/**
+ * @beta
+ */
+interface UseApplyDocumentActions {
+  (): <
+    TDocumentType extends string = string,
+    TDataset extends string = string,
+    TProjectId extends string = string,
+  >(
+    action:
+      | DocumentAction<TDocumentType, TDataset, TProjectId>
+      | DocumentAction<TDocumentType, TDataset, TProjectId>[],
+    options?: ApplyDocumentActionsOptions,
+  ) => Promise<ActionsResult<SanityDocumentResult<TDocumentType, TDataset, TProjectId>>>
+}
+
+/**
+ * @beta
+ *
+ * Provides a stable callback function for applying one or more document actions.
+ *
+ * This hook wraps the core `applyDocumentActions` functionality from `@sanity/sdk`,
+ * integrating it with the React component lifecycle and {@link SanityInstance}.
+ * It allows you to apply actions generated by functions like `createDocument`,
+ * `editDocument`, `deleteDocument`, `publishDocument`, `unpublishDocument`,
+ * and `discardDocument` to documents.
+ *
+ * Features:
+ * - Applies one or multiple `DocumentAction` objects.
+ * - Supports optimistic updates: Local state reflects changes immediately.
+ * - Handles batching: Multiple actions passed together are sent as a single atomic transaction.
+ * - Integrates with the collaborative editing engine for conflict resolution and state synchronization.
+ *
+ * @category Documents
+ * @returns A stable callback function. When called with a single `DocumentAction` or an array of `DocumentAction`s,
+ * it returns a promise that resolves to an {@link ActionsResult}. The `ActionsResult` contains information about the
+ * outcome, including optimistic results if applicable.
+ *
+ * @remarks
+ * This hook is a fundamental part of interacting with document state programmatically.
+ * It operates within the same unified pipeline as other document hooks like `useDocument` (for reading state)
+ * and {@link useEditDocument} (a higher-level hook specifically for edits).
+ *
+ * When multiple actions are provided in a single call, they are guaranteed to be submitted
+ * as a single transaction to Content Lake. This ensures atomicity for related operations (e.g., creating and publishing a document).
+ *
+ * @function
+ *
+ * @example Publish or unpublish a document
+ * ```tsx
+ * import {
+ *   publishDocument,
+ *   unpublishDocument,
+ *   useApplyDocumentActions,
+ *   type DocumentHandle
+ * } from '@sanity/sdk-react'
+ *
+ * // Define props using the DocumentHandle type
+ * interface PublishControlsProps {
+ *   doc: DocumentHandle
+ * }
+ *
+ * function PublishControls({doc}: PublishControlsProps) {
+ *   const apply = useApplyDocumentActions()
+ *
+ *   const handlePublish = () =>  apply(publishDocument(doc))
+ *   const handleUnpublish = () => apply(unpublishDocument(doc))
+ *
+ *   return (
+ *     <>
+ *       <button onClick={handlePublish}>Publish</button>
+ *       <button onClick={handleUnpublish}>Unpublish</button>
+ *     </>
+ *   )
+ * }
+ * ```
+ *
+ * @example Create and publish a new document
+ * ```tsx
+ * import {
+ *   createDocument,
+ *   publishDocument,
+ *   createDocumentHandle,
+ *   useApplyDocumentActions
+ * } from '@sanity/sdk-react'
+ *
+ * function CreateAndPublishButton({documentType}: {documentType: string}) {
+ *   const apply = useApplyDocumentActions()
+ *
+ *   const handleCreateAndPublish = () => {
+ *     // Create a new handle inside the handler
+ *     const newDocHandle = createDocumentHandle({ documentId: crypto.randomUUID(), documentType })
+ *
+ *     // Apply multiple actions for the new handle as a single transaction
+ *     apply([
+ *       createDocument(newDocHandle),
+ *       publishDocument(newDocHandle),
+ *     ])
+ *   }
+ *
+ *   return (
+ *     <button onClick={handleCreateAndPublish}>
+ *       I'm feeling lucky
+ *     </button>
+ *   )
+ * }
+ * ```
+ */
+export const useApplyDocumentActions = createCallbackHook(
+  applyDocumentActions,
+) as UseApplyDocumentActions