@sanity/sdk-react 0.0.0-alpha.21 → 0.0.0-alpha.23

package/src/hooks/users/useUsers.ts

@@ -1,5 +1,13 @@
-import {createUsersStore, type ResourceType, type SanityUser} from '@sanity/sdk'
-import {useCallback, useEffect, useState, useSyncExternalStore} from 'react'
+import {
+  getUsersKey,
+  type GetUsersOptions,
+  getUsersState,
+  loadMoreUsers,
+  parseUsersKey,
+  resolveUsers,
+  type SanityUser,
+} from '@sanity/sdk'
+import {useCallback, useEffect, useMemo, useState, useSyncExternalStore, useTransition} from 'react'
 
 import {useSanityInstance} from '../context/useSanityInstance'
 
@@ -7,34 +15,20 @@ import {useSanityInstance} from '../context/useSanityInstance'
  * @public
  * @category Types
  */
-export interface UseUsersParams {
-  /**
-   * The type of resource to fetch users for.
-   */
-  resourceType: ResourceType
-  /**
-   * The ID of the resource to fetch users for.
-   */
-  resourceId: string
-  /**
-   * The limit of users to fetch.
-   */
-  limit?: number
-}
-
-/**
- * @public
- * @category Types
- */
-export interface UseUsersResult {
+export interface UsersResult {
   /**
    * The users fetched.
    */
-  users: SanityUser[]
+  data: SanityUser[]
   /**
    * Whether there are more users to fetch.
    */
   hasMore: boolean
+
+  /**
+   * Whether a users request is currently in progress
+   */
+  isPending: boolean
   /**
    * Load more users.
    */
@@ -48,60 +42,79 @@ export interface UseUsersResult {
  * Retrieves the users for a given resource (either a project or an organization).
  *
  * @category Users
- * @param params - The resource type and its ID, and the limit of users to fetch
+ * @param params - The resource type, project ID, and the limit of users to fetch
  * @returns A list of users, a boolean indicating whether there are more users to fetch, and a function to load more users
  *
  * @example
  * ```
- * const { users, hasMore, loadMore } = useUsers({
+ * const { data, hasMore, loadMore, isPending } = useUsers({
  *   resourceType: 'organization',
- *   resourceId: 'my-org-id',
- *   limit: 10,
+ *   organizationId: 'my-org-id',
+ *   batchSize: 10,
  * })
  *
  * return (
  *   <div>
- *     {users.map(user => (
+ *     {data.map(user => (
  *       <figure key={user.sanityUserId}>
  *         <img src={user.profile.imageUrl} alt='' />
  *         <figcaption>{user.profile.displayName}</figcaption>
  *         <address>{user.profile.email}</address>
  *       </figure>
  *     ))}
- *     {hasMore && <button onClick={loadMore}>Load More</button>}
+ *     {hasMore && <button onClick={loadMore}>{isPending ? 'Loading...' : 'Load More'</button>}
  *   </div>
  * )
  * ```
  */
-export function useUsers(params: UseUsersParams): UseUsersResult {
-  const instance = useSanityInstance(params.resourceId)
-  const [store] = useState(() => createUsersStore(instance))
+export function useUsers(options?: GetUsersOptions): UsersResult {
+  const instance = useSanityInstance(options)
+  // Use React's useTransition to avoid UI jank when user options change
+  const [isPending, startTransition] = useTransition()
+
+  // Get the unique key for this users request and its options
+  const key = getUsersKey(instance, options)
+  // Use a deferred state to avoid immediate re-renders when the users request changes
+  const [deferredKey, setDeferredKey] = useState(key)
+  // Parse the deferred users key back into users options
+  const deferred = useMemo(() => parseUsersKey(deferredKey), [deferredKey])
+
+  // Create an AbortController to cancel in-flight requests when needed
+  const [ref, setRef] = useState<AbortController>(new AbortController())
 
+  // When the users request or options change, start a transition to update the request
   useEffect(() => {
-    store.setOptions({
-      resourceType: params.resourceType,
-      resourceId: params.resourceId,
-    })
-  }, [params.resourceType, params.resourceId, store])
+    if (key === deferredKey) return
 
-  const subscribe = useCallback(
-    (onStoreChanged: () => void) => {
-      if (store.getState().getCurrent().initialFetchCompleted === false) {
-        store.resolveUsers()
+    startTransition(() => {
+      if (!ref.signal.aborted) {
+        ref.abort()
+        setRef(new AbortController())
       }
-      const unsubscribe = store.getState().subscribe(onStoreChanged)
 
-      return () => {
-        unsubscribe()
-        store.dispose()
-      }
-    },
-    [store],
-  )
+      setDeferredKey(key)
+    })
+  }, [deferredKey, key, ref])
+
+  // Get the state source for this users request from the users store
+  const {getCurrent, subscribe} = useMemo(() => {
+    return getUsersState(instance, deferred)
+  }, [instance, deferred])
+
+  // If data isn't available yet, suspend rendering until it is
+  // This is the React Suspense integration - throwing a promise
+  // will cause React to show the nearest Suspense fallback
+  if (getCurrent() === undefined) {
+    throw resolveUsers(instance, {...deferred, signal: ref.signal})
+  }
 
-  const getSnapshot = useCallback(() => store.getState().getCurrent(), [store])
+  // Subscribe to updates and get the current data
+  // useSyncExternalStore ensures the component re-renders when the data changes
+  const {data, hasMore} = useSyncExternalStore(subscribe, getCurrent)!
 
-  const {users, hasMore} = useSyncExternalStore(subscribe, getSnapshot) || {}
+  const loadMore = useCallback(() => {
+    loadMoreUsers(instance, options)
+  }, [instance, options])
 
-  return {users, hasMore, loadMore: store.loadMore}
+  return {data, hasMore, isPending, loadMore}
 }

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

@@ -1,90 +0,0 @@
-import {AuthStateType, createSanityInstance} from '@sanity/sdk'
-import {SanityProvider, useAuthState, useLoginUrls} from '@sanity/sdk-react'
-import {render, screen} from '@testing-library/react'
-import React from 'react'
-import {beforeEach, describe, expect, it, vi} from 'vitest'
-
-import {LoginLinks} from './LoginLinks'
-
-// Mock the hooks and SDK functions
-vi.mock('../../hooks/auth/useLoginUrls', () => ({
-  useLoginUrls: vi.fn(() => [
-    {
-      name: 'google',
-      title: 'Google',
-      url: 'https://google.com/auth',
-    },
-    {
-      name: 'github',
-      title: 'GitHub',
-      url: 'https://github.com/auth',
-    },
-  ]),
-}))
-vi.mock('@sanity/sdk', async () => {
-  const actual = await vi.importActual('@sanity/sdk')
-
-  return {
-    ...actual,
-    tradeTokenForSession: vi.fn(),
-    getSidUrlHash: vi.fn().mockReturnValue(null),
-    getSidUrlSearch: vi.fn(),
-  }
-})
-
-vi.mock('../../hooks/auth/useAuthState', () => ({
-  useAuthState: vi.fn(() => 'logged-out'),
-}))
-
-vi.mock('../../hooks/auth/useHandleAuthCallback', () => ({
-  useHandleAuthCallback: vi.fn(),
-}))
-
-describe('LoginLinks', () => {
-  beforeEach(() => {
-    vi.clearAllMocks()
-  })
-
-  const sanityInstance = createSanityInstance({projectId: 'test-project-id', dataset: 'production'})
-  const renderWithWrappers = (ui: React.ReactElement) => {
-    return render(<SanityProvider sanityInstances={[sanityInstance]}>{ui}</SanityProvider>)
-  }
-
-  it('renders auth provider links correctly when not authenticated', () => {
-    vi.mocked(useAuthState).mockReturnValue({
-      type: AuthStateType.LOGGED_OUT,
-      isDestroyingSession: false,
-    })
-    renderWithWrappers(<LoginLinks />)
-
-    expect(screen.getByText('Choose login provider')).toBeInTheDocument()
-
-    const authProviders = useLoginUrls()
-    authProviders.forEach((provider) => {
-      const button = screen.getByRole('link', {name: provider.title})
-      expect(button).toBeInTheDocument()
-      expect(button).toHaveAttribute('href', provider.url)
-    })
-  })
-
-  it('shows loading state while logging in', () => {
-    vi.mocked(useAuthState).mockReturnValue({
-      type: AuthStateType.LOGGING_IN,
-      isExchangingToken: false,
-    })
-    renderWithWrappers(<LoginLinks />)
-
-    expect(screen.getByText('Logging in...')).toBeInTheDocument()
-  })
-
-  it('shows success message when logged in', () => {
-    vi.mocked(useAuthState).mockReturnValue({
-      type: AuthStateType.LOGGED_IN,
-      token: 'test-token',
-      currentUser: null,
-    })
-    renderWithWrappers(<LoginLinks />)
-
-    expect(screen.getByText('You are logged in')).toBeInTheDocument()
-  })
-})

package/src/components/Login/LoginLinks.tsx

@@ -1,58 +0,0 @@
-import {type ReactElement} from 'react'
-
-import {useAuthState} from '../../hooks/auth/useAuthState'
-import {useHandleAuthCallback} from '../../hooks/auth/useHandleAuthCallback'
-import {useLoginUrls} from '../../hooks/auth/useLoginUrls'
-
-/**
- * Component that handles Sanity authentication flow and renders login provider options
- *
- * @public
- *
- * @returns Rendered component
- *
- * @remarks
- * The component handles three states:
- * 1. Loading state during token exchange
- * 2. Success state after successful authentication
- * 3. Provider selection UI when not authenticated
- *
- * @example
- * ```tsx
- * const config = { projectId: 'your-project-id', dataset: 'production' }
- * return <LoginLinks sanityInstance={config} />
- * ```
- */
-export const LoginLinks = (): ReactElement => {
-  const loginUrls = useLoginUrls()
-  const authState = useAuthState()
-  useHandleAuthCallback()
-
-  if (authState.type === 'logging-in') {
-    return <div className="sc-login-links__logging-in">Logging in...</div>
-  }
-
-  // Show success state after authentication
-  if (authState.type === 'logged-in') {
-    return <div className="sc-login-links__logged-in">You are logged in</div>
-  }
-
-  /**
-   * Render provider selection UI
-   */
-  return (
-    <div className="sc-login-links">
-      <h2 className="sc-login-links__title">Choose login provider</h2>
-
-      <ul className="sc-login-links__list">
-        {loginUrls.map((provider, index) => (
-          <li key={`${provider.url}_${index}`} className="sc-login-links__item">
-            <a href={provider.url} className="sc-login-links__link">
-              {provider.title}
-            </a>
-          </li>
-        ))}
-      </ul>
-    </div>
-  )
-}

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

@@ -1,27 +0,0 @@
-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', () => ({
-  useLoginUrls: vi.fn(() => [
-    {title: 'Provider A', url: 'https://provider-a.com/auth'},
-    {title: 'Provider B', url: 'https://provider-b.com/auth'},
-  ]),
-}))
-
-describe('Login', () => {
-  it('renders login providers', () => {
-    renderWithWrappers(<Login />)
-    expect(screen.getByText('Choose login provider')).toBeInTheDocument()
-    expect(screen.getByRole('link', {name: 'Provider A'})).toHaveAttribute(
-      'href',
-      'https://provider-a.com/auth',
-    )
-    expect(screen.getByRole('link', {name: 'Provider B'})).toHaveAttribute(
-      'href',
-      'https://provider-b.com/auth',
-    )
-  })
-})

package/src/components/auth/Login.tsx

@@ -1,39 +0,0 @@
-import {type JSX, Suspense} from 'react'
-
-import {useLoginUrls} from '../../hooks/auth/useLoginUrls'
-import {LoginLayout, type LoginLayoutProps} from './LoginLayout'
-
-/**
- * Login component that displays available authentication providers.
- * 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>
-
-        <Suspense fallback={<div className="sc-login__loading">Loading…</div>}>
-          <Providers />
-        </Suspense>
-      </div>
-    </LoginLayout>
-  )
-}
-
-function Providers() {
-  const loginUrls = useLoginUrls()
-
-  return (
-    <div className="sc-login-providers">
-      {loginUrls.map(({title, url}) => (
-        <a key={url} href={url}>
-          {title}
-        </a>
-      ))}
-    </div>
-  )
-}

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

@@ -1,19 +0,0 @@
-import {screen} from '@testing-library/react'
-import {describe, expect, it} from 'vitest'
-
-import {renderWithWrappers} from './authTestHelpers'
-import {LoginLayout} from './LoginLayout'
-
-describe('LoginLayout', () => {
-  it('renders header, children, and footer', () => {
-    renderWithWrappers(
-      <LoginLayout header={<div>Header Content</div>} footer={<div>Footer Content</div>}>
-        <div>Main Content</div>
-      </LoginLayout>,
-    )
-
-    expect(screen.getByText('Header Content')).toBeInTheDocument()
-    expect(screen.getByText('Main Content')).toBeInTheDocument()
-    expect(screen.getByText('Footer Content')).toBeInTheDocument()
-  })
-})

package/src/components/auth/LoginLayout.tsx

@@ -1,69 +0,0 @@
-import {LoginFooter} from './LoginFooter'
-
-/**
- * @alpha
- */
-export interface LoginLayoutProps {
-  /** Optional header content rendered at top of card */
-  header?: React.ReactNode
-
-  /** Optional footer content rendered below card. Defaults to an internal login footer */
-  footer?: React.ReactNode
-
-  /** Main content rendered in card body */
-  children?: React.ReactNode
-}
-
-/**
- * Layout component for login-related screens providing consistent styling and structure.
- * Renders content in a centered card with optional header and footer sections.
- *
- * Can be used to build custom login screens for the AuthBoundary component, including:
- * - Login provider selection (LoginComponent)
- * - OAuth callback handling (CallbackComponent)
- * - Error states (LoginErrorComponent)
- *
- * @example
- * ```tsx
- * // Custom login screen using the layout
- * function CustomLogin({header, footer}: LoginLayoutProps) {
- *   return (
- *     <LoginLayout
- *       header={header}
- *       footer={footer}
- *     >
- *       <CustomLoginContent />
- *     </LoginLayout>
- *   )
- * }
- *
- * // Use with AuthBoundary
- * <AuthBoundary
- *   LoginComponent={CustomLogin}
- *   header={<Logo />}
- * >
- *   <ProtectedContent />
- * </AuthBoundary>
- * ```
- *
- * @alpha
- */
-export function LoginLayout({
-  children,
-  footer = <LoginFooter />,
-  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>}
-
-          {children && <div className="sc-login-layout__card-body">{children}</div>}
-        </div>
-
-        {footer}
-      </div>
-    </div>
-  )
-}

package/src/components/auth/authTestHelpers.tsx

@@ -1,11 +0,0 @@
-import {createSanityInstance} from '@sanity/sdk'
-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'})
-
-export const renderWithWrappers = (ui: React.ReactElement): RenderResult => {
-  return render(<SanityProvider sanityInstances={[sanityInstance]}>{ui}</SanityProvider>)
-}

package/src/context/SanityProvider.test.tsx

@@ -1,25 +0,0 @@
-import {createSanityInstance} from '@sanity/sdk'
-import {render} from '@testing-library/react'
-import {describe, expect, it} from 'vitest'
-
-import {useSanityInstance} from '../hooks/context/useSanityInstance'
-import {SanityProvider} from './SanityProvider'
-
-describe('SanityProvider', () => {
-  const sanityInstance = createSanityInstance({projectId: 'test-project', dataset: 'production'})
-
-  it('provides instance to nested components', () => {
-    const TestComponent = () => {
-      const instance = useSanityInstance()
-      return <div data-testid="test">{instance.identity.projectId}</div>
-    }
-
-    const {getByTestId} = render(
-      <SanityProvider sanityInstances={[sanityInstance]}>
-        <TestComponent />
-      </SanityProvider>,
-    )
-
-    expect(getByTestId('test')).toHaveTextContent('test-project')
-  })
-})

package/src/context/SanityProvider.tsx

@@ -1,50 +0,0 @@
-import {type SanityInstance} from '@sanity/sdk'
-import {type ReactElement} from 'react'
-
-import {SanityInstanceContext} from './SanityInstanceContext'
-
-/**
- * @internal
- */
-export interface SanityProviderProps {
-  children: React.ReactNode
-  sanityInstances: SanityInstance[]
-}
-
-/**
- * @internal
- *
- * Top-level context provider that provides access to the Sanity configuration instance.
- * This must wrap any components making use of the Sanity SDK React hooks.
- *
- * @remarks In most cases, SanityApp should be used rather than SanityProvider directly; SanityApp bundles both SanityProvider and an authentication layer.
- * @param props - Sanity project and dataset configuration
- * @returns Rendered component
- * @example
- * ```tsx
- * import {createSanityInstance} from '@sanity/sdk'
- * import {SanityProvider} from '@sanity/sdk-react'
- *
- * import MyAppRoot from './Root'
- *
- * const sanityInstance = createSanityInstance({
- *   projectId: 'your-project-id',
- *   dataset: 'production',
- * })
- *
- * export default function MyApp() {
- *   return (
- *     <SanityProvider sanityInstance={sanityInstance}>
- *       <MyAppRoot />
- *     </SanityProvider>
- *   )
- * }
- * ```
- */
-export const SanityProvider = ({children, sanityInstances}: SanityProviderProps): ReactElement => {
-  return (
-    <SanityInstanceContext.Provider value={sanityInstances}>
-      {children}
-    </SanityInstanceContext.Provider>
-  )
-}

package/src/hooks/auth/useLoginUrls.test.tsx

@@ -1,68 +0,0 @@
-import {createSanityInstance, fetchLoginUrls, getLoginUrlsState} from '@sanity/sdk'
-import {renderHook} from '@testing-library/react'
-import {act, Suspense} from 'react'
-import {throwError} from 'rxjs'
-import {describe, expect, it, vi} from 'vitest'
-
-import {useLoginUrls} from './useLoginUrls'
-
-vi.mock('../context/useSanityInstance', () => ({
-  useSanityInstance: vi.fn().mockReturnValue(createSanityInstance({projectId: 'p', dataset: 'd'})),
-}))
-
-vi.mock(import('@sanity/sdk'), async (importOriginal) => {
-  const actual = await importOriginal()
-  return {...actual, getLoginUrlsState: vi.fn(), fetchLoginUrls: vi.fn()}
-})
-
-describe('useLoginUrls', () => {
-  it('should suspend by throwing `fetchLoginUrls` if `getLoginUrlsState().getCurrent()` is falsy', async () => {
-    const subscribe = vi.fn()
-    const getCurrent = vi.fn().mockReturnValue(undefined)
-
-    let resolve: () => void
-    const promise = new Promise<void>((thisResolve) => {
-      resolve = thisResolve
-    })
-    vi.mocked(fetchLoginUrls).mockReturnValue(
-      promise as unknown as ReturnType<typeof fetchLoginUrls>,
-    )
-
-    vi.mocked(getLoginUrlsState).mockReturnValue({
-      getCurrent,
-      subscribe,
-      observable: throwError(() => new Error('Unexpected usage of observable')),
-    })
-
-    const wrapper = ({children}: {children: React.ReactNode}) => (
-      <Suspense fallback={<>Loading…</>}>{children}</Suspense>
-    )
-
-    const {result, rerender} = renderHook(() => useLoginUrls(), {wrapper})
-    expect(result.current).toEqual(null)
-
-    const mockProviders = [{name: 'google', title: 'Google', url: 'http://test.com/auth/google'}]
-
-    await act(async () => {
-      getCurrent.mockReturnValue(mockProviders)
-      resolve()
-      rerender()
-      await promise
-    })
-
-    expect(result.current).toEqual(mockProviders)
-  })
-
-  it('should render according to `getLoginUrlsState`', () => {
-    const subscribe = vi.fn()
-    const mockProviders = [{name: 'google', title: 'Google', url: 'http://test.com/auth/google'}]
-    vi.mocked(getLoginUrlsState).mockReturnValue({
-      getCurrent: () => mockProviders,
-      subscribe,
-      observable: throwError(() => new Error('Unexpected usage of observable')),
-    })
-
-    const {result} = renderHook(() => useLoginUrls())
-    expect(result.current).toEqual(mockProviders)
-  })
-})

package/src/hooks/auth/useLoginUrls.tsx

@@ -1,52 +0,0 @@
-import {type AuthProvider, fetchLoginUrls, getLoginUrlsState} from '@sanity/sdk'
-import {useMemo, useSyncExternalStore} from 'react'
-
-import {useSanityInstance} from '../context/useSanityInstance'
-
-/**
- * @internal
- * A React hook that retrieves the available authentication provider URLs for login.
- *
- * @remarks
- * This hook fetches the login URLs from the Sanity auth store when the component mounts.
- * Each provider object contains information about an authentication method, including its URL.
- * The hook will suspend if the login URLs have not yet loaded.
- *
- * @example
- * ```tsx
- * // LoginProviders component that uses the hook
- * function LoginProviders() {
- *   const providers = useLoginUrls()
- *
- *   return (
- *     <div>
- *       {providers.map((provider) => (
- *         <a key={provider.name} href={provider.url}>
- *           Login with {provider.title}
- *         </a>
- *       ))}
- *     </div>
- *   )
- * }
- *
- * // Parent component with Suspense boundary
- * function LoginPage() {
- *   return (
- *     <Suspense fallback={<div>Loading authentication providers...</div>}>
- *       <LoginProviders />
- *     </Suspense>
- *   )
- * }
- * ```
- *
- * @returns An array of {@link AuthProvider} objects containing login URLs and provider information
- * @public
- */
-export function useLoginUrls(): AuthProvider[] {
-  const instance = useSanityInstance()
-  const {subscribe, getCurrent} = useMemo(() => getLoginUrlsState(instance), [instance])
-
-  if (!getCurrent()) throw fetchLoginUrls(instance)
-
-  return useSyncExternalStore(subscribe, getCurrent as () => AuthProvider[])
-}