@portabletext/editor 1.6.1 → 1.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@portabletext/editor",
-  "version": "1.6.1",
+  "version": "1.7.0",
   "description": "Portable Text Editor made in React",
   "keywords": [
     "sanity",
@@ -45,10 +45,11 @@
     "@portabletext/patches": "1.1.0",
     "@xstate/react": "^4.1.3",
     "debug": "^4.3.4",
+    "get-random-values-esm": "^1.0.2",
     "is-hotkey-esm": "^1.0.0",
     "lodash": "^4.17.21",
     "lodash.startcase": "^4.4.0",
-    "react-compiler-runtime": "19.0.0-beta-63b359f-20241101",
+    "react-compiler-runtime": "19.0.0-beta-a7bf2bd-20241110",
     "slate": "0.110.2",
     "slate-dom": "^0.111.0",
     "slate-react": "0.111.0",
@@ -59,10 +60,9 @@
     "@portabletext/toolkit": "^2.0.16",
     "@sanity/block-tools": "^3.63.0",
     "@sanity/diff-match-patch": "^3.1.1",
-    "@sanity/pkg-utils": "^6.11.9",
+    "@sanity/pkg-utils": "^6.11.10",
     "@sanity/schema": "^3.63.0",
     "@sanity/types": "^3.63.0",
-    "@sanity/util": "^3.63.0",
     "@testing-library/jest-dom": "^6.6.3",
     "@testing-library/react": "^16.0.1",
     "@types/debug": "^4.1.5",
@@ -70,13 +70,13 @@
     "@types/lodash.startcase": "^4.4.9",
     "@types/react": "^18.3.12",
     "@types/react-dom": "^18.3.1",
-    "@typescript-eslint/eslint-plugin": "^8.13.0",
-    "@typescript-eslint/parser": "^8.13.0",
+    "@typescript-eslint/eslint-plugin": "^8.14.0",
+    "@typescript-eslint/parser": "^8.14.0",
     "@vitejs/plugin-react": "^4.3.3",
     "@vitest/browser": "^2.1.4",
-    "babel-plugin-react-compiler": "19.0.0-beta-63b359f-20241101",
+    "babel-plugin-react-compiler": "19.0.0-beta-a7bf2bd-20241110",
     "eslint": "8.57.1",
-    "eslint-plugin-react-compiler": "19.0.0-beta-63b359f-20241101",
+    "eslint-plugin-react-compiler": "19.0.0-beta-a7bf2bd-20241110",
     "eslint-plugin-react-hooks": "^5.0.0",
     "jsdom": "^25.0.1",
     "react": "^18.3.1",
@@ -84,7 +84,7 @@
     "rxjs": "^7.8.1",
     "styled-components": "^6.1.13",
     "typescript": "5.6.3",
-    "vite": "^5.4.10",
+    "vite": "^5.4.11",
     "vitest": "^2.1.4",
     "vitest-browser-react": "^0.0.3",
     "@sanity/gherkin-driver": "^0.0.1"
@@ -93,7 +93,6 @@
     "@sanity/block-tools": "^3.63.0",
     "@sanity/schema": "^3.63.0",
     "@sanity/types": "^3.63.0",
-    "@sanity/util": "^3.63.0",
     "react": "^16.9 || ^17 || ^18",
     "rxjs": "^7.8.1",
     "styled-components": "^6.1.13"
@@ -108,7 +107,7 @@
     "build": "pkg-utils build --strict --check --clean",
     "check:lint": "biome lint .",
     "check:types": "tsc",
-    "check:react-compiler": "eslint --cache --no-inline-config --no-eslintrc --ext .cjs,.mjs,.js,.jsx,.ts,.tsx --parser @typescript-eslint/parser --plugin react-compiler --plugin react-hooks --rule 'react-compiler/react-compiler: [warn]' --rule 'react-hooks/rules-of-hooks: [error]' --rule 'react-hooks/exhaustive-deps: [error]' src",
+    "check:react-compiler": "eslint --cache --no-inline-config --no-eslintrc --ignore-pattern '**/__tests__/**' --ext .cjs,.mjs,.js,.jsx,.ts,.tsx --parser @typescript-eslint/parser --plugin react-compiler --plugin react-hooks --rule 'react-compiler/react-compiler: [warn,{__unstable_donotuse_reportAllBailouts: true}]' --rule 'react-hooks/rules-of-hooks: [error]' --rule 'react-hooks/exhaustive-deps: [error]' src",
     "clean": "del .turbo && del lib && del node_modules",
     "dev": "pkg-utils watch",
     "lint:fix": "biome lint --write .",

package/src/editor/Editable.tsx

@@ -1,4 +1,5 @@
 import type {PortableTextBlock} from '@sanity/types'
+import {useSelector} from '@xstate/react'
 import {isEqual, noop} from 'lodash'
 import {
   forwardRef,
@@ -66,8 +67,8 @@ import {Element} from './components/Element'
 import {Leaf} from './components/Leaf'
 import {EditorActorContext} from './editor-actor-context'
 import {usePortableTextEditor} from './hooks/usePortableTextEditor'
-import {usePortableTextEditorReadOnlyStatus} from './hooks/usePortableTextReadOnly'
-import {createWithHotkeys, createWithInsertData} from './plugins'
+import {createWithHotkeys} from './plugins/createWithHotKeys'
+import {createWithInsertData} from './plugins/createWithInsertData'
 import {PortableTextEditor} from './PortableTextEditor'
 import {withSyncRangeDecorations} from './withSyncRangeDecorations'
 
@@ -140,7 +141,6 @@ export const PortableTextEditable = forwardRef<
   } = props
 
   const portableTextEditor = usePortableTextEditor()
-  const readOnly = usePortableTextEditorReadOnlyStatus()
   const ref = useRef<HTMLDivElement | null>(null)
   const [editableElement, setEditableElement] = useState<HTMLDivElement | null>(
     null,
@@ -159,6 +159,7 @@ export const PortableTextEditable = forwardRef<
   const rangeDecorationsRef = useRef(rangeDecorations)
 
   const editorActor = useContext(EditorActorContext)
+  const readOnly = useSelector(editorActor, (s) => s.context.readOnly)
   const {schemaTypes} = portableTextEditor
   const slateEditor = useSlate()
 
@@ -495,7 +496,7 @@ export const PortableTextEditable = forwardRef<
           Transforms.select(slateEditor, Editor.start(slateEditor, []))
           slateEditor.onChange()
         }
-        editorActor.send({type: 'focus', event})
+        editorActor.send({type: 'focused', event})
         const newSelection = PortableTextEditor.getSelection(portableTextEditor)
         // If the selection is the same, emit it explicitly here as there is no actual onChange event triggered.
         if (selection === newSelection) {

package/src/editor/PortableTextEditor.tsx

@@ -13,6 +13,7 @@ import {
   type PropsWithChildren,
 } from 'react'
 import {Subject} from 'rxjs'
+import {Slate} from 'slate-react'
 import {createActor} from 'xstate'
 import type {
   EditableAPI,
@@ -26,14 +27,17 @@ import type {
 import {debugWithName} from '../utils/debug'
 import {getPortableTextMemberSchemaTypes} from '../utils/getPortableTextMemberSchemaTypes'
 import {compileType} from '../utils/schema'
-import {SlateContainer} from './components/SlateContainer'
 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 {PortableTextEditorContext} from './hooks/usePortableTextEditor'
 import {PortableTextEditorSelectionProvider} from './hooks/usePortableTextEditorSelection'
-import {PortableTextEditorReadOnlyContext} from './hooks/usePortableTextReadOnly'
 import {defaultKeyGenerator} from './key-generator'
+import {
+  createEditableAPI,
+  type AddedAnnotationPaths,
+} from './plugins/createWithEditableAPI'
 import type {Editor} from './use-editor'
 
 const debug = debugWithName('component:PortableTextEditor')
@@ -85,12 +89,12 @@ export type PortableTextEditorProps<
          * Backward compatibility (renamed to patches$).
          */
         incomingPatches$?: PatchObservable
-      }) & {
-    /**
-     * Whether or not the editor should be in read-only mode
-     */
-    readOnly?: boolean
 
+        /**
+         * Whether or not the editor should be in read-only mode
+         */
+        readOnly?: boolean
+      }) & {
     /**
      * The current value of the portable text field
      */
@@ -124,12 +128,14 @@ export class PortableTextEditor extends Component<
    */
   private editable?: EditableAPI
   private editorActor: EditorActor
+  private slateEditor: SlateEditor
 
   constructor(props: PortableTextEditorProps) {
     super(props)
 
     if (props.editor) {
-      this.editorActor = props.editor
+      const editor = props.editor as Editor
+      this.editorActor = editor._internal.editorActor
       this.editorActor.start()
       this.schemaTypes = this.editorActor.getSnapshot().context.schema
     } else {
@@ -149,16 +155,37 @@ export class PortableTextEditor extends Component<
           : compileType(props.schemaType),
       )
 
-      this.editorActor =
-        props.editor ??
-        createActor(editorMachine, {
-          input: {
-            keyGenerator: props.keyGenerator || defaultKeyGenerator,
-            schema: this.schemaTypes,
-          },
-        })
+      this.editorActor = createActor(editorMachine, {
+        input: {
+          keyGenerator: props.keyGenerator || defaultKeyGenerator,
+          schema: this.schemaTypes,
+        },
+      })
       this.editorActor.start()
+
+      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.slateEditor = createSlateEditor({
+      editorActor: this.editorActor,
+    })
+    this.editable = createEditableAPI(
+      this.slateEditor.instance,
+      this.editorActor,
+    )
   }
 
   componentDidUpdate(prevProps: PortableTextEditorProps) {
@@ -180,11 +207,33 @@ export class PortableTextEditor extends Component<
       })
     }
 
+    if (!this.props.editor && !prevProps.editor) {
+      if (this.props.readOnly !== prevProps.readOnly) {
+        this.editorActor.send({
+          type: 'toggle readOnly',
+        })
+      }
+
+      if (this.props.maxBlocks !== prevProps.maxBlocks) {
+        this.editorActor.send({
+          type: 'update maxBlocks',
+          maxBlocks:
+            this.props.maxBlocks === undefined
+              ? undefined
+              : Number.parseInt(this.props.maxBlocks.toString(), 10),
+        })
+      }
+    }
+
     if (this.props.editorRef !== prevProps.editorRef && this.props.editorRef) {
       this.props.editorRef.current = this
     }
   }
 
+  componentWillUnmount(): void {
+    this.slateEditor.destroy()
+  }
+
   public setEditable = (editable: EditableAPI) => {
     this.editable = {...this.editable, ...editable}
   }
@@ -198,13 +247,6 @@ export class PortableTextEditor extends Component<
   }
 
   render() {
-    const maxBlocks = !this.props.editor
-      ? typeof this.props.maxBlocks === 'undefined'
-        ? undefined
-        : Number.parseInt(this.props.maxBlocks.toString(), 10) || undefined
-      : undefined
-
-    const readOnly = Boolean(this.props.readOnly)
     const legacyPatches = !this.props.editor
       ? (this.props.incomingPatches$ ?? this.props.patches$)
       : undefined
@@ -218,37 +260,33 @@ export class PortableTextEditor extends Component<
           />
         ) : null}
         <EditorActorContext.Provider value={this.editorActor}>
-          <SlateContainer
-            editorActor={this.editorActor}
-            maxBlocks={maxBlocks}
-            portableTextEditor={this}
-            readOnly={readOnly}
+          <Slate
+            editor={this.slateEditor.instance}
+            initialValue={this.slateEditor.initialValue}
           >
             <PortableTextEditorContext.Provider value={this}>
-              <PortableTextEditorReadOnlyContext.Provider value={readOnly}>
-                <PortableTextEditorSelectionProvider
+              <PortableTextEditorSelectionProvider
+                editorActor={this.editorActor}
+              >
+                <Synchronizer
                   editorActor={this.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)
-                    }}
-                    value={this.props.value}
-                  />
-                  {this.props.children}
-                </PortableTextEditorSelectionProvider>
-              </PortableTextEditorReadOnlyContext.Provider>
+                  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)
+                  }}
+                  value={this.props.value}
+                />
+                {this.props.children}
+              </PortableTextEditorSelectionProvider>
             </PortableTextEditorContext.Provider>
-          </SlateContainer>
+          </Slate>
         </EditorActorContext.Provider>
       </>
     )
@@ -272,22 +310,8 @@ export class PortableTextEditor extends Component<
     editor: PortableTextEditor,
     type: TSchemaType,
     value?: {[prop: string]: unknown},
-  ):
-    | {
-        /**
-         * @deprecated An annotation may be applied to multiple blocks, resulting
-         * in multiple `markDef`'s being created. Use `markDefPaths` instead.
-         */
-        markDefPath: Path
-        markDefPaths: Array<Path>
-        /**
-         * @deprecated Does not return anything meaningful since an annotation
-         * can span multiple blocks and spans. If references the span closest
-         * to the focus point of the selection.
-         */
-        spanPath: Path
-      }
-    | undefined => editor.editable?.addAnnotation(type, value)
+  ): AddedAnnotationPaths | undefined =>
+    editor.editable?.addAnnotation(type, value)
   static blur = (editor: PortableTextEditor): void => {
     debug('Host blurred')
     editor.editable?.blur()

package/src/editor/behavior/behavior.action.insert-break.ts

@@ -2,10 +2,9 @@ import {isEqual} from 'lodash'
 import {Editor, Node, Path, Range, Transforms} from 'slate'
 import type {SlateTextBlock, VoidElement} from '../../types/slate'
 import type {BehaviourActionImplementation} from './behavior.actions'
-import type {BehaviorAction, PickFromUnion} from './behavior.types'
 
 export const insertBreakActionImplementation: BehaviourActionImplementation<
-  PickFromUnion<BehaviorAction, 'type', 'insert break' | 'insert soft break'>
+  'insert break'
 > = ({context, action}) => {
   const keyGenerator = context.keyGenerator
   const schema = context.schema
@@ -204,3 +203,14 @@ export const insertBreakActionImplementation: BehaviourActionImplementation<
     }
   }
 }
+
+export const insertSoftBreakActionImplementation: BehaviourActionImplementation<
+  'insert soft break'
+> = ({context, action}) => {
+  // This mimics Slate's internal which also just does a regular insert break
+  // when soft-breaking
+  insertBreakActionImplementation({
+    context,
+    action: {...action, type: 'insert break'},
+  })
+}

package/src/editor/behavior/behavior.actions.ts

@@ -5,14 +5,23 @@ import {
   insertText,
   Transforms,
 } from 'slate'
+import {ReactEditor} from 'slate-react'
 import type {PortableTextMemberSchemaTypes} from '../../types/editor'
 import {toSlateRange} from '../../utils/ranges'
+import {
+  addAnnotationActionImplementation,
+  removeAnnotationActionImplementation,
+  toggleAnnotationActionImplementation,
+} from '../plugins/createWithEditableAPI'
 import {
   addDecoratorActionImplementation,
   removeDecoratorActionImplementation,
   toggleDecoratorActionImplementation,
 } from '../plugins/createWithPortableTextMarkModel'
-import {insertBreakActionImplementation} from './behavior.action.insert-break'
+import {
+  insertBreakActionImplementation,
+  insertSoftBreakActionImplementation,
+} from './behavior.action.insert-break'
 import type {
   BehaviorAction,
   BehaviorEvent,
@@ -25,25 +34,30 @@ export type BehaviorActionContext = {
 }
 
 export type BehaviourActionImplementation<
-  TBehaviorAction extends BehaviorAction,
+  TBehaviorActionType extends BehaviorAction['type'],
+  TReturnType = void,
 > = ({
   context,
   action,
 }: {
   context: BehaviorActionContext
-  action: TBehaviorAction
-}) => void
+  action: PickFromUnion<BehaviorAction, 'type', TBehaviorActionType>
+}) => TReturnType
 
 type BehaviourActionImplementations = {
-  [TBehaviorActionType in BehaviorAction['type']]: BehaviourActionImplementation<
-    PickFromUnion<BehaviorAction, 'type', TBehaviorActionType>
-  >
+  [TBehaviorActionType in BehaviorAction['type']]: BehaviourActionImplementation<TBehaviorActionType>
 }
 
 const behaviorActionImplementations: BehaviourActionImplementations = {
+  'annotation.add': addAnnotationActionImplementation,
+  'annotation.remove': removeAnnotationActionImplementation,
+  'annotation.toggle': toggleAnnotationActionImplementation,
   'decorator.add': addDecoratorActionImplementation,
   'decorator.remove': removeDecoratorActionImplementation,
   'decorator.toggle': toggleDecoratorActionImplementation,
+  'focus': ({action}) => {
+    ReactEditor.focus(action.editor)
+  },
   'set block': ({action}) => {
     for (const path of action.paths) {
       const at = toSlateRange(
@@ -99,9 +113,7 @@ const behaviorActionImplementations: BehaviourActionImplementations = {
     }
   },
   'insert break': insertBreakActionImplementation,
-  // This mimics Slate's internal which also just does a regular insert break
-  // when on soft break
-  'insert soft break': insertBreakActionImplementation,
+  'insert soft break': insertSoftBreakActionImplementation,
   'insert text': ({action}) => {
     insertText(action.editor, action.text)
   },
@@ -205,7 +217,7 @@ export function performAction({
   }
 }
 
-export function performDefaultAction({
+function performDefaultAction({
   context,
   action,
 }: {
@@ -213,6 +225,27 @@ export function performDefaultAction({
   action: PickFromUnion<BehaviorAction, 'type', BehaviorEvent['type']>
 }) {
   switch (action.type) {
+    case 'annotation.add': {
+      behaviorActionImplementations['annotation.add']({
+        context,
+        action,
+      })
+      break
+    }
+    case 'annotation.remove': {
+      behaviorActionImplementations['annotation.remove']({
+        context,
+        action,
+      })
+      break
+    }
+    case 'annotation.toggle': {
+      behaviorActionImplementations['annotation.toggle']({
+        context,
+        action,
+      })
+      break
+    }
     case 'decorator.add': {
       behaviorActionImplementations['decorator.add']({
         context,
@@ -248,6 +281,13 @@ export function performDefaultAction({
       })
       break
     }
+    case 'focus': {
+      behaviorActionImplementations.focus({
+        context,
+        action,
+      })
+      break
+    }
     case 'insert break': {
       behaviorActionImplementations['insert break']({
         context,

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

@@ -20,6 +20,26 @@ export type BehaviorContext = {
  * @alpha
  */
 export type BehaviorEvent =
+  | {
+      type: 'annotation.add'
+      annotation: {
+        name: string
+        value: {[prop: string]: unknown}
+      }
+    }
+  | {
+      type: 'annotation.remove'
+      annotation: {
+        name: string
+      }
+    }
+  | {
+      type: 'annotation.toggle'
+      annotation: {
+        name: string
+        value: {[prop: string]: unknown}
+      }
+    }
   | {
       type: 'decorator.add'
       decorator: string
@@ -40,6 +60,9 @@ export type BehaviorEvent =
       type: 'delete forward'
       unit: TextUnit
     }
+  | {
+      type: 'focus'
+    }
   | {
       type: 'insert soft break'
     }

package/src/editor/components/Synchronizer.tsx

@@ -1,5 +1,6 @@
 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'
@@ -10,7 +11,6 @@ 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 {usePortableTextEditorReadOnlyStatus} from '../hooks/usePortableTextReadOnly'
 import {useSyncValue} from '../hooks/useSyncValue'
 
 const debug = debugWithName('component:PortableTextEditor:Synchronizer')
@@ -36,7 +36,7 @@ export interface SynchronizerProps {
  */
 export function Synchronizer(props: SynchronizerProps) {
   const portableTextEditor = usePortableTextEditor()
-  const readOnly = usePortableTextEditorReadOnlyStatus()
+  const readOnly = useSelector(props.editorActor, (s) => s.context.readOnly)
   const {editorActor, getValue, onChange, value} = props
   const pendingPatches = useRef<Patch[]>([])
 
@@ -121,6 +121,10 @@ export function Synchronizer(props: SynchronizerProps) {
           handleChange({type: 'loading', isLoading: false})
           break
         }
+        case 'focused': {
+          handleChange({type: 'focus', event: event.event})
+          break
+        }
         case 'offline': {
           handleChange({type: 'connection', value: 'offline'})
           break
@@ -148,9 +152,12 @@ export function Synchronizer(props: SynchronizerProps) {
           })
           break
         }
-        case 'patches': {
+        case 'annotation.add':
+        case 'annotation.remove':
+        case 'annotation.toggle':
+        case 'focus':
+        case 'patches':
           break
-        }
         default:
           handleChange(event)
       }

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

@@ -0,0 +1,67 @@
+import {createEditor, type Descendant} from 'slate'
+import {withReact} from 'slate-react'
+import type {PortableTextSlateEditor} from '../types/editor'
+import {debugWithName} from '../utils/debug'
+import {KEY_TO_SLATE_ELEMENT, KEY_TO_VALUE_ELEMENT} from '../utils/weakMaps'
+import type {EditorActor} from './editor-machine'
+import {withPlugins} from './plugins/with-plugins'
+
+const debug = debugWithName('component:PortableTextEditor:SlateContainer')
+
+type SlateEditorConfig = {
+  editorActor: EditorActor
+}
+
+export type SlateEditor = {
+  instance: PortableTextSlateEditor
+  initialValue: Array<Descendant>
+  destroy: () => void
+}
+
+const slateEditors = new WeakMap<EditorActor, SlateEditor>()
+
+export function createSlateEditor(config: SlateEditorConfig): SlateEditor {
+  const existingSlateEditor = slateEditors.get(config.editorActor)
+
+  if (existingSlateEditor) {
+    debug('Reusing existing Slate editor instance', config.editorActor.id)
+    return existingSlateEditor
+  }
+
+  debug('Creating new Slate editor instance', config.editorActor.id)
+
+  let unsubscriptions: Array<() => void> = []
+  let subscriptions: Array<() => () => void> = []
+
+  const instance = withPlugins(withReact(createEditor()), {
+    editorActor: config.editorActor,
+    subscriptions,
+  })
+
+  KEY_TO_VALUE_ELEMENT.set(instance, {})
+  KEY_TO_SLATE_ELEMENT.set(instance, {})
+
+  for (const subscription of subscriptions) {
+    unsubscriptions.push(subscription())
+  }
+
+  const initialValue = [instance.pteCreateTextBlock({decorators: []})]
+
+  const slateEditor: SlateEditor = {
+    instance,
+    initialValue,
+    destroy: () => {
+      debug('Destroying Slate editor')
+      instance.destroy()
+      for (const unsubscribe of unsubscriptions) {
+        unsubscribe()
+      }
+      subscriptions = []
+      unsubscriptions = []
+    },
+  }
+
+  slateEditors.set(config.editorActor, slateEditor)
+
+  return slateEditor
+}