@sanity/sdk-react 0.0.0-alpha.19 → 0.0.0-alpha.20

package/README.md

@@ -26,7 +26,7 @@ Here's how to implement your Sanity application:
 1. Create a new React TypeScript project using the Sanity template
 
 ```bash
-pnpx sanity@latest init --template core-app
+pnpx sanity@latest init --template app-quickstart
 cd my-content-os-app
 ```
 

package/dist/index.d.ts

@@ -432,6 +432,11 @@ declare type ClientReturn<
   Fallback = Any,
 > = GroqString extends keyof SanityQueries ? SanityQueries[GroqString] : Fallback
 
+/**
+ * @public
+ */
+export declare type ComlinkStatus = 'idle' | 'handshaking' | 'connected' | 'disconnected'
+
 /** @public */
 declare interface ContentSourceMap {
   mappings: ContentSourceMapMappings
@@ -827,7 +832,6 @@ export declare interface FrameConnection<TFrameMessage extends FrameMessage> {
           >['data'],
         ]
   ) => void
-  status: Status
 }
 
 /** @public */
@@ -1139,6 +1143,11 @@ declare interface ManageFavorite {
   isConnected: boolean
 }
 
+/**
+ * @public
+ */
+declare type MessageData = Record<string, unknown> | undefined
+
 /**
  * @internal
  */
@@ -1293,6 +1302,11 @@ declare type MutationSelectionQueryParams = {
   [key: string]: Any
 }
 
+declare interface NavigateToStudioResult {
+  navigateToStudioDocument: () => void
+  isConnected: boolean
+}
+
 /** @internal */
 declare class ObservableAssetsClient {
   #private
@@ -3257,11 +3271,6 @@ export {SortOrderingItem}
 /** @public */
 declare type StackablePerspective = ('published' | 'drafts' | string) & {}
 
-/**
- * @public
- */
-declare type Status = 'idle' | 'handshaking' | 'connected' | 'disconnected'
-
 /** @public */
 declare interface StegaConfig {
   /**
@@ -3308,6 +3317,12 @@ declare type StudioBaseUrl = `/${string}` | `${string}.sanity.studio` | `https:/
 /** @alpha */
 declare type StudioUrl = StudioBaseUrl | StudioBaseRoute
 
+declare interface StudioWorkspacesResult {
+  workspacesByResourceId: WorkspacesByResourceId
+  error: string | null
+  isConnected: boolean
+}
+
 /** @public */
 declare type SyncTag = `s1:${string}`
 
@@ -3648,6 +3663,26 @@ declare type UseCurrentUser = {
  */
 export declare const useCurrentUser: UseCurrentUser
 
+/**
+ * @remarks
+ * A React hook that retrieves the dashboard organization ID that is currently selected in the Sanity Dashboard.
+ *
+ * @example
+ * ```tsx
+ * function DashboardComponent() {
+ *   const orgId = useDashboardOrganizationId()
+ *
+ *   if (!orgId) return null
+ *
+ *   return <div>Organization ID: {String(orgId)}</div>
+ * }
+ * ```
+ *
+ * @returns The dashboard organization ID (string | undefined)
+ * @public
+ */
+export declare function useDashboardOrganizationId(): string | undefined
+
 declare type UseDatasets = {
   /**
    *
@@ -3948,6 +3983,7 @@ export declare interface UseFrameConnectionOptions<TWindowMessage extends Window
     ) => void
   }
   heartbeat?: boolean
+  onStatus?: (status: ComlinkStatus) => void
 }
 
 /**
@@ -4120,6 +4156,18 @@ export declare const useLogOut: () => () => Promise<void>
  */
 export declare function useManageFavorite({_id, _type}: DocumentHandle): ManageFavorite
 
+/**
+ * @public
+ * Hook that provides a function to navigate to a studio document.
+ * @param documentHandle - The document handle containing document ID, type, and resource ID
+ * @returns An object containing:
+ * - navigateToStudioDocument - Function that when called will navigate to the studio document
+ * - isConnected - Boolean indicating if connection to Core UI is established
+ */
+export declare function useNavigateToStudioDocument(
+  documentHandle: DocumentHandle,
+): NavigateToStudioResult
+
 /**
  * Retrieves pages of {@link DocumentHandle}s, narrowed by optional filters, text searches, and custom ordering,
  * with support for traditional paginated interfaces. The number of document handles returned per page is customizable,
@@ -4189,21 +4237,21 @@ export declare function usePaginatedList({
  * import {publishDocument} from '@sanity/sdk'
  *
  * export function PublishButton({doc}: {doc: DocumentHandle}) {
- *   const canPublish = usePermissions(publishDocument(doc))
+ *   const publishPermissions = usePermissions(publishDocument(doc))
  *   const applyAction = useApplyActions()
  *
  *   return (
  *     <>
  *       <button
- *         disabled={!canPublish.allowed}
+ *         disabled={!publishPermissions.allowed}
  *         onClick={() => applyAction(publishDocument(doc))}
- *         popoverTarget={`${canPublish.allowed ? undefined : 'publishButtonPopover'}`}
+ *         popoverTarget={`${publishPermissions.allowed ? undefined : 'publishButtonPopover'}`}
  *       >
  *         Publish
  *       </button>
- *       {!canPublish.allowed && (
+ *       {!publishPermissions.allowed && (
  *         <div popover id="publishButtonPopover">
- *           {canPublish.message}
+ *           {publishPermissions.message}
  *         </div>
  *       )}
  *     </>
@@ -4231,7 +4279,7 @@ export declare function usePermissions(
  * ```
  * // PreviewComponent.jsx
  * export default function PreviewComponent({ document }) {
- *   const { results: { title, subtitle, media }, isPending } = usePreview({ document })
+ *   const { data: { title, subtitle, media }, isPending } = usePreview({ document })
  *   return (
  *     <article style={{ opacity: isPending ? 0.5 : 1}}>
  *       {media?.type === 'image-asset' ? <img src={media.url} alt='' /> : ''}
@@ -4242,12 +4290,12 @@ export declare function usePermissions(
  * }
  *
  * // DocumentList.jsx
- * const { results, isPending } = useDocuments({ filter: '_type == "movie"' })
+ * const { data, isPending } = useDocuments({ filter: '_type == "movie"' })
  * return (
  *   <div>
  *     <h1>Movies</h1>
  *     <ul>
- *       {isPending ? 'Loading…' : results.map(movie => (
+ *       {isPending ? 'Loading…' : data.map(movie => (
  *         <li key={movie._id}>
  *           <Suspense fallback='Loading…'>
  *             <PreviewComponent document={movie} />
@@ -4279,7 +4327,7 @@ export declare interface UsePreviewOptions {
  */
 export declare interface UsePreviewResults {
   /** The results of resolving the document’s preview values */
-  results: PreviewValue
+  data: PreviewValue
   /** True when preview values are being refreshed */
   isPending: boolean
 }
@@ -4323,21 +4371,25 @@ export declare const useProject: UseProject
  * @param options - The document handle for the document you want to project values from, the projection string, and an optional ref
  * @returns The projection values for the given document and a boolean to indicate whether the resolution is pending
  *
- * @example Using a projection to display specific document fields
+ * @example Using a projection to render a preview of document
  * ```
  * // ProjectionComponent.jsx
  * export default function ProjectionComponent({ document }) {
  *   const ref = useRef(null)
- *   const { results: { title, description, authors }, isPending } = useProjection({
+ *   const { results: { title, coverImage, authors }, isPending } = useProjection({
  *     document,
- *     projection: '{title, "description": pt::text("description"), "authors": array::join(authors[]->name, ", ")}',
- *     ref
+ *     ref,
+ *     projection: `{
+ *       title,
+ *       'coverImage': cover.asset->url,
+ *       'authors': array::join(authors[]->{'name': firstName + ' ' + lastName + ' '}.name, ', ')
+ *     }`,
  *   })
  *
  *   return (
  *     <article ref={ref} style={{ opacity: isPending ? 0.5 : 1}}>
  *       <h2>{title}</h2>
- *       <p>{description}</p>
+ *       <img src={coverImage} alt={title} />
  *       <p>{authors}</p>
  *     </article>
  *   )
@@ -4350,13 +4402,13 @@ export declare const useProject: UseProject
  * const { data } = useInfiniteList({ filter: '_type == "article"' })
  * return (
  *   <div>
- *     <h1>Articles</h1>
+ *     <h1>Books</h1>
  *     <ul>
- *       {data.map(article => (
- *         <li key={article._id}>
+ *       {data.map(book => (
+ *         <li key={book._id}>
  *           <Suspense fallback='Loading…'>
  *             <ProjectionComponent
- *               document={article}
+ *               document={book}
  *             />
  *           </Suspense>
  *         </li>
@@ -4372,14 +4424,22 @@ export declare function useProjection<TResult extends object>({
   ref,
 }: UseProjectionOptions): UseProjectionResults<TResult>
 
-declare interface UseProjectionOptions {
+/**
+ * @public
+ * @category Types
+ */
+export declare interface UseProjectionOptions {
   document: DocumentHandle
   projection: ValidProjection
   ref?: React.RefObject<unknown>
 }
 
-declare interface UseProjectionResults<TResult extends object> {
-  results: TResult
+/**
+ * @public
+ * @category Types
+ */
+export declare interface UseProjectionResults<TResult extends object> {
+  data: TResult
   isPending: boolean
 }
 
@@ -4465,6 +4525,7 @@ export declare function useQuery<T>(
  * @public
  * Hook for managing document interaction history in Sanity Studio.
  * This hook provides functionality to record document interactions.
+ * @category History
  * @param documentHandle - The document handle containing document ID and type, like `{_id: '123', _type: 'book'}`
  * @returns An object containing:
  * - `recordEvent` - Function to record document interactions
@@ -4520,6 +4581,12 @@ declare class UsersClient {
  */
 export declare const useSanityInstance: (resourceId?: string) => SanityInstance
 
+/**
+ * Hook that fetches studio workspaces and organizes them by projectId:dataset
+ * @internal
+ */
+export declare function useStudioWorkspacesByResourceId(): StudioWorkspacesResult
+
 /**
  *
  * @public
@@ -4594,11 +4661,22 @@ export declare interface UseUsersResult {
 
 /**
  * @internal
+ * Hook to wrap a Comlink node in a React hook.
+ * Our store functionality takes care of the lifecycle of the node,
+ * as well as sharing a single node between invocations if they share the same name.
+ *
+ * Generally not to be used directly, but to be used as a dependency of
+ * Comlink-powered hooks like `useManageFavorite`.
  */
 export declare function useWindowConnection<
   TWindowMessage extends WindowMessage,
   TFrameMessage extends FrameMessage,
->(options: UseWindowConnectionOptions<TFrameMessage>): WindowConnection<TWindowMessage>
+>({
+  name,
+  connectTo,
+  onMessage,
+  onStatus,
+}: UseWindowConnectionOptions<TFrameMessage>): WindowConnection<TWindowMessage>
 
 /**
  * @internal
@@ -4607,6 +4685,7 @@ export declare interface UseWindowConnectionOptions<TMessage extends FrameMessag
   name: string
   connectTo: string
   onMessage?: Record<TMessage['type'], WindowMessageHandler<TMessage>>
+  onStatus?: (status: ComlinkStatus) => void
 }
 
 /**
@@ -4633,7 +4712,15 @@ export declare interface WindowConnection<TMessage extends WindowMessage> {
       }
     >['data'],
   ) => void
-  status: Status
+  fetch: <TResponse>(
+    type: string,
+    data?: MessageData,
+    options?: {
+      signal?: AbortSignal
+      suppressWarnings?: boolean
+      responseTimeout?: number
+    },
+  ) => Promise<TResponse>
 }
 
 /**
@@ -4643,4 +4730,18 @@ export declare type WindowMessageHandler<TFrameMessage extends FrameMessage> = (
   event: TFrameMessage['data'],
 ) => TFrameMessage['response']
 
+declare interface Workspace {
+  name: string
+  title: string
+  basePath: string
+  dataset: string
+  userApplicationId: string
+  url: string
+  _ref: string
+}
+
+declare interface WorkspacesByResourceId {
+  [key: string]: Workspace[]
+}
+
 export {}