refactor: new resource architecture and updated document handles (#374)

* refactor: new store management and action binding (#344)

* refactor: update store management

* refactor(react): enhance disposal management in ResourceProvider

* refactor(client): update client to new store management (#345)

* feat(client): enhance client management with improved token handling and configuration validation

- Refactored client store to manage clients based on token changes and configuration updates.
- Introduced validation for disallowed configuration keys in `getClient`.
- Updated tests to cover new client creation logic and token handling scenarios.
- Enhanced `useClient` hook to utilize the new configuration structure.

* refactor(auth): update auth to new store management (#346)

* refactor(auth): streamline authentication store and improve test coverage

- Refactored authentication store to utilize a more modular structure with improved action binding.
- Updated tests for `authStore`, `fetchLoginUrls`, `handleCallback`, and `logout`.
- Removed deprecated interfaces and streamlined state management for better maintainability.

* refactor: update query, projection, and preview stores (#347)

* refactor: update query, projection, and preview stores

- Deleted the `createLiveEventSubscriber` function and its associated test file
- Refactored preview and projection stores to eliminate dependencies on the removed functionality.
- Moved `hashString` utility for consistent string hashing, along with corresponding tests.
- Updated various components and hooks to utilize the new document handle structure.

* fix: improve preview/projection handling and abort control

- Remove unused documentTypes from PreviewStoreState
- Implement proper abort control for in-flight requests in preview/projection
- Add PREVIEW_PERSPECTIVE and PROJECTION_PERSPECTIVE constants
- Optimize subscription handling with isSetEqual helper
- Fix useQuery hook to use useRef instead of useState for AbortController
- Add proper error handling and state management for preview/projection queries
- Improve test coverage for abort scenarios

* refactor(react): remove deprecated `document` property

* fix(react): improve useQuery hook's abort signal handling

- Update useQuery to capture the current abort signal in a local variable during suspension
- Refactor the return statement to use useMemo since the compiler is disabled

* fix: use `v2025-02-19` API version for query store

* fix: update QUERY_STORE_API_VERSION to use 'vX' for text::query groq function

* refactor(comlink): update to new store management (#348)

* refactor(comlink): enhance store structure and improve test coverage

- Refactored comlink controller and node to utilize a more modular structure with action binding.
- Updated tests for comlink actions including `destroyController`, `getOrCreateChannel`, and
`releaseNode` to improve coverage and reliability.
- Adjusted state management in tests to align with the new store structure.
- Renamed document handle properties in hooks for consistency and clarity.

* refactor: rename workspace handling

- Rename `useStudioWorkspacesByResourceId` to `useStudioWorkspacesByProjectIdDataset` for clarity
- Remove dependency on resource ID parsing in favor of direct projectId/dataset usage
- Remove documentTypes tracking in preview state test
- Update workspace navigation to use direct projectId/dataset instead of parsing from resourceId
- Improve error messages with more specific context
- Remove old test files in favor of new implementation

* refactor(document): update to new store management (#349)

* refactor(document): standardize document handle structure and enhance action handling

- Updated document handle properties to use `documentId` and `documentType` for
consistency across the codebase.
- Refactored document action functions to utilize the new document handle structure.
- Improved test coverage for document actions and applied actions to ensure correct behavior with
the updated structure.
- Enhanced hooks and components to align with the new document handling conventions, ensuring better
integration with the Sanity instance context.

* refactor: new store management for users, projects, and datasets (#350)

* refactor(users): enhance user store and hooks for improved functionality

- Refactored user store to streamline state management and improve action handling.
- Updated `useUsers` hook to support project and organization parameters, enhancing flexibility.
- Improved test coverage for user-related hooks and store functionalities.
- Introduced new utility functions for better key management and state resolution.
- Removed deprecated tests and consolidated user fetching logic for clarity and maintainability.

* refactor(project): improve project fetching logic and enhance parameter handling

- Updated project fetcher to utilize projectId from options or instance for better flexibility.
- Refactored createFetcherStore to include instance in StoreEntry for improved context management.
- Enhanced initialization and subscription handling for clearer state management and observability.

* fix: update API_VERSIONs and tag prefix

* fix: add `@function` back

* feat(kitchensink-react): add OrgDocumentExplorerRoute (#351)

* refactor(kitchensink-react): standardize document handling and enhance routing

- Removed deprecated `@sanity/mutate` dependency from the project.
- Introduced `OrgDocumentExplorerRoute` for improved document organization and navigation.
- Updated document handling to use `documentId` and `documentType` consistently across components.
- Refactored document-related components to enhance readability and maintainability.
- Improved user interface elements for document previews and lists, ensuring better user experience.
- Adjusted routing structure to accommodate new document exploration features.

* refactor(kitchensink-react): update orgdocumentexplorer

fix: update import to usePaginatedDocuments

* docs: add advanced resource management guide

* docs: update migration guide

* docs: update migration guide examples

* refactor: remove comments from exports

* fix: fix bug with document types resetting

* refactor: add SDKProvider back in

* chore: delete old guide

* chore: use projectId and dataset in debug store names

* docs: remove tip about Advanced Resource Management Guide from Migration Guide

---------

Co-authored-by: Ryan Bonial <[email protected]>

Author: ricokahler

apps/kitchensink-react/package.json

@@ -15,7 +15,6 @@
   "dependencies": {
     "@paramour/css": "1.0.0-rc.2",
     "@sanity/icons": "^3.7.0",
-    "@sanity/mutate": "^0.12.3",
     "@sanity/sdk": "workspace:*",
     "@sanity/sdk-react": "workspace:*",
     "@sanity/types": "^3.79.0",

apps/kitchensink-react/src/App.tsx

@@ -23,7 +23,7 @@ const sanityConfigs: SanityConfig[] = [
 export function App(): JSX.Element {
   return (
     <ThemeProvider theme={theme}>
-      <SanityApp sanityConfigs={sanityConfigs} fallback={<Spinner />}>
+      <SanityApp fallback={<Spinner />} config={sanityConfigs}>
         <BrowserRouter>
           <AppRoutes />
         </BrowserRouter>

apps/kitchensink-react/src/AppRoutes.tsx

@@ -9,6 +9,7 @@ import {DocumentGridRoute} from './DocumentCollection/DocumentGridRoute'
 import {DocumentListRoute} from './DocumentCollection/DocumentListRoute'
 import {DocumentProjectionRoute} from './DocumentCollection/DocumentProjectionRoute'
 import {MultiResourceRoute} from './DocumentCollection/MultiResourceRoute'
+import {OrgDocumentExplorerRoute} from './DocumentCollection/OrgDocumentExplorerRoute'
 import {SearchRoute} from './DocumentCollection/SearchRoute'
 import {ProjectAuthHome} from './ProjectAuthentication/ProjectAuthHome'
 import {ProtectedRoute} from './ProtectedRoute'
@@ -37,6 +38,10 @@ const documentCollectionRoutes = [
     path: 'multi-resource',
     element: <MultiResourceRoute />,
   },
+  {
+    path: 'org-document-explorer',
+    element: <OrgDocumentExplorerRoute />,
+  },
   {
     path: 'search',
     element: <SearchRoute />,

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

@@ -12,26 +12,19 @@ import {DocumentListLayout} from '../components/DocumentListLayout/DocumentListL
 import {DocumentPreview} from './DocumentPreview'
 import {LoadMore} from './LoadMore'
 
-function ActionButtons({document}: {document: DocumentHandle}) {
+function ActionButtons(docHandle: DocumentHandle) {
   const {
     favorite,
     unfavorite,
     isFavorited,
     isConnected: isFavoriteConnected,
-  } = useManageFavorite({
-    documentId: document._id,
-    documentType: document._type,
-    resourceType: 'studio',
-    resourceId: document.resourceId,
-  })
+  } = useManageFavorite({...docHandle, resourceType: 'studio'})
   const {recordEvent, isConnected: isHistoryConnected} = useRecordDocumentHistoryEvent({
-    documentId: document._id,
-    documentType: document._type,
+    ...docHandle,
     resourceType: 'studio',
-    resourceId: document.resourceId,
   })
   const {navigateToStudioDocument, isConnected: isNavigateConnected} =
-    useNavigateToStudioDocument(document)
+    useNavigateToStudioDocument(docHandle)
 
   return (
     <Flex gap={2} padding={2}>
@@ -69,10 +62,6 @@ export function DocumentDashboardInteractionsRoute(): JSX.Element {
     orderings: [{field: '_updatedAt', direction: 'desc'}],
   })
 
-  // since resourceIds are being refactored at the moment, hardcode the resourceId for now
-  // (ideally, they come from document handles returned in the "data" param per document)
-  const datasetResourceId = 'document:ppsg7ml5.test:' // Note: each doc._id will be appended to this
-
   return (
     <Box padding={4}>
       <Heading as="h1" size={5}>
@@ -81,9 +70,9 @@ export function DocumentDashboardInteractionsRoute(): JSX.Element {
       <Box paddingY={5}>
         <DocumentListLayout>
           {data.map((doc) => (
-            <Box key={doc._id}>
-              <DocumentPreview document={doc} />
-              <ActionButtons document={{...doc, resourceId: `${datasetResourceId}${doc._id}`}} />
+            <Box key={doc.documentId}>
+              <DocumentPreview {...doc} />
+              <ActionButtons {...doc} />
             </Box>
           ))}
           <LoadMore hasMore={hasMore} isPending={isPending} onLoadMore={loadMore} />

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

@@ -1,5 +1,4 @@
 /* eslint-disable no-console */
-import {at, patch, set} from '@sanity/mutate'
 import {
   createDocument,
   deleteDocument,
@@ -27,34 +26,32 @@ interface Author extends SanityDocument {
   name?: string
 }
 
-const doc: DocumentHandle<Author> = {
-  _type: 'author',
-  _id: 'db06bc9e-4608-465a-9551-a10cef478037',
-  resourceId: 'document:ppsg7ml5.test:db06bc9e-4608-465a-9551-a10cef478037',
+const docHandle: DocumentHandle<Author> = {
+  documentType: 'author',
+  documentId: 'db06bc9e-4608-465a-9551-a10cef478037',
+  projectId: 'ppsg7ml5',
+  dataset: 'test',
 }
 
 function Editor() {
-  useDocumentEvent((e) => console.log(e), doc)
-  const synced = useDocumentSyncStatus(doc)
+  useDocumentEvent((e) => console.log(e), docHandle)
+  const synced = useDocumentSyncStatus(docHandle)
   const apply = useApplyDocumentActions()
 
-  const canEdit = useDocumentPermissions(editDocument(doc))
-  const canCreate = useDocumentPermissions(createDocument(doc))
-  const canPublish = useDocumentPermissions(publishDocument(doc))
-  const canDelete = useDocumentPermissions(deleteDocument(doc))
-  const canUnpublish = useDocumentPermissions(unpublishDocument(doc))
-  const canDiscard = useDocumentPermissions(discardDocument(doc))
+  const canEdit = useDocumentPermissions(editDocument(docHandle))
+  const canCreate = useDocumentPermissions(createDocument(docHandle))
+  const canPublish = useDocumentPermissions(publishDocument(docHandle))
+  const canDelete = useDocumentPermissions(deleteDocument(docHandle))
+  const canUnpublish = useDocumentPermissions(unpublishDocument(docHandle))
+  const canDiscard = useDocumentPermissions(discardDocument(docHandle))
 
-  const name = useDocument(doc, 'name') ?? ''
-  const setName = useEditDocument(doc, 'name')
+  const name = useDocument(docHandle, 'name') ?? ''
+  const setName = useEditDocument(docHandle, 'name')
 
   const [value, setValue] = useState('')
 
-  const changeNameToValue = editDocument(patch(doc._id, at('name', set(value))))
-  const canChangeNameToValue = useDocumentPermissions(changeNameToValue)
-
-  const document = useDocument(doc)
-  const setDocument = useEditDocument(doc)
+  const document = useDocument(docHandle)
+  const setDocument = useEditDocument(docHandle)
 
   return (
     <Box padding={4}>
@@ -69,7 +66,7 @@ function Editor() {
           <span>
             <Button
               disabled={!canCreate.allowed}
-              onClick={() => apply(createDocument(doc))}
+              onClick={() => apply(createDocument(docHandle))}
               text="Create"
             />
           </span>
@@ -78,7 +75,7 @@ function Editor() {
           <span>
             <Button
               disabled={!canDiscard.allowed}
-              onClick={() => apply(discardDocument(doc))}
+              onClick={() => apply(discardDocument(docHandle))}
               text="Discard"
             />
           </span>
@@ -88,7 +85,7 @@ function Editor() {
             <Button
               disabled={!canPublish.allowed}
               onClick={async () => {
-                const response = await apply(publishDocument(doc))
+                const response = await apply(publishDocument(docHandle))
                 await response.submitted()
               }}
               text="Publish"
@@ -99,7 +96,7 @@ function Editor() {
           <span>
             <Button
               disabled={!canUnpublish.allowed}
-              onClick={() => apply(unpublishDocument(doc))}
+              onClick={() => apply(unpublishDocument(docHandle))}
               text="Unpublish"
             />
           </span>
@@ -108,20 +105,11 @@ function Editor() {
           <span>
             <Button
               disabled={!canDelete.allowed}
-              onClick={() => apply(deleteDocument(doc))}
+              onClick={() => apply(deleteDocument(docHandle))}
               text="Delete"
             />
           </span>
         </Tooltip>
-        <Tooltip content={canChangeNameToValue.message}>
-          <span>
-            <Button
-              disabled={!canChangeNameToValue.allowed}
-              onClick={() => apply(changeNameToValue)}
-              text="Change name to value"
-            />
-          </span>
-        </Tooltip>
 
         <div>{synced ? 'Synced' : 'Syncing…'}</div>
       </div>

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

@@ -19,7 +19,7 @@ export function DocumentGridRoute(): JSX.Element {
       <Box paddingY={5}>
         <DocumentGridLayout>
           {data.map((doc) => (
-            <DocumentPreview key={doc._id} document={doc} />
+            <DocumentPreview key={doc.documentId} {...doc} />
           ))}
         </DocumentGridLayout>
         <Button text="Load more" mode="ghost" disabled={isPending || !hasMore} onClick={loadMore} />

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

@@ -19,8 +19,8 @@ export function DocumentListRoute(): JSX.Element {
       </Heading>
       <Box paddingY={5}>
         <DocumentListLayout>
-          {data.map((doc) => (
-            <DocumentPreview key={doc._id} document={doc} />
+          {data.map((docHandle) => (
+            <DocumentPreview key={docHandle.documentId} {...docHandle} />
           ))}
           <LoadMore hasMore={hasMore} isPending={isPending} onLoadMore={loadMore} />
         </DocumentListLayout>

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

@@ -5,29 +5,25 @@ import {ErrorBoundary} from 'react-error-boundary'
 
 import {DocumentPreviewLayout} from '../components/DocumentPreviewLayout/DocumentPreviewLayout'
 
-interface DocumentPreviewProps {
-  document: DocumentHandle
-}
-
-export function DocumentPreview(props: DocumentPreviewProps): React.ReactNode {
+export function DocumentPreview(docHandle: DocumentHandle): React.ReactNode {
   return (
     <li>
       <ErrorBoundary
         fallback={<DocumentPreviewLayout title="Error" subtitle="This preview failed to render." />}
       >
         <Suspense fallback={<DocumentPreviewLayout title="Loading" />}>
-          <DocumentPreviewResolved {...props} />
+          <DocumentPreviewResolved {...docHandle} />
         </Suspense>
       </ErrorBoundary>
     </li>
   )
 }
 
-function DocumentPreviewResolved({document}: DocumentPreviewProps): React.ReactNode {
+function DocumentPreviewResolved(docHandle: DocumentHandle): React.ReactNode {
   const ref = useRef(null)
   const {
     data: {title, subtitle, media, status},
-  } = usePreview({document, ref})
+  } = usePreview({...docHandle, ref})
 
   let statusLabel
   if (status?.lastEditedPublishedAt && status?.lastEditedDraftAt) {
@@ -50,7 +46,7 @@ function DocumentPreviewResolved({document}: DocumentPreviewProps): React.ReactN
       ref={ref}
       title={title}
       subtitle={subtitle}
-      docType={document._type}
+      docType={docHandle.documentType}
       media={media}
       status={statusLabel}
       onClick={() => alert(`Hello from ${title}`)}

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

@@ -14,13 +14,26 @@ interface AuthorProjection {
 }
 
 // Component for displaying projection data with proper error handling
-function ProjectionData({data}: {data: AuthorProjection}) {
+function ProjectionData(docHandle: DocumentHandle) {
+  const ref = useRef<HTMLTableCellElement>(null)
+  const {data} = useProjection<AuthorProjection>({
+    ...docHandle,
+    ref,
+    projection: `{
+      name,
+      "address": "City: " + address.city + ", Country: " + address.country,
+      "favoriteBookTitles": favoriteBooks[]->{title}.title
+    }`,
+  })
+
   return (
     <>
-      <TD padding={2}>{data.name || 'Untitled'}</TD>
+      <TD ref={ref} padding={2}>
+        {data.name || 'Untitled'}
+      </TD>
       <TD padding={2}>{data.address || 'No address'}</TD>
       <TD padding={2}>
-        {data.favoriteBookTitles.filter(Boolean).join(', ') || 'No favorite books'}
+        {data.favoriteBookTitles?.filter(Boolean).join(', ') || 'No favorite books'}
       </TD>
     </>
   )
@@ -53,24 +66,12 @@ function ProjectionError({error}: {error: Error}): ReactNode {
 }
 
 // Component for displaying a single author row with projection data
-function AuthorRow({document}: {document: DocumentHandle}) {
-  const ref = useRef<HTMLTableRowElement>(null)
-
-  const {data} = useProjection<AuthorProjection>({
-    document,
-    projection: `{
-      name,
-      "address": "City: " + address.city + ", Country: " + address.country,
-      "favoriteBookTitles": favoriteBooks[]->{title}.title
-    }`,
-    ref,
-  })
-
+function AuthorRow(docHandle: DocumentHandle) {
   return (
-    <TR ref={ref}>
+    <TR>
       <ErrorBoundary fallbackRender={({error}) => <ProjectionError error={error} />}>
         <Suspense fallback={<ProjectionFallback />}>
-          <ProjectionData data={data} />
+          <ProjectionData {...docHandle} />
         </Suspense>
       </ErrorBoundary>
     </TR>
@@ -289,7 +290,7 @@ export function DocumentProjectionRoute(): JSX.Element {
             </thead>
             <tbody>
               {data.length > 0 ? (
-                data.map((doc) => <AuthorRow key={doc._id} document={doc} />)
+                data.map((doc) => <AuthorRow key={doc.documentId} {...doc} />)
               ) : (
                 <TR>
                   <TD padding={2}>

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

@@ -34,15 +34,17 @@ export function MultiResourceRoute(): JSX.Element {
     }[]
   }
   const doc: DocumentHandle<Author> = {
-    _type: 'author',
-    _id: 'db06bc9e-4608-465a-9551-a10cef478037',
-    resourceId: 'document:ppsg7ml5.test:db06bc9e-4608-465a-9551-a10cef478037',
+    documentType: 'author',
+    documentId: 'db06bc9e-4608-465a-9551-a10cef478037',
+    projectId: 'ppsg7ml5',
+    dataset: 'test',
   }
 
   const doc2: DocumentHandle<Dog> = {
-    _type: 'dog',
-    _id: 'acc11e96-1a01-4907-bd0e-e8347217cf2f',
-    resourceId: 'document:ezwd8xes.production:acc11e96-1a01-4907-bd0e-e8347217cf2f',
+    documentType: 'dog',
+    documentId: 'acc11e96-1a01-4907-bd0e-e8347217cf2f',
+    projectId: 'ezwd8xes',
+    dataset: 'production',
   }
 
   const setAuthorName = useEditDocument(doc, 'name')