@sanity/sdk-react 0.0.0-alpha.1

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

@@ -0,0 +1,41 @@
+import {createSanityInstance} from '@sanity/sdk'
+import {ThemeProvider} from '@sanity/ui'
+import {buildTheme} from '@sanity/ui/theme'
+import {render, screen} from '@testing-library/react'
+import React from 'react'
+import {describe, expect, it, vi} from 'vitest'
+
+import {SanityProvider} from '../context/SanityProvider'
+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'},
+  ]),
+}))
+
+const theme = buildTheme({})
+const sanityInstance = createSanityInstance({projectId: 'test-project-id', dataset: 'production'})
+const renderWithWrappers = (ui: React.ReactElement) => {
+  return render(
+    <ThemeProvider theme={theme}>
+      <SanityProvider sanityInstance={sanityInstance}>{ui}</SanityProvider>
+    </ThemeProvider>,
+  )
+}
+
+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

@@ -0,0 +1,58 @@
+import {Button, Flex, Heading, Spinner} from '@sanity/ui'
+import {Suspense} from 'react'
+import styled from 'styled-components'
+
+import {useLoginUrls} from '../../hooks/auth/useLoginUrls'
+import {LoginLayout, type LoginLayoutProps} from './LoginLayout'
+
+/**
+ * @alpha
+ */
+export interface LoginProps {
+  header?: React.ReactNode
+  footer?: React.ReactNode
+}
+
+const FallbackRoot = styled(Flex)`
+  height: 123px;
+`
+
+/**
+ * Login component that displays available authentication providers.
+ * Renders a list of login options with a loading fallback while providers load.
+ *
+ * @alpha
+ */
+export function Login({header, footer}: LoginLayoutProps): JSX.Element {
+  return (
+    <LoginLayout header={header} footer={footer}>
+      <Flex direction="column" gap={4}>
+        <Heading as="h1" size={1} align="center">
+          Choose login provider
+        </Heading>
+
+        <Suspense
+          fallback={
+            <FallbackRoot align="center" justify="center">
+              <Spinner />
+            </FallbackRoot>
+          }
+        >
+          <Providers />
+        </Suspense>
+      </Flex>
+    </LoginLayout>
+  )
+}
+
+function Providers() {
+  const loginUrls = useLoginUrls()
+
+  return (
+    <Flex direction="column" gap={3}>
+      {loginUrls.map(({title, url}) => (
+        <Button key={url} text={title} as="a" href={url} mode="ghost" />
+      ))}
+    </Flex>
+  )
+}

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

@@ -0,0 +1,86 @@
+import {createSanityInstance} from '@sanity/sdk'
+import {ThemeProvider} from '@sanity/ui'
+import {buildTheme} from '@sanity/ui/theme'
+import {render, screen, waitFor} from '@testing-library/react'
+import React from 'react'
+import {afterAll, beforeAll, beforeEach, describe, expect, it, vi} from 'vitest'
+
+import {SanityProvider} from '../context/SanityProvider'
+
+const theme = buildTheme({})
+const sanityInstance = createSanityInstance({projectId: 'test-project-id', dataset: 'production'})
+
+const renderWithWrappers = (ui: React.ReactElement) => {
+  return render(
+    <ThemeProvider theme={theme}>
+      <SanityProvider sanityInstance={sanityInstance}>{ui}</SanityProvider>
+    </ThemeProvider>,
+  )
+}
+
+// Mock `useHandleCallback`
+vi.mock('../../hooks/auth/useHandleCallback', () => ({
+  useHandleCallback: vi.fn(() => async (url: string) => {
+    const parsedUrl = new URL(url)
+    const sid = new URLSearchParams(parsedUrl.hash.slice(1)).get('sid')
+    if (sid === 'valid') {
+      return 'https://example.com/new-location'
+    }
+    return false
+  }),
+}))
+
+describe('LoginCallback', () => {
+  beforeAll(() => {
+    // Stub `window.history` and `location`
+    vi.stubGlobal('history', {
+      replaceState: vi.fn(),
+    })
+    vi.stubGlobal('location', {
+      href: 'http://localhost',
+    })
+  })
+
+  afterAll(() => {
+    vi.unstubAllGlobals()
+  })
+
+  beforeEach(() => {
+    vi.clearAllMocks()
+    vi.resetModules()
+  })
+
+  it('renders a loading message', async () => {
+    const {LoginCallback} = await import('./LoginCallback') // Reload after resetModules
+    renderWithWrappers(<LoginCallback />)
+    expect(screen.getByText('Logging you in…')).toBeInTheDocument()
+  })
+
+  it('handles a successful callback and calls history.replaceState', async () => {
+    // Simulate a valid `sid` in the location hash
+    vi.stubGlobal('location', {href: 'http://localhost#sid=valid'})
+    const {LoginCallback} = await import('./LoginCallback') // Reload after resetModules
+
+    renderWithWrappers(<LoginCallback />)
+
+    await waitFor(() => {
+      expect(history.replaceState).toHaveBeenCalledWith(
+        null,
+        '',
+        'https://example.com/new-location',
+      )
+    })
+  })
+
+  it('does not call history.replaceState on an unsuccessful callback', async () => {
+    // Simulate an invalid `sid` in the location hash
+    vi.stubGlobal('location', {href: 'http://localhost#sid=invalid'})
+    const {LoginCallback} = await import('./LoginCallback') // Reload after resetModules
+
+    renderWithWrappers(<LoginCallback />)
+
+    await waitFor(() => {
+      expect(history.replaceState).not.toHaveBeenCalled()
+    })
+  })
+})

package/src/components/auth/LoginCallback.tsx

@@ -0,0 +1,41 @@
+import {Flex, Spinner, Text} from '@sanity/ui'
+import {useEffect} from 'react'
+import styled from 'styled-components'
+
+import {useHandleCallback} from '../../hooks/auth/useHandleCallback'
+import {LoginLayout, type LoginLayoutProps} from './LoginLayout'
+
+const StyledFlex = styled(Flex)`
+  margin: auto;
+`
+
+/**
+ * Component shown during auth callback processing that handles login completion.
+ * Automatically processes the auth callback when mounted and updates the URL
+ * to remove callback parameters without triggering a page reload.
+ *
+ * @alpha
+ */
+export function LoginCallback({header, footer}: LoginLayoutProps): React.ReactNode {
+  const handleCallback = useHandleCallback()
+
+  useEffect(() => {
+    const url = new URL(location.href)
+    handleCallback(url.toString()).then((replacementLocation) => {
+      if (replacementLocation) {
+        // history API with `replaceState` is used to prevent a reload but still
+        // remove the short-lived token from the URL
+        history.replaceState(null, '', replacementLocation)
+      }
+    })
+  }, [handleCallback])
+
+  return (
+    <LoginLayout header={header} footer={footer}>
+      <StyledFlex direction="column" justify="center" align="center" gap={4}>
+        <Text size={1}>Logging you in…</Text>
+        <Spinner size={4} />
+      </StyledFlex>
+    </LoginLayout>
+  )
+}

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

@@ -0,0 +1,56 @@
+import {createSanityInstance} from '@sanity/sdk'
+import {ThemeProvider} from '@sanity/ui'
+import {buildTheme} from '@sanity/ui/theme'
+import {fireEvent, render, screen, waitFor} from '@testing-library/react'
+import React from 'react'
+import {describe, expect, it, vi} from 'vitest'
+
+import {SanityProvider} from '../context/SanityProvider'
+import {AuthError} from './AuthError'
+import {LoginError} from './LoginError'
+
+vi.mock('../../hooks/auth/useLogOut', () => ({
+  useLogOut: vi.fn(() => async () => {}),
+}))
+
+const theme = buildTheme({})
+const sanityInstance = createSanityInstance({projectId: 'test-project-id', dataset: 'production'})
+
+const renderWithWrappers = (ui: React.ReactElement) => {
+  return render(
+    <ThemeProvider theme={theme}>
+      <SanityProvider sanityInstance={sanityInstance}>{ui}</SanityProvider>
+    </ThemeProvider>,
+  )
+}
+
+describe('LoginError', () => {
+  it('shows authentication error and retry button', async () => {
+    const mockReset = vi.fn()
+    const error = new AuthError(new Error('Test error'))
+
+    renderWithWrappers(<LoginError error={error} resetErrorBoundary={mockReset} />)
+
+    expect(screen.getByText('Authentication Error')).toBeInTheDocument()
+    const retryButton = screen.getByRole('button', {name: 'Retry'})
+    fireEvent.click(retryButton)
+
+    await waitFor(() => {
+      expect(mockReset).toHaveBeenCalled()
+    })
+  })
+
+  it('throws an error if the error is not an instance of AuthError', () => {
+    const mockReset = vi.fn()
+    const nonAuthError = new Error('Non-auth error')
+
+    // Suppress console.error during this test
+    const consoleErrorSpy = vi.spyOn(console, 'error').mockImplementation(() => {})
+
+    expect(() => {
+      renderWithWrappers(<LoginError error={nonAuthError} resetErrorBoundary={mockReset} />)
+    }).toThrow('Non-auth error')
+
+    consoleErrorSpy.mockRestore() // Restore original console.error behavior
+  })
+})

package/src/components/auth/LoginError.tsx

@@ -0,0 +1,54 @@
+import {Button, Flex, Text} from '@sanity/ui'
+import {useCallback} from 'react'
+import {type FallbackProps} from 'react-error-boundary'
+import styled from 'styled-components'
+
+import {useLogOut} from '../../hooks/auth/useLogOut'
+import {AuthError} from './AuthError'
+import {LoginLayout, type LoginLayoutProps} from './LoginLayout'
+
+/**
+ * @alpha
+ */
+export type LoginErrorProps = FallbackProps & LoginLayoutProps
+
+const StyledFlex = styled(Flex)`
+  margin: auto;
+`
+
+/**
+ * Displays authentication error details and provides retry functionality.
+ * Only handles {@link AuthError} instances - rethrows other error types.
+ *
+ * @alpha
+ */
+export function LoginError({
+  error,
+  resetErrorBoundary,
+  header,
+  footer,
+}: LoginErrorProps): React.ReactNode {
+  if (!(error instanceof AuthError)) throw error
+  const logout = useLogOut()
+
+  const handleRetry = useCallback(async () => {
+    await logout()
+    resetErrorBoundary()
+  }, [logout, resetErrorBoundary])
+
+  return (
+    <LoginLayout header={header} footer={footer}>
+      <StyledFlex direction="column" gap={4}>
+        <Flex direction="column" gap={3}>
+          <Text as="h2" align="center" weight="bold" size={3}>
+            Authentication Error
+          </Text>
+          <Text size={1} align="center">
+            Please try again or contact support if the problem persists.
+          </Text>
+        </Flex>
+        <Button text="Retry" tone="primary" onClick={handleRetry} />
+      </StyledFlex>
+    </LoginLayout>
+  )
+}

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

@@ -0,0 +1,29 @@
+import {createSanityInstance} from '@sanity/sdk'
+import {ThemeProvider} from '@sanity/ui'
+import {buildTheme} from '@sanity/ui/theme'
+import {render, screen} from '@testing-library/react'
+import React from 'react'
+import {describe, expect, it} from 'vitest'
+
+import {SanityProvider} from '../context/SanityProvider'
+import {LoginFooter} from './LoginFooter'
+
+const theme = buildTheme({})
+const sanityInstance = createSanityInstance({projectId: 'test-project-id', dataset: 'production'})
+const renderWithWrappers = (ui: React.ReactElement) => {
+  return render(
+    <ThemeProvider theme={theme}>
+      <SanityProvider sanityInstance={sanityInstance}>{ui}</SanityProvider>
+    </ThemeProvider>,
+  )
+}
+
+describe('LoginFooter', () => {
+  it('renders footer links', () => {
+    renderWithWrappers(<LoginFooter />)
+    expect(screen.getByText('Community')).toBeInTheDocument()
+    expect(screen.getByText('Docs')).toBeInTheDocument()
+    expect(screen.getByText('Privacy')).toBeInTheDocument()
+    expect(screen.getByText('sanity.io')).toBeInTheDocument()
+  })
+})

package/src/components/auth/LoginFooter.tsx

@@ -0,0 +1,67 @@
+import {SanityLogo} from '@sanity/logos'
+import {Flex, Text} from '@sanity/ui'
+import {Fragment} from 'react'
+import styled from 'styled-components'
+
+const LINKS = [
+  {
+    url: 'https://slack.sanity.io/',
+    i18nKey: 'workspaces.community-title',
+    title: 'Community',
+  },
+  {
+    url: 'https://www.sanity.io/docs',
+    i18nKey: 'workspaces.docs-title',
+    title: 'Docs',
+  },
+  {
+    url: 'https://www.sanity.io/legal/privacy',
+    i18nKey: 'workspaces.privacy-title',
+    title: 'Privacy',
+  },
+  {
+    url: 'https://www.sanity.io',
+    i18nKey: 'workspaces.sanity-io-title',
+    title: 'sanity.io',
+  },
+]
+
+const StyledText = styled(Text)`
+  a {
+    color: inherit;
+  }
+`
+
+/**
+ * Default footer component for login screens showing Sanity branding and legal
+ * links.
+ *
+ * @alpha
+ */
+export function LoginFooter(): React.ReactNode {
+  return (
+    <Flex direction="column" gap={4} justify="center" align="center" paddingTop={2}>
+      <Text size={3}>
+        <SanityLogo />
+      </Text>
+
+      <Flex align="center" gap={2}>
+        {LINKS.map((link, index) => (
+          <Fragment key={link.title}>
+            <StyledText muted size={1}>
+              <a href={link.url} target="_blank" rel="noopener noreferrer">
+                {link.title}
+              </a>
+            </StyledText>
+
+            {index < LINKS.length - 1 && (
+              <Text size={1} muted>
+                •
+              </Text>
+            )}
+          </Fragment>
+        ))}
+      </Flex>
+    </Flex>
+  )
+}

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

@@ -0,0 +1,33 @@
+import {createSanityInstance} from '@sanity/sdk'
+import {ThemeProvider} from '@sanity/ui'
+import {buildTheme} from '@sanity/ui/theme'
+import {render, screen} from '@testing-library/react'
+import React from 'react'
+import {describe, expect, it} from 'vitest'
+
+import {SanityProvider} from '../context/SanityProvider'
+import {LoginLayout} from './LoginLayout'
+
+const theme = buildTheme({})
+const sanityInstance = createSanityInstance({projectId: 'test-project-id', dataset: 'production'})
+const renderWithWrappers = (ui: React.ReactElement) => {
+  return render(
+    <ThemeProvider theme={theme}>
+      <SanityProvider sanityInstance={sanityInstance}>{ui}</SanityProvider>
+    </ThemeProvider>,
+  )
+}
+
+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

@@ -0,0 +1,99 @@
+import {Card, Flex} from '@sanity/ui'
+import styled from 'styled-components'
+
+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
+}
+
+const Root = styled.div`
+  width: 100%;
+  display: flex;
+`
+
+const Container = styled(Flex)`
+  width: 320px;
+  margin: auto;
+  display: flex;
+`
+
+const StyledCard = styled(Card)``
+
+const ChildrenFlex = styled(Flex)`
+  min-height: 154px;
+`
+
+/**
+ * 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 (
+    <Root>
+      <Container direction="column" gap={4}>
+        <StyledCard border radius={2} paddingY={4}>
+          <Flex direction="column" gap={4}>
+            {header && (
+              <Card borderBottom paddingX={4} paddingBottom={3}>
+                {header}
+              </Card>
+            )}
+
+            {children && (
+              <ChildrenFlex paddingX={4} direction="column">
+                {children}
+              </ChildrenFlex>
+            )}
+          </Flex>
+        </StyledCard>
+
+        {footer}
+      </Container>
+    </Root>
+  )
+}

package/src/components/context/SanityProvider.test.tsx

@@ -0,0 +1,25 @@
+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 sanityInstance={sanityInstance}>
+        <TestComponent />
+      </SanityProvider>,
+    )
+
+    expect(getByTestId('test')).toHaveTextContent('test-project')
+  })
+})

package/src/components/context/SanityProvider.tsx

@@ -0,0 +1,42 @@
+import {type SanityInstance} from '@sanity/sdk'
+import {createContext, type ReactElement} from 'react'
+
+/**
+ * @public
+ */
+export interface SanityProviderProps {
+  children: React.ReactNode
+  sanityInstance: SanityInstance
+}
+
+export const SanityInstanceContext = createContext<SanityInstance | null>(null)
+
+/**
+ * Top-level context provider that provides a Sanity configuration instance.
+ * This must wrap any Sanity SDK React component.
+ * @public
+ * @param props - Sanity project and dataset configuration
+ * @returns Rendered component
+ * @example
+ * ```tsx
+ * import {createSanityInstance} from '@sanity/sdk'
+ * import {ExampleComponent, SanityProvider} from '@sanity/sdk-react'
+ *
+ * const sanityInstance = createSanityInstance({projectId: 'your-project-id', dataset: 'production'})
+ *
+ * export default function MyApp() {
+ *   return (
+ *     <SanityProvider sanityInstance={sanityInstance}>
+ *      <ExampleComponent />
+ *     </SanityProvider>
+ *   )
+ * }
+ * ```
+ */
+export const SanityProvider = ({children, sanityInstance}: SanityProviderProps): ReactElement => {
+  return (
+    <SanityInstanceContext.Provider value={sanityInstance}>
+      {children}
+    </SanityInstanceContext.Provider>
+  )
+}