@sanity/sdk-react 0.0.0-alpha.5 → 0.0.0-alpha.6

package/README.md

@@ -44,9 +44,10 @@ import './App.css'
 const sanityConfig: SanityConfig = {
   projectId: '<your-project-id>',
   dataset: '<your-dataset>',
-  // optional auth config set projectId and dataset to '' and authScope to 'org' for a global token
+  // optional auth config set projectId and dataset to '' and authScope to 'global' for a global token
   // auth: {
-  //   authScope: "org",
+  //   authScope: 'global',
+  //   ...
   // },
 }
 

package/dist/hooks.d.ts

@@ -120,13 +120,14 @@ export declare const useCurrentUser: () => CurrentUser | null
  * )
  * ```
  *
- * @example Retrieving all movies released since 1980, sorted by release date
+ * @example Retrieving all movies released since 1980, sorted by director’s last name
  * ```
  * const { results } = useDocuments({
  *   filter: '_type == "movie" && releaseDate >= "1980-01-01"',
  *   sort: [
  *     {
- *       field: 'releaseDate',
+ *       // Expand the `director` reference field with the dereferencing operator `->`
+ *       field: 'director->lastName',
  *       sort: 'asc',
  *     },
  *   ],
@@ -287,7 +288,9 @@ export declare const useLogOut: () => () => Promise<void>
  *     <ul>
  *       {isPending ? 'Loading…' : results.map(movie => (
  *         <li key={movie._id}>
- *           <PreviewComponent document={movie} />
+ *           <Suspense fallback='Loading…'>
+ *             <PreviewComponent document={movie} />
+ *           </Suspense>
  *         </li>
  *       ))}
  *     </ul>
@@ -305,7 +308,7 @@ export declare function usePreview({
  */
 export declare interface UsePreviewOptions {
   document: DocumentHandle
-  ref: HTMLElement | null
+  ref?: React.RefObject<unknown>
 }
 
 /**
@@ -314,7 +317,7 @@ export declare interface UsePreviewOptions {
 export declare interface UsePreviewResults {
   /** The results of resolving the document’s preview values */
   results: PreviewValue
-  /** Whether the resolution of the preview values is pending */
+  /** True when preview values are being refreshed */
   isPending: boolean
 }
 

package/dist/hooks.js

@@ -111,12 +111,13 @@ function usePreview({ document: { _id, _type }, ref }) {
   ), subscribe = useCallback(
     (onStoreChanged) => {
       const subscription = new Observable((observer) => {
-        if (typeof IntersectionObserver > "u") return;
+        if (typeof IntersectionObserver > "u" || typeof HTMLElement > "u")
+          return;
         const intersectionObserver = new IntersectionObserver(
           ([entry]) => observer.next(entry.isIntersecting),
           { rootMargin: "0px", threshold: 0 }
         );
-        return ref && intersectionObserver.observe(ref), () => intersectionObserver.disconnect();
+        return ref?.current && ref.current instanceof HTMLElement && intersectionObserver.observe(ref.current), () => intersectionObserver.disconnect();
       }).pipe(
         startWith(!1),
         distinctUntilChanged(),

package/dist/hooks.js.map

@@ -1 +1 @@
-{"version":3,"file":"hooks.js","sources":["../src/hooks/auth/useAuthToken.tsx","../src/hooks/auth/useCurrentUser.tsx","../src/hooks/comlink/useFrameConnection.ts","../src/hooks/comlink/useWindowConnection.ts","../src/hooks/documentCollection/useDocuments.ts","../src/hooks/preview/usePreview.tsx"],"sourcesContent":["import {getTokenState} from '@sanity/sdk'\n\nimport {createStateSourceHook} from '../helpers/createStateSourceHook'\n\n/**\n * Hook to get the currently logged in user\n * @public\n * @returns The current user or null if not authenticated\n */\nexport const useAuthToken = createStateSourceHook(getTokenState)\n","import {getCurrentUserState} from '@sanity/sdk'\n\nimport {createStateSourceHook} from '../helpers/createStateSourceHook'\n\n/**\n * Hook to get the currently logged in user\n * @public\n * @returns The current user or null if not authenticated\n */\nexport const useCurrentUser = createStateSourceHook(getCurrentUserState)\n","import {\n  type FrameMessage,\n  getOrCreateChannel,\n  getOrCreateController,\n  releaseChannel,\n  type WindowMessage,\n} from '@sanity/sdk'\nimport {useCallback, useEffect, useMemo} from 'react'\n\nimport {useSanityInstance} from '../context/useSanityInstance'\n\n/**\n * @public\n */\nexport type FrameMessageHandler<TWindowMessage extends WindowMessage> = (\n  event: TWindowMessage['data'],\n) => TWindowMessage['response'] | Promise<TWindowMessage['response']>\n\n/**\n * @public\n */\nexport interface UseFrameConnectionOptions<TWindowMessage extends WindowMessage> {\n  name: string\n  connectTo: string\n  targetOrigin: string\n  onMessage?: Record<string, FrameMessageHandler<TWindowMessage>>\n}\n\n/**\n * @public\n */\nexport interface FrameConnection<TFrameMessage extends FrameMessage> {\n  connect: (frameWindow: Window) => () => void // Return cleanup function\n  sendMessage: <T extends TFrameMessage['type']>(\n    ...params: Extract<TFrameMessage, {type: T}>['data'] extends undefined\n      ? [type: T]\n      : [type: T, data: Extract<TFrameMessage, {type: T}>['data']]\n  ) => void\n}\n\n/**\n * @public\n */\nexport function useFrameConnection<\n  TFrameMessage extends FrameMessage,\n  TWindowMessage extends WindowMessage,\n>(options: UseFrameConnectionOptions<TWindowMessage>): FrameConnection<TFrameMessage> {\n  const {onMessage, targetOrigin, name, connectTo} = options\n  const instance = useSanityInstance()\n\n  const controller = useMemo(\n    () => getOrCreateController(instance, targetOrigin),\n    [instance, targetOrigin],\n  )\n\n  const channel = useMemo(\n    () =>\n      getOrCreateChannel(instance, {\n        name,\n        connectTo,\n      }),\n    [instance, name, connectTo],\n  )\n\n  useEffect(() => {\n    if (!channel || !onMessage) return\n\n    const unsubscribers: Array<() => void> = []\n\n    Object.entries(onMessage).forEach(([type, handler]) => {\n      const unsubscribe = channel.on(type, handler)\n      unsubscribers.push(unsubscribe)\n    })\n\n    return () => {\n      unsubscribers.forEach((unsub) => unsub())\n    }\n  }, [channel, onMessage])\n\n  const connect = useCallback(\n    (frameWindow: Window) => {\n      const removeTarget = controller?.addTarget(frameWindow)\n      return () => {\n        removeTarget?.()\n      }\n    },\n    [controller],\n  )\n\n  const sendMessage = useCallback(\n    <T extends TFrameMessage['type']>(\n      type: T,\n      data?: Extract<TFrameMessage, {type: T}>['data'],\n    ) => {\n      channel?.post(type, data)\n    },\n    [channel],\n  )\n\n  // cleanup channel on unmount\n  useEffect(() => {\n    return () => {\n      releaseChannel(instance, name)\n    }\n  }, [name, instance])\n\n  return {\n    connect,\n    sendMessage,\n  }\n}\n","import {type FrameMessage, getOrCreateNode, releaseNode, type WindowMessage} from '@sanity/sdk'\nimport {useCallback, useEffect, useMemo} from 'react'\n\nimport {useSanityInstance} from '../context/useSanityInstance'\n\n/**\n * @public\n */\nexport type WindowMessageHandler<TFrameMessage extends FrameMessage> = (\n  event: TFrameMessage['data'],\n) => TFrameMessage['response']\n\n/**\n * @public\n */\nexport interface UseWindowConnectionOptions<TMessage extends FrameMessage> {\n  name: string\n  connectTo: string\n  onMessage?: Record<TMessage['type'], WindowMessageHandler<TMessage>>\n}\n\n/**\n * @public\n */\nexport interface WindowConnection<TMessage extends WindowMessage> {\n  sendMessage: <TType extends TMessage['type']>(\n    type: TType,\n    data?: Extract<TMessage, {type: TType}>['data'],\n  ) => void\n}\n\n/**\n * @public\n */\nexport function useWindowConnection<\n  TWindowMessage extends WindowMessage,\n  TFrameMessage extends FrameMessage,\n>(options: UseWindowConnectionOptions<TFrameMessage>): WindowConnection<TWindowMessage> {\n  const {name, onMessage, connectTo} = options\n  const instance = useSanityInstance()\n\n  const node = useMemo(\n    () => getOrCreateNode(instance, {name, connectTo}),\n    [instance, name, connectTo],\n  )\n\n  useEffect(() => {\n    if (!onMessage) return\n\n    const unsubscribers: Array<() => void> = []\n\n    Object.entries(onMessage).forEach(([type, handler]) => {\n      const unsubscribe = node.on(type, handler as WindowMessageHandler<TFrameMessage>)\n      unsubscribers.push(unsubscribe)\n    })\n\n    return () => {\n      unsubscribers.forEach((unsub) => unsub())\n    }\n  }, [node, onMessage])\n\n  const sendMessage = useCallback(\n    <TType extends WindowMessage['type']>(\n      type: TType,\n      data?: Extract<WindowMessage, {type: TType}>['data'],\n    ) => {\n      node?.post(type, data)\n    },\n    [node],\n  )\n\n  // cleanup node on unmount\n  useEffect(() => {\n    return () => {\n      releaseNode(instance, name)\n    }\n  }, [instance, name])\n\n  return {\n    sendMessage,\n  }\n}\n","import {createDocumentListStore, type DocumentHandle, type DocumentListOptions} from '@sanity/sdk'\nimport {useCallback, useEffect, useState, useSyncExternalStore} from 'react'\n\nimport {useSanityInstance} from '../context/useSanityInstance'\n\n/**\n * @public\n */\nexport interface DocumentCollection {\n  /** Retrieve more documents matching the provided options */\n  loadMore: () => void\n  /** The retrieved document handles of the documents matching the provided options */\n  results: DocumentHandle[]\n  /** Whether a retrieval of documents is in flight */\n  isPending: boolean\n  /** Whether more documents exist that match the provided options than have been retrieved */\n  hasMore: boolean\n  /** The total number of documents in the collection */\n  count: number\n}\n\ntype DocumentListStore = ReturnType<typeof createDocumentListStore>\ntype DocumentListState = ReturnType<DocumentListStore['getState']>['getCurrent']\nconst STABLE_EMPTY = {\n  results: [],\n  isPending: false,\n  hasMore: false,\n  count: 0,\n}\n\n/**\n * @public\n *\n * The `useDocuments` hook retrieves and provides access to a live collection of documents, optionally filtered, sorted, and matched to a given Content Lake perspective.\n * Because the returned document collection is live, the results will update in real time until the component invoking the hook is unmounted.\n *\n * @param options - Options for narrowing and sorting the document collection\n * @returns The collection of documents matching the provided options (if any), as well as properties describing the collection and a function to load more.\n *\n * @example Retrieving all documents of type 'movie'\n * ```\n * const { results, isPending } = useDocuments({ filter: '_type == \"movie\"' })\n *\n * return (\n *   <div>\n *     <h1>Movies</h1>\n *     {results && (\n *       <ul>\n *         {results.map(movie => (<li key={movie._id}>…</li>))}\n *       </ul>\n *     )}\n *     {isPending && <div>Loading movies…</div>}\n *   </div>\n * )\n * ```\n *\n * @example Retrieving all movies released since 1980, sorted by release date\n * ```\n * const { results } = useDocuments({\n *   filter: '_type == \"movie\" && releaseDate >= \"1980-01-01\"',\n *   sort: [\n *     {\n *       field: 'releaseDate',\n *       sort: 'asc',\n *     },\n *   ],\n * })\n *\n * return (\n *   <div>\n *      <h1>Movies released since 1980</h1>\n *      {results && (\n *        <ol>\n *          {results.map(movie => (<li key={movie._id}>…</li>))}\n *        </ol>\n *     )}\n *   </div>\n * )\n * ```\n */\nexport function useDocuments(options: DocumentListOptions = {}): DocumentCollection {\n  const instance = useSanityInstance()\n\n  // NOTE: useState is used because it guaranteed to return a stable reference\n  // across renders\n  const [ref] = useState<{\n    storeInstance: DocumentListStore | null\n    getCurrent: DocumentListState\n    initialOptions: DocumentListOptions\n  }>(() => ({\n    storeInstance: null,\n    getCurrent: () => STABLE_EMPTY,\n    initialOptions: options,\n  }))\n\n  // serialize options to ensure it only calls `setOptions` when the values\n  // themselves changes (in cases where devs put config inline)\n  const serializedOptions = JSON.stringify(options)\n  useEffect(() => {\n    ref.storeInstance?.setOptions(JSON.parse(serializedOptions))\n  }, [ref, serializedOptions])\n\n  const subscribe = useCallback(\n    (onStoreChanged: () => void) => {\n      // to match the lifecycle of `useSyncExternalState`, we create the store\n      // instance after subscribe and mutate the ref to connect everything\n      ref.storeInstance = createDocumentListStore(instance)\n      ref.storeInstance.setOptions(ref.initialOptions)\n      const state = ref.storeInstance.getState()\n      ref.getCurrent = state.getCurrent\n      const unsubscribe = state.subscribe(onStoreChanged)\n\n      return () => {\n        // unsubscribe to clean up the state subscriptions\n        unsubscribe()\n        // dispose of the instance\n        ref.storeInstance?.dispose()\n      }\n    },\n    [instance, ref],\n  )\n\n  const getSnapshot = useCallback(() => {\n    return ref.getCurrent()\n  }, [ref])\n\n  const state = useSyncExternalStore(subscribe, getSnapshot)\n\n  const loadMore = useCallback(() => {\n    ref.storeInstance?.loadMore()\n  }, [ref])\n\n  return {loadMore, ...state}\n}\n","import {type DocumentHandle, getPreviewState, type PreviewValue, resolvePreview} from '@sanity/sdk'\nimport {useCallback, useMemo, useSyncExternalStore} from 'react'\nimport {distinctUntilChanged, EMPTY, Observable, startWith, switchMap} from 'rxjs'\n\nimport {useSanityInstance} from '../context/useSanityInstance'\n\n/**\n * @alpha\n */\nexport interface UsePreviewOptions {\n  document: DocumentHandle\n  ref: HTMLElement | null\n}\n\n/**\n * @alpha\n */\nexport interface UsePreviewResults {\n  /** The results of resolving the document’s preview values */\n  results: PreviewValue\n  /** Whether the resolution of the preview values is pending */\n  isPending: boolean\n}\n\n/**\n * @alpha\n *\n * The `usePreview` hook takes a document (via a `DocumentHandle`) and returns its resolved preview values,\n * including the document’s `title`, `subtitle`, `media`, and `status`. These values are live and will update in realtime.\n * To reduce unnecessary network requests for resolving the preview values, an optional `ref` can be passed to the hook so that preview\n * resolution will only occur if the `ref` is intersecting the current viewport.\n *\n * @param options - The document handle for the document you want to resolve preview values for, and an optional ref\n * @returns The preview values for the given document and a boolean to indicate whether the resolution is pending\n *\n * @example Combining with useDocuments to render a collection of document previews\n * ```\n * // PreviewComponent.jsx\n * export default function PreviewComponent({ document }) {\n *   const { results: { title, subtitle, media }, isPending } = usePreview({ document })\n *   return isPending ? 'Loading…' : (\n *     <article>\n *       {media?.type === 'image-asset' ? <img src={media.url} alt='' /> : ''}\n *       <h2>{title}</h2>\n *       <p>{subtitle}</p>\n *     </article>\n *   )\n * }\n *\n * // DocumentList.jsx\n * const { results, isPending } = useDocuments({ filter: '_type == \"movie\"' })\n * return (\n *   <div>\n *     <h1>Movies</h1>\n *     <ul>\n *       {isPending ? 'Loading…' : results.map(movie => (\n *         <li key={movie._id}>\n *           <PreviewComponent document={movie} />\n *         </li>\n *       ))}\n *     </ul>\n *   </div>\n * )\n * ```\n */\nexport function usePreview({document: {_id, _type}, ref}: UsePreviewOptions): UsePreviewResults {\n  const instance = useSanityInstance()\n\n  const stateSource = useMemo(\n    () => getPreviewState(instance, {document: {_id, _type}}),\n    [instance, _id, _type],\n  )\n\n  // Create subscribe function for useSyncExternalStore\n  const subscribe = useCallback(\n    (onStoreChanged: () => void) => {\n      const subscription = new Observable<boolean>((observer) => {\n        // for environments that don't have an intersection observer\n        if (typeof IntersectionObserver === 'undefined') return\n\n        const intersectionObserver = new IntersectionObserver(\n          ([entry]) => observer.next(entry.isIntersecting),\n          {rootMargin: '0px', threshold: 0},\n        )\n        if (ref) intersectionObserver.observe(ref)\n        return () => intersectionObserver.disconnect()\n      })\n        .pipe(\n          startWith(false),\n          distinctUntilChanged(),\n          switchMap((isVisible) =>\n            isVisible\n              ? new Observable<void>((obs) => {\n                  return stateSource.subscribe(() => obs.next())\n                })\n              : EMPTY,\n          ),\n        )\n        .subscribe({next: onStoreChanged})\n\n      return () => subscription.unsubscribe()\n    },\n    [stateSource, ref],\n  )\n\n  // Create getSnapshot function to return current state\n  const getSnapshot = useCallback(() => {\n    const currentState = stateSource.getCurrent()\n    if (currentState.results === null) throw resolvePreview(instance, {document: {_id, _type}})\n    return currentState as UsePreviewResults\n  }, [_id, _type, instance, stateSource])\n\n  return useSyncExternalStore(subscribe, getSnapshot)\n}\n"],"names":["state"],"mappings":"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"}
+{"version":3,"file":"hooks.js","sources":["../src/hooks/auth/useAuthToken.tsx","../src/hooks/auth/useCurrentUser.tsx","../src/hooks/comlink/useFrameConnection.ts","../src/hooks/comlink/useWindowConnection.ts","../src/hooks/documentCollection/useDocuments.ts","../src/hooks/preview/usePreview.tsx"],"sourcesContent":["import {getTokenState} from '@sanity/sdk'\n\nimport {createStateSourceHook} from '../helpers/createStateSourceHook'\n\n/**\n * Hook to get the currently logged in user\n * @public\n * @returns The current user or null if not authenticated\n */\nexport const useAuthToken = createStateSourceHook(getTokenState)\n","import {getCurrentUserState} from '@sanity/sdk'\n\nimport {createStateSourceHook} from '../helpers/createStateSourceHook'\n\n/**\n * Hook to get the currently logged in user\n * @public\n * @returns The current user or null if not authenticated\n */\nexport const useCurrentUser = createStateSourceHook(getCurrentUserState)\n","import {\n  type FrameMessage,\n  getOrCreateChannel,\n  getOrCreateController,\n  releaseChannel,\n  type WindowMessage,\n} from '@sanity/sdk'\nimport {useCallback, useEffect, useMemo} from 'react'\n\nimport {useSanityInstance} from '../context/useSanityInstance'\n\n/**\n * @public\n */\nexport type FrameMessageHandler<TWindowMessage extends WindowMessage> = (\n  event: TWindowMessage['data'],\n) => TWindowMessage['response'] | Promise<TWindowMessage['response']>\n\n/**\n * @public\n */\nexport interface UseFrameConnectionOptions<TWindowMessage extends WindowMessage> {\n  name: string\n  connectTo: string\n  targetOrigin: string\n  onMessage?: Record<string, FrameMessageHandler<TWindowMessage>>\n}\n\n/**\n * @public\n */\nexport interface FrameConnection<TFrameMessage extends FrameMessage> {\n  connect: (frameWindow: Window) => () => void // Return cleanup function\n  sendMessage: <T extends TFrameMessage['type']>(\n    ...params: Extract<TFrameMessage, {type: T}>['data'] extends undefined\n      ? [type: T]\n      : [type: T, data: Extract<TFrameMessage, {type: T}>['data']]\n  ) => void\n}\n\n/**\n * @public\n */\nexport function useFrameConnection<\n  TFrameMessage extends FrameMessage,\n  TWindowMessage extends WindowMessage,\n>(options: UseFrameConnectionOptions<TWindowMessage>): FrameConnection<TFrameMessage> {\n  const {onMessage, targetOrigin, name, connectTo} = options\n  const instance = useSanityInstance()\n\n  const controller = useMemo(\n    () => getOrCreateController(instance, targetOrigin),\n    [instance, targetOrigin],\n  )\n\n  const channel = useMemo(\n    () =>\n      getOrCreateChannel(instance, {\n        name,\n        connectTo,\n      }),\n    [instance, name, connectTo],\n  )\n\n  useEffect(() => {\n    if (!channel || !onMessage) return\n\n    const unsubscribers: Array<() => void> = []\n\n    Object.entries(onMessage).forEach(([type, handler]) => {\n      const unsubscribe = channel.on(type, handler)\n      unsubscribers.push(unsubscribe)\n    })\n\n    return () => {\n      unsubscribers.forEach((unsub) => unsub())\n    }\n  }, [channel, onMessage])\n\n  const connect = useCallback(\n    (frameWindow: Window) => {\n      const removeTarget = controller?.addTarget(frameWindow)\n      return () => {\n        removeTarget?.()\n      }\n    },\n    [controller],\n  )\n\n  const sendMessage = useCallback(\n    <T extends TFrameMessage['type']>(\n      type: T,\n      data?: Extract<TFrameMessage, {type: T}>['data'],\n    ) => {\n      channel?.post(type, data)\n    },\n    [channel],\n  )\n\n  // cleanup channel on unmount\n  useEffect(() => {\n    return () => {\n      releaseChannel(instance, name)\n    }\n  }, [name, instance])\n\n  return {\n    connect,\n    sendMessage,\n  }\n}\n","import {type FrameMessage, getOrCreateNode, releaseNode, type WindowMessage} from '@sanity/sdk'\nimport {useCallback, useEffect, useMemo} from 'react'\n\nimport {useSanityInstance} from '../context/useSanityInstance'\n\n/**\n * @public\n */\nexport type WindowMessageHandler<TFrameMessage extends FrameMessage> = (\n  event: TFrameMessage['data'],\n) => TFrameMessage['response']\n\n/**\n * @public\n */\nexport interface UseWindowConnectionOptions<TMessage extends FrameMessage> {\n  name: string\n  connectTo: string\n  onMessage?: Record<TMessage['type'], WindowMessageHandler<TMessage>>\n}\n\n/**\n * @public\n */\nexport interface WindowConnection<TMessage extends WindowMessage> {\n  sendMessage: <TType extends TMessage['type']>(\n    type: TType,\n    data?: Extract<TMessage, {type: TType}>['data'],\n  ) => void\n}\n\n/**\n * @public\n */\nexport function useWindowConnection<\n  TWindowMessage extends WindowMessage,\n  TFrameMessage extends FrameMessage,\n>(options: UseWindowConnectionOptions<TFrameMessage>): WindowConnection<TWindowMessage> {\n  const {name, onMessage, connectTo} = options\n  const instance = useSanityInstance()\n\n  const node = useMemo(\n    () => getOrCreateNode(instance, {name, connectTo}),\n    [instance, name, connectTo],\n  )\n\n  useEffect(() => {\n    if (!onMessage) return\n\n    const unsubscribers: Array<() => void> = []\n\n    Object.entries(onMessage).forEach(([type, handler]) => {\n      const unsubscribe = node.on(type, handler as WindowMessageHandler<TFrameMessage>)\n      unsubscribers.push(unsubscribe)\n    })\n\n    return () => {\n      unsubscribers.forEach((unsub) => unsub())\n    }\n  }, [node, onMessage])\n\n  const sendMessage = useCallback(\n    <TType extends WindowMessage['type']>(\n      type: TType,\n      data?: Extract<WindowMessage, {type: TType}>['data'],\n    ) => {\n      node?.post(type, data)\n    },\n    [node],\n  )\n\n  // cleanup node on unmount\n  useEffect(() => {\n    return () => {\n      releaseNode(instance, name)\n    }\n  }, [instance, name])\n\n  return {\n    sendMessage,\n  }\n}\n","import {createDocumentListStore, type DocumentHandle, type DocumentListOptions} from '@sanity/sdk'\nimport {useCallback, useEffect, useState, useSyncExternalStore} from 'react'\n\nimport {useSanityInstance} from '../context/useSanityInstance'\n\n/**\n * @public\n */\nexport interface DocumentCollection {\n  /** Retrieve more documents matching the provided options */\n  loadMore: () => void\n  /** The retrieved document handles of the documents matching the provided options */\n  results: DocumentHandle[]\n  /** Whether a retrieval of documents is in flight */\n  isPending: boolean\n  /** Whether more documents exist that match the provided options than have been retrieved */\n  hasMore: boolean\n  /** The total number of documents in the collection */\n  count: number\n}\n\ntype DocumentListStore = ReturnType<typeof createDocumentListStore>\ntype DocumentListState = ReturnType<DocumentListStore['getState']>['getCurrent']\nconst STABLE_EMPTY = {\n  results: [],\n  isPending: false,\n  hasMore: false,\n  count: 0,\n}\n\n/**\n * @public\n *\n * The `useDocuments` hook retrieves and provides access to a live collection of documents, optionally filtered, sorted, and matched to a given Content Lake perspective.\n * Because the returned document collection is live, the results will update in real time until the component invoking the hook is unmounted.\n *\n * @param options - Options for narrowing and sorting the document collection\n * @returns The collection of documents matching the provided options (if any), as well as properties describing the collection and a function to load more.\n *\n * @example Retrieving all documents of type 'movie'\n * ```\n * const { results, isPending } = useDocuments({ filter: '_type == \"movie\"' })\n *\n * return (\n *   <div>\n *     <h1>Movies</h1>\n *     {results && (\n *       <ul>\n *         {results.map(movie => (<li key={movie._id}>…</li>))}\n *       </ul>\n *     )}\n *     {isPending && <div>Loading movies…</div>}\n *   </div>\n * )\n * ```\n *\n * @example Retrieving all movies released since 1980, sorted by director’s last name\n * ```\n * const { results } = useDocuments({\n *   filter: '_type == \"movie\" && releaseDate >= \"1980-01-01\"',\n *   sort: [\n *     {\n *       // Expand the `director` reference field with the dereferencing operator `->`\n *       field: 'director->lastName',\n *       sort: 'asc',\n *     },\n *   ],\n * })\n *\n * return (\n *   <div>\n *      <h1>Movies released since 1980</h1>\n *      {results && (\n *        <ol>\n *          {results.map(movie => (<li key={movie._id}>…</li>))}\n *        </ol>\n *     )}\n *   </div>\n * )\n * ```\n */\nexport function useDocuments(options: DocumentListOptions = {}): DocumentCollection {\n  const instance = useSanityInstance()\n\n  // NOTE: useState is used because it guaranteed to return a stable reference\n  // across renders\n  const [ref] = useState<{\n    storeInstance: DocumentListStore | null\n    getCurrent: DocumentListState\n    initialOptions: DocumentListOptions\n  }>(() => ({\n    storeInstance: null,\n    getCurrent: () => STABLE_EMPTY,\n    initialOptions: options,\n  }))\n\n  // serialize options to ensure it only calls `setOptions` when the values\n  // themselves changes (in cases where devs put config inline)\n  const serializedOptions = JSON.stringify(options)\n  useEffect(() => {\n    ref.storeInstance?.setOptions(JSON.parse(serializedOptions))\n  }, [ref, serializedOptions])\n\n  const subscribe = useCallback(\n    (onStoreChanged: () => void) => {\n      // to match the lifecycle of `useSyncExternalState`, we create the store\n      // instance after subscribe and mutate the ref to connect everything\n      ref.storeInstance = createDocumentListStore(instance)\n      ref.storeInstance.setOptions(ref.initialOptions)\n      const state = ref.storeInstance.getState()\n      ref.getCurrent = state.getCurrent\n      const unsubscribe = state.subscribe(onStoreChanged)\n\n      return () => {\n        // unsubscribe to clean up the state subscriptions\n        unsubscribe()\n        // dispose of the instance\n        ref.storeInstance?.dispose()\n      }\n    },\n    [instance, ref],\n  )\n\n  const getSnapshot = useCallback(() => {\n    return ref.getCurrent()\n  }, [ref])\n\n  const state = useSyncExternalStore(subscribe, getSnapshot)\n\n  const loadMore = useCallback(() => {\n    ref.storeInstance?.loadMore()\n  }, [ref])\n\n  return {loadMore, ...state}\n}\n","import {type DocumentHandle, getPreviewState, type PreviewValue, resolvePreview} from '@sanity/sdk'\nimport {useCallback, useMemo, useSyncExternalStore} from 'react'\nimport {distinctUntilChanged, EMPTY, Observable, startWith, switchMap} from 'rxjs'\n\nimport {useSanityInstance} from '../context/useSanityInstance'\n\n/**\n * @alpha\n */\nexport interface UsePreviewOptions {\n  document: DocumentHandle\n  ref?: React.RefObject<unknown>\n}\n\n/**\n * @alpha\n */\nexport interface UsePreviewResults {\n  /** The results of resolving the document’s preview values */\n  results: PreviewValue\n  /** True when preview values are being refreshed */\n  isPending: boolean\n}\n\n/**\n * @alpha\n *\n * The `usePreview` hook takes a document (via a `DocumentHandle`) and returns its resolved preview values,\n * including the document’s `title`, `subtitle`, `media`, and `status`. These values are live and will update in realtime.\n * To reduce unnecessary network requests for resolving the preview values, an optional `ref` can be passed to the hook so that preview\n * resolution will only occur if the `ref` is intersecting the current viewport.\n *\n * @param options - The document handle for the document you want to resolve preview values for, and an optional ref\n * @returns The preview values for the given document and a boolean to indicate whether the resolution is pending\n *\n * @example Combining with useDocuments to render a collection of document previews\n * ```\n * // PreviewComponent.jsx\n * export default function PreviewComponent({ document }) {\n *   const { results: { title, subtitle, media }, isPending } = usePreview({ document })\n *   return isPending ? 'Loading…' : (\n *     <article>\n *       {media?.type === 'image-asset' ? <img src={media.url} alt='' /> : ''}\n *       <h2>{title}</h2>\n *       <p>{subtitle}</p>\n *     </article>\n *   )\n * }\n *\n * // DocumentList.jsx\n * const { results, isPending } = useDocuments({ filter: '_type == \"movie\"' })\n * return (\n *   <div>\n *     <h1>Movies</h1>\n *     <ul>\n *       {isPending ? 'Loading…' : results.map(movie => (\n *         <li key={movie._id}>\n *           <Suspense fallback='Loading…'>\n *             <PreviewComponent document={movie} />\n *           </Suspense>\n *         </li>\n *       ))}\n *     </ul>\n *   </div>\n * )\n * ```\n */\nexport function usePreview({document: {_id, _type}, ref}: UsePreviewOptions): UsePreviewResults {\n  const instance = useSanityInstance()\n\n  const stateSource = useMemo(\n    () => getPreviewState(instance, {document: {_id, _type}}),\n    [instance, _id, _type],\n  )\n\n  // Create subscribe function for useSyncExternalStore\n  const subscribe = useCallback(\n    (onStoreChanged: () => void) => {\n      const subscription = new Observable<boolean>((observer) => {\n        // for environments that don't have an intersection observer\n        if (typeof IntersectionObserver === 'undefined' || typeof HTMLElement === 'undefined') {\n          return\n        }\n\n        const intersectionObserver = new IntersectionObserver(\n          ([entry]) => observer.next(entry.isIntersecting),\n          {rootMargin: '0px', threshold: 0},\n        )\n        if (ref?.current && ref.current instanceof HTMLElement) {\n          intersectionObserver.observe(ref.current)\n        }\n        return () => intersectionObserver.disconnect()\n      })\n        .pipe(\n          startWith(false),\n          distinctUntilChanged(),\n          switchMap((isVisible) =>\n            isVisible\n              ? new Observable<void>((obs) => {\n                  return stateSource.subscribe(() => obs.next())\n                })\n              : EMPTY,\n          ),\n        )\n        .subscribe({next: onStoreChanged})\n\n      return () => subscription.unsubscribe()\n    },\n    [stateSource, ref],\n  )\n\n  // Create getSnapshot function to return current state\n  const getSnapshot = useCallback(() => {\n    const currentState = stateSource.getCurrent()\n    if (currentState.results === null) throw resolvePreview(instance, {document: {_id, _type}})\n    return currentState as UsePreviewResults\n  }, [_id, _type, instance, stateSource])\n\n  return useSyncExternalStore(subscribe, getSnapshot)\n}\n"],"names":["state"],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sanity/sdk-react",
-  "version": "0.0.0-alpha.5",
+  "version": "0.0.0-alpha.6",
   "private": false,
   "description": "Sanity SDK React toolkit for Content OS",
   "keywords": [
@@ -71,7 +71,7 @@
     "@sanity/ui": "^2.8.19",
     "react-error-boundary": "^4.1.2",
     "rxjs": "^7.8.1",
-    "@sanity/sdk": "0.0.0-alpha.5"
+    "@sanity/sdk": "0.0.0-alpha.6"
   },
   "devDependencies": {
     "@sanity/client": "^6.24.1",
@@ -92,10 +92,10 @@
     "typescript": "^5.7.2",
     "vite": "^5.4.11",
     "vitest": "^2.1.8",
-    "@repo/config-eslint": "0.0.0",
-    "@repo/config-test": "0.0.1",
     "@repo/package.config": "0.0.1",
-    "@repo/tsconfig": "0.0.1"
+    "@repo/tsconfig": "0.0.1",
+    "@repo/config-test": "0.0.1",
+    "@repo/config-eslint": "0.0.0"
   },
   "peerDependencies": {
     "react": "^18.0.0 || ^19.0.0",

package/src/hooks/documentCollection/useDocuments.ts

@@ -54,13 +54,14 @@ const STABLE_EMPTY = {
  * )
  * ```
  *
- * @example Retrieving all movies released since 1980, sorted by release date
+ * @example Retrieving all movies released since 1980, sorted by director’s last name
  * ```
  * const { results } = useDocuments({
  *   filter: '_type == "movie" && releaseDate >= "1980-01-01"',
  *   sort: [
  *     {
- *       field: 'releaseDate',
+ *       // Expand the `director` reference field with the dereferencing operator `->`
+ *       field: 'director->lastName',
  *       sort: 'asc',
  *     },
  *   ],

package/src/hooks/preview/usePreview.test.tsx

@@ -1,6 +1,6 @@
 import {type DocumentHandle, getPreviewState, type PreviewValue, resolvePreview} from '@sanity/sdk'
 import {act, render, screen} from '@testing-library/react'
-import {Suspense, useState} from 'react'
+import {Suspense, useRef} from 'react'
 import {type Mock} from 'vitest'
 
 import {usePreview} from './usePreview'
@@ -44,11 +44,11 @@ const mockDocument: DocumentHandle = {
 }
 
 function TestComponent({document}: {document: DocumentHandle}) {
-  const [ref, setRef] = useState<HTMLElement | null>(null)
+  const ref = useRef(null)
   const {results, isPending} = usePreview({document, ref})
 
   return (
-    <div ref={setRef}>
+    <div ref={ref}>
       <h1>{results?.title}</h1>
       <p>{results?.subtitle}</p>
       {isPending && <div>Pending...</div>}

package/src/hooks/preview/usePreview.tsx

@@ -9,7 +9,7 @@ import {useSanityInstance} from '../context/useSanityInstance'
  */
 export interface UsePreviewOptions {
   document: DocumentHandle
-  ref: HTMLElement | null
+  ref?: React.RefObject<unknown>
 }
 
 /**
@@ -18,7 +18,7 @@ export interface UsePreviewOptions {
 export interface UsePreviewResults {
   /** The results of resolving the document’s preview values */
   results: PreviewValue
-  /** Whether the resolution of the preview values is pending */
+  /** True when preview values are being refreshed */
   isPending: boolean
 }
 
@@ -55,7 +55,9 @@ export interface UsePreviewResults {
  *     <ul>
  *       {isPending ? 'Loading…' : results.map(movie => (
  *         <li key={movie._id}>
- *           <PreviewComponent document={movie} />
+ *           <Suspense fallback='Loading…'>
+ *             <PreviewComponent document={movie} />
+ *           </Suspense>
  *         </li>
  *       ))}
  *     </ul>
@@ -76,13 +78,17 @@ export function usePreview({document: {_id, _type}, ref}: UsePreviewOptions): Us
     (onStoreChanged: () => void) => {
       const subscription = new Observable<boolean>((observer) => {
         // for environments that don't have an intersection observer
-        if (typeof IntersectionObserver === 'undefined') return
+        if (typeof IntersectionObserver === 'undefined' || typeof HTMLElement === 'undefined') {
+          return
+        }
 
         const intersectionObserver = new IntersectionObserver(
           ([entry]) => observer.next(entry.isIntersecting),
           {rootMargin: '0px', threshold: 0},
         )
-        if (ref) intersectionObserver.observe(ref)
+        if (ref?.current && ref.current instanceof HTMLElement) {
+          intersectionObserver.observe(ref.current)
+        }
         return () => intersectionObserver.disconnect()
       })
         .pipe(