@sanity/sdk-react 0.0.0-alpha.1

package/src/components/DocumentPreviewLayout/DocumentPreviewLayout.md

@@ -0,0 +1,49 @@
+# DocumentPreviewLayout
+
+The DocumentPreviewLayout component is used to render a compact representation of a [document](#). These previews are often rendered for each document within a [DocumentListUI component](#), but can also be rendered as standalone components.
+
+Document previews surface the following information about each document:
+
+- The document's title
+- A subtitle (optional)
+- A piece of media, such as an icon or image (optional)
+- The document type (optional)
+- The document’s state, such as draft or published (optional)
+
+Additionally, each document preview can take a `url` prop to enable navigation changes when selecting the document, and a `selected` prop to indicate that a given document has been selected.
+
+![An image of the stock preview component]()
+
+```jsx
+<DocumentPreviewLayout
+  title={doc.title}
+  subtitle={doc.subtitle}
+  media={doc.media}
+  docType={doc.type}
+  docState={doc.published ? 'published' : 'draft'}
+  url={doc.url}
+  selected={true}
+/>
+```
+
+## Installation
+
+```shell
+npm install @sanity/sdk
+```
+
+```javascript
+import DocumentPreviewLayout from `@sanity/sdk/react/DocumentPreviewLayout`
+```
+
+## Props
+
+| Name       | Type                 | Description                                                 |
+| ---------- | -------------------- | ----------------------------------------------------------- |
+| `title`    | `string`             | The title to display for the document                       |
+| `subtitle` | `string` (optional)  | The subtitle to display for the document                    |
+| `media`    | `node` (optional)    | The image, icon, or other node to display with the document |
+| `docType`  | `string` (optional)  | The document type                                           |
+| `docState` | `string` (optional)  | The state of the document, such as 'published' or 'draft'   |
+| `url`      | `string` (optional)  | The URL to navigate to when selecting the document          |
+| `selected` | `boolean` (optional) | The `selected` state of the document; defaults to `false`   |

package/src/components/DocumentPreviewLayout/DocumentPreviewLayout.stories.tsx

@@ -0,0 +1,34 @@
+import {type Meta, type StoryObj} from '@storybook/react'
+
+import {DocumentPreviewLayout} from './DocumentPreviewLayout'
+
+const meta: Meta<typeof DocumentPreviewLayout> = {
+  title: 'DocumentPreviewLayout',
+  component: DocumentPreviewLayout,
+}
+
+export default meta
+type Story = StoryObj<typeof meta>
+
+export const Basic: Story = {
+  args: {
+    title: 'Hello World',
+    url: '#',
+  },
+  render: (props) => {
+    return <DocumentPreviewLayout {...props} />
+  },
+}
+
+export const AllProps: Story = {
+  args: {
+    title: 'Hello World',
+    subtitle: 'It’s nice to meet you',
+    url: '#',
+    docType: 'article',
+    status: 'published',
+  },
+  render: (props) => {
+    return <DocumentPreviewLayout {...props} />
+  },
+}

package/src/components/DocumentPreviewLayout/DocumentPreviewLayout.test.tsx

@@ -0,0 +1,30 @@
+import {render, screen} from '../../../test/test-utils.tsx'
+import {DocumentPreviewLayout} from './DocumentPreviewLayout'
+
+describe('DocumentPreviewLayout', () => {
+  it('renders the data it receives via props', () => {
+    render(<DocumentPreviewLayout title="Test Preview" subtitle="It works" />)
+    expect(screen.getByText('Test Preview')).toBeVisible()
+    expect(screen.getByText('It works')).toBeVisible()
+  })
+
+  it('renders empty when no title is provided (todo)', () => {
+    const {container} = render(<DocumentPreviewLayout title="" />)
+    expect(container).toBeEmptyDOMElement()
+  })
+
+  it('renders the doctype when one is provided', () => {
+    render(<DocumentPreviewLayout title="Test Preview" docType="article" />)
+    expect(screen.getByText('article')).toBeVisible()
+  })
+
+  it('renders the published status when provided', () => {
+    render(<DocumentPreviewLayout title="Test Preview" status="published" />)
+    expect(screen.getByText('published')).toBeVisible()
+  })
+
+  it('renders the draft status when provided', () => {
+    render(<DocumentPreviewLayout title="Test Preview" status="draft" />)
+    expect(screen.getByText('draft')).toBeVisible()
+  })
+})

package/src/components/DocumentPreviewLayout/DocumentPreviewLayout.tsx

@@ -0,0 +1,115 @@
+import {Badge, Button, Stack, Text} from '@sanity/ui'
+import styled from 'styled-components'
+
+/**
+ * @public
+ */
+export interface DocumentPreviewLayoutProps {
+  docType?: string
+  media?: React.ReactNode // Todo: determine how media data will be passed to this component; need to represent either an image or an icon
+  selected?: boolean
+  status?: string
+  subtitle?: string
+  title: string
+  url?: string
+}
+
+// Todo: replace with actual media (either image or icon)
+const TempMedia = styled.div`
+  aspect-ratio: 1 / 1;
+  inline-size: 33px;
+  border: 1px solid #ccc;
+`
+
+// Set a containment context for the Preview
+const Container = styled.div`
+  container-type: inline-size;
+  display: flex;
+  align-items: center;
+  gap: 0.75em;
+`
+
+// Status labels are visually hidden when a narrow document list is rendered;
+// text remains accessible to screen readers
+const StatusLabel = styled.span`
+  @container (width < 52ch) {
+    clip: rect(0 0 0 0);
+    clip-path: inset(50%);
+    height: 1px;
+    overflow: hidden;
+    position: absolute;
+    white-space: nowrap;
+    width: 1px;
+  }
+`
+
+/**
+ * This is a component that renders a document preview.
+ *
+ * @public
+ *
+ * @param props - The props for the DocumentPreviewLayout component.
+ * @returns - The DocumentPreviewLayout component.
+ */
+export const DocumentPreviewLayout = ({
+  docType,
+  selected = false,
+  status = '',
+  subtitle = '',
+  title,
+  url = '',
+}: DocumentPreviewLayoutProps): JSX.Element => {
+  // Todo: empty state
+  if (!title) {
+    return <></>
+  }
+
+  return (
+    <Button
+      as="a"
+      href={url}
+      mode="bleed"
+      width="fill"
+      padding={3}
+      selected={selected}
+      data-ui="DocumentPreviewLayout"
+    >
+      <Container>
+        <TempMedia />
+
+        <Stack flex={1} space={2}>
+          <Text size={1} weight="medium" textOverflow="ellipsis">
+            {title}
+          </Text>
+          {subtitle && (
+            <Text muted size={1} textOverflow="ellipsis">
+              {subtitle}
+            </Text>
+          )}
+        </Stack>
+
+        {docType && (
+          <Badge padding={2} fontSize={0}>
+            {docType}
+          </Badge>
+        )}
+
+        {/* Todo: finalize UI for this */}
+        {status === 'published' && (
+          <Badge padding={2} fontSize={0} tone="positive">
+            ✔︎ <StatusLabel>published</StatusLabel>
+          </Badge>
+        )}
+
+        {/* Todo: finalize UI for this, determine if we need to show 'draft' or just 'published' */}
+        {status === 'draft' && (
+          <Badge padding={2} fontSize={0} tone="caution">
+            ⛑︎ <StatusLabel>draft</StatusLabel>
+          </Badge>
+        )}
+      </Container>
+    </Button>
+  )
+}
+
+DocumentPreviewLayout.displayName = 'DocumentPreviewLayout'

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

@@ -0,0 +1,100 @@
+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 {beforeEach, describe, expect, it, vi} from 'vitest'
+
+import {useAuthState} from '../../hooks/auth/useAuthState'
+import {useLoginUrls} from '../../hooks/auth/useLoginUrls'
+import {SanityProvider} from '../context/SanityProvider'
+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/useHandleCallback', () => ({
+  useHandleCallback: vi.fn(),
+}))
+
+const theme = buildTheme({})
+
+describe('LoginLinks', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+  })
+
+  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>,
+    )
+  }
+
+  it('renders auth provider links correctly when not authenticated', () => {
+    vi.mocked(useAuthState).mockReturnValue({
+      type: '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: 'logging-in',
+      isExchangingToken: false,
+    })
+    renderWithWrappers(<LoginLinks />)
+
+    expect(screen.getByText('Logging in...')).toBeInTheDocument()
+  })
+
+  it('shows success message when logged in', () => {
+    vi.mocked(useAuthState).mockReturnValue({
+      type: 'logged-in',
+      token: 'test-token',
+      currentUser: null,
+    })
+    renderWithWrappers(<LoginLinks />)
+
+    expect(screen.getByText('You are logged in')).toBeInTheDocument()
+  })
+})

package/src/components/Login/LoginLinks.tsx

@@ -0,0 +1,73 @@
+import {Button, Card, Container, Flex, Heading, Stack} from '@sanity/ui'
+import {type ReactElement} from 'react'
+
+import {useAuthState} from '../../hooks/auth/useAuthState'
+import {useHandleCallback} from '../../hooks/auth/useHandleCallback'
+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()
+  useHandleCallback()
+
+  if (authState.type === 'logging-in') {
+    return <div>Logging in...</div>
+  }
+
+  // Show success state after authentication
+  if (authState.type === 'logged-in') {
+    return <div>You are logged in</div>
+  }
+
+  /**
+   * Render provider selection UI
+   * Uses Sanity UI components for consistent styling
+   */
+  return (
+    <Card height="fill" overflow="auto" paddingX={4}>
+      <Flex height="fill" direction="column" align="center" justify="center" paddingTop={4}>
+        <Container width={0}>
+          <Stack space={4}>
+            <Heading align="center" size={1}>
+              Choose login provider
+            </Heading>
+
+            <Stack space={2}>
+              {loginUrls.map((provider, index) => (
+                <Button
+                  key={`${provider.url}_${index}`}
+                  as="a"
+                  href={provider.url}
+                  mode="ghost"
+                  tone="default"
+                  space={3}
+                  padding={3}
+                  text={provider.title}
+                />
+              ))}
+            </Stack>
+          </Stack>
+        </Container>
+      </Flex>
+    </Card>
+  )
+}

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

@@ -0,0 +1,103 @@
+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 {beforeEach, describe, expect, it, type MockInstance, vi} from 'vitest'
+
+import {useAuthState} from '../../hooks/auth/useAuthState'
+import {SanityProvider} from '../context/SanityProvider'
+import {AuthBoundary} from './AuthBoundary'
+
+// Mock hooks
+vi.mock('../../hooks/auth/useAuthState', () => ({
+  useAuthState: vi.fn(() => 'logged-out'),
+}))
+vi.mock('../../hooks/auth/useLoginUrls', () => ({
+  useLoginUrls: vi.fn(() => [{title: 'Provider A', url: 'https://provider-a.com/auth'}]),
+}))
+vi.mock('../../hooks/auth/useHandleCallback', () => ({
+  useHandleCallback: vi.fn(() => async () => {}),
+}))
+vi.mock('../../hooks/auth/useLogOut', () => ({
+  useLogOut: vi.fn(() => async () => {}),
+}))
+
+// Mock AuthError throwing scenario
+vi.mock('./AuthError', async (importOriginal) => {
+  const actual = await importOriginal<typeof import('./AuthError')>()
+  return {
+    ...actual,
+    AuthError: class MockAuthError extends Error {
+      constructor(error: Error) {
+        super(error.message)
+        this.name = 'AuthError'
+        this.cause = error
+      }
+    },
+  }
+})
+
+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('AuthBoundary', () => {
+  let consoleErrorSpy: MockInstance
+  beforeEach(() => {
+    vi.clearAllMocks()
+    consoleErrorSpy = vi.spyOn(console, 'error').mockImplementation(() => {})
+  })
+
+  afterEach(() => {
+    consoleErrorSpy?.mockRestore()
+  })
+
+  it('renders the Login component when authState="logged-out"', () => {
+    vi.mocked(useAuthState).mockReturnValue({type: 'logged-out', isDestroyingSession: false})
+    renderWithWrappers(<AuthBoundary>Protected Content</AuthBoundary>)
+
+    // The login screen should show "Choose login provider" by default
+    expect(screen.getByText('Choose login provider')).toBeInTheDocument()
+    expect(screen.queryByText('Protected Content')).not.toBeInTheDocument()
+  })
+
+  it('renders the LoginCallback component when authState="logging-in"', () => {
+    vi.mocked(useAuthState).mockReturnValue({type: 'logging-in', isExchangingToken: false})
+    renderWithWrappers(<AuthBoundary>Protected Content</AuthBoundary>)
+
+    // The callback screen shows "Logging you in…"
+    expect(screen.getByText('Logging you in…')).toBeInTheDocument()
+  })
+
+  it('renders children when authState="logged-in"', () => {
+    vi.mocked(useAuthState).mockReturnValue({
+      type: 'logged-in',
+      currentUser: null,
+      token: 'exampleToken',
+    })
+    renderWithWrappers(<AuthBoundary>Protected Content</AuthBoundary>)
+
+    expect(screen.getByText('Protected Content')).toBeInTheDocument()
+  })
+
+  it('shows the LoginError (via ErrorBoundary) when authState="error"', async () => {
+    vi.mocked(useAuthState).mockReturnValue({type: 'error', error: new Error('test error')})
+    renderWithWrappers(<AuthBoundary>Protected Content</AuthBoundary>)
+
+    // The AuthBoundary should throw an AuthError internally
+    // and then display the LoginError component as the fallback.
+    await waitFor(() => {
+      expect(screen.getByText('Authentication Error')).toBeInTheDocument()
+      expect(
+        screen.getByText('Please try again or contact support if the problem persists.'),
+      ).toBeInTheDocument()
+    })
+  })
+})

package/src/components/auth/AuthBoundary.tsx

@@ -0,0 +1,101 @@
+import {useMemo} from 'react'
+import {ErrorBoundary, type FallbackProps} from 'react-error-boundary'
+
+import {useAuthState} from '../../hooks/auth/useAuthState'
+import {AuthError} from './AuthError'
+import {Login} from './Login'
+import {LoginCallback} from './LoginCallback'
+import {LoginError, type LoginErrorProps} from './LoginError'
+import type {LoginLayoutProps} from './LoginLayout'
+
+/**
+ * @alpha
+ */
+export interface AuthBoundaryProps extends LoginLayoutProps {
+  /**
+   * Custom component to render the login screen.
+   * Receives all login layout props. Defaults to {@link Login}.
+   */
+  LoginComponent?: React.ComponentType<LoginLayoutProps>
+
+  /**
+   * Custom component to render during OAuth callback processing.
+   * Receives all login layout props. Defaults to {@link LoginCallback}.
+   */
+  CallbackComponent?: React.ComponentType<LoginLayoutProps>
+
+  /**
+   * Custom component to render when authentication errors occur.
+   * Receives login layout props and error boundary props. Defaults to
+   * {@link LoginError}
+   */
+  LoginErrorComponent?: React.ComponentType<LoginErrorProps>
+}
+
+/**
+ * A component that handles authentication flow and error boundaries for a
+ * protected section of the application.
+ *
+ * @remarks
+ * This component manages different authentication states and renders the
+ * appropriate components based on that state.
+ *
+ * @example
+ * ```tsx
+ * function App() {
+ *   return (
+ *     <AuthBoundary header={<MyLogo />}>
+ *       <ProtectedContent />
+ *     </AuthBoundary>
+ *   )
+ * }
+ * ```
+ *
+ * @alpha
+ */
+export function AuthBoundary({
+  LoginErrorComponent = LoginError,
+  ...props
+}: AuthBoundaryProps): React.ReactNode {
+  const {header, footer} = props
+  const FallbackComponent = useMemo(() => {
+    return function LoginComponentWithLayoutProps(fallbackProps: FallbackProps) {
+      return <LoginErrorComponent {...fallbackProps} header={header} footer={footer} />
+    }
+  }, [header, footer, LoginErrorComponent])
+
+  return (
+    <ErrorBoundary FallbackComponent={FallbackComponent}>
+      <AuthSwitch {...props} />
+    </ErrorBoundary>
+  )
+}
+
+interface AuthSwitchProps extends LoginLayoutProps {
+  LoginComponent?: React.ComponentType<LoginLayoutProps>
+  CallbackComponent?: React.ComponentType<LoginLayoutProps>
+}
+
+function AuthSwitch({
+  LoginComponent = Login,
+  CallbackComponent = LoginCallback,
+  children,
+  ...props
+}: AuthSwitchProps) {
+  const authState = useAuthState()
+
+  switch (authState.type) {
+    case 'error': {
+      throw new AuthError(authState.error)
+    }
+    case 'logging-in': {
+      return <CallbackComponent {...props} />
+    }
+    case 'logged-in': {
+      return children
+    }
+    default: {
+      return <LoginComponent {...props} />
+    }
+  }
+}

package/src/components/auth/AuthError.test.ts

@@ -0,0 +1,36 @@
+import {describe, expect, it} from 'vitest'
+
+import {AuthError} from './AuthError'
+
+describe('AuthError', () => {
+  it('should use error message if provided', () => {
+    const originalError = new Error('Authentication failed')
+    const authError = new AuthError(originalError)
+
+    expect(authError.message).toBe('Authentication failed')
+    expect(authError.cause).toBe(originalError)
+  })
+
+  it('should handle non-error objects with message property', () => {
+    const customError = {message: 'Custom error message'}
+    const authError = new AuthError(customError)
+
+    expect(authError.message).toBe('Custom error message')
+    expect(authError.cause).toBe(customError)
+  })
+
+  it('should handle errors without message property', () => {
+    const nonError = {foo: 'bar'}
+    const authError = new AuthError(nonError)
+
+    expect(authError.message).toBe('')
+    expect(authError.cause).toBe(nonError)
+  })
+
+  it('should handle primitive error values', () => {
+    const authError = new AuthError('string error')
+
+    expect(authError.message).toBe('')
+    expect(authError.cause).toBe('string error')
+  })
+})

package/src/components/auth/AuthError.ts

@@ -0,0 +1,27 @@
+/**
+ * Error class for authentication-related errors. Wraps errors thrown during the
+ * authentication flow.
+ *
+ * @remarks
+ * This class provides a consistent error type for authentication failures while
+ * preserving the original error as the cause. If the original error has a
+ * message property, it will be used as the error message.
+ *
+ * @alpha
+ */
+export class AuthError extends Error {
+  constructor(error: unknown) {
+    if (
+      typeof error === 'object' &&
+      !!error &&
+      'message' in error &&
+      typeof error.message === 'string'
+    ) {
+      super(error.message)
+    } else {
+      super()
+    }
+
+    this.cause = error
+  }
+}