@sanity/sdk-react 0.0.0-alpha.9 → 0.0.0-rc.1

package/src/hooks/document/useEditDocument.ts

@@ -3,6 +3,7 @@ import {
   type DocumentHandle,
   editDocument,
   getDocumentState,
+  getResourceId,
   type JsonMatch,
   type JsonMatchPath,
   resolveDocument,
@@ -15,53 +16,180 @@ import {useApplyActions} from './useApplyActions'
 
 const ignoredKeys = ['_id', '_type', '_createdAt', '_updatedAt', '_rev']
 
-/** @beta */
+type Updater<TValue> = TValue | ((nextValue: TValue) => TValue)
+
+/**
+ *
+ * @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>,
 >(
-  doc: string | DocumentHandle<TDocument>,
+  doc: DocumentHandle<TDocument>,
   path: TPath,
-): (nextValue: JsonMatch<TDocument, TPath>) => Promise<ActionsResult<TDocument>>
-/** @beta */
+): (nextValue: Updater<JsonMatch<TDocument, TPath>>) => Promise<ActionsResult<TDocument>>
+
+/**
+ *
+ * @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. If you pass a `DocumentHandle` with a `resourceId` (in the format of `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.
+ * @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: Partial<TDocument>) => Promise<ActionsResult<TDocument>>
-/** @beta */
+  doc: DocumentHandle<TDocument>,
+): (nextValue: Updater<TDocument>) => Promise<ActionsResult<TDocument>>
+
+/**
+ *
+ * @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,
+  doc: DocumentHandle,
   path?: string,
-): (nextValue: unknown) => Promise<ActionsResult> {
-  const documentId = typeof doc === 'string' ? doc : doc._id
-  const instance = useSanityInstance()
-  const apply = useApplyActions()
+): (updater: Updater<unknown>) => Promise<ActionsResult> {
+  const resourceId = getResourceId(doc.resourceId)!
+  const documentId = doc._id
+  const instance = useSanityInstance(resourceId)
+  const apply = useApplyActions(resourceId)
   const isDocumentReady = useCallback(
     () => getDocumentState(instance, documentId).getCurrent() !== undefined,
     [instance, documentId],
   )
   if (!isDocumentReady()) throw resolveDocument(instance, documentId)
 
-  return useCallback(
-    (next: unknown) => {
-      if (path) {
-        return apply(editDocument(documentId, {set: {[path]: next}}))
-      }
+  return (updater: Updater<unknown>) => {
+    if (path) {
+      const nextValue =
+        typeof updater === 'function'
+          ? updater(getDocumentState(instance, documentId, path).getCurrent())
+          : updater
 
-      const current = getDocumentState(instance, documentId).getCurrent()
+      return apply(editDocument(doc, {set: {[path]: nextValue}}))
+    }
 
-      if (typeof next !== 'object' || !next) {
-        throw new Error(
-          `No path was provided to \`useEditDocument\` and the value provided was not a document object.`,
-        )
-      }
+    const current = getDocumentState(instance, documentId).getCurrent()
+    const nextValue = typeof updater === 'function' ? updater(current) : updater
 
-      const editActions = Object.entries(next)
-        .filter(([key]) => !ignoredKeys.includes(key))
-        .filter(([key, value]) => current?.[key] !== value)
-        .map(([key, value]) => editDocument(documentId, {set: {[key]: value}}))
+    if (typeof nextValue !== 'object' || !nextValue) {
+      throw new Error(
+        `No path was provided to \`useEditDocument\` and the value provided was not a document object.`,
+      )
+    }
 
-      return apply(editActions)
-    },
-    [apply, documentId, instance, path],
-  )
+    const allKeys = Object.keys({...current, ...nextValue})
+    const editActions = allKeys
+      .filter((key) => !ignoredKeys.includes(key))
+      .filter((key) => current?.[key] !== nextValue[key])
+      .map((key) =>
+        key in nextValue
+          ? editDocument(doc, {set: {[key]: nextValue[key]}})
+          : editDocument(doc, {unset: [key]}),
+      )
+
+    return apply(editActions)
+  }
 }

package/src/hooks/document/usePermissions.ts

@@ -0,0 +1,82 @@
+import {
+  type DocumentAction,
+  getPermissionsState,
+  getResourceId,
+  type PermissionsResult,
+} from '@sanity/sdk'
+import {useCallback, useMemo, useSyncExternalStore} from 'react'
+import {filter, firstValueFrom} from 'rxjs'
+
+import {useSanityInstance} from '../context/useSanityInstance'
+
+/**
+ *
+ * @beta
+ *
+ * Check if the current user has the specified permissions for the given document actions.
+ *
+ * @category Permissions
+ * @param actions - One more more calls to a particular document action function for a given document
+ * @returns An object that specifies whether the action is allowed; if the action is not allowed, an explanatory message and list of reasons is also provided.
+ *
+ * @example Checking for permission to publish a document
+ * ```ts
+ * import {usePermissions, useApplyActions} from '@sanity/sdk-react'
+ * import {publishDocument} from '@sanity/sdk'
+ *
+ * export function PublishButton({doc}: {doc: DocumentHandle}) {
+ *   const publishPermissions = usePermissions(publishDocument(doc))
+ *   const applyAction = useApplyActions()
+ *
+ *   return (
+ *     <>
+ *       <button
+ *         disabled={!publishPermissions.allowed}
+ *         onClick={() => applyAction(publishDocument(doc))}
+ *         popoverTarget={`${publishPermissions.allowed ? undefined : 'publishButtonPopover'}`}
+ *       >
+ *         Publish
+ *       </button>
+ *       {!publishPermissions.allowed && (
+ *         <div popover id="publishButtonPopover">
+ *           {publishPermissions.message}
+ *         </div>
+ *       )}
+ *     </>
+ *   )
+ * }
+ * ```
+ */
+export function usePermissions(actions: DocumentAction | DocumentAction[]): PermissionsResult {
+  // 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)
+    const uniqueResourceIds = new Set(resourceIds)
+    if (uniqueResourceIds.size !== 1) {
+      throw new Error('All actions must have the same resourceId')
+    }
+  }
+  const resourceId = Array.isArray(actions)
+    ? getResourceId(actions[0].resourceId)
+    : getResourceId(actions.resourceId)
+
+  const instance = useSanityInstance(resourceId)
+  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/helpers/createCallbackHook.tsx

@@ -1,13 +1,14 @@
-import {type SanityInstance} from '@sanity/sdk'
+import {type ResourceId, type SanityInstance} from '@sanity/sdk'
 import {useCallback} from 'react'
 
 import {useSanityInstance} from '../context/useSanityInstance'
 
 export function createCallbackHook<TParams extends unknown[], TReturn>(
   callback: (instance: SanityInstance, ...params: TParams) => TReturn,
+  resourceId?: ResourceId,
 ): () => (...params: TParams) => TReturn {
   function useHook() {
-    const instance = useSanityInstance()
+    const instance = useSanityInstance(resourceId)
     return useCallback((...params: TParams) => callback(instance, ...params), [instance])
   }
 

package/src/hooks/helpers/createStateSourceHook.test.tsx

@@ -127,4 +127,70 @@ describe('createStateSourceHook', () => {
     expect(result.current).toEqual('test_123')
     expect(stateSourceFactory).toHaveBeenCalledWith(mockInstance, 'test', 123)
   })
+
+  it('should throw suspender promise when shouldSuspend is true', () => {
+    const mockInstance = createSanityInstance({projectId: 'p', dataset: 'd'})
+    vi.mocked(useSanityInstance).mockReturnValue(mockInstance)
+
+    const mockGetState = vi.fn().mockReturnValue({
+      subscribe: vi.fn(),
+      getCurrent: vi.fn().mockReturnValue('state'),
+      observable: throwError(() => new Error('unexpected usage of observable')),
+    })
+
+    const mockShouldSuspend = vi.fn().mockReturnValue(true)
+    const mockSuspender = vi.fn().mockReturnValue(Promise.resolve())
+
+    const options = {
+      getState: mockGetState,
+      shouldSuspend: mockShouldSuspend,
+      suspender: mockSuspender,
+    }
+
+    const useTestHook = createStateSourceHook(options)
+    const {result} = renderHook(() => {
+      try {
+        useTestHook('param1', 2)
+      } catch (e) {
+        return e
+      }
+    })
+
+    expect(mockShouldSuspend).toHaveBeenCalledWith(mockInstance, 'param1', 2)
+    expect(mockSuspender).toHaveBeenCalledWith(mockInstance, 'param1', 2)
+    expect(result.current).toBe(mockSuspender.mock.results[0].value)
+    expect(mockGetState).not.toHaveBeenCalled()
+  })
+
+  it('should not suspend when shouldSuspend returns false', () => {
+    const mockInstance = createSanityInstance({projectId: 'p', dataset: 'd'})
+    vi.mocked(useSanityInstance).mockReturnValue(mockInstance)
+
+    const mockState = {value: 'test'}
+    const mockSubscribe = vi.fn()
+    const mockGetCurrent = vi.fn(() => mockState)
+
+    const mockGetState = vi.fn().mockReturnValue({
+      subscribe: mockSubscribe,
+      getCurrent: mockGetCurrent,
+      observable: throwError(() => new Error('unexpected usage of observable')),
+    })
+
+    const mockShouldSuspend = vi.fn().mockReturnValue(false)
+    const mockSuspender = vi.fn()
+
+    const options = {
+      getState: mockGetState,
+      shouldSuspend: mockShouldSuspend,
+      suspender: mockSuspender,
+    }
+
+    const useTestHook = createStateSourceHook(options)
+    const {result} = renderHook(() => useTestHook('param', 123))
+
+    expect(mockShouldSuspend).toHaveBeenCalledWith(mockInstance, 'param', 123)
+    expect(mockSuspender).not.toHaveBeenCalled()
+    expect(mockGetState).toHaveBeenCalledWith(mockInstance, 'param', 123)
+    expect(result.current).toBe(mockState)
+  })
 })

package/src/hooks/helpers/createStateSourceHook.tsx

@@ -1,20 +1,39 @@
-import {type SanityInstance, type StateSource} from '@sanity/sdk'
-import {useMemo, useSyncExternalStore} from 'react'
+import {type ResourceId, type SanityInstance, type StateSource} from '@sanity/sdk'
+import {useSyncExternalStore} from 'react'
 
 import {useSanityInstance} from '../context/useSanityInstance'
 
+type StateSourceFactory<TParams extends unknown[], TState> = (
+  instance: SanityInstance,
+  ...params: TParams
+) => StateSource<TState>
+
+interface CreateStateSourceHookOptions<TParams extends unknown[], TState> {
+  getState: StateSourceFactory<TParams, TState>
+  shouldSuspend?: (instance: SanityInstance, ...params: TParams) => boolean
+  suspender?: (instance: SanityInstance, ...params: TParams) => Promise<unknown>
+  getResourceId?: (...params: TParams) => ResourceId | undefined
+}
+
 export function createStateSourceHook<TParams extends unknown[], TState>(
-  stateSourceFactory: (instance: SanityInstance, ...params: TParams) => StateSource<TState>,
+  options: StateSourceFactory<TParams, TState> | CreateStateSourceHookOptions<TParams, TState>,
 ): (...params: TParams) => TState {
+  const getState = typeof options === 'function' ? options : options.getState
+  const getResourceId = 'getResourceId' in options ? options.getResourceId : undefined
+  const suspense = 'shouldSuspend' in options && 'suspender' in options ? options : undefined
+
   function useHook(...params: TParams) {
-    const instance = useSanityInstance()
-    const {subscribe, getCurrent} = useMemo(
-      () => stateSourceFactory(instance, ...params),
-      // eslint-disable-next-line react-hooks/exhaustive-deps
-      [instance, ...params],
-    )
+    let resourceId: ResourceId | undefined
+    if (getResourceId) {
+      resourceId = getResourceId(...params)
+    }
+    const instance = useSanityInstance(resourceId)
+    if (suspense?.suspender && suspense?.shouldSuspend?.(instance, ...params)) {
+      throw suspense.suspender(instance, ...params)
+    }
 
-    return useSyncExternalStore(subscribe, getCurrent)
+    const state = getState(instance, ...params)
+    return useSyncExternalStore(state.subscribe, state.getCurrent)
   }
 
   return useHook

package/src/hooks/infiniteList/useInfiniteList.test.tsx

@@ -0,0 +1,152 @@
+import {act, renderHook} from '@testing-library/react'
+import {describe, vi} from 'vitest'
+
+import {evaluateSync, parse} from '../_synchronous-groq-js.mjs'
+import {useQuery} from '../query/useQuery'
+import {useInfiniteList} from './useInfiniteList'
+
+vi.mock('../query/useQuery')
+
+describe('useInfiniteList', () => {
+  beforeEach(() => {
+    const dataset = [
+      {
+        _id: 'movie1',
+        _type: 'movie',
+        title: 'The Matrix',
+        releaseYear: 1999,
+        _createdAt: '2021-03-09T00:00:00.000Z',
+        _updatedAt: '2021-03-09T00:00:00.000Z',
+        _rev: 'tx0',
+      },
+      {
+        _id: 'movie2',
+        _type: 'movie',
+        title: 'Inception',
+        releaseYear: 2010,
+        _createdAt: '2021-03-10T00:00:00.000Z',
+        _updatedAt: '2021-03-10T00:00:00.000Z',
+        _rev: 'tx1',
+      },
+      {
+        _id: 'movie3',
+        _type: 'movie',
+        title: 'Interstellar',
+        releaseYear: 2014,
+        _createdAt: '2021-03-11T00:00:00.000Z',
+        _updatedAt: '2021-03-11T00:00:00.000Z',
+        _rev: 'tx2',
+      },
+      {
+        _id: 'book1',
+        _type: 'book',
+        title: 'Dune',
+        _createdAt: '2021-03-12T00:00:00.000Z',
+        _updatedAt: '2021-03-12T00:00:00.000Z',
+        _rev: 'tx3',
+      },
+      {
+        _id: 'movie4',
+        _type: 'movie',
+        title: 'The Dark Knight',
+        releaseYear: 2008,
+        _createdAt: '2021-03-13T00:00:00.000Z',
+        _updatedAt: '2021-03-13T00:00:00.000Z',
+        _rev: 'tx4',
+      },
+      {
+        _id: 'movie5',
+        _type: 'movie',
+        title: 'Pulp Fiction',
+        releaseYear: 1994,
+        _createdAt: '2021-03-14T00:00:00.000Z',
+        _updatedAt: '2021-03-14T00:00:00.000Z',
+        _rev: 'tx5',
+      },
+    ]
+
+    vi.mocked(useQuery).mockImplementation((query, options) => {
+      const result = evaluateSync(parse(query), {dataset, params: options?.params}).get()
+      return {
+        data: result,
+        isPending: false,
+      }
+    })
+  })
+
+  it('should respect custom page size', () => {
+    const customBatchSize = 2
+    const {result} = renderHook(() => useInfiniteList({batchSize: customBatchSize}))
+
+    expect(result.current.data.length).toBe(customBatchSize)
+  })
+
+  it('should filter by document type', () => {
+    const {result} = renderHook(() => useInfiniteList({filter: '_type == "movie"'}))
+
+    expect(result.current.data.every((doc) => doc._type === 'movie')).toBe(true)
+    expect(result.current.count).toBe(5) // 5 movies in the dataset
+  })
+
+  // groq-js doesn't support search filters yet
+  it.skip('should apply search filter', () => {
+    const {result} = renderHook(() => useInfiniteList({search: 'inter'}))
+
+    // Should match "Interstellar"
+    expect(result.current.data.some((doc) => doc._id === 'movie3')).toBe(true)
+  })
+
+  it('should apply ordering', () => {
+    const {result} = renderHook(() =>
+      useInfiniteList({
+        filter: '_type == "movie"',
+        orderings: [{field: 'releaseYear', direction: 'desc'}],
+      }),
+    )
+
+    // First item should be the most recent movie (Interstellar, 2014)
+    expect(result.current.data[0]._id).toBe('movie3')
+  })
+
+  it('should load more data when loadMore is called', () => {
+    const batchSize = 2
+    const {result} = renderHook(() => useInfiniteList({batchSize: batchSize}))
+
+    expect(result.current.data.length).toBe(batchSize)
+
+    act(() => {
+      result.current.loadMore()
+    })
+
+    expect(result.current.data.length).toBe(batchSize * 2)
+  })
+
+  it('should indicate when there is more data to load', () => {
+    const {result} = renderHook(() => useInfiniteList({batchSize: 3}))
+    expect(result.current.hasMore).toBe(true)
+    // Load all remaining data
+    act(() => {
+      result.current.loadMore()
+    })
+    expect(result.current.hasMore).toBe(false)
+  })
+
+  // New test case for resetting limit when filter changes
+  it('should reset limit when filter changes', () => {
+    const {result, rerender} = renderHook((props) => useInfiniteList(props), {
+      initialProps: {batchSize: 2, filter: ''},
+    })
+    // Initially, data length equals pageSize (2)
+    expect(result.current.data.length).toBe(2)
+    // Load more to increase limit
+    act(() => {
+      result.current.loadMore()
+    })
+    // After loadMore, data length should be increased (2 + 2 = 4)
+    expect(result.current.data.length).toBe(4)
+    // Now update filter to trigger resetting the limit
+    rerender({batchSize: 2, filter: '_type == "movie"'})
+    // With the filter applied, the limit is reset to pageSize (i.e. 2)
+    expect(result.current.data.length).toBe(2)
+  })
+})