refactor(react): update useDocument to return data (#510)

* refactor: update useDocument hook to return data under a `data` for consistency across the SDK

* fix: ensure useDocument hook returns an empty string as default for name

* fix: correct path parameter in useEditDocument hook for clarity

* Update 0-Migration-Guide.md

Co-authored-by: Cole Peters <[email protected]>

---------

Co-authored-by: Cole Peters <[email protected]>

Author: ricokahler

apps/kitchensink-react/src/DocumentCollection/DocumentEditorRoute.tsx

@@ -37,12 +37,12 @@ function Editor() {
   const canUnpublish = useDocumentPermissions(unpublishDocument(docHandle))
   const canDiscard = useDocumentPermissions(discardDocument(docHandle))
 
-  const name = useDocument({...docHandle, path: 'name'}) ?? ''
+  const {data: name = ''} = useDocument({...docHandle, path: 'name'})
   const setName = useEditDocument({...docHandle, path: 'name'})
 
   const [value, setValue] = useState('')
 
-  const document = useDocument({...docHandle})
+  const {data: document} = useDocument({...docHandle})
   const setDocument = useEditDocument(docHandle)
 
   return (

apps/kitchensink-react/src/DocumentCollection/MultiResourceRoute.tsx

@@ -17,8 +17,8 @@ const doc2 = createDocumentHandle({
 })
 
 export function MultiResourceRoute(): JSX.Element {
-  const author = useDocument(doc)
-  const dog = useDocument(doc2)
+  const {data: author} = useDocument(doc)
+  const {data: dog} = useDocument(doc2)
   const setAuthorName = useEditDocument({...doc, path: 'name'})
   const setDogName = useEditDocument({...doc2, path: 'name'})
 

apps/kitchensink-react/src/DocumentCollection/OrgDocumentExplorerRoute.tsx

@@ -51,7 +51,7 @@ function DocumentEditorDialog({
   open,
 }: DocumentEditorDialogProps) {
   const handle = {documentId, documentType}
-  const document = useDocument(handle)
+  const {data: document} = useDocument(handle)
   const editDocument = useEditDocument(handle)
   const isSaving = useDocumentSyncStatus(handle)
 

packages/react/guides/0-Migration-Guide.md

@@ -166,6 +166,42 @@ Also renamed associated types to match:
 - `UseProjectionOptions` → `useDocumentProjectionOptions`
 - `UseProjectionResults` → `useDocumentProjectionResults`
 
+3. Updated `useDocument` return structure
+
+The `useDocument` hook now returns its data under a `data` property for consistency with other hooks in the SDK.
+
+**Before:**
+
+```typescript
+// Full document
+const product = useDocument({documentId: '123', documentType: 'product'})
+console.log(product?.title)
+
+// Path selection
+const title = useDocument({
+  documentId: '123',
+  documentType: 'product',
+  path: 'title',
+})
+console.log(title)
+```
+
+**After:**
+
+```typescript
+// Full document - now returns {data: T | null}
+const {data: product} = useDocument({documentId: '123', documentType: 'product'})
+console.log(product?.title) // product is possibly null
+
+// Path selection - now returns {data: T | undefined}
+const {data: title} = useDocument({
+  documentId: '123',
+  documentType: 'product',
+  path: 'title',
+})
+console.log(title) // title is possibly undefined
+```
+
 ## Migrating to @sanity/sdk-react@0.0.0-rc.7
 
 This version introduces significant improvements for TypeScript users by integrating [Sanity TypeGen](https://www.sanity.io/docs/sanity-typegen). While Typegen is optional, using it unlocks strong type safety for documents, queries, and projections. These changes also refine hook signatures for better consistency, even for JavaScript users.

packages/react/src/hooks/document/useDocument.test.ts

@@ -85,7 +85,7 @@ describe('useDocument hook', () => {
 
     const {result} = renderHook(() => useDocument({documentId: 'doc1', documentType: 'book'}))
 
-    expect(result.current).toEqual(book)
+    expect(result.current.data).toEqual(book)
     expect(getCurrent).toHaveBeenCalled()
     expect(subscribe).toHaveBeenCalled()
   })

packages/react/src/hooks/document/useDocument.ts

@@ -9,11 +9,35 @@ import type {useDocumentProjection} from '../projection/useDocumentProjection'
 // eslint-disable-next-line import/consistent-type-specifier-style, unused-imports/no-unused-imports
 import type {useQuery} from '../query/useQuery'
 
+const useDocumentValue = createStateSourceHook({
+  // Pass options directly to getDocumentState
+  getState: (instance, options: DocumentOptions<string | undefined>) =>
+    getDocumentState(instance, options),
+  // Pass options directly to getDocumentState for checking current value
+  shouldSuspend: (instance, {path: _path, ...options}: DocumentOptions<string | undefined>) =>
+    getDocumentState(instance, options).getCurrent() === undefined,
+  // Extract handle part for resolveDocument
+  suspender: (instance, options: DocumentOptions<string | undefined>) =>
+    resolveDocument(instance, options),
+  getConfig: identity as (
+    options: DocumentOptions<string | undefined>,
+  ) => DocumentOptions<string | undefined>,
+})
+
+const wrapHookWithData = <TParams extends unknown[], TReturn>(
+  useValue: (...params: TParams) => TReturn,
+) => {
+  function useHook(...params: TParams) {
+    return {data: useValue(...params)}
+  }
+  return useHook
+}
+
 interface UseDocument {
   /** @internal */
   <TDocumentType extends string, TDataset extends string, TProjectId extends string = string>(
     options: DocumentOptions<undefined, TDocumentType, TDataset, TProjectId>,
-  ): SanityDocumentResult<TDocumentType, TDataset, TProjectId> | null
+  ): {data: SanityDocumentResult<TDocumentType, TDataset, TProjectId> | null}
 
   /** @internal */
   <
@@ -23,12 +47,12 @@ interface UseDocument {
     TProjectId extends string = string,
   >(
     options: DocumentOptions<TPath, TDocumentType, TDataset, TProjectId>,
-  ): JsonMatch<SanityDocumentResult<TDocumentType, TDataset, TProjectId>, TPath> | undefined
+  ): {data: JsonMatch<SanityDocumentResult<TDocumentType, TDataset, TProjectId>, TPath> | undefined}
 
   /** @internal */
-  <TData>(options: DocumentOptions<undefined>): TData | null
+  <TData>(options: DocumentOptions<undefined>): {data: TData | null}
   /** @internal */
-  <TData>(options: DocumentOptions<string>): TData | undefined
+  <TData>(options: DocumentOptions<string>): {data: TData | undefined}
 
   /**
    * ## useDocument via Type Inference (Recommended)
@@ -68,7 +92,7 @@ interface UseDocument {
    * }
    *
    * function ProductView({doc}: ProductViewProps) {
-   *   const product = useDocument({...doc}) // Fully typed product
+   *   const {data: product} = useDocument({...doc}) // Fully typed product
    *   return <h1>{product.title ?? 'Untitled'}</h1>
    * }
    * ```
@@ -82,7 +106,7 @@ interface UseDocument {
    * }
    *
    * function ProductTitle({doc}: ProductTitleProps) {
-   *   const title = useDocument({
+   *   const {data: title} = useDocument({
    *     ...doc,
    *     path: 'title' // Returns just the title field
    *   })
@@ -100,8 +124,12 @@ interface UseDocument {
   >(
     options: DocumentOptions<TPath, TDocumentType, TDataset, TProjectId>,
   ): TPath extends string
-    ? JsonMatch<SanityDocumentResult<TDocumentType, TDataset, TProjectId>, TPath> | undefined
-    : SanityDocumentResult<TDocumentType, TDataset, TProjectId> | null
+    ? {
+        data:
+          | JsonMatch<SanityDocumentResult<TDocumentType, TDataset, TProjectId>, TPath>
+          | undefined
+      }
+    : {data: SanityDocumentResult<TDocumentType, TDataset, TProjectId> | null}
 
   /**
    * @beta
@@ -142,7 +170,7 @@ interface UseDocument {
    * }
    *
    * function BookView({doc}: BookViewProps) {
-   *   const book = useDocument<Book>({...doc})
+   *   const {data: book} = useDocument<Book>({...doc})
    *   return <h1>{book?.title ?? 'Untitled'} by {book?.author ?? 'Unknown'}</h1>
    * }
    * ```
@@ -156,7 +184,7 @@ interface UseDocument {
    * }
    *
    * function BookTitle({doc}: BookTitleProps) {
-   *   const title = useDocument<string>({...doc, path: 'title'})
+   *   const {data: title} = useDocument<string>({...doc, path: 'title'})
    *   return <h1>{title ?? 'Untitled'}</h1>
    * }
    * ```
@@ -165,12 +193,12 @@ interface UseDocument {
    */
   <TData, TPath extends string>(
     options: DocumentOptions<TPath>,
-  ): TPath extends string ? TData | undefined : TData | null
+  ): TPath extends string ? {data: TData | undefined} : {data: TData | null}
 
   /**
    * @internal
    */
-  (options: DocumentOptions): unknown
+  (options: DocumentOptions): {data: unknown}
 }
 
 /**
@@ -196,17 +224,4 @@ interface UseDocument {
  *
  * @function
  */
-export const useDocument = createStateSourceHook({
-  // Pass options directly to getDocumentState
-  getState: (instance, options: DocumentOptions<string | undefined>) =>
-    getDocumentState(instance, options),
-  // Pass options directly to getDocumentState for checking current value
-  shouldSuspend: (instance, {path: _path, ...options}: DocumentOptions<string | undefined>) =>
-    getDocumentState(instance, options).getCurrent() === undefined,
-  // Extract handle part for resolveDocument
-  suspender: (instance, options: DocumentOptions<string | undefined>) =>
-    resolveDocument(instance, options),
-  getConfig: identity as (
-    options: DocumentOptions<string | undefined>,
-  ) => DocumentOptions<string | undefined>,
-}) as UseDocument
+export const useDocument = wrapHookWithData(useDocumentValue) as UseDocument

packages/react/src/hooks/document/useEditDocument.ts

@@ -115,7 +115,7 @@ export function useEditDocument<TData>(
  *
  * function ProductEditor({ productHandle }: ProductEditorProps) {
  *   // Fetch the document to display its current state (optional)
- *   const product = useDocument(productHandle);
+ *   const {data: product} = useDocument(productHandle);
  *   // Get the edit function for the full document
  *   const editProduct = useEditDocument(productHandle);
  *
@@ -162,7 +162,7 @@ export function useEditDocument<TData>(
  *   };
  *
  *   // Fetch the current price to display it
- *   const currentPrice = useDocument(priceOptions);
+ *   const {data: currentPrice} = useDocument(priceOptions);
  *   // Get the edit function for the specific path 'price'
  *   const editPrice = useEditDocument(priceOptions);
  *
@@ -195,7 +195,7 @@ export function useEditDocument<TData>(
  * }
  *
  * function BookEditor({ bookHandle }: BookEditorProps) {
- *   const book = useDocument<Book>(bookHandle);
+ *   const {data: book} = useDocument<Book>(bookHandle);
  *   // Provide the explicit type <Book>
  *   const editBook = useEditDocument<Book>(bookHandle);
  *
@@ -235,9 +235,9 @@ export function useEditDocument<TData>(
  *
  * function AuthorNameEditor({ bookHandle }: AuthorNameEditorProps) {*
  *   // Fetch current value
- *   const currentName = useDocument<string>({...bookHandle, path: 'author.name'});
+ *   const {data: currentName} = useDocument<string>({...bookHandle, path: 'author.name'});
  *   // Provide the explicit type <string> for the path's value
- *   const editAuthorName = useEditDocument<string>({...bookHandle, 'author.name'});
+ *   const editAuthorName = useEditDocument<string>({...bookHandle, path: 'author.name'});
  *
  *   const handleUpdate = useCallback(() => {
  *     // Update with a hardcoded string directly