feat(visual-editing): add svelte optimistic state support

apps/svelte/src/components/Shoe.svelte

@@ -1,7 +1,9 @@
 <script lang="ts">
   import {PortableText} from '@portabletext/svelte'
+  import type {SanityDocument} from '@sanity/client'
   import {stegaClean} from '@sanity/client/stega'
   import {createDataAttribute} from '@sanity/visual-editing'
+  import {useOptimistic} from '@sanity/visual-editing/svelte'
   import {page} from '$app/stores'
   import type {ShoeResult} from '$lib/queries'
   import {urlFor, urlForCrossDatasetReference} from '$lib/sanity'
@@ -13,7 +15,19 @@
 
   const parentPath = $page.url.pathname.split('/').slice(0, -1).join('/')
 
-  $: [coverImage, ...otherImages] = product?.media || []
+  const {value: media, update: updateMedia} = useOptimistic<
+    ShoeResult['media'],
+    SanityDocument<ShoeResult>
+  >(product.media, (state, action) => {
+    if (action.id === product._id && action.document.media) {
+      return action.document.media
+    }
+    return state
+  })
+
+  $: updateMedia(product.media)
+
+  $: [coverImage, ...otherImages] = $media || []
 </script>
 
 <svelte:head>

packages/visual-editing/package.json

@@ -40,6 +40,12 @@
       "require": "./dist/next-pages-router/index.cjs",
       "default": "./dist/next-pages-router/index.js"
     },
+    "./optimistic": {
+      "source": "./src/optimistic/index.ts",
+      "import": "./dist/optimistic/index.js",
+      "require": "./dist/optimistic/index.cjs",
+      "default": "./dist/optimistic/index.js"
+    },
     "./react": {
       "source": "./src/react/index.ts",
       "import": "./dist/react/index.js",
@@ -82,6 +88,9 @@
       "next-pages-router": [
         "./dist/next-pages-router/index.d.ts"
       ],
+      "optimistic": [
+        "./dist/optimistic/index.d.ts"
+      ],
       "react": [
         "./dist/react/index.d.ts"
       ],

packages/visual-editing/src/index.ts

@@ -53,19 +53,6 @@ export type {
   VisualEditingOptions,
 } from './types'
 export {enableVisualEditing} from './ui/enableVisualEditing'
-export type {DatasetMutatorMachineInput} from './ui/optimistic-state/machines/datasetMutatorMachine'
-export {
-  type DocumentsGet,
-  type DocumentsMutate,
-  type OptimisticDocument,
-  type OptimisticDocumentPatches,
-  type OptimisticReducer,
-  type OptimisticReducerAction,
-  type Path,
-  type PathValue,
-  useDocuments,
-  useOptimistic,
-} from './ui/optimistic-state'
 export {useSharedState} from './ui/shared-state/useSharedState'
 export {
   type CreateDataAttribute,
@@ -89,3 +76,22 @@ export {
   createDataAttribute,
 } from '@repo/visual-editing-helpers'
 export {getArrayItemKeyAndParentPath} from './util/mutations'
+
+/**
+ * Deprecated exports: React specific exports moved to `/react`. Generic
+ * optimistic type exports moved to `/optimistic`.
+ * @todo How can these be marked as deprecated OR remove and major?
+ */
+export {useDocuments} from './react/useDocuments'
+export {useOptimistic} from './react/useOptimistic'
+export type {DatasetMutatorMachineInput} from './optimistic/state/datasetMutator'
+export type {
+  DocumentsGet,
+  DocumentsMutate,
+  OptimisticDocument,
+  OptimisticDocumentPatches,
+  OptimisticReducer,
+  OptimisticReducerAction,
+  Path,
+  PathValue,
+} from './optimistic/types'

packages/visual-editing/src/ui/optimistic-state/context.ts → packages/visual-editing/src/optimistic/context.ts

@@ -1,5 +1,5 @@
 import {createEmptyActor, type ActorRefFrom} from 'xstate'
-import {createDatasetMutator} from '../comlink'
+import {createDatasetMutator} from './state/datasetMutator'
 
 export type MutatorActor = ActorRefFrom<ReturnType<typeof createDatasetMutator>>
 export type EmptyActor = typeof emptyActor

packages/visual-editing/src/optimistic/index.ts

@@ -0,0 +1,54 @@
+export type {VisualEditingNode} from '../types'
+export type {
+  DocumentSchema,
+  HistoryRefresh,
+  HistoryUpdate,
+  PreviewSnapshot,
+  ResolvedSchemaTypeMap,
+  SanityNode,
+  SanityStegaNode,
+  SchemaArrayItem,
+  SchemaArrayNode,
+  SchemaBooleanNode,
+  SchemaInlineNode,
+  SchemaNode,
+  SchemaNullNode,
+  SchemaNumberNode,
+  SchemaObjectField,
+  SchemaObjectNode,
+  SchemaStringNode,
+  SchemaType,
+  SchemaUnionNode,
+  SchemaUnionNodeOptions,
+  SchemaUnionOption,
+  SchemaUnknownNode,
+  Serializable,
+  SerializableArray,
+  SerializableObject,
+  SerializablePrimitive,
+  TypeSchema,
+  UnresolvedPath,
+  VisualEditingControllerMsg,
+  VisualEditingNodeMsg,
+} from '@repo/visual-editing-helpers'
+export type {
+  DocumentsGet,
+  DocumentsMutate,
+  OptimisticDocument,
+  OptimisticDocumentPatches,
+  OptimisticReducerAction,
+  Path,
+  PathValue,
+  OptimisticReducer,
+} from './types'
+export {
+  type MutatorActor,
+  type EmptyActor,
+  emptyActor,
+  actor,
+  listeners,
+  isEmptyActor,
+  setActor,
+} from './context'
+export {createDatasetMutator, type DatasetMutatorMachineInput} from './state/datasetMutator'
+export {createDocumentMutator} from './state/documentMutator'

packages/visual-editing/src/ui/optimistic-state/machines/createSharedListener.ts → packages/visual-editing/src/optimistic/state/createSharedListener.ts

@@ -1,6 +1,6 @@
 import {type ListenEvent} from '@sanity/client'
 import {merge, ReplaySubject, Subject, type Observable, type ObservedValueOf} from 'rxjs'
-import type {VisualEditingNode} from '../../../types'
+import type {VisualEditingNode} from '../../types'
 
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 type SharedListenEvent = ListenEvent<Record<string, any>>

packages/visual-editing/src/ui/optimistic-state/machines/datasetMutatorMachine.ts → packages/visual-editing/src/optimistic/state/datasetMutator.ts

@@ -11,7 +11,8 @@ import {
   type DocumentMutatorMachineParentEvent,
 } from '@sanity/mutate/_unstable_machine'
 import {assertEvent, assign, emit, setup, stopChild, type ActorRefFrom} from 'xstate'
-import type {createDocumentMutator} from '../../comlink'
+import type {VisualEditingNode} from '../../types'
+import {createDocumentMutator} from './documentMutator'
 
 export interface DatasetMutatorMachineInput extends Omit<DocumentMutatorMachineInput, 'id'> {
   client: SanityClient
@@ -118,3 +119,12 @@ export const datasetMutatorMachine = setup({
     pristine: {},
   },
 })
+
+// eslint-disable-next-line @typescript-eslint/explicit-module-boundary-types
+export const createDatasetMutator = (comlink: VisualEditingNode) => {
+  return datasetMutatorMachine.provide({
+    actors: {
+      documentMutatorMachine: createDocumentMutator(comlink),
+    },
+  })
+}

packages/visual-editing/src/ui/comlink/index.ts → packages/visual-editing/src/optimistic/state/documentMutator.ts

@@ -6,7 +6,6 @@ import {
 } from '@sanity/mutate/_unstable_machine'
 import {enqueueActions, fromPromise} from 'xstate'
 import type {VisualEditingNode} from '../../types'
-import {datasetMutatorMachine} from '../optimistic-state/machines/datasetMutatorMachine'
 
 // eslint-disable-next-line @typescript-eslint/explicit-module-boundary-types
 export const createDocumentMutator = (comlink: VisualEditingNode) => {
@@ -56,12 +55,3 @@ export const createDocumentMutator = (comlink: VisualEditingNode) => {
     },
   })
 }
-
-// eslint-disable-next-line @typescript-eslint/explicit-module-boundary-types
-export const createDatasetMutator = (comlink: VisualEditingNode) => {
-  return datasetMutatorMachine.provide({
-    actors: {
-      documentMutatorMachine: createDocumentMutator(comlink),
-    },
-  })
-}

packages/visual-editing/src/optimistic/types.ts

@@ -0,0 +1,77 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import type {SanityDocument} from '@sanity/client'
+import {type Mutation, type NodePatchList} from '@sanity/mutate'
+
+export type Path<T, K extends keyof T> = K extends string
+  ? T[K] extends Record<string, any>
+    ? `${K}.${Path<T[K], keyof T[K]>}` | K
+    : K
+  : never
+
+export type PathValue<T, P extends string> = P extends `${infer K}.${infer Rest}`
+  ? K extends keyof T
+    ? PathValue<T[K], Rest>
+    : never
+  : P extends keyof T
+    ? T[P]
+    : never
+
+export type DocumentsMutate = (
+  documentId: string,
+  mutations: Mutation[],
+  options?: {commit?: boolean | {debounce: number}},
+) => void
+
+export type DocumentsGet = <T extends Record<string, any>>(
+  documentId: string,
+) => OptimisticDocument<T>
+
+export type OptimisticDocumentPatches<T extends Record<string, any> = Record<string, any>> =
+  | ((context: {
+      draftId: string
+      publishedId: string
+      /**
+       * @deprecated - use `getSnapshot` instead
+       */
+      snapshot: SanityDocument<T> | undefined
+      getSnapshot: () => Promise<SanityDocument<T> | null>
+    }) => Promise<NodePatchList> | NodePatchList)
+  | NodePatchList
+
+export type OptimisticDocument<T extends Record<string, any> = Record<string, any>> = {
+  /**
+   * The document ID
+   */
+  id: string
+  /**
+   * Commits any locally applied mutations to the remote document
+   */
+  commit: () => void
+  /**
+   * @deprecated - use `getSnapshot` instead
+   */
+  get: {
+    (): SanityDocument<T> | undefined
+    <P extends Path<T, keyof T>>(path: P): PathValue<T, P> | undefined
+  }
+  /**
+   * Returns a promise that resolves to the current document snapshot
+   */
+  getSnapshot: () => Promise<SanityDocument<T> | null>
+  /**
+   * Applies the given patches to the document
+   */
+  patch: (
+    patches: OptimisticDocumentPatches<T>,
+    options?: {commit?: boolean | {debounce: number}},
+  ) => void
+}
+
+export type OptimisticReducerAction<T> = {
+  document: T
+  id: string
+  originalId: string
+  type: 'appear' | 'mutate' | 'disappear'
+}
+
+export type OptimisticReducer<T, U> = (state: T, action: OptimisticReducerAction<U>) => T

packages/visual-editing/src/overlay-components/components/UnionInsertMenuOverlay.tsx

@@ -11,8 +11,8 @@ import {
   type MouseEvent,
 } from 'react'
 import {styled} from 'styled-components'
+import {useDocuments} from '../../react/useDocuments'
 import type {ElementNode, OverlayComponent} from '../../types'
-import {useDocuments} from '../../ui/optimistic-state/useDocuments'
 import {getArrayInsertPatches} from '../../util/mutations'
 import {InsertMenuPopover} from './InsertMenu'
 

packages/visual-editing/src/react/index.ts

@@ -12,26 +12,58 @@ export type {
   OverlayElementParent,
   SanityNode,
   VisualEditingOptions,
-} from '../types.ts'
+  VisualEditingNode,
+} from '../types'
 export {VisualEditing} from '../ui/VisualEditing'
 export {
   createDataAttribute,
   type CreateDataAttribute,
   type CreateDataAttributeProps,
   type DocumentSchema,
+  type PreviewSnapshot,
+  type ResolvedSchemaTypeMap,
+  type SanityStegaNode,
   type SchemaArrayItem,
-  type SchemaNode,
-  type SchemaUnionOption,
-  type WithRequired,
   type SchemaArrayNode,
   type SchemaBooleanNode,
   type SchemaInlineNode,
+  type SchemaNode,
   type SchemaNullNode,
   type SchemaNumberNode,
   type SchemaObjectField,
   type SchemaObjectNode,
   type SchemaStringNode,
+  type SchemaType,
   type SchemaUnionNode,
   type SchemaUnionNodeOptions,
+  type SchemaUnionOption,
   type SchemaUnknownNode,
+  type Serializable,
+  type SerializableArray,
+  type SerializableObject,
+  type SerializablePrimitive,
+  type TypeSchema,
+  type UnresolvedPath,
+  type VisualEditingControllerMsg,
+  type VisualEditingNodeMsg,
+  type WithRequired,
 } from '@repo/visual-editing-helpers'
+export {createDocumentMutator} from '../optimistic/state/documentMutator'
+export {
+  createDatasetMutator,
+  type DatasetMutatorMachineInput,
+} from '../optimistic/state/datasetMutator'
+export {emptyActor, type MutatorActor, type EmptyActor} from '../optimistic/context'
+export type {
+  DocumentsGet,
+  DocumentsMutate,
+  OptimisticDocument,
+  OptimisticDocumentPatches,
+  OptimisticReducer,
+  OptimisticReducerAction,
+  Path,
+  PathValue,
+} from '../optimistic/types'
+export {useOptimistic} from './useOptimistic'
+export {useOptimisticActor} from './useOptimisticActor'
+export {useDocuments} from './useDocuments'