@portabletext/editor 1.10.2 → 1.11.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@portabletext/editor",
-  "version": "1.10.2",
+  "version": "1.11.0",
   "description": "Portable Text Editor made in React",
   "keywords": [
     "sanity",
@@ -58,11 +58,11 @@
   },
   "devDependencies": {
     "@portabletext/toolkit": "^2.0.16",
-    "@sanity/block-tools": "^3.64.1",
+    "@sanity/block-tools": "^3.64.2",
     "@sanity/diff-match-patch": "^3.1.1",
-    "@sanity/pkg-utils": "^6.11.11",
-    "@sanity/schema": "^3.64.1",
-    "@sanity/types": "^3.64.1",
+    "@sanity/pkg-utils": "^6.11.12",
+    "@sanity/schema": "^3.64.2",
+    "@sanity/types": "^3.64.2",
     "@testing-library/jest-dom": "^6.6.3",
     "@testing-library/react": "^16.0.1",
     "@types/debug": "^4.1.5",
@@ -70,8 +70,8 @@
     "@types/lodash.startcase": "^4.4.9",
     "@types/react": "^18.3.12",
     "@types/react-dom": "^18.3.1",
-    "@typescript-eslint/eslint-plugin": "^8.14.0",
-    "@typescript-eslint/parser": "^8.14.0",
+    "@typescript-eslint/eslint-plugin": "^8.15.0",
+    "@typescript-eslint/parser": "^8.15.0",
     "@vitejs/plugin-react": "^4.3.3",
     "@vitest/browser": "^2.1.5",
     "babel-plugin-react-compiler": "19.0.0-beta-0dec889-20241115",
@@ -90,9 +90,9 @@
     "@sanity/gherkin-driver": "^0.0.1"
   },
   "peerDependencies": {
-    "@sanity/block-tools": "^3.64.1",
-    "@sanity/schema": "^3.64.1",
-    "@sanity/types": "^3.64.1",
+    "@sanity/block-tools": "^3.64.2",
+    "@sanity/schema": "^3.64.2",
+    "@sanity/types": "^3.64.2",
     "react": "^16.9 || ^17 || ^18",
     "rxjs": "^7.8.1",
     "styled-components": "^6.1.13"

package/src/editor/Editable.tsx

@@ -160,7 +160,7 @@ export const PortableTextEditable = forwardRef<
 
   const editorActor = useContext(EditorActorContext)
   const readOnly = useSelector(editorActor, (s) => s.context.readOnly)
-  const {schemaTypes} = portableTextEditor
+  const schemaTypes = useSelector(editorActor, (s) => s.context.schema)
   const slateEditor = useSlate()
 
   const blockTypeName = schemaTypes.block.name

package/src/editor/PortableTextEditor.tsx

@@ -14,7 +14,7 @@ import {
 } from 'react'
 import {Subject} from 'rxjs'
 import {Slate} from 'slate-react'
-import {createActor} from 'xstate'
+import {useEffectEvent} from 'use-effect-event'
 import type {
   EditableAPI,
   EditableAPIDeleteOptions,
@@ -28,17 +28,13 @@ import {debugWithName} from '../utils/debug'
 import {getPortableTextMemberSchemaTypes} from '../utils/getPortableTextMemberSchemaTypes'
 import {compileType} from '../utils/schema'
 import {Synchronizer} from './components/Synchronizer'
-import {createSlateEditor, type SlateEditor} from './create-slate-editor'
 import {EditorActorContext} from './editor-actor-context'
-import {editorMachine, type EditorActor} from './editor-machine'
+import type {EditorActor} from './editor-machine'
 import {PortableTextEditorContext} from './hooks/usePortableTextEditor'
 import {PortableTextEditorSelectionProvider} from './hooks/usePortableTextEditorSelection'
 import {defaultKeyGenerator} from './key-generator'
-import {
-  createEditableAPI,
-  type AddedAnnotationPaths,
-} from './plugins/createWithEditableAPI'
-import type {Editor} from './use-editor'
+import type {AddedAnnotationPaths} from './plugins/createWithEditableAPI'
+import {createEditor, type Editor} from './use-editor'
 
 const debug = debugWithName('component:PortableTextEditor')
 
@@ -124,71 +120,35 @@ export class PortableTextEditor extends Component<
    */
   public schemaTypes: PortableTextMemberSchemaTypes
   /**
+   * The editor instance
+   */
+  private editor: Editor
+  /*
    * The editor API (currently implemented with Slate).
    */
-  private editable?: EditableAPI
-  private editorActor: EditorActor
-  private slateEditor: SlateEditor
+  private editable: EditableAPI
 
   constructor(props: PortableTextEditorProps) {
     super(props)
 
     if (props.editor) {
-      const editor = props.editor as Editor
-      this.editorActor = editor._internal.editorActor
-      this.slateEditor = editor._internal.slateEditor
-      this.editorActor.start()
-      this.schemaTypes = this.editorActor.getSnapshot().context.schema
+      this.editor = props.editor as Editor
     } else {
-      if (!props.schemaType) {
-        throw new Error('PortableTextEditor: missing "schemaType" property')
-      }
-
-      if (props.incomingPatches$) {
-        console.warn(
-          `The prop 'incomingPatches$' is deprecated and renamed to 'patches$'`,
-        )
-      }
-
-      this.schemaTypes = getPortableTextMemberSchemaTypes(
-        props.schemaType.hasOwnProperty('jsonType')
-          ? props.schemaType
-          : compileType(props.schemaType),
-      )
-
-      this.editorActor = createActor(editorMachine, {
-        input: {
-          keyGenerator: props.keyGenerator || defaultKeyGenerator,
-          schema: this.schemaTypes,
-          value: props.value,
-        },
-      })
-      this.editorActor.start()
-
-      this.slateEditor = createSlateEditor({
-        editorActor: this.editorActor,
+      this.editor = createEditor({
+        keyGenerator: props.keyGenerator ?? defaultKeyGenerator,
+        schema: props.schemaType,
+        initialValue: props.value,
+        maxBlocks:
+          props.maxBlocks === undefined
+            ? undefined
+            : Number.parseInt(props.maxBlocks.toString(), 10),
+        readOnly: props.readOnly,
       })
-
-      if (props.readOnly) {
-        this.editorActor.send({
-          type: 'toggle readOnly',
-        })
-      }
-
-      if (props.maxBlocks) {
-        this.editorActor.send({
-          type: 'update maxBlocks',
-          maxBlocks:
-            props.maxBlocks === undefined
-              ? undefined
-              : Number.parseInt(props.maxBlocks.toString(), 10),
-        })
-      }
     }
-    this.editable = createEditableAPI(
-      this.slateEditor.instance,
-      this.editorActor,
-    )
+
+    this.schemaTypes =
+      this.editor._internal.editorActor.getSnapshot().context.schema
+    this.editable = this.editor.editable
   }
 
   componentDidUpdate(prevProps: PortableTextEditorProps) {
@@ -204,7 +164,7 @@ export class PortableTextEditor extends Component<
           : compileType(this.props.schemaType),
       )
 
-      this.editorActor.send({
+      this.editor._internal.editorActor.send({
         type: 'update schema',
         schema: this.schemaTypes,
       })
@@ -212,13 +172,13 @@ export class PortableTextEditor extends Component<
 
     if (!this.props.editor && !prevProps.editor) {
       if (this.props.readOnly !== prevProps.readOnly) {
-        this.editorActor.send({
+        this.editor._internal.editorActor.send({
           type: 'toggle readOnly',
         })
       }
 
       if (this.props.maxBlocks !== prevProps.maxBlocks) {
-        this.editorActor.send({
+        this.editor._internal.editorActor.send({
           type: 'update maxBlocks',
           maxBlocks:
             this.props.maxBlocks === undefined
@@ -228,7 +188,7 @@ export class PortableTextEditor extends Component<
       }
 
       if (this.props.value !== prevProps.value) {
-        this.editorActor.send({
+        this.editor._internal.editorActor.send({
           type: 'update value',
           value: this.props.value,
         })
@@ -244,15 +204,7 @@ export class PortableTextEditor extends Component<
   }
 
   public setEditable = (editable: EditableAPI) => {
-    this.editable = {...this.editable, ...editable}
-  }
-
-  private getValue = () => {
-    if (this.editable) {
-      return this.editable.getValue()
-    }
-
-    return undefined
+    this.editor.editable = {...this.editor.editable, ...editable}
   }
 
   render() {
@@ -264,33 +216,38 @@ export class PortableTextEditor extends Component<
       <>
         {legacyPatches ? (
           <RoutePatchesObservableToEditorActor
-            editorActor={this.editorActor}
+            editorActor={this.editor._internal.editorActor}
             patches$={legacyPatches}
           />
         ) : null}
-        <EditorActorContext.Provider value={this.editorActor}>
+        <RouteEventsToChanges
+          editorActor={this.editor._internal.editorActor}
+          onChange={(change) => {
+            if (!this.props.editor) {
+              this.props.onChange(change)
+            }
+            /**
+             * For backwards compatibility, we relay all changes to the
+             * `change$` Subject as well.
+             */
+            this.change$.next(change)
+          }}
+        />
+        <Synchronizer
+          editorActor={this.editor._internal.editorActor}
+          getValue={this.editor.editable.getValue}
+          portableTextEditor={this}
+          slateEditor={this.editor._internal.slateEditor.instance}
+        />
+        <EditorActorContext.Provider value={this.editor._internal.editorActor}>
           <Slate
-            editor={this.slateEditor.instance}
-            initialValue={this.slateEditor.initialValue}
+            editor={this.editor._internal.slateEditor.instance}
+            initialValue={this.editor._internal.slateEditor.initialValue}
           >
             <PortableTextEditorContext.Provider value={this}>
               <PortableTextEditorSelectionProvider
-                editorActor={this.editorActor}
+                editorActor={this.editor._internal.editorActor}
               >
-                <Synchronizer
-                  editorActor={this.editorActor}
-                  getValue={this.getValue}
-                  onChange={(change) => {
-                    if (!this.props.editor) {
-                      this.props.onChange(change)
-                    }
-                    /**
-                     * For backwards compatibility, we relay all changes to the
-                     * `change$` Subject as well.
-                     */
-                    this.change$.next(change)
-                  }}
-                />
                 {this.props.children}
               </PortableTextEditorSelectionProvider>
             </PortableTextEditorContext.Provider>
@@ -468,3 +425,73 @@ function RoutePatchesObservableToEditorActor(props: {
 
   return null
 }
+
+export function RouteEventsToChanges(props: {
+  editorActor: EditorActor
+  onChange: (change: EditorChange) => void
+}) {
+  // We want to ensure that _when_ `props.onChange` is called, it uses the current value.
+  // But we don't want to have the `useEffect` run setup + teardown + setup every time the prop might change, as that's unnecessary.
+  // So we use our own polyfill that lets us use an upcoming React hook that solves this exact problem.
+  // https://19.react.dev/learn/separating-events-from-effects#declaring-an-effect-event
+  const handleChange = useEffectEvent((change: EditorChange) =>
+    props.onChange(change),
+  )
+
+  useEffect(() => {
+    debug('Subscribing to editor changes')
+    const sub = props.editorActor.on('*', (event) => {
+      switch (event.type) {
+        case 'patch':
+          handleChange(event)
+          break
+        case 'loading': {
+          handleChange({type: 'loading', isLoading: true})
+          break
+        }
+        case 'done loading': {
+          handleChange({type: 'loading', isLoading: false})
+          break
+        }
+        case 'focused': {
+          handleChange({type: 'focus', event: event.event})
+          break
+        }
+        case 'value changed': {
+          handleChange({type: 'value', value: event.value})
+          break
+        }
+        case 'invalid value': {
+          handleChange({
+            type: 'invalidValue',
+            resolution: event.resolution,
+            value: event.value,
+          })
+          break
+        }
+        case 'error': {
+          handleChange({
+            ...event,
+            level: 'warning',
+          })
+          break
+        }
+        case 'annotation.add':
+        case 'annotation.remove':
+        case 'annotation.toggle':
+        case 'focus':
+        case 'patches':
+        case 'readOnly toggled':
+          break
+        default:
+          handleChange(event)
+      }
+    })
+    return () => {
+      debug('Unsubscribing to changes')
+      sub.unsubscribe()
+    }
+  }, [props.editorActor, handleChange])
+
+  return null
+}

package/src/editor/behavior/behavior.types.ts

@@ -212,3 +212,12 @@ export type PickFromUnion<
   TTagKey extends keyof TUnion,
   TPickedTags extends TUnion[TTagKey],
 > = TUnion extends Record<TTagKey, TPickedTags> ? TUnion : never
+
+/**
+ * @alpha
+ */
+export type OmitFromUnion<
+  TUnion,
+  TTagKey extends keyof TUnion,
+  TOmittedTags extends TUnion[TTagKey],
+> = TUnion extends Record<TTagKey, TOmittedTags> ? never : TUnion

package/src/editor/components/Synchronizer.tsx

@@ -4,14 +4,12 @@ import {useSelector} from '@xstate/react'
 import {throttle} from 'lodash'
 import {useCallback, useEffect, useRef} from 'react'
 import {Editor} from 'slate'
-import {useSlate} from 'slate-react'
-import {useEffectEvent} from 'use-effect-event'
-import type {EditorChange} from '../../types/editor'
+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 {usePortableTextEditor} from '../hooks/usePortableTextEditor'
 import {useSyncValue} from '../hooks/useSyncValue'
+import type {PortableTextEditor} from '../PortableTextEditor'
 
 const debug = debugWithName('component:PortableTextEditor:Synchronizer')
 const debugVerbose = debug.enabled && false
@@ -26,7 +24,8 @@ const FLUSH_PATCHES_THROTTLED_MS = process.env.NODE_ENV === 'test' ? 500 : 1000
 export interface SynchronizerProps {
   editorActor: EditorActor
   getValue: () => Array<PortableTextBlock> | undefined
-  onChange: (change: EditorChange) => void
+  portableTextEditor: PortableTextEditor
+  slateEditor: PortableTextSlateEditor
 }
 
 /**
@@ -34,20 +33,18 @@ export interface SynchronizerProps {
  * @internal
  */
 export function Synchronizer(props: SynchronizerProps) {
-  const portableTextEditor = usePortableTextEditor()
   const readOnly = useSelector(props.editorActor, (s) => s.context.readOnly)
   const value = useSelector(props.editorActor, (s) => s.context.value)
-  const {editorActor, getValue, onChange} = props
+  const {editorActor, getValue, portableTextEditor, slateEditor} = props
   const pendingPatches = useRef<Patch[]>([])
 
   const syncValue = useSyncValue({
     editorActor,
     portableTextEditor,
     readOnly,
+    slateEditor,
   })
 
-  const slateEditor = useSlate()
-
   useEffect(() => {
     IS_PROCESSING_LOCAL_CHANGES.set(slateEditor, false)
   }, [slateEditor])
@@ -76,14 +73,6 @@ export function Synchronizer(props: SynchronizerProps) {
     }
   }, [onFlushPendingPatches])
 
-  // We want to ensure that _when_ `props.onChange` is called, it uses the current value.
-  // But we don't want to have the `useEffect` run setup + teardown + setup every time the prop might change, as that's unnecessary.
-  // So we use our own polyfill that lets us use an upcoming React hook that solves this exact problem.
-  // https://19.react.dev/learn/separating-events-from-effects#declaring-an-effect-event
-  const handleChange = useEffectEvent((change: EditorChange) =>
-    onChange(change),
-  )
-
   // Subscribe to, and handle changes from the editor
   useEffect(() => {
     const onFlushPendingPatchesThrottled = throttle(
@@ -104,61 +93,17 @@ export function Synchronizer(props: SynchronizerProps) {
       },
     )
 
-    debug('Subscribing to editor changes')
-    const sub = editorActor.on('*', (event) => {
-      switch (event.type) {
-        case 'patch':
-          IS_PROCESSING_LOCAL_CHANGES.set(slateEditor, true)
-          pendingPatches.current.push(event.patch)
-          onFlushPendingPatchesThrottled()
-          handleChange(event)
-          break
-        case 'loading': {
-          handleChange({type: 'loading', isLoading: true})
-          break
-        }
-        case 'done loading': {
-          handleChange({type: 'loading', isLoading: false})
-          break
-        }
-        case 'focused': {
-          handleChange({type: 'focus', event: event.event})
-          break
-        }
-        case 'value changed': {
-          handleChange({type: 'value', value: event.value})
-          break
-        }
-        case 'invalid value': {
-          handleChange({
-            type: 'invalidValue',
-            resolution: event.resolution,
-            value: event.value,
-          })
-          break
-        }
-        case 'error': {
-          handleChange({
-            ...event,
-            level: 'warning',
-          })
-          break
-        }
-        case 'annotation.add':
-        case 'annotation.remove':
-        case 'annotation.toggle':
-        case 'focus':
-        case 'patches':
-          break
-        default:
-          handleChange(event)
-      }
+    debug('Subscribing to patch events')
+    const sub = editorActor.on('patch', (event) => {
+      IS_PROCESSING_LOCAL_CHANGES.set(slateEditor, true)
+      pendingPatches.current.push(event.patch)
+      onFlushPendingPatchesThrottled()
     })
     return () => {
-      debug('Unsubscribing to changes')
+      debug('Unsubscribing to patch events')
       sub.unsubscribe()
     }
-  }, [editorActor, handleChange, onFlushPendingPatches, slateEditor])
+  }, [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.

package/src/editor/create-slate-editor.tsx

@@ -32,8 +32,8 @@ export function createSlateEditor(config: SlateEditorConfig): SlateEditor {
 
   debug('Creating new Slate editor instance', config.editorActor.id)
 
-  let unsubscriptions: Array<() => void> = []
-  let subscriptions: Array<() => () => void> = []
+  const unsubscriptions: Array<() => void> = []
+  const subscriptions: Array<() => () => void> = []
 
   const instance = withPlugins(withReact(createEditor()), {
     editorActor: config.editorActor,
@@ -47,18 +47,6 @@ export function createSlateEditor(config: SlateEditorConfig): SlateEditor {
     unsubscriptions.push(subscription())
   }
 
-  config.editorActor.subscribe((snapshot) => {
-    if (snapshot.status !== 'active') {
-      debug('Destroying Slate editor')
-      instance.destroy()
-      for (const unsubscribe of unsubscriptions) {
-        unsubscribe()
-      }
-      subscriptions = []
-      unsubscriptions = []
-    }
-  })
-
   const initialValue = [instance.pteCreateTextBlock({decorators: []})]
 
   const slateEditor: SlateEditor = {

package/src/editor/editor-event-listener.tsx

@@ -0,0 +1,24 @@
+import {useEffect} from 'react'
+import {useEffectEvent} from 'use-effect-event'
+import type {EditorEmittedEvent} from './editor-machine'
+import {useEditorContext} from './editor-provider'
+
+/**
+ * @alpha
+ */
+export function EditorEventListener(props: {
+  on: (event: EditorEmittedEvent) => void
+}) {
+  const editor = useEditorContext()
+  const on = useEffectEvent(props.on)
+
+  useEffect(() => {
+    const subscription = editor.on('*', on)
+
+    return () => {
+      subscription.unsubscribe()
+    }
+  }, [editor, on])
+
+  return null
+}

package/src/editor/editor-machine.ts

@@ -27,6 +27,7 @@ import type {
   BehaviorActionIntend,
   BehaviorContext,
   BehaviorEvent,
+  OmitFromUnion,
   PickFromUnion,
 } from './behavior/behavior.types'
 
@@ -95,7 +96,27 @@ export type InternalEditorEvent =
       type: 'update maxBlocks'
       maxBlocks: number | undefined
     }
-  | InternalEditorEmittedEvent
+  | OmitFromUnion<InternalEditorEmittedEvent, 'type', 'readOnly toggled'>
+
+/**
+ * @alpha
+ */
+export type EditorEmittedEvent = PickFromUnion<
+  InternalEditorEmittedEvent,
+  'type',
+  | 'blur'
+  | 'done loading'
+  | 'error'
+  | 'focus'
+  | 'invalid value'
+  | 'loading'
+  | 'mutation'
+  | 'patch'
+  | 'readOnly toggled'
+  | 'ready'
+  | 'selection'
+  | 'value changed'
+>
 
 /**
  * @internal
@@ -129,6 +150,7 @@ export type InternalEditorEmittedEvent =
   | {type: 'focused'; event: FocusEvent<HTMLDivElement, Element>}
   | {type: 'loading'}
   | {type: 'done loading'}
+  | {type: 'readOnly toggled'; readOnly: boolean}
   | PickFromUnion<
       BehaviorEvent,
       'type',
@@ -154,6 +176,8 @@ export const editorMachine = setup({
     input: {} as {
       behaviors?: Array<Behavior>
       keyGenerator: () => string
+      maxBlocks?: number
+      readOnly?: boolean
       schema: PortableTextMemberSchemaTypes
       value?: Array<PortableTextBlock>
     },
@@ -296,8 +320,8 @@ export const editorMachine = setup({
     keyGenerator: input.keyGenerator,
     pendingEvents: [],
     schema: input.schema,
-    readOnly: false,
-    maxBlocks: undefined,
+    readOnly: input.readOnly ?? false,
+    maxBlocks: input.maxBlocks,
     value: input.value,
   }),
   on: {
@@ -332,7 +356,13 @@ export const editorMachine = setup({
     'update schema': {actions: 'assign schema'},
     'update value': {actions: assign({value: ({event}) => event.value})},
     'toggle readOnly': {
-      actions: assign({readOnly: ({context}) => !context.readOnly}),
+      actions: [
+        assign({readOnly: ({context}) => !context.readOnly}),
+        emit(({context}) => ({
+          type: 'readOnly toggled',
+          readOnly: context.readOnly,
+        })),
+      ],
     },
     'update maxBlocks': {
       actions: assign({maxBlocks: ({event}) => event.maxBlocks}),