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

package/src/_exports/hooks.ts

@@ -17,5 +17,9 @@ export {
   type WindowMessageHandler,
 } from '../hooks/comlink/useWindowConnection'
 export {useSanityInstance} from '../hooks/context/useSanityInstance'
-export {type UseDocuments, useDocuments} from '../hooks/documentCollection/useDocuments'
-export {usePreview, type UsePreviewOptions} from '../hooks/preview/usePreview'
+export {type DocumentCollection, useDocuments} from '../hooks/documentCollection/useDocuments'
+export {
+  usePreview,
+  type UsePreviewOptions,
+  type UsePreviewResults,
+} from '../hooks/preview/usePreview'

package/src/components/auth/AuthBoundary.test.tsx

@@ -1,11 +1,10 @@
-import {AuthStateType, createSanityInstance} from '@sanity/sdk'
-import {SanityProvider} from '@sanity/sdk-react/context'
+import {AuthStateType} from '@sanity/sdk'
 import {useAuthState} from '@sanity/sdk-react/hooks'
-import {render, screen, waitFor} from '@testing-library/react'
-import React from 'react'
+import {screen, waitFor} from '@testing-library/react'
 import {beforeEach, describe, expect, it, type MockInstance, vi} from 'vitest'
 
 import {AuthBoundary} from './AuthBoundary'
+import {renderWithWrappers} from './authTestHelpers'
 
 // Mock hooks
 vi.mock('../../hooks/auth/useAuthState', () => ({
@@ -36,11 +35,6 @@ vi.mock('./AuthError', async (importOriginal) => {
   }
 })
 
-const sanityInstance = createSanityInstance({projectId: 'test-project-id', dataset: 'production'})
-const renderWithWrappers = (ui: React.ReactElement) => {
-  return render(<SanityProvider sanityInstance={sanityInstance}>{ui}</SanityProvider>)
-}
-
 describe('AuthBoundary', () => {
   let consoleErrorSpy: MockInstance
   beforeEach(() => {
@@ -60,7 +54,7 @@ describe('AuthBoundary', () => {
     renderWithWrappers(<AuthBoundary>Protected Content</AuthBoundary>)
 
     // The login screen should show "Choose login provider" by default
-    expect(screen.getByText('Choose login provider')).toBeInTheDocument()
+    expect(screen.getByText('Choose login provider:')).toBeInTheDocument()
     expect(screen.queryByText('Protected Content')).not.toBeInTheDocument()
   })
 

package/src/components/auth/Login.test.tsx

@@ -1,9 +1,7 @@
-import {createSanityInstance} from '@sanity/sdk'
-import {SanityProvider} from '@sanity/sdk-react/context'
-import {render, screen} from '@testing-library/react'
-import React from 'react'
+import {screen} from '@testing-library/react'
 import {describe, expect, it, vi} from 'vitest'
 
+import {renderWithWrappers} from './authTestHelpers'
 import {Login} from './Login'
 
 vi.mock('../../hooks/auth/useLoginUrls', () => ({
@@ -13,15 +11,10 @@ vi.mock('../../hooks/auth/useLoginUrls', () => ({
   ]),
 }))
 
-const sanityInstance = createSanityInstance({projectId: 'test-project-id', dataset: 'production'})
-const renderWithWrappers = (ui: React.ReactElement) => {
-  return render(<SanityProvider sanityInstance={sanityInstance}>{ui}</SanityProvider>)
-}
-
 describe('Login', () => {
   it('renders login providers', () => {
     renderWithWrappers(<Login />)
-    expect(screen.getByText('Choose login provider')).toBeInTheDocument()
+    expect(screen.getByText('Choose login provider:')).toBeInTheDocument()
     expect(screen.getByRole('link', {name: 'Provider A'})).toHaveAttribute(
       'href',
       'https://provider-a.com/auth',

package/src/components/auth/Login.tsx

@@ -1,3 +1,4 @@
+import {Box, Button, Flex, Heading, Spinner, Stack} from '@sanity/ui'
 import {type JSX, Suspense} from 'react'
 
 import {useLoginUrls} from '../../hooks/auth/useLoginUrls'
@@ -8,17 +9,26 @@ import {LoginLayout, type LoginLayoutProps} from './LoginLayout'
  * Renders a list of login options with a loading fallback while providers load.
  *
  * @alpha
+ * @internal
  */
 export function Login({header, footer}: LoginLayoutProps): JSX.Element {
   return (
     <LoginLayout header={header} footer={footer}>
-      <div className="sc-login">
-        <h1 className="sc-login__title">Choose login provider</h1>
+      <Heading as="h6" align="center">
+        Choose login provider:
+      </Heading>
 
-        <Suspense fallback={<div className="sc-login__loading">Loading…</div>}>
-          <Providers />
-        </Suspense>
-      </div>
+      <Suspense
+        fallback={
+          <Box padding={5}>
+            <Flex align="center" justify="center">
+              <Spinner />
+            </Flex>
+          </Box>
+        }
+      >
+        <Providers />
+      </Suspense>
     </LoginLayout>
   )
 }
@@ -27,12 +37,18 @@ function Providers() {
   const loginUrls = useLoginUrls()
 
   return (
-    <div className="sc-login-providers">
+    <Stack space={3} marginY={5}>
       {loginUrls.map(({title, url}) => (
-        <a key={url} href={url}>
-          {title}
-        </a>
+        <Button
+          key={url}
+          as="a"
+          href={url}
+          mode="ghost"
+          text={title}
+          textAlign="center"
+          fontSize={2}
+        ></Button>
       ))}
-    </div>
+    </Stack>
   )
 }

package/src/components/auth/LoginCallback.test.tsx

@@ -1,14 +1,7 @@
-import {createSanityInstance} from '@sanity/sdk'
-import {SanityProvider} from '@sanity/sdk-react/context'
-import {render, screen, waitFor} from '@testing-library/react'
-import React from 'react'
+import {screen, waitFor} from '@testing-library/react'
 import {afterAll, beforeAll, beforeEach, describe, expect, it, vi} from 'vitest'
 
-const sanityInstance = createSanityInstance({projectId: 'test-project-id', dataset: 'production'})
-
-const renderWithWrappers = (ui: React.ReactElement) => {
-  return render(<SanityProvider sanityInstance={sanityInstance}>{ui}</SanityProvider>)
-}
+import {renderWithWrappers} from './authTestHelpers'
 
 // Mock `useHandleCallback`
 vi.mock('../../hooks/auth/useHandleCallback', () => ({

package/src/components/auth/LoginCallback.tsx

@@ -1,3 +1,4 @@
+import {Flex, Heading, Spinner} from '@sanity/ui'
 import {useEffect} from 'react'
 
 import {useHandleCallback} from '../../hooks/auth/useHandleCallback'
@@ -27,10 +28,12 @@ export function LoginCallback({header, footer}: LoginLayoutProps): React.ReactNo
 
   return (
     <LoginLayout header={header} footer={footer}>
-      <div className="sc-login-callback">
-        <h1 className="sc-login-callback__title">Logging you in…</h1>
-        <div className="sc-login-callback__loading">Loading…</div>
-      </div>
+      <Heading as="h6" align="center">
+        Logging you in…
+      </Heading>
+      <Flex paddingY={5} align="center" justify="center">
+        <Spinner />
+      </Flex>
     </LoginLayout>
   )
 }

package/src/components/auth/LoginError.test.tsx

@@ -1,22 +1,14 @@
-import {createSanityInstance} from '@sanity/sdk'
-import {SanityProvider} from '@sanity/sdk-react/context'
-import {fireEvent, render, screen, waitFor} from '@testing-library/react'
-import React from 'react'
+import {fireEvent, screen, waitFor} from '@testing-library/react'
 import {describe, expect, it, vi} from 'vitest'
 
 import {AuthError} from './AuthError'
+import {renderWithWrappers} from './authTestHelpers'
 import {LoginError} from './LoginError'
 
 vi.mock('../../hooks/auth/useLogOut', () => ({
   useLogOut: vi.fn(() => async () => {}),
 }))
 
-const sanityInstance = createSanityInstance({projectId: 'test-project-id', dataset: 'production'})
-
-const renderWithWrappers = (ui: React.ReactElement) => {
-  return render(<SanityProvider sanityInstance={sanityInstance}>{ui}</SanityProvider>)
-}
-
 describe('LoginError', () => {
   it('shows authentication error and retry button', async () => {
     const mockReset = vi.fn()

package/src/components/auth/LoginError.tsx

@@ -1,3 +1,4 @@
+import {Button, Heading, Stack, Text} from '@sanity/ui'
 import {useCallback} from 'react'
 import {type FallbackProps} from 'react-error-boundary'
 
@@ -32,18 +33,13 @@ export function LoginError({
 
   return (
     <LoginLayout header={header} footer={footer}>
-      <div className="sc-login-error">
-        <div className="sc-login-error__content">
-          <h2 className="sc-login-error__title">Authentication Error</h2>
-          <p className="sc-login-error__description">
-            Please try again or contact support if the problem persists.
-          </p>
-        </div>
-
-        <button className="sc-login-error__button" onClick={handleRetry}>
-          Retry
-        </button>
-      </div>
+      <Stack space={5} marginBottom={5}>
+        <Heading as="h6" align="center">
+          Authentication Error
+        </Heading>
+        <Text align="center">Please try again or contact support if the problem persists.</Text>
+        <Button mode="ghost" onClick={handleRetry} text="Retry" fontSize={2} />
+      </Stack>
     </LoginLayout>
   )
 }

package/src/components/auth/LoginFooter.test.tsx

@@ -1,16 +1,9 @@
-import {createSanityInstance} from '@sanity/sdk'
-import {SanityProvider} from '@sanity/sdk-react/context'
-import {render, screen} from '@testing-library/react'
-import React from 'react'
+import {screen} from '@testing-library/react'
 import {describe, expect, it} from 'vitest'
 
+import {renderWithWrappers} from './authTestHelpers'
 import {LoginFooter} from './LoginFooter'
 
-const sanityInstance = createSanityInstance({projectId: 'test-project-id', dataset: 'production'})
-const renderWithWrappers = (ui: React.ReactElement) => {
-  return render(<SanityProvider sanityInstance={sanityInstance}>{ui}</SanityProvider>)
-}
-
 describe('LoginFooter', () => {
   it('renders footer links', () => {
     renderWithWrappers(<LoginFooter />)

package/src/components/auth/LoginFooter.tsx

@@ -1,5 +1,5 @@
 import {SanityLogo} from '@sanity/logos'
-import {Fragment} from 'react'
+import {Box, Flex, Inline, Text} from '@sanity/ui'
 
 const LINKS = [
   {
@@ -32,20 +32,27 @@ const LINKS = [
  */
 export function LoginFooter(): React.ReactNode {
   return (
-    <div className="sc-login-footer">
-      <SanityLogo className="sc-login-footer__logo" />
+    <Box>
+      <Flex justify="center">
+        <SanityLogo />
+      </Flex>
 
-      <ul className="sc-login-footer__links">
-        {LINKS.map((link) => (
-          <Fragment key={link.title}>
-            <li className="sc-login-footer__link">
-              <a href={link.url} target="_blank" rel="noopener noreferrer">
+      <Flex justify="center">
+        <Inline space={2} paddingY={3}>
+          {LINKS.map((link) => (
+            <Text size={0} key={link.url}>
+              <a
+                href={link.url}
+                target="_blank"
+                rel="noopener noreferrer"
+                style={{color: 'inherit'}}
+              >
                 {link.title}
               </a>
-            </li>
-          </Fragment>
-        ))}
-      </ul>
-    </div>
+            </Text>
+          ))}
+        </Inline>
+      </Flex>
+    </Box>
   )
 }

package/src/components/auth/LoginLayout.test.tsx

@@ -1,16 +1,9 @@
-import {createSanityInstance} from '@sanity/sdk'
-import {SanityProvider} from '@sanity/sdk-react/context'
-import {render, screen} from '@testing-library/react'
-import React from 'react'
+import {screen} from '@testing-library/react'
 import {describe, expect, it} from 'vitest'
 
+import {renderWithWrappers} from './authTestHelpers'
 import {LoginLayout} from './LoginLayout'
 
-const sanityInstance = createSanityInstance({projectId: 'test-project-id', dataset: 'production'})
-const renderWithWrappers = (ui: React.ReactElement) => {
-  return render(<SanityProvider sanityInstance={sanityInstance}>{ui}</SanityProvider>)
-}
-
 describe('LoginLayout', () => {
   it('renders header, children, and footer', () => {
     renderWithWrappers(

package/src/components/auth/LoginLayout.tsx

@@ -1,7 +1,10 @@
+import {Card, Container} from '@sanity/ui'
+
 import {LoginFooter} from './LoginFooter'
 
 /**
  * @alpha
+ * @internal
  */
 export interface LoginLayoutProps {
   /** Optional header content rendered at top of card */
@@ -54,16 +57,14 @@ export function LoginLayout({
   header,
 }: LoginLayoutProps): React.ReactNode {
   return (
-    <div className="sc-login-layout">
-      <div className="sc-login-layout__container">
-        <div className="sc-login-layout__card">
-          {header && <div className="sc-login-layout__card-header">{header}</div>}
+    <Container width={0}>
+      <Card shadow={1} radius={2} padding={4}>
+        {header && header}
 
-          {children && <div className="sc-login-layout__card-body">{children}</div>}
-        </div>
+        {children && children}
 
         {footer}
-      </div>
-    </div>
+      </Card>
+    </Container>
   )
 }

package/src/components/auth/authTestHelpers.tsx

@@ -0,0 +1,18 @@
+import {createSanityInstance} from '@sanity/sdk'
+import {ThemeProvider} from '@sanity/ui'
+import {buildTheme} from '@sanity/ui/theme'
+import {render, type RenderResult} from '@testing-library/react'
+import React from 'react'
+
+import {SanityProvider} from '../../context/SanityProvider'
+
+const sanityInstance = createSanityInstance({projectId: 'test-project-id', dataset: 'production'})
+const theme = buildTheme()
+
+export const renderWithWrappers = (ui: React.ReactElement): RenderResult => {
+  return render(
+    <SanityProvider sanityInstance={sanityInstance}>
+      <ThemeProvider theme={theme}>{ui}</ThemeProvider>
+    </SanityProvider>,
+  )
+}

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/preview/usePreview.test.tsx

@@ -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)