@portabletext/editor 1.26.3 → 1.28.0

package/src/editor/PortableTextEditor.tsx

@@ -261,12 +261,32 @@ export class PortableTextEditor extends Component<
     )
   }
 
-  // Static API methods
+  /**
+   * @deprecated
+   * Use built-in selectors or write your own: https://www.portabletext.org/reference/selectors/
+   *
+   * ```
+   * import * as selectors from '@portabletext/editor/selectors'
+   * const editor = useEditor()
+   * const isActive = useEditorSelector(editor, selectors.getActiveAnnotations)
+   * ```
+   */
   static activeAnnotations = (
     editor: PortableTextEditor,
   ): PortableTextObject[] => {
     return editor && editor.editable ? editor.editable.activeAnnotations() : []
   }
+
+  /**
+   * @deprecated
+   * Use built-in selectors or write your own: https://www.portabletext.org/reference/selectors/
+   *
+   * ```
+   * import * as selectors from '@portabletext/editor/selectors'
+   * const editor = useEditor()
+   * const isActive = useEditorSelector(editor, selectors.isActiveAnnotation(...))
+   * ```
+   */
   static isAnnotationActive = (
     editor: PortableTextEditor,
     annotationType: PortableTextObject['_type'],
@@ -275,60 +295,224 @@ export class PortableTextEditor extends Component<
       ? editor.editable.isAnnotationActive(annotationType)
       : false
   }
+
+  /**
+   * @deprecated
+   * Use `editor.send(...)` instead
+   *
+   * ```
+   * const editor = useEditor()
+   * editor.send({
+   *  type: 'annotation.add',
+   *  annotation: {
+   *    name: '...',
+   *    value: {...},
+   *  }
+   * })
+   * ```
+   */
   static addAnnotation = <TSchemaType extends {name: string}>(
     editor: PortableTextEditor,
     type: TSchemaType,
     value?: {[prop: string]: unknown},
   ): AddedAnnotationPaths | undefined =>
     editor.editable?.addAnnotation(type, value)
+
+  /**
+   * @deprecated
+   * Use `editor.send(...)` instead
+   *
+   * ```
+   * const editor = useEditor()
+   * editor.send({
+   *  type: 'blur',
+   * })
+   * ```
+   */
   static blur = (editor: PortableTextEditor): void => {
     debug('Host blurred')
     editor.editable?.blur()
   }
+
   static delete = (
     editor: PortableTextEditor,
     selection: EditorSelection,
     options?: EditableAPIDeleteOptions,
   ) => editor.editable?.delete(selection, options)
+
   static findDOMNode = (
     editor: PortableTextEditor,
     element: PortableTextBlock | PortableTextChild,
   ) => {
     return editor.editable?.findDOMNode(element)
   }
+
   static findByPath = (editor: PortableTextEditor, path: Path) => {
     return editor.editable?.findByPath(path) || []
   }
+
+  /**
+   * @deprecated
+   * Use `editor.send(...)` instead
+   *
+   * ```
+   * const editor = useEditor()
+   * editor.send({
+   *  type: 'focus',
+   * })
+   * ```
+   */
   static focus = (editor: PortableTextEditor): void => {
     debug('Host requesting focus')
     editor.editable?.focus()
   }
+
+  /**
+   * @deprecated
+   * Use built-in selectors or write your own: https://www.portabletext.org/reference/selectors/
+   *
+   * ```
+   * import * as selectors from '@portabletext/editor/selectors'
+   * const editor = useEditor()
+   * const focusBlock = useEditorSelector(editor, selectors.getFocusBlock)
+   * ```
+   */
   static focusBlock = (editor: PortableTextEditor) => {
     return editor.editable?.focusBlock()
   }
+
+  /**
+   * @deprecated
+   * Use built-in selectors or write your own: https://www.portabletext.org/reference/selectors/
+   *
+   * ```
+   * import * as selectors from '@portabletext/editor/selectors'
+   * const editor = useEditor()
+   * const focusChild = useEditorSelector(editor, selectors.getFocusChild)
+   * ```
+   */
   static focusChild = (
     editor: PortableTextEditor,
   ): PortableTextChild | undefined => {
     return editor.editable?.focusChild()
   }
+
+  /**
+   * @deprecated
+   * Use built-in selectors or write your own: https://www.portabletext.org/reference/selectors/
+   *
+   * ```
+   * import * as selectors from '@portabletext/editor/selectors'
+   * const editor = useEditor()
+   * const selection = useEditorSelector(editor, selectors.getSelection)
+   * ```
+   */
   static getSelection = (editor: PortableTextEditor) => {
     return editor.editable ? editor.editable.getSelection() : null
   }
+
+  /**
+   * @deprecated
+   * Use built-in selectors or write your own: https://www.portabletext.org/reference/selectors/
+   *
+   * ```
+   * import * as selectors from '@portabletext/editor/selectors'
+   * const editor = useEditor()
+   * const value = useEditorSelector(editor, selectors.getValue)
+   * ```
+   */
   static getValue = (editor: PortableTextEditor) => {
     return editor.editable?.getValue()
   }
+
+  /**
+   * @deprecated
+   * Use built-in selectors or write your own: https://www.portabletext.org/reference/selectors/
+   *
+   * ```
+   * import * as selectors from '@portabletext/editor/selectors'
+   * const editor = useEditor()
+   * const isActive = useEditorSelector(editor, selectors.isActiveStyle(...))
+   * ```
+   */
   static hasBlockStyle = (editor: PortableTextEditor, blockStyle: string) => {
     return editor.editable?.hasBlockStyle(blockStyle)
   }
+
+  /**
+   * @deprecated
+   * Use built-in selectors or write your own: https://www.portabletext.org/reference/selectors/
+   *
+   * ```
+   * import * as selectors from '@portabletext/editor/selectors'
+   * const editor = useEditor()
+   * const isActive = useEditorSelector(editor, selectors.isActiveListItem(...))
+   * ```
+   */
   static hasListStyle = (editor: PortableTextEditor, listStyle: string) => {
     return editor.editable?.hasListStyle(listStyle)
   }
+
+  /**
+   * @deprecated
+   * Use built-in selectors or write your own: https://www.portabletext.org/reference/selectors/
+   *
+   * ```
+   * import * as selectors from '@portabletext/editor/selectors'
+   * const editor = useEditor()
+   * const isSelectionCollapsed = useEditorSelector(editor, selectors.isSelectionCollapsed)
+   * ```
+   */
   static isCollapsedSelection = (editor: PortableTextEditor) =>
     editor.editable?.isCollapsedSelection()
+
+  /**
+   * @deprecated
+   * Use built-in selectors or write your own: https://www.portabletext.org/reference/selectors/
+   *
+   * ```
+   * import * as selectors from '@portabletext/editor/selectors'
+   * const editor = useEditor()
+   * const isSelectionExpanded = useEditorSelector(editor, selectors.isSelectionExpanded)
+   * ```
+   */
   static isExpandedSelection = (editor: PortableTextEditor) =>
     editor.editable?.isExpandedSelection()
+
+  /**
+   * @deprecated
+   * Use built-in selectors or write your own: https://www.portabletext.org/reference/selectors/
+   *
+   * ```
+   * import * as selectors from '@portabletext/editor/selectors'
+   * const editor = useEditor()
+   * const isActive = useEditorSelector(editor, selectors.isActiveDecorator(...))
+   * ```
+   */
   static isMarkActive = (editor: PortableTextEditor, mark: string) =>
     editor.editable?.isMarkActive(mark)
+
+  /**
+   * @deprecated
+   * Use `editor.send(...)` instead
+   *
+   * ```
+   * const editor = useEditor()
+   * editor.send({
+   *  type: 'insert.span',
+   *  text: '...',
+   *  annotations: [{name: '...', value: {...}}],
+   *  decorators: ['...'],
+   * })
+   * editor.send({
+   *  type: 'insert.inline object',
+   *  inlineObject: {
+   *    name: '...',
+   *    value: {...},
+   *  },
+   * })
+   * ```
+   */
   static insertChild = <TSchemaType extends {name: string}>(
     editor: PortableTextEditor,
     type: TSchemaType,
@@ -337,6 +521,23 @@ export class PortableTextEditor extends Component<
     debug(`Host inserting child`)
     return editor.editable?.insertChild(type, value)
   }
+
+  /**
+   * @deprecated
+   * Use `editor.send(...)` instead
+   *
+   * ```
+   * const editor = useEditor()
+   * editor.send({
+   *  type: 'insert.block object',
+   *  blockObject: {
+   *    name: '...',
+   *    value: {...},
+   *  },
+   *  placement: 'auto' | 'after' | 'before',
+   * })
+   * ```
+   */
   static insertBlock = <TSchemaType extends {name: string}>(
     editor: PortableTextEditor,
     type: TSchemaType,
@@ -344,24 +545,52 @@ export class PortableTextEditor extends Component<
   ): Path | undefined => {
     return editor.editable?.insertBlock(type, value)
   }
+
+  /**
+   * @deprecated
+   * Use `editor.send(...)` instead
+   *
+   * ```
+   * const editor = useEditor()
+   * editor.send({
+   *  type: 'insert.break',
+   * })
+   * ```
+   */
   static insertBreak = (editor: PortableTextEditor): void => {
     return editor.editable?.insertBreak()
   }
+
   static isVoid = (
     editor: PortableTextEditor,
     element: PortableTextBlock | PortableTextChild,
   ) => {
     return editor.editable?.isVoid(element)
   }
+
   static isObjectPath = (_editor: PortableTextEditor, path: Path): boolean => {
     if (!path || !Array.isArray(path)) return false
     const isChildObjectEditPath = path.length > 3 && path[1] === 'children'
     const isBlockObjectEditPath = path.length > 1 && path[1] !== 'children'
     return isBlockObjectEditPath || isChildObjectEditPath
   }
+
   static marks = (editor: PortableTextEditor) => {
     return editor.editable?.marks()
   }
+
+  /**
+   * @deprecated
+   * Use `editor.send(...)` instead
+   *
+   * ```
+   * const editor = useEditor()
+   * editor.send({
+   *  type: 'select',
+   *  selection: {...},
+   * })
+   * ```
+   */
   static select = (
     editor: PortableTextEditor,
     selection: EditorSelection | null,
@@ -369,10 +598,38 @@ export class PortableTextEditor extends Component<
     debug(`Host setting selection`, selection)
     editor.editable?.select(selection)
   }
+
+  /**
+   * @deprecated
+   * Use `editor.send(...)` instead
+   *
+   * ```
+   * const editor = useEditor()
+   * editor.send({
+   *  type: 'annotation.remove',
+   *  annotation: {
+   *    name: '...',
+   *  },
+   * })
+   * ```
+   */
   static removeAnnotation = <TSchemaType extends {name: string}>(
     editor: PortableTextEditor,
     type: TSchemaType,
   ) => editor.editable?.removeAnnotation(type)
+
+  /**
+   * @deprecated
+   * Use `editor.send(...)` instead
+   *
+   * ```
+   * const editor = useEditor()
+   * editor.send({
+   *  type: 'style.toggle',
+   *  style: '...',
+   * })
+   * ```
+   */
   static toggleBlockStyle = (
     editor: PortableTextEditor,
     blockStyle: string,
@@ -380,27 +637,57 @@ export class PortableTextEditor extends Component<
     debug(`Host is toggling block style`)
     return editor.editable?.toggleBlockStyle(blockStyle)
   }
+
+  /**
+   * @deprecated
+   * Use `editor.send(...)` instead
+   *
+   * ```
+   * const editor = useEditor()
+   * editor.send({
+   *  type: 'list item.toggle',
+   *  listItem: '...',
+   * })
+   * ```
+   */
   static toggleList = (editor: PortableTextEditor, listStyle: string): void => {
     return editor.editable?.toggleList(listStyle)
   }
+
+  /**
+   * @deprecated
+   * Use `editor.send(...)` instead
+   *
+   * ```
+   * const editor = useEditor()
+   * editor.send({
+   *  type: 'decorator.toggle',
+   *  decorator: '...',
+   * })
+   * ```
+   */
   static toggleMark = (editor: PortableTextEditor, mark: string): void => {
     debug(`Host toggling mark`, mark)
     editor.editable?.toggleMark(mark)
   }
+
   static getFragment = (
     editor: PortableTextEditor,
   ): PortableTextBlock[] | undefined => {
     debug(`Host getting fragment`)
     return editor.editable?.getFragment()
   }
+
   static undo = (editor: PortableTextEditor): void => {
     debug('Host undoing')
     editor.editable?.undo()
   }
+
   static redo = (editor: PortableTextEditor): void => {
     debug('Host redoing')
     editor.editable?.redo()
   }
+
   static isSelectionsOverlapping = (
     editor: PortableTextEditor,
     selectionA: EditorSelection,

package/src/editor/__tests__/PortableTextEditor.test.tsx

@@ -32,7 +32,6 @@ describe('initialization', () => {
     await waitFor(() => {
       expect(editorRef.current).not.toBe(null)
       expect(onChange).toHaveBeenCalledWith({type: 'ready'})
-      expect(onChange).toHaveBeenCalledWith({type: 'value', value: undefined})
       expect(container).toMatchInlineSnapshot(`
 <div>
   <div

package/src/editor/components/DefaultObject.tsx

@@ -0,0 +1,21 @@
+import type {PortableTextBlock, PortableTextChild} from '@sanity/types'
+
+export function DefaultBlockObject(props: {
+  value: PortableTextBlock | PortableTextChild
+}) {
+  return (
+    <div style={{userSelect: 'none'}}>
+      [{props.value._type}: {props.value._key}]
+    </div>
+  )
+}
+
+export function DefaultInlineObject(props: {
+  value: PortableTextBlock | PortableTextChild
+}) {
+  return (
+    <span style={{userSelect: 'none'}}>
+      [{props.value._type}: {props.value._key}]
+    </span>
+  )
+}

package/src/editor/components/Element.tsx

@@ -29,7 +29,7 @@ import type {
   RenderListItemFunction,
   RenderStyleFunction,
 } from '../../types/editor'
-import ObjectNode from '../nodes/DefaultObject'
+import {DefaultBlockObject, DefaultInlineObject} from './DefaultObject'
 import {DraggableBlock} from './DraggableBlock'
 
 const debug = debugWithName('components:Element')
@@ -137,7 +137,7 @@ export const Element: FunctionComponent<ElementProps> = ({
             {renderChild &&
               renderChild({
                 annotations: EMPTY_ANNOTATIONS, // These inline objects currently doesn't support annotations. This is a limitation of the current PT spec/model.
-                children: <ObjectNode value={value} />,
+                children: <DefaultInlineObject value={value} />,
                 editorElementRef: inlineBlockObjectRef,
                 focused,
                 path: elmPath,
@@ -146,7 +146,7 @@ export const Element: FunctionComponent<ElementProps> = ({
                 type: schemaType,
                 value: value as PortableTextChild,
               })}
-            {!renderChild && <ObjectNode value={value} />}
+            {!renderChild && <DefaultInlineObject value={value} />}
           </span>
         </span>
       )
@@ -280,7 +280,7 @@ export const Element: FunctionComponent<ElementProps> = ({
   if (renderBlock) {
     const _props: Omit<BlockRenderProps, 'type'> = Object.defineProperty(
       {
-        children: <ObjectNode value={value} />,
+        children: <DefaultBlockObject value={value} />,
         editorElementRef: blockRef,
         focused,
         path: blockPath,
@@ -310,7 +310,7 @@ export const Element: FunctionComponent<ElementProps> = ({
           {renderedBlockFromProps ? (
             renderedBlockFromProps
           ) : (
-            <ObjectNode value={value} />
+            <DefaultBlockObject value={value} />
           )}
         </div>
       </DraggableBlock>

package/src/editor/components/Leaf.tsx

@@ -27,7 +27,6 @@ import type {
 } from '../../types/editor'
 import type {EditorActor} from '../editor-machine'
 import {usePortableTextEditor} from '../hooks/usePortableTextEditor'
-import {DefaultAnnotation} from '../nodes/DefaultAnnotation'
 import {PortableTextEditor} from '../PortableTextEditor'
 
 const debug = debugWithName('components:Leaf')
@@ -264,11 +263,7 @@ export const Leaf = (props: LeafProps) => {
                 </span>
               )
             } else {
-              returnedChildren = (
-                <DefaultAnnotation annotation={annotation}>
-                  <span ref={spanRef}>{returnedChildren}</span>
-                </DefaultAnnotation>
-              )
+              returnedChildren = <span ref={spanRef}>{returnedChildren}</span>
             }
           }
         })

package/src/editor/components/Synchronizer.tsx

@@ -67,7 +67,22 @@ export function Synchronizer(props: SynchronizerProps) {
 
   useEffect(() => {
     const subscription = syncActorRef.on('*', (event) => {
-      props.editorActor.send(event)
+      switch (event.type) {
+        case 'invalid value':
+          props.editorActor.send({
+            ...event,
+            type: 'notify.invalid value',
+          })
+          break
+        case 'value changed':
+          props.editorActor.send({
+            ...event,
+            type: 'notify.value changed',
+          })
+          break
+        default:
+          props.editorActor.send(event)
+      }
     })
 
     return () => {

package/src/editor/create-editor.ts

@@ -11,10 +11,13 @@ import {
   type EventObject,
   type Snapshot,
 } from 'xstate'
-import type {Behavior, CustomBehaviorEvent} from '../behaviors/behavior.types'
+import type {
+  Behavior,
+  CustomBehaviorEvent,
+  SyntheticBehaviorEvent,
+} from '../behaviors/behavior.types'
 import {coreConverters} from '../converters/converters.core'
 import {compileType} from '../internal-utils/schema'
-import type {PickFromUnion} from '../type-utils'
 import type {EditableAPI} from '../types/editor'
 import {createEditorSchema} from './create-editor-schema'
 import {createSlateEditor, type SlateEditor} from './create-slate-editor'
@@ -23,7 +26,7 @@ import {
   editorMachine,
   type EditorActor,
   type EditorEmittedEvent,
-  type InternalEditorEvent,
+  type ExternalEditorEvent,
 } from './editor-machine'
 import {getEditorSnapshot} from './editor-selector'
 import type {EditorSnapshot} from './editor-snapshot'
@@ -60,51 +63,8 @@ export type EditorConfig = {
  * @public
  */
 export type EditorEvent =
-  | PickFromUnion<
-      InternalEditorEvent,
-      'type',
-      | 'annotation.add'
-      | 'annotation.remove'
-      | 'annotation.toggle'
-      | 'block.set'
-      | 'block.unset'
-      | 'blur'
-      | 'data transfer.set'
-      | 'decorator.add'
-      | 'decorator.remove'
-      | 'decorator.toggle'
-      | 'delete.block'
-      | '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'
-      | 'patches'
-      | 'update behaviors'
-      | 'update key generator'
-      | 'update readOnly'
-      | 'update value'
-    >
+  | ExternalEditorEvent
+  | SyntheticBehaviorEvent
   | CustomBehaviorEvent
 
 /**