@portabletext/editor 1.26.3 → 1.28.0

package/src/editor/editor-machine.ts

@@ -21,7 +21,7 @@ import {
   type SyntheticBehaviorEvent,
 } from '../behaviors/behavior.types'
 import type {Converter} from '../converters/converter.types'
-import type {OmitFromUnion, PickFromUnion} from '../type-utils'
+import type {NamespaceEvent} from '../type-utils'
 import type {
   EditorSelection,
   InvalidValueResolution,
@@ -34,17 +34,7 @@ import {withApplyingBehaviorActions} from './with-applying-behavior-actions'
 export * from 'xstate/guards'
 
 /**
- * @internal
- */
-export type EditorActor = ActorRefFrom<typeof editorMachine>
-
-/**
- * @internal
- */
-export type PatchEvent = {type: 'patch'; patch: Patch}
-
-/**
- * @internal
+ * @public
  */
 export type PatchesEvent = {
   type: 'patches'
@@ -53,7 +43,7 @@ export type PatchesEvent = {
 }
 
 /**
- * @internal
+ * @public
  */
 export type MutationEvent = {
   type: 'mutation'
@@ -66,26 +56,9 @@ export type MutationEvent = {
 }
 
 /**
- * @internal
+ * @public
  */
-export type InternalEditorEvent =
-  | {type: 'normalizing'}
-  | {type: 'done normalizing'}
-  | {type: 'done syncing initial value'}
-  | {
-      type: 'behavior event'
-      behaviorEvent: SyntheticBehaviorEvent | NativeBehaviorEvent
-      editor: PortableTextSlateEditor
-      defaultActionCallback?: () => void
-      nativeEvent?: {preventDefault: () => void}
-    }
-  | {
-      type: 'custom behavior event'
-      behaviorEvent: CustomBehaviorEvent
-      editor: PortableTextSlateEditor
-      nativeEvent?: {preventDefault: () => void}
-    }
-  | CustomBehaviorEvent
+export type ExternalEditorEvent =
   | {
       type: 'add behavior'
       behavior: Behavior
@@ -118,53 +91,21 @@ export type InternalEditorEvent =
       type: 'update maxBlocks'
       maxBlocks: number | undefined
     }
-  | OmitFromUnion<
-      InternalEditorEmittedEvent,
-      'type',
-      'ready' | 'read only' | 'editable'
-    >
+  | PatchesEvent
 
 /**
  * @public
  */
-export type EditorEmittedEvent = PickFromUnion<
-  InternalEditorEmittedEvent,
-  'type',
-  | 'blurred'
-  | 'done loading'
-  | 'editable'
-  | 'error'
-  | 'focused'
-  | 'invalid value'
-  | 'loading'
-  | 'mutation'
-  | 'patch'
-  | 'read only'
-  | 'ready'
-  | 'selection'
-  | 'value changed'
->
-
-/**
- * @internal
- */
-export type InternalEditorEmittedEvent =
-  | {type: 'ready'}
-  | PatchEvent
-  | PatchesEvent
-  | MutationEvent
+export type EditorEmittedEvent =
   | {
-      type: 'unset'
-      previousValue: Array<PortableTextBlock>
+      type: 'blurred'
+      event: FocusEvent<HTMLDivElement, Element>
     }
   | {
-      type: 'value changed'
-      value: Array<PortableTextBlock> | undefined
+      type: 'done loading'
     }
   | {
-      type: 'invalid value'
-      resolution: InvalidValueResolution | null
-      value: Array<PortableTextBlock> | undefined
+      type: 'editable'
     }
   | {
       type: 'error'
@@ -172,59 +113,96 @@ export type InternalEditorEmittedEvent =
       description: string
       data: unknown
     }
-  | {type: 'selection'; selection: EditorSelection}
-  | {type: 'blurred'; event: FocusEvent<HTMLDivElement, Element>}
-  | {type: 'focused'; event: FocusEvent<HTMLDivElement, Element>}
-  | {type: 'loading'}
-  | {type: 'done loading'}
-  | {type: 'read only'}
-  | {type: 'editable'}
-  | PickFromUnion<
-      SyntheticBehaviorEvent,
-      'type',
-      | 'annotation.add'
-      | 'annotation.remove'
-      | 'annotation.toggle'
-      | 'block.set'
-      | 'block.unset'
-      | 'blur'
-      | 'data transfer.set'
-      | 'decorator.add'
-      | 'decorator.remove'
-      | 'decorator.toggle'
-      | 'delete.backward'
-      | 'delete.block'
-      | 'delete.forward'
-      | 'delete.text'
-      | 'deserialization.failure'
-      | 'deserialization.success'
-      | 'focus'
-      | 'insert.block'
-      | 'insert.block object'
-      | 'insert.inline object'
-      | 'insert.span'
-      | 'insert.text block'
-      | 'list item.add'
-      | 'list item.remove'
-      | 'list item.toggle'
-      | 'move.block'
-      | 'move.block down'
-      | 'move.block up'
-      | 'select'
-      | 'select.next block'
-      | 'select.previous block'
-      | 'serialization.failure'
-      | 'serialization.success'
-      | 'style.add'
-      | 'style.remove'
-      | 'style.toggle'
-      | 'text block.set'
-      | 'text block.unset'
-    >
+  | {
+      type: 'focused'
+      event: FocusEvent<HTMLDivElement, Element>
+    }
+  | {
+      type: 'invalid value'
+      resolution: InvalidValueResolution | null
+      value: Array<PortableTextBlock> | undefined
+    }
+  | {
+      type: 'loading'
+    }
+  | MutationEvent
+  | PatchEvent
+  | {
+      type: 'read only'
+    }
+  | {
+      type: 'ready'
+    }
+  | {
+      type: 'selection'
+      selection: EditorSelection
+    }
+  | {
+      type: 'value changed'
+      value: Array<PortableTextBlock> | undefined
+    }
+
+type PatchEvent = {
+  type: 'patch'
+  patch: Patch
+}
+
+type UnsetEvent = {
+  type: 'unset'
+  previousValue: Array<PortableTextBlock>
+}
+
+/**
+ * @internal
+ */
+export type EditorActor = ActorRefFrom<typeof editorMachine>
+
+/**
+ * @internal
+ */
+export type InternalEditorEvent =
+  | {
+      type: 'normalizing'
+    }
+  | {
+      type: 'done normalizing'
+    }
+  | {
+      type: 'done syncing initial value'
+    }
+  | {
+      type: 'behavior event'
+      behaviorEvent: SyntheticBehaviorEvent | NativeBehaviorEvent
+      editor: PortableTextSlateEditor
+      defaultActionCallback?: () => void
+      nativeEvent?: {preventDefault: () => void}
+    }
+  | {
+      type: 'custom behavior event'
+      behaviorEvent: CustomBehaviorEvent
+      editor: PortableTextSlateEditor
+      nativeEvent?: {preventDefault: () => void}
+    }
+  | CustomBehaviorEvent
+  | ExternalEditorEvent
+  | MutationEvent
+  | NamespaceEvent<EditorEmittedEvent, 'notify'>
+  | NamespaceEvent<UnsetEvent, 'notify'>
+  | PatchEvent
+  | SyntheticBehaviorEvent
+
+/**
+ * @internal
+ */
+export type InternalEditorEmittedEvent =
+  | EditorEmittedEvent
+  | PatchesEvent
+  | UnsetEvent
   | {
       type: 'custom.*'
       event: CustomBehaviorEvent
     }
+  | SyntheticBehaviorEvent
 
 /**
  * @internal
@@ -514,23 +492,32 @@ export const editorMachine = setup({
     value: input.value,
   }),
   on: {
-    'add behavior': {actions: 'add behavior to context'},
-    'remove behavior': {actions: 'remove behavior from context'},
-    'unset': {actions: emit(({event}) => event)},
-    'value changed': {actions: emit(({event}) => event)},
-    'invalid value': {actions: emit(({event}) => event)},
-    'error': {actions: emit(({event}) => event)},
-    'selection': {
+    'notify.blurred': {
+      actions: emit(({event}) => ({...event, type: 'blurred'})),
+    },
+    'notify.done loading': {actions: emit({type: 'done loading'})},
+    'notify.error': {actions: emit(({event}) => ({...event, type: 'error'}))},
+    'notify.invalid value': {
+      actions: emit(({event}) => ({...event, type: 'invalid value'})),
+    },
+    'notify.focused': {
+      actions: emit(({event}) => ({...event, type: 'focused'})),
+    },
+    'notify.selection': {
       actions: [
         assign({selection: ({event}) => event.selection}),
-        emit(({event}) => event),
+        emit(({event}) => ({...event, type: 'selection'})),
       ],
     },
-    'blurred': {actions: emit(({event}) => event)},
-    'focused': {actions: emit(({event}) => event)},
-    'loading': {actions: emit({type: 'loading'})},
+    'notify.unset': {actions: emit(({event}) => ({...event, type: 'unset'}))},
+    'notify.loading': {actions: emit({type: 'loading'})},
+    'notify.value changed': {
+      actions: emit(({event}) => ({...event, type: 'value changed'})),
+    },
+
+    'add behavior': {actions: 'add behavior to context'},
+    'remove behavior': {actions: 'remove behavior from context'},
     'patches': {actions: emit(({event}) => event)},
-    'done loading': {actions: emit({type: 'done loading'})},
     'update behaviors': {actions: 'assign behaviors'},
     'update key generator': {
       actions: assign({keyGenerator: ({event}) => event.keyGenerator}),

package/src/editor/plugins/create-with-event-listeners.ts

@@ -17,6 +17,24 @@ export function createWithEventListeners(
     subscriptions.push(() => {
       const subscription = editorActor.on('*', (event) => {
         switch (event.type) {
+          // These events are not relevant for Behaviors
+          case 'blurred':
+          case 'done loading':
+          case 'editable':
+          case 'error':
+          case 'focused':
+          case 'invalid value':
+          case 'loading':
+          case 'mutation':
+          case 'patch':
+          case 'patches':
+          case 'read only':
+          case 'ready':
+          case 'selection':
+          case 'value changed':
+          case 'unset':
+            break
+
           case 'custom.*':
             editorActor.send({
               type: 'custom behavior event',
@@ -25,44 +43,7 @@ export function createWithEventListeners(
             })
             break
 
-          case 'annotation.add':
-          case 'annotation.remove':
-          case 'annotation.toggle':
-          case 'block.set':
-          case 'block.unset':
-          case 'blur':
-          case 'data transfer.set':
-          case 'decorator.add':
-          case 'decorator.remove':
-          case 'decorator.toggle':
-          case 'delete.backward':
-          case 'delete.block':
-          case 'delete.forward':
-          case 'delete.text':
-          case 'deserialization.failure':
-          case 'deserialization.success':
-          case 'focus':
-          case 'insert.block':
-          case 'insert.block object':
-          case 'insert.inline object':
-          case 'insert.span':
-          case 'insert.text block':
-          case 'list item.add':
-          case 'list item.remove':
-          case 'list item.toggle':
-          case 'move.block':
-          case 'move.block down':
-          case 'move.block up':
-          case 'select':
-          case 'select.next block':
-          case 'select.previous block':
-          case 'serialization.failure':
-          case 'serialization.success':
-          case 'style.add':
-          case 'style.remove':
-          case 'style.toggle':
-          case 'text block.set':
-          case 'text block.unset':
+          default:
             editorActor.send({
               type: 'behavior event',
               behaviorEvent: event,

package/src/editor/plugins/createWithPatches.ts

@@ -271,7 +271,7 @@ export function createWithPatches({
       ) {
         patches = [...patches, unset([])]
         editorActor.send({
-          type: 'unset',
+          type: 'notify.unset',
           previousValue: fromSlateValue(
             previousChildren,
             schemaTypes.block.name,

package/src/editor/plugins/createWithPortableTextSelections.ts

@@ -45,9 +45,9 @@ export function createWithPortableTextSelections(
           )
         }
         if (ptRange) {
-          editorActor.send({type: 'selection', selection: ptRange})
+          editorActor.send({type: 'notify.selection', selection: ptRange})
         } else {
-          editorActor.send({type: 'selection', selection: null})
+          editorActor.send({type: 'notify.selection', selection: null})
         }
       }
       prevSelection = editor.selection

package/src/editor/sync-machine.ts

@@ -168,11 +168,9 @@ export const syncMachine = setup({
       assertEvent(event, 'done syncing')
       return context.pendingValue !== event.value
     },
-    'pending value equals previous value': ({context}) =>
-      !(
-        context.previousValue === undefined &&
-        context.pendingValue === undefined
-      ) && isEqual(context.pendingValue, context.previousValue),
+    'pending value equals previous value': ({context}) => {
+      return isEqual(context.pendingValue, context.previousValue)
+    },
   },
   actors: {
     'sync value': syncValueLogic,

package/src/index.ts

@@ -25,16 +25,11 @@ export type {PortableTextMemberSchemaTypes} from './types/editor'
 export type {EditorSchema} from './editor/define-schema'
 export {PortableTextEditable} from './editor/Editable'
 export type {PortableTextEditableProps} from './editor/Editable'
-export {EditorEventListener} from './editor/editor-event-listener'
-export {
-  editorMachine,
-  type EditorActor,
-  type EditorEmittedEvent,
-  type InternalEditorEmittedEvent,
-  type InternalEditorEvent,
-  type MutationEvent,
-  type PatchEvent,
-  type PatchesEvent,
+export {EventListenerPlugin as EditorEventListener} from './plugins/plugin.event-listener'
+export type {
+  EditorEmittedEvent,
+  MutationEvent,
+  PatchesEvent,
 } from './editor/editor-machine'
 export {
   EditorProvider,
@@ -49,6 +44,5 @@ export {defaultKeyGenerator as keyGenerator} from './editor/key-generator'
 export type {AddedAnnotationPaths} from './editor/plugins/createWithEditableAPI'
 export {PortableTextEditor} from './editor/PortableTextEditor'
 export type {PortableTextEditorProps} from './editor/PortableTextEditor'
-export type {OmitFromUnion, PickFromUnion} from './type-utils'
 export * from './types/editor'
 export type {HotkeyOptions} from './types/options'

package/src/plugins/_exports/index.ts

@@ -0,0 +1 @@
+export * from '../index'

package/src/plugins/index.ts

@@ -0,0 +1,3 @@
+export {EventListenerPlugin} from './plugin.event-listener'
+export {EditorRefPlugin} from './plugin.editor-ref'
+export {MarkdownPlugin, type MarkdownPluginConfig} from './plugin.markdown'

package/src/plugins/plugin.editor-ref.tsx

@@ -0,0 +1,17 @@
+import React from 'react'
+import type {Editor} from '../editor/create-editor'
+import {useEditor} from '../editor/editor-provider'
+
+/**
+ * @beta
+ */
+export const EditorRefPlugin = React.forwardRef<Editor | null>((_, ref) => {
+  const editor = useEditor()
+
+  const portableTextEditorRef = React.useRef(editor)
+
+  React.useImperativeHandle(ref, () => portableTextEditorRef.current, [])
+
+  return null
+})
+EditorRefPlugin.displayName = 'EditorRefPlugin'

package/src/{editor/editor-event-listener.tsx → plugins/plugin.event-listener.tsx}

@@ -1,7 +1,7 @@
 import {useEffect} from 'react'
 import {useEffectEvent} from 'use-effect-event'
-import type {EditorEmittedEvent} from './editor-machine'
-import {useEditor} from './editor-provider'
+import type {EditorEmittedEvent} from '../editor/editor-machine'
+import {useEditor} from '../editor/editor-provider'
 
 /**
  * @public
@@ -23,12 +23,13 @@ import {useEditor} from './editor-provider'
  * @example
  * Listen and log events.
  * ```tsx
- * import {EditorEventListener, EditorProvider} from '@portabletext/editor'
+ * import {EditorProvider} from '@portabletext/editor'
+ * import {EventListenerPlugin} from '@portabletext/editor/plugins'
  *
  * function MyComponent() {
  *  return (
  *  <EditorProvider>
- *   <EditorEventListener
+ *   <EventListenerPlugin
  *    on={(event) => {
  *     console.log(event)
  *    }
@@ -41,7 +42,7 @@ import {useEditor} from './editor-provider'
  * @example
  * Handle events when there is a mutation.
  * ```tsx
- * <EditorEventListener
+ * <EventListenerPlugin
  *  on={(event) => {
  *    if (event.type === 'mutation') {
  *      console.log('Value changed:', event.snapshot)
@@ -51,7 +52,7 @@ import {useEditor} from './editor-provider'
  * ```
  * @group Components
  */
-export function EditorEventListener(props: {
+export function EventListenerPlugin(props: {
   on: (event: EditorEmittedEvent) => void
 }) {
   const editor = useEditor()

package/src/plugins/plugin.markdown.tsx

@@ -0,0 +1,70 @@
+import {useEffect} from 'react'
+import {
+  createMarkdownBehaviors,
+  type MarkdownBehaviorsConfig,
+} from '../behaviors/behavior.markdown'
+import {useEditor} from '../editor/editor-provider'
+
+/**
+ * @beta
+ */
+export type MarkdownPluginConfig = MarkdownBehaviorsConfig
+
+/**
+ * @beta
+ * Add markdown behaviors for common markdown actions such as converting ### to headings, --- to HRs, and more.
+ *
+ * @example
+ * Configure the bundled markdown behaviors
+ * ```ts
+ * import {EditorProvider} from '@portabletext/editor'
+ * import {MarkdownPlugin} from '@portabletext/editor/plugins'
+ *
+ * function App() {
+ *   return (
+ *    <EditorProvider>
+ *      <MarkdownPlugin
+ *        config={{
+ *          horizontalRuleObject: ({schema}) => {
+ *            const name = schema.blockObjects.find(
+ *              (object) => object.name === 'break',
+ *            )?.name
+ *            return name ? {name} : undefined
+ *          },
+ *          defaultStyle: ({schema}) => schema.styles[0].value,
+ *          headingStyle: ({schema, level}) =>
+ *            schema.styles.find((style) => style.value === `h${level}`)
+ *              ?.value,
+ *          blockquoteStyle: ({schema}) =>
+ *            schema.styles.find((style) => style.value === 'blockquote')
+ *              ?.value,
+ *          unorderedListStyle: ({schema}) =>
+ *            schema.lists.find((list) => list.value === 'bullet')?.value,
+ *          orderedListStyle: ({schema}) =>
+ *            schema.lists.find((list) => list.value === 'number')?.value,
+ *        }}
+ *      />
+ *      {...}
+ *    </EditorProvider>
+ *  )
+ * }
+ */
+export function MarkdownPlugin(props: {config: MarkdownPluginConfig}) {
+  const editor = useEditor()
+
+  useEffect(() => {
+    const behaviors = createMarkdownBehaviors(props.config)
+
+    const unregisterBehaviors = behaviors.map((behavior) =>
+      editor.registerBehavior({behavior}),
+    )
+
+    return () => {
+      for (const unregisterBehavior of unregisterBehaviors) {
+        unregisterBehavior()
+      }
+    }
+  }, [editor, props.config])
+
+  return null
+}

package/src/selectors/index.ts

@@ -1,3 +1,4 @@
+export type {EditorSchema} from '../editor/define-schema'
 export type {EditorSelector} from '../editor/editor-selector'
 export type {EditorContext, EditorSnapshot} from '../editor/editor-snapshot'
 export type {
@@ -5,14 +6,15 @@ export type {
   EditorSelectionPoint,
   PortableTextMemberSchemaTypes,
 } from '../types/editor'
-
-export type {EditorSchema} from '../editor/define-schema'
+export {getActiveAnnotations} from './selector.get-active-annotations'
 export {getActiveListItem} from './selector.get-active-list-item'
 export {getActiveStyle} from './selector.get-active-style'
 export {getSelectedSlice} from './selector.get-selected-slice'
 export {getSelectedSpans} from './selector.get-selected-spans'
+export {getSelection} from './selector.get-selection'
 export {getSelectionText} from './selector.get-selection-text'
 export {getBlockTextBefore} from './selector.get-text-before'
+export {getValue} from './selector.get-value'
 export {isActiveAnnotation} from './selector.is-active-annotation'
 export {isActiveDecorator} from './selector.is-active-decorator'
 export {isActiveListItem} from './selector.is-active-list-item'