@portabletext/editor 1.15.3 → 1.16.0

package/src/editor/components/Synchronizer.tsx

@@ -1,30 +1,18 @@
-import type {Patch} from '@portabletext/patches'
-import type {PortableTextBlock} from '@sanity/types'
-import {useSelector} from '@xstate/react'
-import {throttle} from 'lodash'
-import {useCallback, useEffect, useRef} from 'react'
-import {Editor} from 'slate'
+import {useActorRef, useSelector} from '@xstate/react'
+import {useEffect} from 'react'
 import type {PortableTextSlateEditor} from '../../types/editor'
 import {debugWithName} from '../../utils/debug'
-import {IS_PROCESSING_LOCAL_CHANGES} from '../../utils/weakMaps'
 import type {EditorActor} from '../editor-machine'
-import {useSyncValue} from '../hooks/useSyncValue'
-import type {PortableTextEditor} from '../PortableTextEditor'
+import {mutationMachine} from '../mutation-machine'
+import {syncMachine} from '../sync-machine'
 
 const debug = debugWithName('component:PortableTextEditor:Synchronizer')
-const debugVerbose = debug.enabled && false
-
-// The editor will commit changes in a throttled fashion in order
-// not to overload the network and degrade performance while typing.
-const FLUSH_PATCHES_THROTTLED_MS = process.env.NODE_ENV === 'test' ? 500 : 1000
 
 /**
  * @internal
  */
 export interface SynchronizerProps {
   editorActor: EditorActor
-  getValue: () => Array<PortableTextBlock> | undefined
-  portableTextEditor: PortableTextEditor
   slateEditor: PortableTextSlateEditor
 }
 
@@ -33,90 +21,75 @@ export interface SynchronizerProps {
  * @internal
  */
 export function Synchronizer(props: SynchronizerProps) {
-  const readOnly = useSelector(props.editorActor, (s) => s.context.readOnly)
-  const value = useSelector(props.editorActor, (s) => s.context.value)
-  const {editorActor, getValue, portableTextEditor, slateEditor} = props
-  const pendingPatches = useRef<Patch[]>([])
+  const {editorActor, slateEditor} = props
 
-  const syncValue = useSyncValue({
-    editorActor,
-    portableTextEditor,
-    readOnly,
-    slateEditor,
+  const value = useSelector(props.editorActor, (s) => s.context.value)
+  const readOnly = useSelector(props.editorActor, (s) =>
+    s.matches({'edit mode': 'read only'}),
+  )
+  const syncActorRef = useActorRef(syncMachine, {
+    input: {
+      keyGenerator: props.editorActor.getSnapshot().context.keyGenerator,
+      readOnly: props.editorActor
+        .getSnapshot()
+        .matches({'edit mode': 'read only'}),
+      schema: props.editorActor.getSnapshot().context.schema,
+      slateEditor,
+    },
+  })
+  const mutationActorRef = useActorRef(mutationMachine, {
+    input: {
+      schema: editorActor.getSnapshot().context.schema,
+      slateEditor,
+    },
   })
 
   useEffect(() => {
-    IS_PROCESSING_LOCAL_CHANGES.set(slateEditor, false)
-  }, [slateEditor])
-
-  const onFlushPendingPatches = useCallback(() => {
-    if (pendingPatches.current.length > 0) {
-      debug('Flushing pending patches')
-      if (debugVerbose) {
-        debug(`Patches:\n${JSON.stringify(pendingPatches.current, null, 2)}`)
+    const subscription = mutationActorRef.on('*', (event) => {
+      if (event.type === 'has pending patches') {
+        syncActorRef.send({type: 'has pending patches'})
+      }
+      if (event.type === 'mutation') {
+        syncActorRef.send({type: 'mutation'})
+        editorActor.send(event)
       }
-      const snapshot = getValue()
-      editorActor.send({
-        type: 'mutation',
-        patches: pendingPatches.current,
-        snapshot,
-      })
-      pendingPatches.current = []
+    })
+
+    return () => {
+      subscription.unsubscribe()
     }
-    IS_PROCESSING_LOCAL_CHANGES.set(slateEditor, false)
-  }, [editorActor, slateEditor, getValue])
+  }, [mutationActorRef, syncActorRef, editorActor])
 
-  // Flush pending patches immediately on unmount
   useEffect(() => {
+    const subscription = syncActorRef.on('*', (event) => {
+      props.editorActor.send(event)
+    })
+
     return () => {
-      onFlushPendingPatches()
+      subscription.unsubscribe()
     }
-  }, [onFlushPendingPatches])
+  }, [props.editorActor, syncActorRef])
 
-  // Subscribe to, and handle changes from the editor
   useEffect(() => {
-    const onFlushPendingPatchesThrottled = throttle(
-      () => {
-        // If the editor is normalizing (each operation) it means that it's not in the middle of a bigger transform,
-        // and we can flush these changes immediately.
-        if (Editor.isNormalizing(slateEditor)) {
-          onFlushPendingPatches()
-          return
-        }
-        // If it's in the middle of something, try again.
-        onFlushPendingPatchesThrottled()
-      },
-      FLUSH_PATCHES_THROTTLED_MS,
-      {
-        leading: false,
-        trailing: true,
-      },
-    )
+    syncActorRef.send({type: 'toggle readOnly'})
+  }, [syncActorRef, readOnly])
 
+  useEffect(() => {
+    debug('Value from props changed, syncing new value')
+    syncActorRef.send({type: 'update value', value})
+  }, [syncActorRef, value])
+
+  // Subscribe to, and handle changes from the editor
+  useEffect(() => {
     debug('Subscribing to patch events')
     const sub = editorActor.on('patch', (event) => {
-      IS_PROCESSING_LOCAL_CHANGES.set(slateEditor, true)
-      pendingPatches.current.push(event.patch)
-      onFlushPendingPatchesThrottled()
+      mutationActorRef.send(event)
     })
     return () => {
       debug('Unsubscribing to patch events')
       sub.unsubscribe()
     }
-  }, [editorActor, onFlushPendingPatches, slateEditor])
-
-  // This hook must be set up after setting up the subscription above, or it will not pick up validation errors from the useSyncValue hook.
-  // This will cause the editor to not be able to signal a validation error and offer invalid value resolution of the initial value.
-  const isInitialValueFromProps = useRef(true)
-  useEffect(() => {
-    debug('Value from props changed, syncing new value')
-    syncValue(value)
-    // Signal that we have our first value, and are ready to roll.
-    if (isInitialValueFromProps.current) {
-      editorActor.send({type: 'ready'})
-      isInitialValueFromProps.current = false
-    }
-  }, [editorActor, syncValue, value])
+  }, [editorActor, mutationActorRef, slateEditor])
 
   return null
 }

package/src/editor/editor-machine.ts

@@ -31,6 +31,7 @@ import {fromSlateValue} from '../utils/values'
 import {KEY_TO_VALUE_ELEMENT} from '../utils/weakMaps'
 import type {EditorSchema} from './define-schema'
 import type {EditorContext} from './editor-snapshot'
+import {getActiveDecorators} from './get-active-decorators'
 
 export * from 'xstate/guards'
 
@@ -68,6 +69,7 @@ export type MutationEvent = {
 export type InternalEditorEvent =
   | {type: 'normalizing'}
   | {type: 'done normalizing'}
+  | {type: 'done syncing'}
   | {
       type: 'behavior event'
       behaviorEvent: SyntheticBehaviorEvent | NativeBehaviorEvent
@@ -98,7 +100,7 @@ export type InternalEditorEvent =
       type: 'update maxBlocks'
       maxBlocks: number | undefined
     }
-  | OmitFromUnion<InternalEditorEmittedEvent, 'type', 'readOnly toggled'>
+  | OmitFromUnion<InternalEditorEmittedEvent, 'type', 'read only' | 'editable'>
 
 /**
  * @alpha
@@ -108,13 +110,14 @@ export type EditorEmittedEvent = PickFromUnion<
   'type',
   | 'blurred'
   | 'done loading'
+  | 'editable'
   | 'error'
   | 'focused'
   | 'invalid value'
   | 'loading'
   | 'mutation'
   | 'patch'
-  | 'readOnly toggled'
+  | 'read only'
   | 'ready'
   | 'selection'
   | 'value changed'
@@ -152,7 +155,8 @@ export type InternalEditorEmittedEvent =
   | {type: 'focused'; event: FocusEvent<HTMLDivElement, Element>}
   | {type: 'loading'}
   | {type: 'done loading'}
-  | {type: 'readOnly toggled'; readOnly: boolean}
+  | {type: 'read only'}
+  | {type: 'editable'}
   | PickFromUnion<
       SyntheticBehaviorEvent,
       'type',
@@ -180,7 +184,7 @@ export const editorMachine = setup({
       keyGenerator: () => string
       pendingEvents: Array<PatchEvent | MutationEvent>
       schema: EditorSchema
-      readOnly: boolean
+      initialReadOnly: boolean
       maxBlocks: number | undefined
       selection: EditorSelection
       value: Array<PortableTextBlock> | undefined
@@ -217,6 +221,8 @@ export const editorMachine = setup({
       assertEvent(event, 'mutation')
       return event
     }),
+    'emit read only': emit({type: 'read only'}),
+    'emit editable': emit({type: 'editable'}),
     'defer event': assign({
       pendingEvents: ({context, event}) => {
         assertEvent(event, ['patch', 'mutation'])
@@ -228,6 +234,7 @@ export const editorMachine = setup({
         enqueue(emit(event))
       }
     }),
+    'emit ready': emit({type: 'ready'}),
     'clear pending events': assign({
       pendingEvents: [],
     }),
@@ -276,6 +283,10 @@ export const editorMachine = setup({
       )
 
       const editorContext = {
+        activeDecorators: getActiveDecorators({
+          schema: context.schema,
+          slateEditorInstance: event.editor,
+        }),
         keyGenerator: context.keyGenerator,
         schema: context.schema,
         selection,
@@ -345,48 +356,11 @@ export const editorMachine = setup({
     pendingEvents: [],
     schema: input.schema,
     selection: null,
-    readOnly: input.readOnly ?? false,
+    initialReadOnly: input.readOnly ?? false,
     maxBlocks: input.maxBlocks,
     value: input.value,
   }),
   on: {
-    'annotation.add': {
-      actions: emit(({event}) => event),
-      guard: ({context}) => !context.readOnly,
-    },
-    'annotation.remove': {
-      actions: emit(({event}) => event),
-      guard: ({context}) => !context.readOnly,
-    },
-    'annotation.toggle': {
-      actions: emit(({event}) => event),
-      guard: ({context}) => !context.readOnly,
-    },
-    'blur': {
-      actions: emit(({event}) => event),
-      guard: ({context}) => !context.readOnly,
-    },
-    'decorator.*': {
-      actions: emit(({event}) => event),
-      guard: ({context}) => !context.readOnly,
-    },
-    'focus': {
-      actions: emit(({event}) => event),
-      guard: ({context}) => !context.readOnly,
-    },
-    'insert.*': {
-      actions: emit(({event}) => event),
-      guard: ({context}) => !context.readOnly,
-    },
-    'list item.*': {
-      actions: emit(({event}) => event),
-      guard: ({context}) => !context.readOnly,
-    },
-    'style.*': {
-      actions: emit(({event}) => event),
-      guard: ({context}) => !context.readOnly,
-    },
-    'ready': {actions: emit(({event}) => event)},
     'unset': {actions: emit(({event}) => event)},
     'value changed': {actions: emit(({event}) => event)},
     'invalid value': {actions: emit(({event}) => event)},
@@ -405,22 +379,9 @@ export const editorMachine = setup({
     'update behaviors': {actions: 'assign behaviors'},
     'update schema': {actions: 'assign schema'},
     'update value': {actions: assign({value: ({event}) => event.value})},
-    'toggle readOnly': {
-      actions: [
-        assign({readOnly: ({context}) => !context.readOnly}),
-        emit(({context}) => ({
-          type: 'readOnly toggled',
-          readOnly: context.readOnly,
-        })),
-      ],
-    },
     'update maxBlocks': {
       actions: assign({maxBlocks: ({event}) => event.maxBlocks}),
     },
-    'behavior event': {
-      actions: 'handle behavior event',
-      guard: ({context}) => !context.readOnly,
-    },
     'behavior action intends': {
       actions: [
         ({context, event}) => {
@@ -455,49 +416,137 @@ export const editorMachine = setup({
       ],
     },
   },
-  initial: 'pristine',
+  type: 'parallel',
   states: {
-    pristine: {
-      initial: 'idle',
+    'edit mode': {
+      initial: 'read only',
       states: {
-        idle: {
+        'read only': {
+          initial: 'determine initial edit mode',
+          states: {
+            'determine initial edit mode': {
+              on: {
+                'done syncing': [
+                  {
+                    target: '#editor.edit mode.read only.read only',
+                    guard: ({context}) => context.initialReadOnly,
+                  },
+                  {
+                    target: '#editor.edit mode.editable',
+                  },
+                ],
+              },
+            },
+            'read only': {
+              on: {
+                'toggle readOnly': {
+                  target: '#editor.edit mode.editable',
+                  actions: ['emit editable'],
+                },
+              },
+            },
+          },
+        },
+        'editable': {
           on: {
-            normalizing: {
-              target: 'normalizing',
+            'toggle readOnly': {
+              target: '#editor.edit mode.read only.read only',
+              actions: ['emit read only'],
             },
-            patch: {
-              actions: 'defer event',
-              target: '#editor.dirty',
+            'behavior event': {
+              actions: 'handle behavior event',
             },
-            mutation: {
-              actions: 'defer event',
-              target: '#editor.dirty',
+            'annotation.add': {
+              actions: emit(({event}) => event),
+            },
+            'annotation.remove': {
+              actions: emit(({event}) => event),
+            },
+            'annotation.toggle': {
+              actions: emit(({event}) => event),
+            },
+            'blur': {
+              actions: emit(({event}) => event),
+            },
+            'decorator.*': {
+              actions: emit(({event}) => event),
+            },
+            'focus': {
+              actions: emit(({event}) => event),
+            },
+            'insert.*': {
+              actions: emit(({event}) => event),
+            },
+            'list item.*': {
+              actions: emit(({event}) => event),
+            },
+            'style.*': {
+              actions: emit(({event}) => event),
             },
           },
         },
-        normalizing: {
+      },
+    },
+    'setup': {
+      initial: 'setting up',
+      states: {
+        'setting up': {
+          exit: ['emit ready'],
           on: {
-            'done normalizing': {
-              target: 'idle',
-            },
             'patch': {
               actions: 'defer event',
             },
             'mutation': {
               actions: 'defer event',
             },
+            'done syncing': {
+              target: 'pristine',
+            },
           },
         },
-      },
-    },
-    dirty: {
-      entry: ['emit pending events', 'clear pending events'],
-      on: {
-        patch: {
-          actions: 'emit patch event',
+        'pristine': {
+          initial: 'idle',
+          states: {
+            idle: {
+              on: {
+                normalizing: {
+                  target: 'normalizing',
+                },
+                patch: {
+                  actions: 'defer event',
+                  target: '#editor.setup.dirty',
+                },
+                mutation: {
+                  actions: 'defer event',
+                  target: '#editor.setup.dirty',
+                },
+              },
+            },
+            normalizing: {
+              on: {
+                'done normalizing': {
+                  target: 'idle',
+                },
+                'patch': {
+                  actions: 'defer event',
+                },
+                'mutation': {
+                  actions: 'defer event',
+                },
+              },
+            },
+          },
         },
-        mutation: {
-          actions: 'emit mutation event',
+        'dirty': {
+          entry: ['emit pending events', 'clear pending events'],
+          on: {
+            patch: {
+              actions: 'emit patch event',
+            },
+            mutation: {
+              actions: 'emit mutation event',
+            },
+          },
         },
       },
     },

package/src/editor/editor-provider.tsx

@@ -28,7 +28,6 @@ export function EditorProvider(props: EditorProviderProps) {
   const editor = useCreateEditor(props.initialConfig)
   const editorActor = editor._internal.editorActor
   const slateEditor = editor._internal.slateEditor
-  const editable = editor._internal.editable
   const portableTextEditor = useMemo(
     () =>
       new PortableTextEditor({
@@ -47,8 +46,6 @@ export function EditorProvider(props: EditorProviderProps) {
       />
       <Synchronizer
         editorActor={editorActor}
-        getValue={editable.getValue}
-        portableTextEditor={portableTextEditor}
         slateEditor={slateEditor.instance}
       />
       <EditorActorContext.Provider value={editorActor}>

package/src/editor/editor-selector.ts

@@ -1,6 +1,7 @@
 import {useSelector} from '@xstate/react'
 import type {Editor} from './create-editor'
 import type {EditorSnapshot} from './editor-snapshot'
+import {getActiveDecorators} from './get-active-decorators'
 import {getValue} from './get-value'
 
 function defaultCompare<T>(a: T, b: T) {
@@ -24,6 +25,10 @@ export function useEditorSelector<TSelected>(
     editor._internal.editorActor,
     (snapshot) => {
       const context = {
+        activeDecorators: getActiveDecorators({
+          schema: snapshot.context.schema,
+          slateEditorInstance: editor._internal.slateEditor.instance,
+        }),
         keyGenerator: snapshot.context.keyGenerator,
         schema: snapshot.context.schema,
         selection: snapshot.context.selection,

package/src/editor/editor-snapshot.ts

@@ -6,6 +6,7 @@ import type {EditorSchema} from './define-schema'
  * @alpha
  */
 export type EditorContext = {
+  activeDecorators: Array<string>
   keyGenerator: () => string
   schema: EditorSchema
   selection: EditorSelection

package/src/editor/get-active-decorators.ts

@@ -0,0 +1,20 @@
+import {Editor} from 'slate'
+import type {PortableTextSlateEditor} from '../types/editor'
+import type {EditorSchema} from './define-schema'
+
+export function getActiveDecorators({
+  schema,
+  slateEditorInstance,
+}: {
+  schema: EditorSchema
+  slateEditorInstance: PortableTextSlateEditor
+}) {
+  const decorators = schema.decorators.map((decorator) => decorator.value)
+
+  const marks =
+    {
+      ...(Editor.marks(slateEditorInstance) ?? {}),
+    }.marks ?? []
+
+  return marks.filter((mark) => decorators.includes(mark))
+}

package/src/editor/mutation-machine.ts

@@ -0,0 +1,100 @@
+import type {Patch} from '@portabletext/patches'
+import type {PortableTextBlock} from '@sanity/types'
+import {Editor} from 'slate'
+import {assign, emit, setup} from 'xstate'
+import type {PortableTextSlateEditor} from '../types/editor'
+import {fromSlateValue} from '../utils/values'
+import {KEY_TO_VALUE_ELEMENT} from '../utils/weakMaps'
+import type {EditorSchema} from './define-schema'
+
+const FLUSH_PATCHES_THROTTLED_MS = process.env.NODE_ENV === 'test' ? 500 : 1000
+
+/**
+ * Makes sure editor mutation events are debounced
+ */
+export const mutationMachine = setup({
+  types: {
+    context: {} as {
+      pendingPatches: Array<Patch>
+      schema: EditorSchema
+      slateEditor: PortableTextSlateEditor
+    },
+    events: {} as {type: 'patch'; patch: Patch},
+    input: {} as {
+      schema: EditorSchema
+      slateEditor: PortableTextSlateEditor
+    },
+    emitted: {} as
+      | {
+          type: 'has pending patches'
+        }
+      | {
+          type: 'mutation'
+          patches: Array<Patch>
+          snapshot: Array<PortableTextBlock> | undefined
+        },
+  },
+  actions: {
+    'emit has pending patches': emit({type: 'has pending patches'}),
+    'emit mutation': emit(({context}) => ({
+      type: 'mutation' as const,
+      patches: context.pendingPatches,
+      snapshot: fromSlateValue(
+        context.slateEditor.children,
+        context.schema.block.name,
+        KEY_TO_VALUE_ELEMENT.get(context.slateEditor),
+      ),
+    })),
+    'clear pending patches': assign({
+      pendingPatches: [],
+    }),
+    'defer patch': assign({
+      pendingPatches: ({context, event}) => [
+        ...context.pendingPatches,
+        event.patch,
+      ],
+    }),
+  },
+  guards: {
+    'slate is normalizing': ({context}) =>
+      Editor.isNormalizing(context.slateEditor),
+  },
+}).createMachine({
+  id: 'mutation',
+  context: ({input}) => ({
+    pendingPatches: [],
+    schema: input.schema,
+    slateEditor: input.slateEditor,
+  }),
+  initial: 'idle',
+  states: {
+    'idle': {
+      on: {
+        patch: {
+          actions: ['defer patch', 'emit has pending patches'],
+          target: 'has pending patches',
+        },
+      },
+    },
+    'has pending patches': {
+      after: {
+        [FLUSH_PATCHES_THROTTLED_MS]: [
+          {
+            guard: 'slate is normalizing',
+            target: 'idle',
+            actions: ['emit mutation', 'clear pending patches'],
+          },
+          {
+            reenter: true,
+          },
+        ],
+      },
+      on: {
+        patch: {
+          actions: ['defer patch'],
+          reenter: true,
+        },
+      },
+    },
+  },
+})