@sanity/sdk-react 2.18.0 → 2.19.0

package/dist/index.d.ts

@@ -18,6 +18,7 @@ import { DocumentEvent } from "@sanity/sdk";
 import { DocumentHandle as DocumentHandle_2 } from "@sanity/sdk";
 import { DocumentOptions } from "@sanity/sdk";
 import { DocumentPermissionsResult } from "@sanity/sdk";
+import { DocumentPresence } from "@sanity/sdk";
 import { DocumentResource } from "@sanity/sdk";
 import { DocumentTypeHandle as DocumentTypeHandle_2 } from "@sanity/sdk";
 import { FallbackProps } from "react-error-boundary";
@@ -31,7 +32,9 @@ import { Organization } from "@sanity/sdk";
 import { OrganizationOptions } from "@sanity/sdk";
 import { Organizations } from "@sanity/sdk";
 import { OrganizationsOptions } from "@sanity/sdk";
+import { Path } from "@sanity/types";
 import { PathChangeMessage } from "@sanity/message-protocol";
+import { PresenceSelection } from "@sanity/sdk";
 import { PreviewValue } from "@sanity/sdk";
 import { Project } from "@sanity/sdk";
 import { ProjectHandle } from "@sanity/sdk";
@@ -153,10 +156,7 @@ export declare interface AuthBoundaryProps {
  * @public
  */
 export declare type ComlinkStatus =
-  | "idle"
-  | "handshaking"
-  | "connected"
-  | "disconnected";
+  "idle" | "handshaking" | "connected" | "disconnected";
 
 /**
  * This provider is used to provide the Comlink token refresh feature.
@@ -327,11 +327,7 @@ export declare interface FrameConnection<TFrameMessage extends FrameMessage> {
 }
 
 declare type IgnoredKey =
-  | "_id"
-  | "_type"
-  | "_rev"
-  | "_createdAt"
-  | "_updatedAt";
+  "_id" | "_type" | "_rev" | "_createdAt" | "_updatedAt";
 
 /**
  * @alpha
@@ -3066,9 +3062,7 @@ export declare function useManageFavorite({
 declare interface UseManageFavoriteProps extends DocumentHandle_2 {
   resourceId?: string;
   resourceType:
-    | StudioResource["type"]
-    | MediaResource["type"]
-    | CanvasResource["type"];
+    StudioResource["type"] | MediaResource["type"] | CanvasResource["type"];
   /**
    * The name of the schema collection this document belongs to.
    * Typically is the name of the workspace when used in the context of a studio.
@@ -3312,13 +3306,80 @@ export declare function usePerspective(
 ): string | string[];
 
 /**
- * A hook for subscribing to presence information for the current project or Canvas.
+ * Every participant in the current project and dataset, or Canvas.
+ *
+ * Reading presence never announces anything. Call `useReportPresence` to make the
+ * current user visible to others, including to the Studio, which shares the same
+ * presence room.
+ *
+ * This returns everyone in the whole resource and leaves the filtering to you.
+ * Prefer `usePresenceForDocument` when you care about one document: it scopes and
+ * flattens the result for rendering. Note that participants are counted by session,
+ * so one person in two tabs appears twice.
+ *
+ * Presence is scoped to a single project and dataset. It is not a list of everyone
+ * signed in to your organization.
+ *
  * @public
  */
 export declare function usePresence(options?: ResourceHandle): {
   locations: UserPresence[];
 };
 
+/**
+ * Who else is in a document, flattened to one entry per participant per location
+ * so it can be rendered straight against a field.
+ *
+ * Reading presence never announces anything. Use `useReportPresence` to make the
+ * current user visible to others.
+ *
+ * Prefer this over `usePresence` when you care about one document: `usePresence`
+ * returns every participant in the whole project and dataset, leaving the filtering
+ * to you.
+ *
+ * Resolves the document through its perspective exactly as `useReportPresence` does,
+ * so reads match writes. Participants are counted by session, so one person in two
+ * tabs appears twice.
+ *
+ * @example Avatars on a document
+ * ```tsx
+ * const {presence} = usePresenceForDocument({documentId, documentType})
+ * return presence.map((p) => <Avatar key={p.sessionId} user={p.user} />)
+ * ```
+ *
+ * @example Avatars on a single field
+ * ```tsx
+ * const {presence} = usePresenceForDocument({
+ *   documentId,
+ *   documentType,
+ *   path: ['title'],
+ *   excludeVersions: true,
+ * })
+ * ```
+ *
+ * @beta
+ */
+export declare function usePresenceForDocument(
+  options: UsePresenceForDocumentOptions,
+): {
+  presence: DocumentPresence[];
+};
+
+/** @beta */
+export declare interface UsePresenceForDocumentOptions extends DocumentHandle {
+  /**
+   * Narrows to participants at or below this field path, which is what a field
+   * indicator wants. Omit it for everyone in the document.
+   */
+  path?: Path;
+  /**
+   * By default a draft, its published version, and any release versions count as
+   * the same document, which is what document lists want. Set this to compare ids
+   * exactly, so that a draft and a release version do not bleed into each other.
+   */
+  excludeVersions?: boolean;
+}
+
 /**
  * Returns metadata for a given project.
  *
@@ -3567,9 +3628,7 @@ export declare function useRecordDocumentHistoryEvent({
  */
 declare interface UseRecordDocumentHistoryEventProps extends DocumentHandle_2 {
   resourceType:
-    | StudioResource["type"]
-    | MediaResource["type"]
-    | CanvasResource["type"];
+    StudioResource["type"] | MediaResource["type"] | CanvasResource["type"];
   resourceId?: string;
   /**
    * The name of the schema collection this document belongs to.
@@ -3578,6 +3637,74 @@ declare interface UseRecordDocumentHistoryEventProps extends DocumentHandle_2 {
   schemaName?: string;
 }
 
+/**
+ * Announces that the current user is in a document, so that other clients in the
+ * same project and dataset can show them.
+ *
+ * Writing presence is opt-in. Reading it with `usePresenceForDocument` or
+ * `usePresence` never announces anything, and this hook is the only thing that
+ * makes an app visible to others. That includes the Studio, which shares the same
+ * presence room and will show these users in its navbar and field indicators.
+ *
+ * Announcements are throttled, collapsed over a short window, and then repeated
+ * every 30 seconds while the user is idle. That repeat is what tells peers the
+ * session is still alive, so the intended usage is to mount this hook for as long
+ * as the user is in the document. On unmount the location is cleared, leaving the
+ * user present in the app but not in any particular document.
+ *
+ * The perspective decides which specific document is reported: the draft under
+ * `drafts`, the published document under `published`, a version under a release.
+ * It is taken from `ResourceProvider` unless you pass one on the handle. That
+ * matters for interoperability, because the Studio's field indicators compare the
+ * exact id its form is on, so a mismatch shows your user at document level while
+ * never lighting up a field.
+ *
+ * Presence is scoped to a single project and dataset. It is not a list of everyone
+ * signed in to your organization.
+ *
+ * @example Document-level presence
+ * ```tsx
+ * function DocumentEditor({documentId, documentType}: DocumentHandle) {
+ *   useReportPresence({documentId, documentType})
+ *   return <Editor />
+ * }
+ * ```
+ *
+ * @example Presence in a release version
+ * ```tsx
+ * // The document id stays plain; the perspective selects the version.
+ * useReportPresence({documentId, documentType, perspective: {releaseName: 'autumn'}})
+ * ```
+ *
+ * @example Field-level presence
+ * ```tsx
+ * function TitleField({documentId, documentType}: DocumentHandle) {
+ *   const [focused, setFocused] = useState(false)
+ *   useReportPresence({documentId, documentType, path: focused ? ['title'] : undefined})
+ *   return <input onFocus={() => setFocused(true)} onBlur={() => setFocused(false)} />
+ * }
+ * ```
+ *
+ * @beta
+ */
+export declare function useReportPresence(
+  options: UseReportPresenceOptions,
+): void;
+
+/** @beta */
+export declare interface UseReportPresenceOptions extends DocumentHandle {
+  /**
+   * The focused field path. Omit it for document-level presence. Keyed and numeric
+   * segments are supported, so array items and Portable Text spans can be
+   * addressed.
+   */
+  path?: Path;
+  /** The Portable Text caret, when the focused field is a Portable Text field. */
+  selection?: PresenceSelection;
+  /** Overrides the throttle interval. Mainly useful in tests. */
+  throttleMs?: number;
+}
+
 /**
  * Returns the currently active `DocumentResource` for the nearest resource context.
  *

package/dist/index.js

@@ -1,7 +1,7 @@
 import { jsx, jsxs, Fragment } from "react/jsx-runtime";
 import { c } from "react-compiler-runtime";
 import { ClientError, CorsOriginError } from "@sanity/client";
-import { getAuthState, getNodeState, getIsInDashboardState, isStudioConfig, setAuthToken, AuthStateType, getLoginUrlState, observeOrganizationVerificationState, handleAuthCallback, logout, isProjectUserNotFoundClientError, getClientErrorApiDescription, getClientErrorApiBody, isImportError, getCorsErrorProjectId, getDashboardOrganizationId, getClientState, isDatasetResource, createSanityInstance, agentGenerate, agentPatch, agentPrompt, agentTransform, agentTranslate, getTokenState, getCurrentUserState, getOrCreateController, getOrCreateChannel, releaseChannel, isMediaLibraryResource, isCanvasResource, getFavoritesState, resolveFavoritesState, resolveDatasets, getDatasetsState, applyDocumentActions, createDocument, resolveDocument, getDocumentState, subscribeDocumentEvents, getPermissionsState, getDocumentSyncStatus, editDocument, getQueryKey, parseQueryKey, getQueryState, resolveQuery, createGroqSearchFilter, resolveOrganization, getOrganizationState, resolveOrganizations, getOrganizationsState, getPresence, getProjectionState, resolveProjection, transformProjectionToPreview, PREVIEW_PROJECTION, resolveProject, getProjectState, resolveProjects, getProjectsState, getActiveReleasesState, getAllReleasesState, getPerspectiveState, getUsersKey, parseUsersKey, getUsersState, resolveUsers, loadMoreUsers } from "@sanity/sdk";
+import { getAuthState, getNodeState, getIsInDashboardState, isStudioConfig, setAuthToken, AuthStateType, getLoginUrlState, observeOrganizationVerificationState, handleAuthCallback, logout, isProjectUserNotFoundClientError, getClientErrorApiDescription, getClientErrorApiBody, isImportError, getCorsErrorProjectId, getDashboardOrganizationId, getClientState, isDatasetResource, createSanityInstance, agentGenerate, agentPatch, agentPrompt, agentTransform, agentTranslate, getTokenState, getCurrentUserState, getOrCreateController, getOrCreateChannel, releaseChannel, isMediaLibraryResource, isCanvasResource, getFavoritesState, resolveFavoritesState, resolveDatasets, getDatasetsState, applyDocumentActions, createDocument, resolveDocument, getDocumentState, subscribeDocumentEvents, getPermissionsState, getDocumentSyncStatus, editDocument, getQueryKey, parseQueryKey, getQueryState, resolveQuery, createGroqSearchFilter, resolveOrganization, getOrganizationState, resolveOrganizations, getOrganizationsState, getPresence, getDocumentPresence, reportPresence, getProjectionState, resolveProjection, PREVIEW_PROJECTION, transformProjectionToPreview, resolveProject, getProjectState, resolveProjects, getProjectsState, getActiveReleasesState, getAllReleasesState, getPerspectiveState, getUsersKey, parseUsersKey, getUsersState, resolveUsers, loadMoreUsers } from "@sanity/sdk";
 export * from "@sanity/sdk";
 import { createContext, useContext, useSyncExternalStore, useRef, useEffect, useState, Suspense, use, StrictMode, useCallback, useMemo, useInsertionEffect, useTransition } from "react";
 import { getErrorMessage, ErrorBoundary } from "react-error-boundary";
@@ -1798,6 +1798,137 @@ function usePresence(t0) {
     locations: t6
   }, $[12] = t6, $[13] = t7) : t7 = $[13], t7;
 }
+function usePresenceForDocument(options) {
+  const $ = c(23);
+  let excludeVersions, handle, path;
+  $[0] !== options ? ({
+    path,
+    excludeVersions,
+    ...handle
+  } = options, $[0] = options, $[1] = excludeVersions, $[2] = handle, $[3] = path) : (excludeVersions = $[1], handle = $[2], path = $[3]);
+  const normalizedOptions = useNormalizedResourceOptions(handle);
+  if (normalizedOptions.resource && isMediaLibraryResource(normalizedOptions.resource))
+    throw new Error("usePresenceForDocument() does not support media library resources. Presence tracking requires a canvas or dataset resource.");
+  const sanityInstance = useSanityInstance();
+  trackHookUsage(sanityInstance, "usePresenceForDocument");
+  const {
+    resource,
+    perspective
+  } = normalizedOptions, {
+    documentId,
+    liveEdit
+  } = options;
+  let t0;
+  $[4] !== path ? (t0 = JSON.stringify(path ?? null), $[4] = path, $[5] = t0) : t0 = $[5];
+  const pathKey = t0;
+  let t1;
+  $[6] !== documentId || $[7] !== excludeVersions || $[8] !== liveEdit || $[9] !== pathKey || $[10] !== perspective || $[11] !== resource || $[12] !== sanityInstance ? (t1 = getDocumentPresence(sanityInstance, {
+    ...resource ? {
+      resource
+    } : {},
+    documentId,
+    ...perspective ? {
+      perspective
+    } : {},
+    ...liveEdit ? {
+      liveEdit
+    } : {},
+    ...pathKey === "null" ? {} : {
+      path: JSON.parse(pathKey)
+    },
+    ...excludeVersions === void 0 ? {} : {
+      excludeVersions
+    }
+  }), $[6] = documentId, $[7] = excludeVersions, $[8] = liveEdit, $[9] = pathKey, $[10] = perspective, $[11] = resource, $[12] = sanityInstance, $[13] = t1) : t1 = $[13];
+  const source = t1;
+  let t2;
+  $[14] !== source ? (t2 = (callback) => source.subscribe(callback), $[14] = source, $[15] = t2) : t2 = $[15];
+  const subscribe = t2;
+  let t3, t4;
+  $[16] !== source ? (t3 = () => source.getCurrent(), t4 = () => source.getCurrent(), $[16] = source, $[17] = t3, $[18] = t4) : (t3 = $[17], t4 = $[18]);
+  const presence = useSyncExternalStore(subscribe, t3, t4);
+  let t5;
+  $[19] !== presence ? (t5 = presence || [], $[19] = presence, $[20] = t5) : t5 = $[20];
+  let t6;
+  return $[21] !== t5 ? (t6 = {
+    presence: t5
+  }, $[21] = t5, $[22] = t6) : t6 = $[22], t6;
+}
+const FOCUS_THROTTLE_MS = 1e3, SELECTION_THROTTLE_MS = 250;
+function useReportPresence(options) {
+  const $ = c(37);
+  let handle, path, selection, throttleMs;
+  $[0] !== options ? ({
+    path,
+    selection,
+    throttleMs,
+    ...handle
+  } = options, $[0] = options, $[1] = handle, $[2] = path, $[3] = selection, $[4] = throttleMs) : (handle = $[1], path = $[2], selection = $[3], throttleMs = $[4]);
+  const normalizedOptions = useNormalizedResourceOptions(handle);
+  if (normalizedOptions.resource && isMediaLibraryResource(normalizedOptions.resource))
+    throw new Error("useReportPresence() does not support media library resources. Presence tracking requires a canvas or dataset resource.");
+  const sanityInstance = useSanityInstance();
+  trackHookUsage(sanityInstance, "useReportPresence");
+  const {
+    resource,
+    perspective
+  } = normalizedOptions, {
+    documentId,
+    liveEdit
+  } = options, interval = throttleMs ?? (selection ? SELECTION_THROTTLE_MS : FOCUS_THROTTLE_MS);
+  let t0;
+  $[5] !== documentId || $[6] !== liveEdit || $[7] !== path || $[8] !== perspective || $[9] !== selection ? (t0 = JSON.stringify([documentId, path ?? [], selection ?? null, perspective ?? null, liveEdit]), $[5] = documentId, $[6] = liveEdit, $[7] = path, $[8] = perspective, $[9] = selection, $[10] = t0) : t0 = $[10];
+  const locationKey = t0;
+  let t1;
+  $[11] !== locationKey ? (t1 = JSON.parse(locationKey), $[11] = locationKey, $[12] = t1) : t1 = $[12];
+  const [id, parsedPath, parsedSelection, parsedPerspective, parsedLiveEdit] = t1;
+  let t2;
+  $[13] !== parsedPerspective ? (t2 = parsedPerspective ? {
+    perspective: parsedPerspective
+  } : {}, $[13] = parsedPerspective, $[14] = t2) : t2 = $[14];
+  let t3;
+  $[15] !== parsedLiveEdit ? (t3 = parsedLiveEdit ? {
+    liveEdit: parsedLiveEdit
+  } : {}, $[15] = parsedLiveEdit, $[16] = t3) : t3 = $[16];
+  let t4;
+  $[17] !== parsedPath ? (t4 = parsedPath.length > 0 ? {
+    path: parsedPath
+  } : {}, $[17] = parsedPath, $[18] = t4) : t4 = $[18];
+  let t5;
+  $[19] !== parsedSelection ? (t5 = parsedSelection ? {
+    selection: parsedSelection
+  } : {}, $[19] = parsedSelection, $[20] = t5) : t5 = $[20];
+  let t6;
+  $[21] !== id || $[22] !== t2 || $[23] !== t3 || $[24] !== t4 || $[25] !== t5 ? (t6 = {
+    documentId: id,
+    ...t2,
+    ...t3,
+    ...t4,
+    ...t5
+  }, $[21] = id, $[22] = t2, $[23] = t3, $[24] = t4, $[25] = t5, $[26] = t6) : t6 = $[26];
+  const location2 = t6, lastSentAt = useRef(0), pending = useRef(void 0);
+  let t7, t8;
+  $[27] !== interval || $[28] !== location2 || $[29] !== resource || $[30] !== sanityInstance ? (t7 = () => {
+    const send = () => {
+      lastSentAt.current = Date.now(), reportPresence(sanityInstance, {
+        ...resource ? {
+          resource
+        } : {},
+        locations: [location2]
+      });
+    }, elapsed = Date.now() - lastSentAt.current;
+    return elapsed >= interval ? send() : (clearTimeout(pending.current), pending.current = setTimeout(send, interval - elapsed)), () => clearTimeout(pending.current);
+  }, t8 = [location2, interval, sanityInstance, resource], $[27] = interval, $[28] = location2, $[29] = resource, $[30] = sanityInstance, $[31] = t7, $[32] = t8) : (t7 = $[31], t8 = $[32]), useEffect(t7, t8);
+  let t10, t9;
+  $[33] !== resource || $[34] !== sanityInstance ? (t9 = () => () => {
+    reportPresence(sanityInstance, {
+      ...resource ? {
+        resource
+      } : {},
+      locations: []
+    });
+  }, t10 = [sanityInstance, resource], $[33] = resource, $[34] = sanityInstance, $[35] = t10, $[36] = t9) : (t10 = $[35], t9 = $[36]), useEffect(t9, t10);
+}
 function useDocumentProjection(t0) {
   const $ = c(13);
   let docHandle, projection, ref;
@@ -2015,7 +2146,7 @@ function useUsers(options) {
     loadMore
   }, $[20] = data, $[21] = hasMore, $[22] = isPending, $[23] = loadMore, $[24] = t8) : t8 = $[24], t8;
 }
-var version = "2.18.0";
+var version = "2.19.0";
 function getEnv(key) {
   if (typeof import.meta < "u" && import.meta.env)
     return import.meta.env[key];
@@ -2073,10 +2204,12 @@ export {
   usePaginatedDocuments,
   usePerspective,
   usePresence,
+  usePresenceForDocument,
   useProject,
   useProjects,
   useQuery,
   useRecordDocumentHistoryEvent,
+  useReportPresence,
   useResource,
   useSanityInstance,
   useStudioWorkspacesByProjectIdDataset,