@portabletext/editor 1.3.1 → 1.4.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@portabletext/editor",
-  "version": "1.3.1",
+  "version": "1.4.1",
   "description": "Portable Text Editor made in React",
   "keywords": [
     "sanity",
@@ -43,17 +43,19 @@
   ],
   "dependencies": {
     "@portabletext/patches": "1.1.0",
+    "@xstate/react": "^4.1.3",
     "debug": "^4.3.4",
     "is-hotkey-esm": "^1.0.0",
     "lodash": "^4.17.21",
     "react-compiler-runtime": "19.0.0-beta-6fc168f-20241025",
     "slate": "0.110.2",
-    "slate-react": "0.110.3",
+    "slate-dom": "^0.111.0",
+    "slate-react": "0.111.0",
     "use-effect-event": "^1.0.2",
     "xstate": "^5.18.2"
   },
   "devDependencies": {
-    "@babel/preset-env": "^7.25.9",
+    "@babel/preset-env": "^7.26.0",
     "@babel/preset-react": "^7.25.9",
     "@jest/globals": "^29.7.0",
     "@jest/types": "^29.6.3",
@@ -64,7 +66,7 @@
     "@sanity/pkg-utils": "^6.11.8",
     "@sanity/schema": "^3.62.3",
     "@sanity/types": "^3.62.3",
-    "@sanity/ui": "^2.8.17",
+    "@sanity/ui": "^2.8.18",
     "@sanity/util": "^3.62.3",
     "@testing-library/dom": "^10.4.0",
     "@testing-library/jest-dom": "^6.6.3",
@@ -73,7 +75,7 @@
     "@types/debug": "^4.1.5",
     "@types/express": "^4.17.21",
     "@types/express-ws": "^3.0.5",
-    "@types/lodash": "^4.17.12",
+    "@types/lodash": "^4.17.13",
     "@types/node": "^18.19.8",
     "@types/node-ipc": "^9.2.3",
     "@types/react": "^18.3.12",
@@ -83,16 +85,15 @@
     "@typescript-eslint/parser": "^8.12.2",
     "@vitejs/plugin-react": "^4.3.3",
     "@vitest/browser": "^2.1.4",
-    "@xstate/react": "^4.1.3",
     "babel-plugin-react-compiler": "beta",
     "dotenv": "^16.4.5",
-    "eslint": "8",
+    "eslint": "8.57.1",
     "eslint-plugin-react-compiler": "beta",
     "eslint-plugin-react-hooks": "^5.0.0",
     "express": "^4.21.1",
     "express-ws": "^5.0.2",
     "jest": "^29.7.0",
-    "jest-dev-server": "^10.1.1",
+    "jest-dev-server": "^10.1.4",
     "jest-environment-node": "^29.7.0",
     "jsdom": "^25.0.1",
     "node-ipc": "npm:@node-ipc/compat@9.2.5",

package/src/editor/PortableTextEditor.tsx

@@ -29,7 +29,6 @@ import type {
 import {debugWithName} from '../utils/debug'
 import {getPortableTextMemberSchemaTypes} from '../utils/getPortableTextMemberSchemaTypes'
 import {compileType} from '../utils/schema'
-import {coreBehaviors} from './behavior/behavior.core'
 import {SlateContainer} from './components/SlateContainer'
 import {Synchronizer} from './components/Synchronizer'
 import {EditorActorContext} from './editor-actor-context'
@@ -38,6 +37,7 @@ import {PortableTextEditorContext} from './hooks/usePortableTextEditor'
 import {PortableTextEditorSelectionProvider} from './hooks/usePortableTextEditorSelection'
 import {PortableTextEditorReadOnlyContext} from './hooks/usePortableTextReadOnly'
 import {defaultKeyGenerator} from './key-generator'
+import type {Editor} from './use-editor'
 
 const debug = debugWithName('component:PortableTextEditor')
 
@@ -46,58 +46,73 @@ const debug = debugWithName('component:PortableTextEditor')
  *
  * @public
  */
-export type PortableTextEditorProps = PropsWithChildren<{
-  /**
-   * Function that gets called when the editor changes the value
-   */
-  onChange: (change: EditorChange) => void
+export type PortableTextEditorProps<
+  TEditor extends Editor | undefined = undefined,
+> = PropsWithChildren<
+  (TEditor extends Editor
+    ? {
+        /**
+         * @alpha
+         */
+        editor: TEditor
+      }
+    : {
+        editor?: undefined
 
-  /**
-   * Schema type for the portable text field
-   */
-  schemaType: ArraySchemaType<PortableTextBlock> | ArrayDefinition
+        /**
+         * Function that gets called when the editor changes the value
+         */
+        onChange: (change: EditorChange) => void
 
-  /**
-   * Maximum number of blocks to allow within the editor
-   */
-  maxBlocks?: number | string
+        /**
+         * Schema type for the portable text field
+         */
+        schemaType: ArraySchemaType<PortableTextBlock> | ArrayDefinition
 
-  /**
-   * Whether or not the editor should be in read-only mode
-   */
-  readOnly?: boolean
+        /**
+         * Maximum number of blocks to allow within the editor
+         */
+        maxBlocks?: number | string
 
-  /**
-   * The current value of the portable text field
-   */
-  value?: PortableTextBlock[]
+        /**
+         * Function used to generate keys for array items (`_key`)
+         */
+        keyGenerator?: () => string
 
-  /**
-   * Function used to generate keys for array items (`_key`)
-   */
-  keyGenerator?: () => string
+        /**
+         * Observable of local and remote patches for the edited value.
+         */
+        patches$?: PatchObservable
 
-  /**
-   * Observable of local and remote patches for the edited value.
-   */
-  patches$?: PatchObservable
+        /**
+         * Backward compatibility (renamed to patches$).
+         */
+        incomingPatches$?: PatchObservable
+      }) & {
+    /**
+     * Whether or not the editor should be in read-only mode
+     */
+    readOnly?: boolean
 
-  /**
-   * Backward compatibility (renamed to patches$).
-   */
-  incomingPatches$?: PatchObservable
+    /**
+     * The current value of the portable text field
+     */
+    value?: PortableTextBlock[]
 
-  /**
-   * A ref to the editor instance
-   */
-  editorRef?: MutableRefObject<PortableTextEditor | null>
-}>
+    /**
+     * A ref to the editor instance
+     */
+    editorRef?: MutableRefObject<PortableTextEditor | null>
+  }
+>
 
 /**
  * The main Portable Text Editor component.
  * @public
  */
-export class PortableTextEditor extends Component<PortableTextEditorProps> {
+export class PortableTextEditor extends Component<
+  PortableTextEditorProps<Editor | undefined>
+> {
   public static displayName = 'PortableTextEditor'
   /**
    * An observable of all the editor changes.
@@ -116,35 +131,46 @@ export class PortableTextEditor extends Component<PortableTextEditorProps> {
   constructor(props: PortableTextEditorProps) {
     super(props)
 
-    if (!props.schemaType) {
-      throw new Error('PortableTextEditor: missing "schemaType" property')
-    }
+    if (props.editor) {
+      this.editorActor = props.editor
+      this.editorActor.start()
+      this.schemaTypes = this.editorActor.getSnapshot().context.schema
+    } 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$'`,
-      )
-    }
+      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.schemaTypes = getPortableTextMemberSchemaTypes(
+        props.schemaType.hasOwnProperty('jsonType')
+          ? props.schemaType
+          : compileType(props.schemaType),
+      )
 
-    this.editorActor = createActor(editorMachine, {
-      input: {
-        behaviors: coreBehaviors,
-        keyGenerator: props.keyGenerator || defaultKeyGenerator,
-        schema: this.schemaTypes,
-      },
-    })
-    this.editorActor.start()
+      this.editorActor =
+        props.editor ??
+        createActor(editorMachine, {
+          input: {
+            keyGenerator: props.keyGenerator || defaultKeyGenerator,
+            schema: this.schemaTypes,
+          },
+        })
+      this.editorActor.start()
+    }
   }
 
   componentDidUpdate(prevProps: PortableTextEditorProps) {
     // Set up the schema type lookup table again if the source schema type changes
-    if (this.props.schemaType !== prevProps.schemaType) {
+    if (
+      !this.props.editor &&
+      !prevProps.editor &&
+      this.props.schemaType !== prevProps.schemaType
+    ) {
       this.schemaTypes = getPortableTextMemberSchemaTypes(
         this.props.schemaType.hasOwnProperty('jsonType')
           ? this.props.schemaType
@@ -175,22 +201,23 @@ export class PortableTextEditor extends Component<PortableTextEditorProps> {
   }
 
   render() {
-    const {value, children, patches$, incomingPatches$} = this.props
-    const _patches$ = incomingPatches$ || patches$ // Backward compatibility
-
-    const maxBlocks =
-      typeof this.props.maxBlocks === 'undefined'
+    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
 
     return (
       <>
-        {_patches$ ? (
+        {legacyPatches ? (
           <RoutePatchesObservableToEditorActor
             editorActor={this.editorActor}
-            patches$={_patches$}
+            patches$={legacyPatches}
           />
         ) : null}
         <EditorActorContext.Provider value={this.editorActor}>
@@ -209,16 +236,18 @@ export class PortableTextEditor extends Component<PortableTextEditorProps> {
                     editorActor={this.editorActor}
                     getValue={this.getValue}
                     onChange={(change) => {
-                      this.props.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={value}
+                    value={this.props.value}
                   />
-                  {children}
+                  {this.props.children}
                 </PortableTextEditorSelectionProvider>
               </PortableTextEditorReadOnlyContext.Provider>
             </PortableTextEditorContext.Provider>

package/src/editor/behavior/behavior.markdown.ts

@@ -0,0 +1,203 @@
+import type {PortableTextMemberSchemaTypes} from '../../types/editor'
+import {defineBehavior} from './behavior.types'
+import {
+  getFocusSpan,
+  getFocusTextBlock,
+  selectionIsCollapsed,
+} from './behavior.utils'
+
+/**
+ * @alpha
+ */
+export type MarkdownBehaviorsConfig = {
+  mapDefaultStyle: (schema: PortableTextMemberSchemaTypes) => string | undefined
+  mapHeadingStyle: (
+    schema: PortableTextMemberSchemaTypes,
+    level: number,
+  ) => string | undefined
+  mapBlockquoteStyle: (
+    schema: PortableTextMemberSchemaTypes,
+  ) => string | undefined
+  mapUnorderedListStyle: (
+    schema: PortableTextMemberSchemaTypes,
+  ) => string | undefined
+  mapOrderedListStyle: (
+    schema: PortableTextMemberSchemaTypes,
+  ) => string | undefined
+}
+
+/**
+ * @alpha
+ */
+export function createMarkdownBehaviors(config: MarkdownBehaviorsConfig) {
+  const automaticStyleOnSpace = defineBehavior({
+    on: 'insert text',
+    guard: ({context, event}) => {
+      const isSpace = event.text === ' '
+
+      if (!isSpace) {
+        return false
+      }
+
+      const selectionCollapsed = selectionIsCollapsed(context)
+      const focusTextBlock = getFocusTextBlock(context)
+      const focusSpan = getFocusSpan(context)
+
+      if (!selectionCollapsed || !focusTextBlock || !focusSpan) {
+        return false
+      }
+
+      const looksLikeMarkdownHeading = /^#+/.test(focusSpan.node.text)
+      const headingStyle = config.mapHeadingStyle(
+        context.schema,
+        focusSpan.node.text.length,
+      )
+
+      const looksLikeMarkdownQuote = /^>/.test(focusSpan.node.text)
+      const blockquoteStyle = config.mapBlockquoteStyle(context.schema)
+
+      if (looksLikeMarkdownHeading && headingStyle !== undefined) {
+        return {focusTextBlock, focusSpan, style: headingStyle}
+      }
+
+      if (looksLikeMarkdownQuote && blockquoteStyle !== undefined) {
+        return {focusTextBlock, focusSpan, style: blockquoteStyle}
+      }
+
+      return false
+    },
+    actions: [
+      () => [
+        {
+          type: 'insert text',
+          text: ' ',
+        },
+      ],
+      (_, {focusTextBlock, focusSpan, style}) => [
+        {
+          type: 'set block',
+          style,
+          paths: [focusTextBlock.path],
+        },
+        {
+          type: 'delete',
+          selection: {
+            anchor: {path: focusSpan.path, offset: 0},
+            focus: {
+              path: focusSpan.path,
+              offset: focusSpan.node.text.length + 1,
+            },
+          },
+        },
+      ],
+    ],
+  })
+  const clearStyleOnBackspace = defineBehavior({
+    on: 'delete backward',
+    guard: ({context}) => {
+      const selectionCollapsed = selectionIsCollapsed(context)
+      const focusTextBlock = getFocusTextBlock(context)
+      const focusSpan = getFocusSpan(context)
+
+      if (!selectionCollapsed || !focusTextBlock || !focusSpan) {
+        return false
+      }
+
+      const defaultStyle = config.mapDefaultStyle(context.schema)
+
+      if (
+        defaultStyle &&
+        focusTextBlock.node.children.length === 1 &&
+        focusTextBlock.node.style !== config.mapDefaultStyle(context.schema) &&
+        focusSpan.node.text === ''
+      ) {
+        return {defaultStyle, focusTextBlock}
+      }
+
+      return false
+    },
+    actions: [
+      (_, {defaultStyle, focusTextBlock}) => [
+        {
+          type: 'set block',
+          style: defaultStyle,
+          paths: [focusTextBlock.path],
+        },
+      ],
+    ],
+  })
+
+  const automaticListOnSpace = defineBehavior({
+    on: 'insert text',
+    guard: ({context, event}) => {
+      const isSpace = event.text === ' '
+
+      if (!isSpace) {
+        return false
+      }
+
+      const selectionCollapsed = selectionIsCollapsed(context)
+      const focusTextBlock = getFocusTextBlock(context)
+      const focusSpan = getFocusSpan(context)
+
+      if (!selectionCollapsed || !focusTextBlock || !focusSpan) {
+        return false
+      }
+
+      const looksLikeUnorderedList = /^-/.test(focusSpan.node.text)
+      const unorderedListStyle = config.mapUnorderedListStyle(context.schema)
+
+      if (looksLikeUnorderedList && unorderedListStyle !== undefined) {
+        return {focusTextBlock, focusSpan, listItem: unorderedListStyle}
+      }
+
+      const looksLikeOrderedList = /^1./.test(focusSpan.node.text)
+      const orderedListStyle = config.mapOrderedListStyle(context.schema)
+
+      if (looksLikeOrderedList && orderedListStyle !== undefined) {
+        return {focusTextBlock, focusSpan, listItem: orderedListStyle}
+      }
+
+      return false
+    },
+    actions: [
+      () => [
+        {
+          type: 'insert text',
+          text: ' ',
+        },
+      ],
+      (_, {focusTextBlock, focusSpan, listItem}) => [
+        {
+          type: 'unset block',
+          props: ['style'],
+          paths: [focusTextBlock.path],
+        },
+        {
+          type: 'set block',
+          listItem,
+          level: 1,
+          paths: [focusTextBlock.path],
+        },
+        {
+          type: 'delete',
+          selection: {
+            anchor: {path: focusSpan.path, offset: 0},
+            focus: {
+              path: focusSpan.path,
+              offset: focusSpan.node.text.length + 1,
+            },
+          },
+        },
+      ],
+    ],
+  })
+
+  const markdownBehaviors = [
+    automaticStyleOnSpace,
+    clearStyleOnBackspace,
+    automaticListOnSpace,
+  ]
+
+  return markdownBehaviors
+}

package/src/editor/editor-machine.ts

@@ -21,6 +21,7 @@ import {toPortableTextRange} from '../utils/ranges'
 import {fromSlateValue} from '../utils/values'
 import {KEY_TO_VALUE_ELEMENT} from '../utils/weakMaps'
 import {performAction, performDefaultAction} from './behavior/behavior.actions'
+import {coreBehaviors} from './behavior/behavior.core'
 import type {
   Behavior,
   BehaviorAction,
@@ -91,6 +92,10 @@ type EditorEvent =
       type: 'update schema'
       schema: PortableTextMemberSchemaTypes
     }
+  | {
+      type: 'update behaviors'
+      behaviors: Array<Behavior>
+    }
   | EditorEmittedEvent
 
 type EditorEmittedEvent =
@@ -139,12 +144,18 @@ export const editorMachine = setup({
     events: {} as EditorEvent,
     emitted: {} as EditorEmittedEvent,
     input: {} as {
-      behaviors: Array<Behavior>
+      behaviors?: Array<Behavior>
       keyGenerator: () => string
       schema: PortableTextMemberSchemaTypes
     },
   },
   actions: {
+    'assign behaviors': assign({
+      behaviors: ({event}) => {
+        assertEvent(event, 'update behaviors')
+        return [...coreBehaviors, ...event.behaviors]
+      },
+    }),
     'assign schema': assign({
       schema: ({event}) => {
         assertEvent(event, 'update schema')
@@ -263,7 +274,9 @@ export const editorMachine = setup({
 }).createMachine({
   id: 'editor',
   context: ({input}) => ({
-    behaviors: input.behaviors,
+    behaviors: input.behaviors
+      ? [...coreBehaviors, ...input.behaviors]
+      : coreBehaviors,
     keyGenerator: input.keyGenerator,
     pendingEvents: [],
     schema: input.schema,
@@ -286,6 +299,7 @@ export const editorMachine = setup({
     'loading': {actions: emit({type: 'loading'})},
     'patches': {actions: emit(({event}) => event)},
     'done loading': {actions: emit({type: 'done loading'})},
+    'update behaviors': {actions: 'assign behaviors'},
     'update schema': {actions: 'assign schema'},
     'behavior event': {actions: 'handle behavior event'},
     'behavior action intends': {

package/src/editor/plugins/createWithEditableAPI.ts

@@ -18,8 +18,8 @@ import {
   Text,
   Transforms,
 } from 'slate'
+import type {DOMNode} from 'slate-dom'
 import {ReactEditor} from 'slate-react'
-import type {DOMNode} from 'slate-react/dist/utils/dom'
 import type {
   EditableAPI,
   EditableAPIDeleteOptions,

package/src/editor/use-editor.ts

@@ -0,0 +1,45 @@
+import type {
+  ArrayDefinition,
+  ArraySchemaType,
+  PortableTextBlock,
+} from '@sanity/types'
+import {useActorRef} from '@xstate/react'
+import {getPortableTextMemberSchemaTypes} from '../utils/getPortableTextMemberSchemaTypes'
+import {compileType} from '../utils/schema'
+import type {Behavior} from './behavior/behavior.types'
+import {editorMachine} from './editor-machine'
+import {defaultKeyGenerator} from './key-generator'
+
+/**
+ * @alpha
+ */
+export type EditorConfig = {
+  behaviors?: Array<Behavior>
+  keyGenerator?: () => string
+  schema: ArraySchemaType<PortableTextBlock> | ArrayDefinition
+}
+
+/**
+ * @alpha
+ */
+export type Editor = ReturnType<typeof useEditor>
+
+/**
+ * @alpha
+ */
+export function useEditor(config: EditorConfig) {
+  const schema = getPortableTextMemberSchemaTypes(
+    config.schema.hasOwnProperty('jsonType')
+      ? config.schema
+      : compileType(config.schema),
+  )
+  const editorActor = useActorRef(editorMachine, {
+    input: {
+      behaviors: config.behaviors,
+      keyGenerator: config.keyGenerator ?? defaultKeyGenerator,
+      schema,
+    },
+  })
+
+  return editorActor
+}

package/src/index.ts

@@ -1,13 +1,18 @@
 export type {Patch} from '@portabletext/patches'
-export type {
-  Behavior,
-  BehaviorActionIntend,
-  BehaviorContext,
-  BehaviorEvent,
-  BehaviorGuard,
-  PickFromUnion,
-  BehaviorActionIntendSet,
+export {
+  type Behavior,
+  type BehaviorActionIntend,
+  type BehaviorContext,
+  type BehaviorEvent,
+  type BehaviorGuard,
+  type PickFromUnion,
+  type BehaviorActionIntendSet,
+  defineBehavior,
 } from './editor/behavior/behavior.types'
+export {
+  createMarkdownBehaviors,
+  type MarkdownBehaviorsConfig,
+} from './editor/behavior/behavior.markdown'
 export {PortableTextEditable} from './editor/Editable'
 export type {PortableTextEditableProps} from './editor/Editable'
 export {
@@ -22,5 +27,6 @@ export {usePortableTextEditorSelection} from './editor/hooks/usePortableTextEdit
 export {defaultKeyGenerator as keyGenerator} from './editor/key-generator'
 export {PortableTextEditor} from './editor/PortableTextEditor'
 export type {PortableTextEditorProps} from './editor/PortableTextEditor'
+export {useEditor, type Editor, type EditorConfig} from './editor/use-editor'
 export * from './types/editor'
 export * from './types/options'

package/src/types/editor.ts

@@ -30,8 +30,8 @@ import type {
   Node as SlateNode,
   Operation as SlateOperation,
 } from 'slate'
+import type {DOMNode} from 'slate-dom'
 import type {ReactEditor} from 'slate-react'
-import type {DOMNode} from 'slate-react/dist/utils/dom'
 import type {PortableTextEditableProps} from '../editor/Editable'
 import type {PortableTextEditor} from '../editor/PortableTextEditor'