@sanity/sdk-react 0.0.0-alpha.19 → 0.0.0-alpha.2

package/README.md

@@ -5,64 +5,93 @@
   <h1 align="center">Sanity SDK - React</h1>
 </p>
 
-React hooks for creating Sanity applications.
+React components and hooks for creating Sanity applications.
 
-## 💻 Installation
+## Installation
 
 ```bash
-npm i @sanity/sdk-react @sanity/sdk
+npm i @sanity/sdk-react @sanity/sdk styled-components
 ```
 
-> 💡 Looking to build a Sanity application? Check out the [Quick Start](#quick-start) section.
-
-## 📚 SDK Documentation
+## SDK Documentation
 
 See the [SDK Documentation](https://sdk-docs.sanity.dev) for more information.
 
-## 🚀 Quick Start
+## Quick Start
 
 Here's how to implement your Sanity application:
 
-1. Create a new React TypeScript project using the Sanity template
-
-```bash
-pnpx sanity@latest init --template core-app
-cd my-content-os-app
+```tsx
+import {createSanityInstance} from '@sanity/sdk'
+import {AuthBoundary, SanityProvider} from '@sanity/sdk-react/components'
+import {useCurrentUser, useLogOut} from '@sanity/sdk-react/hooks'
+import {Button, Flex, Spinner, Text, ThemeProvider} from '@sanity/ui'
+import {buildTheme} from '@sanity/ui/theme'
+import {Suspense} from 'react'
+
+const theme = buildTheme({})
+const sanityInstance = createSanityInstance({
+  projectId: '<your-project-id>',
+  dataset: '<your-dataset>',
+  // optional auth config set projectId and dataset to '' and authScope to 'org' for a global token
+  // auth: {
+  //   authScope: 'org',
+  //   ...
+  // },
+})
+
+export function App(): JSX.Element {
+  return (
+    <ThemeProvider theme={theme}>
+      <Suspense fallback={<Spinner />}>
+        <SanityProvider sanityInstance={sanityInstance}>
+          <AuthBoundary header={<Text>My Sanity App</Text>}>
+            <Authenticated />
+          </AuthBoundary>
+        </SanityProvider>
+      </Suspense>
+    </ThemeProvider>
+  )
+}
+
+function Authenticated() {
+  const currentUser = useCurrentUser()
+  const logout = useLogOut()
+
+  return (
+    <Flex direction="column" gap={2}>
+      <Text>Hello, {currentUser?.name}!</Text>
+      <Button text="Logout" onClick={logout} mode="ghost" />
+    </Flex>
+  )
+}
 ```
 
-2. Install dependencies
+## Customizing your application
 
-```bash
-npm i
-```
+If you would like to implement a custom look and feel, you can use the hooks in your own components.
 
-3. Run the app
+## Available Hooks
 
-```bash
-npm run dev
-```
-
-4. Open the App in Sanity Dashboard with your organization ID
+- `useAuthState` - Get current authentication state
+- `useCurrentUser` - Access the currently authenticated user
+- `useAuthToken` - Access the authentication token
+- `useLoginUrls` - Get OAuth login URLs
+- `useLogOut` - Handle user logout
+- `useSanityInstance` - Access the Sanity client instance
+- and more...
 
-```
-https://core.sanity.io/<your-organization-id>?dev=http://localhost:3333
-```
+## TypeScript Support
 
-5. Update the `src/App.tsx` file with your Sanity project and dataset
+This package includes TypeScript definitions. You can import types like:
 
 ```tsx
-// src/App.tsx
-import {createSanityInstance} from '@sanity/sdk'
-...
-
-const sanityConfig: SanityConfigs = [
-  {
-    projectId: 'abc123',
-    dataset: 'production',
-  },
-]
-
-...
+import type {
+  SanityProviderProps,
+  AuthBoundaryProps,
+  LoginLayoutProps,
+  LoginErrorProps,
+} from '@sanity/react'
 ```
 
 ## License

package/dist/_chunks-es/useLogOut.js

@@ -0,0 +1,44 @@
+import { getAuthState, getLoginUrlsState, fetchLoginUrls, handleCallback, logout } from "@sanity/sdk";
+import { createContext, useContext, useMemo, useSyncExternalStore, useCallback } from "react";
+import { jsx } from "react/jsx-runtime";
+const SanityInstanceContext = createContext(null), SanityProvider = ({ children, sanityInstance }) => /* @__PURE__ */ jsx(SanityInstanceContext.Provider, { value: sanityInstance, children }), useSanityInstance = () => {
+  const sanityInstance = useContext(SanityInstanceContext);
+  if (!sanityInstance)
+    throw new Error("useSanityInstance must be called from within the SanityProvider");
+  return sanityInstance;
+};
+function createStateSourceHook(stateSourceFactory) {
+  function useHook(...params) {
+    const instance = useSanityInstance(), { subscribe, getCurrent } = useMemo(
+      () => stateSourceFactory(instance, ...params),
+      // eslint-disable-next-line react-hooks/exhaustive-deps
+      [instance, ...params]
+    );
+    return useSyncExternalStore(subscribe, getCurrent);
+  }
+  return useHook;
+}
+const useAuthState = createStateSourceHook(getAuthState);
+function useLoginUrls() {
+  const instance = useSanityInstance(), { subscribe, getCurrent } = useMemo(() => getLoginUrlsState(instance), [instance]);
+  if (!getCurrent()) throw fetchLoginUrls(instance);
+  return useSyncExternalStore(subscribe, getCurrent);
+}
+function createCallbackHook(callback) {
+  function useHook() {
+    const instance = useSanityInstance();
+    return useCallback((...params) => callback(instance, ...params), [instance]);
+  }
+  return useHook;
+}
+const useHandleCallback = createCallbackHook(handleCallback), useLogOut = createCallbackHook(logout);
+export {
+  SanityProvider,
+  createStateSourceHook,
+  useAuthState,
+  useHandleCallback,
+  useLogOut,
+  useLoginUrls,
+  useSanityInstance
+};
+//# sourceMappingURL=useLogOut.js.map

package/dist/_chunks-es/useLogOut.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useLogOut.js","sources":["../../src/components/context/SanityProvider.tsx","../../src/hooks/context/useSanityInstance.ts","../../src/hooks/helpers/createStateSourceHook.tsx","../../src/hooks/auth/useAuthState.tsx","../../src/hooks/auth/useLoginUrls.tsx","../../src/hooks/helpers/createCallbackHook.tsx","../../src/hooks/auth/useHandleCallback.tsx","../../src/hooks/auth/useLogOut.tsx"],"sourcesContent":["import {type SanityInstance} from '@sanity/sdk'\nimport {createContext, type ReactElement} from 'react'\n\n/**\n * @public\n */\nexport interface SanityProviderProps {\n  children: React.ReactNode\n  sanityInstance: SanityInstance\n}\n\nexport const SanityInstanceContext = createContext<SanityInstance | null>(null)\n\n/**\n * Top-level context provider that provides a Sanity configuration instance.\n * This must wrap any Sanity SDK React component.\n * @public\n * @param props - Sanity project and dataset configuration\n * @returns Rendered component\n * @example\n * ```tsx\n * import {createSanityInstance} from '@sanity/sdk'\n * import {ExampleComponent, SanityProvider} from '@sanity/sdk-react'\n *\n * const sanityInstance = createSanityInstance({projectId: 'your-project-id', dataset: 'production'})\n *\n * export default function MyApp() {\n *   return (\n *     <SanityProvider sanityInstance={sanityInstance}>\n *      <ExampleComponent />\n *     </SanityProvider>\n *   )\n * }\n * ```\n */\nexport const SanityProvider = ({children, sanityInstance}: SanityProviderProps): ReactElement => {\n  return (\n    <SanityInstanceContext.Provider value={sanityInstance}>\n      {children}\n    </SanityInstanceContext.Provider>\n  )\n}\n","import type {SanityInstance} from '@sanity/sdk'\nimport {useContext} from 'react'\n\nimport {SanityInstanceContext} from '../../components/context/SanityProvider'\n\n/**\n * Hook that provides the current Sanity instance from the context.\n * This must be called from within a `SanityProvider` component.\n * @public\n * @returns the current Sanity instance\n * @example\n * ```tsx\n * const instance = useSanityInstance()\n * ```\n */\nexport const useSanityInstance = (): SanityInstance => {\n  const sanityInstance = useContext(SanityInstanceContext)\n  if (!sanityInstance) {\n    throw new Error('useSanityInstance must be called from within the SanityProvider')\n  }\n\n  return sanityInstance\n}\n","import type {SanityInstance, StateSource} from '@sanity/sdk'\nimport {useMemo, useSyncExternalStore} from 'react'\n\nimport {useSanityInstance} from '../context/useSanityInstance'\n\nexport function createStateSourceHook<TParams extends unknown[], TState>(\n  stateSourceFactory: (instance: SanityInstance, ...params: TParams) => StateSource<TState>,\n): (...params: TParams) => TState {\n  function useHook(...params: TParams) {\n    const instance = useSanityInstance()\n    const {subscribe, getCurrent} = useMemo(\n      () => stateSourceFactory(instance, ...params),\n      // eslint-disable-next-line react-hooks/exhaustive-deps\n      [instance, ...params],\n    )\n\n    return useSyncExternalStore(subscribe, getCurrent)\n  }\n\n  return useHook\n}\n","import {getAuthState} from '@sanity/sdk'\n\nimport {createStateSourceHook} from '../helpers/createStateSourceHook'\n\n/**\n * A React hook that subscribes to authentication state changes.\n *\n * This hook provides access to the current authentication state type from the Sanity auth store.\n * It automatically re-renders the component when the authentication state changes.\n *\n * @remarks\n * The hook uses `useSyncExternalStore` to safely subscribe to auth state changes\n * and ensure consistency between server and client rendering.\n *\n * @returns The current authentication state type\n *\n * @example\n * ```tsx\n * function AuthStatus() {\n *   const authState = useAuthState()\n *   return <div>Current auth state: {authState}</div>\n * }\n * ```\n *\n * @public\n */\nexport const useAuthState = createStateSourceHook(getAuthState)\n","import {type AuthProvider, fetchLoginUrls, getLoginUrlsState} from '@sanity/sdk'\nimport {useMemo, useSyncExternalStore} from 'react'\n\nimport {useSanityInstance} from '../context/useSanityInstance'\n\n/**\n * A React hook that retrieves the available authentication provider URLs for login.\n *\n * @remarks\n * This hook fetches the login URLs from the Sanity auth store when the component mounts.\n * Each provider object contains information about an authentication method, including its URL.\n * The hook will suspend if the login URLs have not yet loaded.\n *\n * @example\n * ```tsx\n * // LoginProviders component that uses the hook\n * function LoginProviders() {\n *   const providers = useLoginUrls()\n *\n *   return (\n *     <div>\n *       {providers.map((provider) => (\n *         <a key={provider.name} href={provider.url}>\n *           Login with {provider.title}\n *         </a>\n *       ))}\n *     </div>\n *   )\n * }\n *\n * // Parent component with Suspense boundary\n * function LoginPage() {\n *   return (\n *     <Suspense fallback={<div>Loading authentication providers...</div>}>\n *       <LoginProviders />\n *     </Suspense>\n *   )\n * }\n * ```\n *\n * @returns An array of {@link AuthProvider} objects containing login URLs and provider information\n * @public\n */\nexport function useLoginUrls(): AuthProvider[] {\n  const instance = useSanityInstance()\n  const {subscribe, getCurrent} = useMemo(() => getLoginUrlsState(instance), [instance])\n\n  if (!getCurrent()) throw fetchLoginUrls(instance)\n\n  return useSyncExternalStore(subscribe, getCurrent as () => AuthProvider[])\n}\n","import type {SanityInstance} from '@sanity/sdk'\nimport {useCallback} from 'react'\n\nimport {useSanityInstance} from '../context/useSanityInstance'\n\nexport function createCallbackHook<TParams extends unknown[], TReturn>(\n  callback: (instance: SanityInstance, ...params: TParams) => TReturn,\n): () => (...params: TParams) => TReturn {\n  function useHook() {\n    const instance = useSanityInstance()\n    return useCallback((...params: TParams) => callback(instance, ...params), [instance])\n  }\n\n  return useHook\n}\n","import {handleCallback} from '@sanity/sdk'\n\nimport {createCallbackHook} from '../helpers/createCallbackHook'\n\n/**\n * A React hook that returns a function for handling authentication callbacks.\n *\n * @remarks\n * This hook provides access to the authentication store's callback handler,\n * which processes auth redirects by extracting the session ID and fetching the\n * authentication token. If fetching the long-lived token is successful,\n * `handleCallback` will return a Promise that resolves a new location that\n * removes the short-lived token from the URL. Use this in combination with\n * `history.replaceState` or your own router's `replace` function to update the\n * current location without triggering a reload.\n *\n * @example\n * ```tsx\n * function AuthCallback() {\n *   const handleCallback = useHandleCallback()\n *   const router = useRouter() // Example router\n *\n *   useEffect(() => {\n *     async function processCallback() {\n *       // Handle the callback and get the cleaned URL\n *       const newUrl = await handleCallback(window.location.href)\n *\n *       if (newUrl) {\n *         // Replace URL without triggering navigation\n *         router.replace(newUrl, {shallow: true})\n *       }\n *     }\n *\n *     processCallback().catch(console.error)\n *   }, [handleCallback, router])\n *\n *   return <div>Completing login...</div>\n * }\n * ```\n *\n * @returns A callback handler function that processes OAuth redirects\n * @public\n */\nexport const useHandleCallback = createCallbackHook(handleCallback)\n","import {logout} from '@sanity/sdk'\n\nimport {createCallbackHook} from '../helpers/createCallbackHook'\n\n/**\n * Hook to log out of the current session\n * @public\n * @returns A function to log out of the current session\n */\nexport const useLogOut = createCallbackHook(logout)\n"],"names":[],"mappings":";;;AAWO,MAAM,wBAAwB,cAAqC,IAAI,GAwBjE,iBAAiB,CAAC,EAAC,UAAU,eAAc,0BAEnD,sBAAsB,UAAtB,EAA+B,OAAO,gBACpC,SACH,CAAA,GCxBS,oBAAoB,MAAsB;AAC/C,QAAA,iBAAiB,WAAW,qBAAqB;AACvD,MAAI,CAAC;AACG,UAAA,IAAI,MAAM,iEAAiE;AAG5E,SAAA;AACT;ACjBO,SAAS,sBACd,oBACgC;AAChC,WAAS,WAAW,QAAiB;AACnC,UAAM,WAAW,kBAAkB,GAC7B,EAAC,WAAW,WAAc,IAAA;AAAA,MAC9B,MAAM,mBAAmB,UAAU,GAAG,MAAM;AAAA;AAAA,MAE5C,CAAC,UAAU,GAAG,MAAM;AAAA,IACtB;AAEO,WAAA,qBAAqB,WAAW,UAAU;AAAA,EAAA;AAG5C,SAAA;AACT;ACMa,MAAA,eAAe,sBAAsB,YAAY;ACiBvD,SAAS,eAA+B;AAC7C,QAAM,WAAW,qBACX,EAAC,WAAW,WAAU,IAAI,QAAQ,MAAM,kBAAkB,QAAQ,GAAG,CAAC,QAAQ,CAAC;AAErF,MAAI,CAAC,WAAA,EAAc,OAAM,eAAe,QAAQ;AAEzC,SAAA,qBAAqB,WAAW,UAAkC;AAC3E;AC7CO,SAAS,mBACd,UACuC;AACvC,WAAS,UAAU;AACjB,UAAM,WAAW,kBAAkB;AAC5B,WAAA,YAAY,IAAI,WAAoB,SAAS,UAAU,GAAG,MAAM,GAAG,CAAC,QAAQ,CAAC;AAAA,EAAA;AAG/E,SAAA;AACT;AC6Ba,MAAA,oBAAoB,mBAAmB,cAAc,GClCrD,YAAY,mBAAmB,MAAM;"}

package/dist/assets/bundle-CcAyERuZ.css

@@ -0,0 +1,11 @@
+@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/dist/components.d.ts

@@ -0,0 +1,257 @@
+import {FallbackProps} from 'react-error-boundary'
+import {ForwardRefExoticComponent} from 'react'
+import type {PropsWithChildren} from 'react'
+import {ReactElement} from 'react'
+import {RefAttributes} from 'react'
+import {SanityInstance} from '@sanity/sdk'
+
+/**
+ * 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 declare function AuthBoundary({
+  LoginErrorComponent,
+  ...props
+}: AuthBoundaryProps): React.ReactNode
+
+/**
+ * @alpha
+ */
+export declare 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>
+}
+
+/**
+ * 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 declare class AuthError extends Error {
+  constructor(error: unknown)
+}
+
+/**
+ * @public
+ */
+export declare const DocumentGridLayout: {
+  (props: PropsWithChildren): ReactElement
+  displayName: string
+}
+
+/**
+ * @public
+ */
+export declare const DocumentListLayout: {
+  (props: PropsWithChildren): ReactElement
+  displayName: string
+}
+
+/**
+ * This is a component that renders a document preview.
+ *
+ * @public
+ *
+ * @param props - The props for the DocumentPreviewLayout component.
+ * @returns - The DocumentPreviewLayout component.
+ */
+export declare const DocumentPreviewLayout: ForwardRefExoticComponent<
+  DocumentPreviewLayoutProps & RefAttributes<HTMLElement>
+>
+
+/**
+ * @public
+ */
+export declare interface DocumentPreviewLayoutProps {
+  docType?: string
+  media?:
+    | {
+        type: string
+        url: string
+      }
+    | null
+    | undefined
+  onClick?: () => void
+  selected?: boolean
+  status?: string
+  subtitle?: string
+  title: string
+}
+
+/**
+ * Login component that displays available authentication providers.
+ * Renders a list of login options with a loading fallback while providers load.
+ *
+ * @alpha
+ */
+export declare function Login({header, footer}: LoginLayoutProps): JSX.Element
+
+/**
+ * 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 declare function LoginCallback({header, footer}: LoginLayoutProps): React.ReactNode
+
+/**
+ * Displays authentication error details and provides retry functionality.
+ * Only handles {@link AuthError} instances - rethrows other error types.
+ *
+ * @alpha
+ */
+export declare function LoginError({
+  error,
+  resetErrorBoundary,
+  header,
+  footer,
+}: LoginErrorProps): React.ReactNode
+
+/**
+ * @alpha
+ */
+export declare type LoginErrorProps = FallbackProps & LoginLayoutProps
+
+/**
+ * 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 declare function LoginLayout({children, footer, header}: LoginLayoutProps): React.ReactNode
+
+/**
+ * @alpha
+ */
+export declare 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
+}
+
+/**
+ * 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 declare const LoginLinks: () => ReactElement
+
+/**
+ * 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 declare const SanityProvider: ({
+  children,
+  sanityInstance,
+}: SanityProviderProps) => ReactElement
+
+/**
+ * @public
+ */
+export declare interface SanityProviderProps {
+  children: React.ReactNode
+  sanityInstance: SanityInstance
+}
+
+export {}