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

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 canPublish = usePermissions(publishDocument(doc))
+ *   const applyAction = useApplyActions()
+ *
+ *   return (
+ *     <>
+ *       <button
+ *         disabled={!canPublish.allowed}
+ *         onClick={() => applyAction(publishDocument(doc))}
+ *         popoverTarget={`${canPublish.allowed ? undefined : 'publishButtonPopover'}`}
+ *       >
+ *         Publish
+ *       </button>
+ *       {!canPublish.allowed && (
+ *         <div popover id="publishButtonPopover">
+ *           {canPublish.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)
+  })
+})

package/src/hooks/infiniteList/useInfiniteList.ts

@@ -0,0 +1,174 @@
+import {type DocumentHandle, type QueryOptions} from '@sanity/sdk'
+import {type SortOrderingItem} from '@sanity/types'
+import {useCallback, useEffect, useMemo, useState} from 'react'
+
+import {useQuery} from '../query/useQuery'
+
+const DEFAULT_BATCH_SIZE = 25
+const DEFAULT_PERSPECTIVE = 'drafts'
+
+/**
+ * Result structure returned from the infinite list query
+ * @internal
+ */
+interface InfiniteListQueryResult {
+  count: number
+  data: DocumentHandle[]
+}
+
+/**
+ * Configuration options for the useInfiniteList hook
+ *
+ * @beta
+ * @category Types
+ */
+export interface InfiniteListOptions extends QueryOptions {
+  /**
+   * GROQ filter expression to apply to the query
+   */
+  filter?: string
+  /**
+   * Number of items to load per batch (defaults to 25)
+   */
+  batchSize?: number
+  /**
+   * Sorting configuration for the results
+   */
+  orderings?: SortOrderingItem[]
+  /**
+   * Text search query to filter results
+   */
+  search?: string
+}
+
+/**
+ * Return value from the useInfiniteList hook
+ *
+ * @beta
+ * @category Types
+ */
+export interface InfiniteList {
+  /**
+   * Array of document handles for the current batch
+   */
+  data: DocumentHandle[]
+  /**
+   * Whether there are more items available to load
+   */
+  hasMore: boolean
+  /**
+   * Total count of items matching the query
+   */
+  count: number
+  /**
+   * Whether a query is currently in progress
+   */
+  isPending: boolean
+  /**
+   * Function to load the next batch of results
+   */
+  loadMore: () => void
+}
+
+/**
+ * Retrieves batches of {@link DocumentHandle}s, narrowed by optional filters, text searches, and custom ordering,
+ * with infinite scrolling support. The number of document handles returned per batch is customizable,
+ * and additional batches can be loaded using the supplied `loadMore` function.
+ *
+ * @beta
+ * @category Documents
+ * @param options - Configuration options for the infinite list
+ * @returns An object containing the list of document handles, the loading state, the total count of retrived document handles, and a function to load more
+ * @example
+ * ```tsx
+ * const {data, hasMore, isPending, loadMore} = useInfiniteList({
+ *   filter: '_type == "post"',
+ *   search: searchTerm,
+ *   batchSize: 10,
+ *   orderings: [{field: '_createdAt', direction: 'desc'}]
+ * })
+ *
+ * return (
+ *   <div>
+ *     Total documents: {count}
+ *     <ol>
+ *       {data.map((doc) => (
+ *         <li key={doc._id}>
+ *           <MyDocumentComponent doc={doc} />
+ *         </li>
+ *       ))}
+ *     </ol>
+ *     {hasMore && <button onClick={loadMore}>Load More</button>}
+ *   </div>
+ * )
+ * ```
+ *
+ */
+export function useInfiniteList({
+  batchSize = DEFAULT_BATCH_SIZE,
+  params,
+  search,
+  filter,
+  orderings,
+  ...options
+}: InfiniteListOptions): InfiniteList {
+  const perspective = options.perspective ?? DEFAULT_PERSPECTIVE
+  const [limit, setLimit] = useState(batchSize)
+
+  // Reset the limit to the current batchSize whenever any query parameters
+  // (filter, search, params, orderings) or batchSize changes
+  const key = JSON.stringify({filter, search, params, orderings, batchSize})
+  useEffect(() => {
+    setLimit(batchSize)
+  }, [key, batchSize])
+
+  const filterClause = useMemo(() => {
+    const conditions: string[] = []
+
+    // Add search query if specified
+    if (search?.trim()) {
+      conditions.push(`[@] match text::query("${search.trim()}")`)
+    }
+
+    // Add additional filter if specified
+    if (filter) {
+      conditions.push(`(${filter})`)
+    }
+
+    return conditions.length ? `[${conditions.join(' && ')}]` : ''
+  }, [filter, search])
+
+  const orderClause = orderings
+    ? `| order(${orderings
+        .map((ordering) =>
+          [ordering.field, ordering.direction.toLowerCase()]
+            .map((str) => str.trim())
+            .filter(Boolean)
+            .join(' '),
+        )
+        .join(',')})`
+    : ''
+
+  const dataQuery = `*${filterClause}${orderClause}[0...${limit}]{_id,_type}`
+  const countQuery = `count(*${filterClause})`
+
+  const {
+    data: {count, data},
+    isPending,
+  } = useQuery<InfiniteListQueryResult>(`{"count":${countQuery},"data":${dataQuery}}`, {
+    ...options,
+    params,
+    perspective,
+  })
+
+  const hasMore = data.length < count
+
+  const loadMore = useCallback(() => {
+    setLimit((prev) => Math.min(prev + batchSize, count))
+  }, [count, batchSize])
+
+  return useMemo(
+    () => ({data, hasMore, count, isPending, loadMore}),
+    [data, hasMore, count, isPending, loadMore],
+  )
+}