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

package/src/hooks/comlink/useFrameConnection.ts

@@ -0,0 +1,111 @@
+import {
+  type FrameMessage,
+  getOrCreateChannel,
+  getOrCreateController,
+  releaseChannel,
+  type WindowMessage,
+} from '@sanity/sdk'
+import {useCallback, useEffect, useMemo} from 'react'
+
+import {useSanityInstance} from '../context/useSanityInstance'
+
+/**
+ * @public
+ */
+export type FrameMessageHandler<TWindowMessage extends WindowMessage> = (
+  event: TWindowMessage['data'],
+) => TWindowMessage['response'] | Promise<TWindowMessage['response']>
+
+/**
+ * @public
+ */
+export interface UseFrameConnectionOptions<TWindowMessage extends WindowMessage> {
+  name: string
+  connectTo: string
+  targetOrigin: string
+  onMessage?: Record<string, FrameMessageHandler<TWindowMessage>>
+}
+
+/**
+ * @public
+ */
+export interface FrameConnection<TFrameMessage extends FrameMessage> {
+  connect: (frameWindow: Window) => () => void // Return cleanup function
+  sendMessage: <T extends TFrameMessage['type']>(
+    ...params: Extract<TFrameMessage, {type: T}>['data'] extends undefined
+      ? [type: T]
+      : [type: T, data: Extract<TFrameMessage, {type: T}>['data']]
+  ) => void
+}
+
+/**
+ * @public
+ */
+export function useFrameConnection<
+  TFrameMessage extends FrameMessage,
+  TWindowMessage extends WindowMessage,
+>(options: UseFrameConnectionOptions<TWindowMessage>): FrameConnection<TFrameMessage> {
+  const {onMessage, targetOrigin, name, connectTo} = options
+  const instance = useSanityInstance()
+
+  const controller = useMemo(
+    () => getOrCreateController(instance, targetOrigin),
+    [instance, targetOrigin],
+  )
+
+  const channel = useMemo(
+    () =>
+      getOrCreateChannel(instance, {
+        name,
+        connectTo,
+      }),
+    [instance, name, connectTo],
+  )
+
+  useEffect(() => {
+    if (!channel || !onMessage) return
+
+    const unsubscribers: Array<() => void> = []
+
+    Object.entries(onMessage).forEach(([type, handler]) => {
+      const unsubscribe = channel.on(type, handler)
+      unsubscribers.push(unsubscribe)
+    })
+
+    return () => {
+      unsubscribers.forEach((unsub) => unsub())
+    }
+  }, [channel, onMessage])
+
+  const connect = useCallback(
+    (frameWindow: Window) => {
+      const removeTarget = controller?.addTarget(frameWindow)
+      return () => {
+        removeTarget?.()
+      }
+    },
+    [controller],
+  )
+
+  const sendMessage = useCallback(
+    <T extends TFrameMessage['type']>(
+      type: T,
+      data?: Extract<TFrameMessage, {type: T}>['data'],
+    ) => {
+      channel?.post(type, data)
+    },
+    [channel],
+  )
+
+  // cleanup channel on unmount
+  useEffect(() => {
+    return () => {
+      releaseChannel(instance, name)
+    }
+  }, [name, instance])
+
+  return {
+    connect,
+    sendMessage,
+  }
+}

package/src/hooks/comlink/useWindowConnection.test.ts

@@ -0,0 +1,94 @@
+import {type Message, type Node} from '@sanity/comlink'
+import {getOrCreateNode, releaseNode} from '@sanity/sdk'
+import {beforeEach, describe, expect, it, vi} from 'vitest'
+
+import {renderHook} from '../../../test/test-utils'
+import {useWindowConnection} from './useWindowConnection'
+
+vi.mock(import('@sanity/sdk'), async (importOriginal) => {
+  const actual = await importOriginal()
+  return {
+    ...actual,
+    getOrCreateNode: vi.fn(),
+    createNode: vi.fn(),
+    releaseNode: vi.fn(),
+  }
+})
+interface TestMessage {
+  type: 'TEST_MESSAGE'
+  data: {someData: string}
+}
+
+interface AnotherMessage {
+  type: 'ANOTHER_MESSAGE'
+  data: {otherData: number}
+}
+
+type TestMessages = TestMessage | AnotherMessage
+
+function createMockNode() {
+  return {
+    // return unsubscribe function
+    on: vi.fn(() => () => {}),
+    post: vi.fn(),
+    stop: vi.fn(),
+  } as unknown as Node<Message, Message>
+}
+
+describe('useWindowConnection', () => {
+  let node: Node<Message, Message>
+
+  beforeEach(() => {
+    node = createMockNode()
+
+    vi.mocked(getOrCreateNode).mockReturnValue(node as unknown as Node<Message, Message>)
+  })
+
+  it('should register message handlers', () => {
+    const mockHandler = vi.fn()
+    const mockData = {someData: 'test'}
+
+    renderHook(() =>
+      useWindowConnection<TestMessages, TestMessages>({
+        name: 'test',
+        connectTo: 'window',
+        onMessage: {
+          TEST_MESSAGE: mockHandler,
+          ANOTHER_MESSAGE: vi.fn(),
+        },
+      }),
+    )
+
+    const onCallback = vi.mocked(node.on).mock.calls[0][1]
+    onCallback(mockData)
+
+    expect(mockHandler).toHaveBeenCalledWith(mockData)
+  })
+
+  it('should send messages through the node', () => {
+    const {result} = renderHook(() =>
+      useWindowConnection<TestMessages, TestMessages>({
+        name: 'test',
+        connectTo: 'window',
+      }),
+    )
+
+    result.current.sendMessage('TEST_MESSAGE', {someData: 'test'})
+    expect(node.post).toHaveBeenCalledWith('TEST_MESSAGE', {someData: 'test'})
+
+    result.current.sendMessage('ANOTHER_MESSAGE', {otherData: 123})
+    expect(node.post).toHaveBeenCalledWith('ANOTHER_MESSAGE', {otherData: 123})
+  })
+
+  it('should cleanup on unmount', () => {
+    const {unmount} = renderHook(() =>
+      useWindowConnection<TestMessages, TestMessages>({
+        name: 'test',
+        connectTo: 'window',
+      }),
+    )
+
+    unmount()
+    expect(releaseNode).toHaveBeenCalled()
+  })
+})

package/src/hooks/comlink/useWindowConnection.ts

@@ -0,0 +1,82 @@
+import {type FrameMessage, getOrCreateNode, releaseNode, type WindowMessage} from '@sanity/sdk'
+import {useCallback, useEffect, useMemo} from 'react'
+
+import {useSanityInstance} from '../context/useSanityInstance'
+
+/**
+ * @public
+ */
+export type WindowMessageHandler<TFrameMessage extends FrameMessage> = (
+  event: TFrameMessage['data'],
+) => TFrameMessage['response']
+
+/**
+ * @public
+ */
+export interface UseWindowConnectionOptions<TMessage extends FrameMessage> {
+  name: string
+  connectTo: string
+  onMessage?: Record<TMessage['type'], WindowMessageHandler<TMessage>>
+}
+
+/**
+ * @public
+ */
+export interface WindowConnection<TMessage extends WindowMessage> {
+  sendMessage: <TType extends TMessage['type']>(
+    type: TType,
+    data?: Extract<TMessage, {type: TType}>['data'],
+  ) => void
+}
+
+/**
+ * @public
+ */
+export function useWindowConnection<
+  TWindowMessage extends WindowMessage,
+  TFrameMessage extends FrameMessage,
+>(options: UseWindowConnectionOptions<TFrameMessage>): WindowConnection<TWindowMessage> {
+  const {name, onMessage, connectTo} = options
+  const instance = useSanityInstance()
+
+  const node = useMemo(
+    () => getOrCreateNode(instance, {name, connectTo}),
+    [instance, name, connectTo],
+  )
+
+  useEffect(() => {
+    if (!onMessage) return
+
+    const unsubscribers: Array<() => void> = []
+
+    Object.entries(onMessage).forEach(([type, handler]) => {
+      const unsubscribe = node.on(type, handler as WindowMessageHandler<TFrameMessage>)
+      unsubscribers.push(unsubscribe)
+    })
+
+    return () => {
+      unsubscribers.forEach((unsub) => unsub())
+    }
+  }, [node, onMessage])
+
+  const sendMessage = useCallback(
+    <TType extends WindowMessage['type']>(
+      type: TType,
+      data?: Extract<WindowMessage, {type: TType}>['data'],
+    ) => {
+      node?.post(type, data)
+    },
+    [node],
+  )
+
+  // cleanup node on unmount
+  useEffect(() => {
+    return () => {
+      releaseNode(instance, name)
+    }
+  }, [instance, name])
+
+  return {
+    sendMessage,
+  }
+}

package/src/hooks/context/useSanityInstance.test.tsx

@@ -3,7 +3,7 @@ import {renderHook} from '@testing-library/react'
 import React from 'react'
 import {describe, expect, it, vi} from 'vitest'
 
-import {SanityProvider} from '../../components/context/SanityProvider'
+import {SanityProvider} from '../../context/SanityProvider'
 import {useSanityInstance} from './useSanityInstance'
 
 describe('useSanityInstance', () => {

package/src/hooks/context/useSanityInstance.ts

@@ -1,7 +1,7 @@
-import type {SanityInstance} from '@sanity/sdk'
+import {type SanityInstance} from '@sanity/sdk'
 import {useContext} from 'react'
 
-import {SanityInstanceContext} from '../../components/context/SanityProvider'
+import {SanityInstanceContext} from '../../context/SanityProvider'
 
 /**
  * Hook that provides the current Sanity instance from the context.

package/src/hooks/documentCollection/useDocuments.ts

@@ -6,11 +6,16 @@ import {useSanityInstance} from '../context/useSanityInstance'
 /**
  * @public
  */
-export interface UseDocuments {
+export interface DocumentCollection {
+  /** Retrieve more documents matching the provided options */
   loadMore: () => void
+  /** The retrieved document handles of the documents matching the provided options */
   results: DocumentHandle[]
+  /** Whether a retrieval of documents is in flight */
   isPending: boolean
+  /** Whether more documents exist that match the provided options than have been retrieved */
   hasMore: boolean
+  /** The total number of documents in the collection */
   count: number
 }
 
@@ -24,14 +29,56 @@ const STABLE_EMPTY = {
 }
 
 /**
- * Hook to get the list of documents for specified options
- *
  * @public
  *
- * @param options - options for the document list
- * @returns result of the document list and function to load more
+ * The `useDocuments` hook retrieves and provides access to a live collection of documents, optionally filtered, sorted, and matched to a given Content Lake perspective.
+ * Because the returned document collection is live, the results will update in real time until the component invoking the hook is unmounted.
+ *
+ * @param options - Options for narrowing and sorting the document collection
+ * @returns The collection of documents matching the provided options (if any), as well as properties describing the collection and a function to load more.
+ *
+ * @example Retrieving all documents of type 'movie'
+ * ```
+ * const { results, isPending } = useDocuments({ filter: '_type == "movie"' })
+ *
+ * return (
+ *   <div>
+ *     <h1>Movies</h1>
+ *     {results && (
+ *       <ul>
+ *         {results.map(movie => (<li key={movie._id}>…</li>))}
+ *       </ul>
+ *     )}
+ *     {isPending && <div>Loading movies…</div>}
+ *   </div>
+ * )
+ * ```
+ *
+ * @example Retrieving all movies released since 1980, sorted by release date
+ * ```
+ * const { results } = useDocuments({
+ *   filter: '_type == "movie" && releaseDate >= "1980-01-01"',
+ *   sort: [
+ *     {
+ *       field: 'releaseDate',
+ *       sort: 'asc',
+ *     },
+ *   ],
+ * })
+ *
+ * return (
+ *   <div>
+ *      <h1>Movies released since 1980</h1>
+ *      {results && (
+ *        <ol>
+ *          {results.map(movie => (<li key={movie._id}>…</li>))}
+ *        </ol>
+ *     )}
+ *   </div>
+ * )
+ * ```
  */
-export function useDocuments(options: DocumentListOptions = {}): UseDocuments {
+export function useDocuments(options: DocumentListOptions = {}): DocumentCollection {
   const instance = useSanityInstance()
 
   // NOTE: useState is used because it guaranteed to return a stable reference

package/src/hooks/helpers/createCallbackHook.tsx

@@ -1,4 +1,4 @@
-import type {SanityInstance} from '@sanity/sdk'
+import {type SanityInstance} from '@sanity/sdk'
 import {useCallback} from 'react'
 
 import {useSanityInstance} from '../context/useSanityInstance'

package/src/hooks/helpers/createStateSourceHook.tsx

@@ -1,4 +1,4 @@
-import type {SanityInstance, StateSource} from '@sanity/sdk'
+import {type SanityInstance, type StateSource} from '@sanity/sdk'
 import {useMemo, useSyncExternalStore} from 'react'
 
 import {useSanityInstance} from '../context/useSanityInstance'

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

@@ -1,7 +1,7 @@
 import {type DocumentHandle, getPreviewState, type PreviewValue, resolvePreview} from '@sanity/sdk'
 import {act, render, screen} from '@testing-library/react'
 import {Suspense, useState} from 'react'
-import type {Mock} from 'vitest'
+import {type Mock} from 'vitest'
 
 import {usePreview} from './usePreview'
 
@@ -45,13 +45,13 @@ const mockDocument: DocumentHandle = {
 
 function TestComponent({document}: {document: DocumentHandle}) {
   const [ref, setRef] = useState<HTMLElement | null>(null)
-  const [previewValue, pending] = usePreview({document, ref})
+  const {results, isPending} = usePreview({document, ref})
 
   return (
     <div ref={setRef}>
-      <h1>{previewValue.title}</h1>
-      <p>{previewValue.subtitle}</p>
-      {pending && <div>Pending...</div>}
+      <h1>{results?.title}</h1>
+      <p>{results?.subtitle}</p>
+      {isPending && <div>Pending...</div>}
     </div>
   )
 }
@@ -74,7 +74,10 @@ describe('usePreview', () => {
 
   test('it only subscribes when element is visible', async () => {
     // Setup initial state
-    getCurrent.mockReturnValue([{title: 'Initial Title', subtitle: 'Initial Subtitle'}, false])
+    getCurrent.mockReturnValue({
+      results: {title: 'Initial Title', subtitle: 'Initial Subtitle'},
+      isPending: false,
+    })
     const eventsUnsubscribe = vi.fn()
     subscribe.mockImplementation(() => eventsUnsubscribe)
 
@@ -135,7 +138,10 @@ describe('usePreview', () => {
     await act(async () => {
       intersectionObserverCallback([{isIntersecting: true} as IntersectionObserverEntry])
       await resolvePromise
-      getCurrent.mockReturnValue([{title: 'Resolved Title', subtitle: 'Resolved Subtitle'}, false])
+      getCurrent.mockReturnValue({
+        results: {title: 'Resolved Title', subtitle: 'Resolved Subtitle'},
+        isPending: false,
+      })
       subscriber?.()
     })
 
@@ -149,7 +155,10 @@ describe('usePreview', () => {
     // @ts-expect-error - Intentionally removing IntersectionObserver
     delete window.IntersectionObserver
 
-    getCurrent.mockReturnValue([{title: 'Fallback Title', subtitle: 'Fallback Subtitle'}, false])
+    getCurrent.mockReturnValue({
+      results: {title: 'Fallback Title', subtitle: 'Fallback Subtitle'},
+      isPending: false,
+    })
     subscribe.mockImplementation(() => vi.fn())
 
     render(

package/src/hooks/preview/usePreview.tsx

@@ -15,10 +15,55 @@ export interface UsePreviewOptions {
 /**
  * @alpha
  */
-export function usePreview({
-  document: {_id, _type},
-  ref,
-}: UsePreviewOptions): [PreviewValue, boolean] {
+export interface UsePreviewResults {
+  /** The results of resolving the document’s preview values */
+  results: PreviewValue
+  /** Whether the resolution of the preview values is pending */
+  isPending: boolean
+}
+
+/**
+ * @alpha
+ *
+ * The `usePreview` hook takes a document (via a `DocumentHandle`) and returns its resolved preview values,
+ * including the document’s `title`, `subtitle`, `media`, and `status`. These values are live and will update in realtime.
+ * To reduce unnecessary network requests for resolving the preview values, an optional `ref` can be passed to the hook so that preview
+ * resolution will only occur if the `ref` is intersecting the current viewport.
+ *
+ * @param options - The document handle for the document you want to resolve preview values for, and an optional ref
+ * @returns The preview values for the given document and a boolean to indicate whether the resolution is pending
+ *
+ * @example Combining with useDocuments to render a collection of document previews
+ * ```
+ * // PreviewComponent.jsx
+ * export default function PreviewComponent({ document }) {
+ *   const { results: { title, subtitle, media }, isPending } = usePreview({ document })
+ *   return isPending ? 'Loading…' : (
+ *     <article>
+ *       {media?.type === 'image-asset' ? <img src={media.url} alt='' /> : ''}
+ *       <h2>{title}</h2>
+ *       <p>{subtitle}</p>
+ *     </article>
+ *   )
+ * }
+ *
+ * // DocumentList.jsx
+ * const { results, isPending } = useDocuments({ filter: '_type == "movie"' })
+ * return (
+ *   <div>
+ *     <h1>Movies</h1>
+ *     <ul>
+ *       {isPending ? 'Loading…' : results.map(movie => (
+ *         <li key={movie._id}>
+ *           <PreviewComponent document={movie} />
+ *         </li>
+ *       ))}
+ *     </ul>
+ *   </div>
+ * )
+ * ```
+ */
+export function usePreview({document: {_id, _type}, ref}: UsePreviewOptions): UsePreviewResults {
   const instance = useSanityInstance()
 
   const stateSource = useMemo(
@@ -60,9 +105,9 @@ export function usePreview({
 
   // Create getSnapshot function to return current state
   const getSnapshot = useCallback(() => {
-    const previewTuple = stateSource.getCurrent()
-    if (!previewTuple[0]) throw resolvePreview(instance, {document: {_id, _type}})
-    return previewTuple as [PreviewValue, boolean]
+    const currentState = stateSource.getCurrent()
+    if (currentState.results === null) throw resolvePreview(instance, {document: {_id, _type}})
+    return currentState as UsePreviewResults
   }, [_id, _type, instance, stateSource])
 
   return useSyncExternalStore(subscribe, getSnapshot)

package/src/vite-env.d.ts

@@ -0,0 +1,10 @@
+/// <reference types="vite/client" />
+/// <reference types="vite/types/importMeta.d.ts" />
+
+interface ImportMetaEnv {
+  DEV: boolean
+}
+
+interface ImportMeta {
+  readonly env: ImportMetaEnv
+}

package/dist/assets/bundle-CcAyERuZ.css

@@ -1,11 +0,0 @@
-@import './paramour.css';
-
-body {
-  color-scheme: light dark;
-  color: light-dark(var(--gray-1), var(--gray-10));
-  background-color: light-dark(var(--gray-11), var(--gray-1));
-}
-
-.container-inline {
-  container-type: inline-size;
-}

package/src/components/DocumentGridLayout/DocumentGridLayout.stories.tsx

@@ -1,113 +0,0 @@
-import {type Meta, type StoryObj} from '@storybook/react'
-
-import {DocumentPreviewLayout} from '../DocumentPreviewLayout/DocumentPreviewLayout.tsx'
-import {DocumentGridLayout} from './DocumentGridLayout.tsx'
-
-const meta: Meta<typeof DocumentGridLayout> = {
-  title: 'DocumentGridLayout',
-  component: DocumentGridLayout,
-}
-
-export default meta
-type Story = StoryObj<typeof meta>
-
-const mockDocs = [
-  {id: '1', title: 'Just a title', url: '#', docType: 'article', status: 'published'},
-  {
-    id: '2',
-    title: 'A title, but also',
-    subtitle: 'A subtitle',
-    docType: 'article',
-    status: 'draft',
-    media: {
-      type: 'image-asset',
-      url: 'https://picsum.photos/75/75',
-    },
-  },
-  {
-    id: '3',
-    title: 'Hello World',
-    subtitle: 'What a nice list I get to live in',
-    docType: 'image',
-    status: 'published',
-    media: {
-      type: 'image-asset',
-      url: 'https://picsum.photos/80/80',
-    },
-  },
-  {
-    id: '4',
-    title: 'I’ve been selected',
-    subtitle: 'I feel special',
-    selected: true,
-    docType: 'video',
-    status: 'draft',
-    media: {
-      type: 'image-asset',
-      url: 'https://picsum.photos/100/100',
-    },
-  },
-  {
-    id: '5',
-    title: 'A very long title that at some point might get truncated if it goes for long enough',
-    subtitle:
-      'Along with a subtitle that is quite long as well, in order to demonstrate the truncation of its text',
-    docType: 'audio',
-    status: 'published',
-    media: {
-      type: 'image-asset',
-      url: 'https://picsum.photos/75/75',
-    },
-  },
-  {
-    id: '6',
-    title: 'Hello World',
-    subtitle: 'What a nice list I get to live in',
-    docType: 'pdf',
-    status: 'published',
-    media: {
-      type: 'image-asset',
-      url: 'https://picsum.photos/75/75',
-    },
-  },
-  {id: '7', title: 'Just a title', url: '#', docType: 'note', status: 'published,'},
-  {
-    id: '8',
-    title: 'A title, but also',
-    subtitle: 'A subtitle',
-    docType: 'document',
-    status: 'draft',
-  },
-  {
-    id: '9',
-    title: 'Hello World',
-    subtitle: 'What a nice list I get to live in',
-    docType: 'biography',
-    status: 'published',
-    media: {
-      type: 'image-asset',
-      url: 'https://picsum.photos/200/200',
-    },
-  },
-]
-
-export const Default: Story = {
-  render: () => {
-    return (
-      <DocumentGridLayout>
-        {mockDocs.map((doc) => (
-          <li key={doc.id}>
-            <DocumentPreviewLayout
-              title={doc.title}
-              subtitle={doc.subtitle}
-              media={doc.media}
-              selected={doc.selected}
-              docType={doc.docType}
-              status={doc.status}
-            />
-          </li>
-        ))}
-      </DocumentGridLayout>
-    )
-  },
-}