@sanity/sdk-react 2.15.0 → 2.16.0

package/README.md

@@ -146,7 +146,7 @@ await apply([publishDocument(handle1), publishDocument(handle2), deleteDocument(
 useDocumentEvent({
   ...handle,
   onEvent: (event) => {
-    // event.type: 'documentEdited' | 'documentPublished' | 'documentDeleted' | ...
+    // event.type: 'edited' | 'published' | 'deleted' | 'created' | 'unpublished' | 'discarded' | ...
     console.log(event.type, event.documentId)
   },
 })
@@ -297,6 +297,27 @@ function ArticleList() {
 
 ---
 
+### Viewport-Based Lazy Loading
+
+Pass a `ref` to `useDocumentProjection` to fetch only when the element enters the viewport. Wrap the component in Suspense like any other data hook:
+
+```tsx
+import {useRef} from 'react'
+
+function LazyArticleCard({handle}: {handle: DocumentHandle}) {
+  const ref = useRef<HTMLDivElement>(null)
+  const {data} = useDocumentProjection({
+    ...handle,
+    ref, // Only fetches when element is visible
+    projection: '{ title }',
+  })
+
+  return <div ref={ref}>{data?.title}</div>
+}
+```
+
+---
+
 ### Draft/Published Model
 
 Sanity has two document states:

package/dist/index.d.ts

@@ -34,6 +34,7 @@ import { OrganizationsOptions } from "@sanity/sdk";
 import { PathChangeMessage } from "@sanity/message-protocol";
 import { PreviewValue } from "@sanity/sdk";
 import { Project } from "@sanity/sdk";
+import { ProjectHandle } from "@sanity/sdk";
 import { ProjectOptions } from "@sanity/sdk";
 import { ProjectsOptions } from "@sanity/sdk";
 import { PropsWithChildren } from "react";
@@ -668,6 +669,35 @@ export declare interface SanityAppProps {
   resources?: Record<string, DocumentResource>;
   children: React.ReactNode;
   fallback: React.ReactNode;
+  /**
+   * Set this to automatically fetch and register the organization's media library and canvas as named resources.
+   * These resources will be available to hooks as `media-library` and `canvas`.
+   *
+   * The SDK App must be running in the organization's Dashboard to use this feature.
+   *
+   * @example
+   * ```tsx
+   *
+   * const MyApp = () => {
+   *   // should "just work" because of inferMediaLibraryAndCanvas.
+   *   const {data: assets} = useDocuments({
+   *     documentType: 'sanity.asset',
+   *     resourceName: 'media-library',
+   *   })
+   *   return (
+   *     <div>
+   *       {assets.map((asset) => (
+   *         <div key={asset._id}>{asset.originalFilename}</div>
+   *       ))}
+   *     </div>
+   *   )
+   * }
+   * <SanityApp inferMediaLibraryAndCanvas>
+   *   <MyApp />
+   * </SanityApp>
+   * ```
+   */
+  inferMediaLibraryAndCanvas?: boolean;
 }
 
 export { SanityDocument };
@@ -744,6 +774,7 @@ export declare function SDKProvider({
   children,
   config,
   fallback,
+  inferMediaLibraryAndCanvas,
   ...props
 }: SDKProviderProps): ReactElement;
 
@@ -755,6 +786,8 @@ export declare interface SDKProviderProps extends AuthBoundaryProps {
   config: SanityConfig | SanityConfig[];
   fallback: ReactNode;
   resources?: Record<string, DocumentResource>;
+  /** When set, automatically fetches and registers the organization's media library and canvas as named resources. */
+  inferMediaLibraryAndCanvas?: boolean;
 }
 
 /**
@@ -1908,6 +1941,8 @@ declare type UseDatasets = {
    * Returns metadata for each dataset the current user has access to.
    *
    * @category Datasets
+   * @param options - Optional project/resource to read datasets for. Defaults to
+   *   the resource named in `ResourceProvider`/`SDKProvider`.
    * @returns The metadata for your the datasets
    *
    * @example
@@ -1923,8 +1958,14 @@ declare type UseDatasets = {
    * )
    * ```
    *
-   */
-  (): DatasetsResponse;
+   * @remarks
+   * The `projectId` is resolved in order from:
+   * 1. an explicit `projectId` option
+   * 2. A legacy ProjectContext (e.g. a `<ResourceProvider projectId="…">` with no dataset), then
+   * 3. The active resource (`ResourceProvider`/`SDKProvider`)
+   * 4. `instance.config`.
+   */
+  (options?: ProjectHandle): DatasetsResponse;
 };
 
 /**
@@ -3304,6 +3345,12 @@ export declare function usePresence(options?: ResourceHandle): {
  * const projectWithoutMembers = useProject({projectId, includeMembers: false})
  * const projectWithoutFeatures = useProject({projectId, includeFeatures: false})
  * ```
+ * @remarks
+ * The `projectId` is resolved in order from:
+ * 1. an explicit `projectId` option
+ * 2. A legacy ProjectContext (e.g. a `<ResourceProvider projectId="…">` with no dataset), then
+ * 3. The active resource (`ResourceProvider`/`SDKProvider`)
+ * 4. `instance.config`.
  * @public
  * @function
  */
@@ -3718,6 +3765,12 @@ export declare function useUser(options: GetUserOptions): UserResult;
  *   </div>
  * )
  * ```
+ * @remarks
+ * For project-scoped queries the `projectId` is resolved in order from:
+ * 1. an explicit `projectId` option
+ * 2. A legacy ProjectContext (e.g. a `<ResourceProvider projectId="…">` with no dataset), then
+ * 3. The active resource (`ResourceProvider`/`SDKProvider`)
+ * 4. `instance.config`.
  */
 export declare function useUsers(options?: GetUsersOptions): UsersResult;