@portabletext/editor 1.3.0 → 1.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@portabletext/editor",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "description": "Portable Text Editor made in React",
   "keywords": [
     "sanity",
@@ -67,7 +67,7 @@
     "@sanity/ui": "^2.8.17",
     "@sanity/util": "^3.62.3",
     "@testing-library/dom": "^10.4.0",
-    "@testing-library/jest-dom": "^6.6.2",
+    "@testing-library/jest-dom": "^6.6.3",
     "@testing-library/react": "^16.0.1",
     "@testing-library/user-event": "^14.5.2",
     "@types/debug": "^4.1.5",

package/src/editor/PortableTextEditor.tsx

@@ -9,7 +9,12 @@ import type {
   PortableTextObject,
   SpanSchemaType,
 } from '@sanity/types'
-import {Component, type MutableRefObject, type PropsWithChildren} from 'react'
+import {
+  Component,
+  useEffect,
+  type MutableRefObject,
+  type PropsWithChildren,
+} from 'react'
 import {Subject} from 'rxjs'
 import {createActor} from 'xstate'
 import type {
@@ -24,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'
@@ -33,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')
 
@@ -41,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.
@@ -111,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
@@ -170,49 +201,59 @@ 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 (
-      <EditorActorContext.Provider value={this.editorActor}>
-        <SlateContainer
-          editorActor={this.editorActor}
-          maxBlocks={maxBlocks}
-          patches$={_patches$}
-          portableTextEditor={this}
-          readOnly={readOnly}
-        >
-          <PortableTextEditorContext.Provider value={this}>
-            <PortableTextEditorReadOnlyContext.Provider value={readOnly}>
-              <PortableTextEditorSelectionProvider
-                editorActor={this.editorActor}
-              >
-                <Synchronizer
+      <>
+        {legacyPatches ? (
+          <RoutePatchesObservableToEditorActor
+            editorActor={this.editorActor}
+            patches$={legacyPatches}
+          />
+        ) : null}
+        <EditorActorContext.Provider value={this.editorActor}>
+          <SlateContainer
+            editorActor={this.editorActor}
+            maxBlocks={maxBlocks}
+            portableTextEditor={this}
+            readOnly={readOnly}
+          >
+            <PortableTextEditorContext.Provider value={this}>
+              <PortableTextEditorReadOnlyContext.Provider value={readOnly}>
+                <PortableTextEditorSelectionProvider
                   editorActor={this.editorActor}
-                  getValue={this.getValue}
-                  onChange={(change) => {
-                    this.props.onChange(change)
-                    /**
-                     * For backwards compatibility, we relay all changes to the
-                     * `change$` Subject as well.
-                     */
-                    this.change$.next(change)
-                  }}
-                  value={value}
-                />
-                {children}
-              </PortableTextEditorSelectionProvider>
-            </PortableTextEditorReadOnlyContext.Provider>
-          </PortableTextEditorContext.Provider>
-        </SlateContainer>
-      </EditorActorContext.Provider>
+                >
+                  <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>
+            </PortableTextEditorContext.Provider>
+          </SlateContainer>
+        </EditorActorContext.Provider>
+      </>
     )
   }
 
@@ -378,3 +419,23 @@ export class PortableTextEditor extends Component<PortableTextEditorProps> {
     return editor.editable?.isSelectionsOverlapping(selectionA, selectionB)
   }
 }
+
+function RoutePatchesObservableToEditorActor(props: {
+  editorActor: EditorActor
+  patches$: PatchObservable
+}) {
+  useEffect(() => {
+    const subscription = props.patches$.subscribe((payload) => {
+      props.editorActor.send({
+        type: 'patches',
+        ...payload,
+      })
+    })
+
+    return () => {
+      subscription.unsubscribe()
+    }
+  }, [props.editorActor, props.patches$])
+
+  return null
+}

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/components/SlateContainer.tsx

@@ -1,7 +1,6 @@
 import {useEffect, useMemo, useState, type PropsWithChildren} from 'react'
 import {createEditor} from 'slate'
 import {Slate, withReact} from 'slate-react'
-import type {PatchObservable} 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'
@@ -16,7 +15,6 @@ const debug = debugWithName('component:PortableTextEditor:SlateContainer')
 export interface SlateContainerProps extends PropsWithChildren {
   editorActor: EditorActor
   maxBlocks: number | undefined
-  patches$?: PatchObservable
   portableTextEditor: PortableTextEditor
   readOnly: boolean
 }
@@ -26,7 +24,7 @@ export interface SlateContainerProps extends PropsWithChildren {
  * @internal
  */
 export function SlateContainer(props: SlateContainerProps) {
-  const {editorActor, patches$, portableTextEditor, readOnly, maxBlocks} = props
+  const {editorActor, portableTextEditor, readOnly, maxBlocks} = props
 
   // Create the slate instance, using `useState` ensures setup is only run once, initially
   const [[slateEditor, subscribe]] = useState(() => {
@@ -34,7 +32,6 @@ export function SlateContainer(props: SlateContainerProps) {
     const {editor, subscribe: _sub} = withPlugins(withReact(createEditor()), {
       editorActor,
       maxBlocks,
-      patches$,
       portableTextEditor,
       readOnly,
     })
@@ -56,18 +53,10 @@ export function SlateContainer(props: SlateContainerProps) {
     withPlugins(slateEditor, {
       editorActor,
       maxBlocks,
-      patches$,
       portableTextEditor,
       readOnly,
     })
-  }, [
-    editorActor,
-    portableTextEditor,
-    maxBlocks,
-    readOnly,
-    patches$,
-    slateEditor,
-  ])
+  }, [editorActor, portableTextEditor, maxBlocks, readOnly, slateEditor])
 
   const initialValue = useMemo(() => {
     return [slateEditor.pteCreateTextBlock({decorators: []})]