@portabletext/editor 1.21.6 → 1.23.0

package/src/editor/editor-event-listener.tsx

@@ -5,6 +5,51 @@ import {useEditor} from './editor-provider'
 
 /**
  * @public
+ * Listen for events emitted by the editor. Must be used inside `EditorProvider`. Events available include:
+ *  - 'blurred'
+ *  - 'done loading'
+ *  - 'editable'
+ *  - 'error'
+ *  - 'focused'
+ *  - 'invalid value'
+ *  - 'loading'
+ *  - 'mutation'
+ *  - 'patch'
+ *  - 'read only'
+ *  - 'ready'
+ *  - 'selection'
+ *  - 'value changed'
+ *
+ * @example
+ * Listen and log events.
+ * ```tsx
+ * import {EditorEventListener, EditorProvider} from '@portabletext/editor'
+ *
+ * function MyComponent() {
+ *  return (
+ *  <EditorProvider>
+ *   <EditorEventListener
+ *    on={(event) => {
+ *     console.log(event)
+ *    }
+ *   } />
+ *   { ... }
+ * </EditorProvider>
+ *  )
+ * }
+ * ```
+ * @example
+ * Handle events when there is a mutation.
+ * ```tsx
+ * <EditorEventListener
+ *  on={(event) => {
+ *    if (event.type === 'mutation') {
+ *      console.log('Value changed:', event.snapshot)
+ *    }
+ *  }}
+ * />
+ * ```
+ * @group Components
  */
 export function EditorEventListener(props: {
   on: (event: EditorEmittedEvent) => void

package/src/editor/editor-machine.ts

@@ -20,9 +20,6 @@ import {
   type NativeBehaviorEvent,
   type SyntheticBehaviorEvent,
 } from '../behaviors/behavior.types'
-import {toPortableTextRange} from '../internal-utils/ranges'
-import {fromSlateValue} from '../internal-utils/values'
-import {KEY_TO_VALUE_ELEMENT} from '../internal-utils/weakMaps'
 import type {OmitFromUnion, PickFromUnion} from '../type-utils'
 import type {
   EditorSelection,
@@ -30,8 +27,7 @@ import type {
   PortableTextSlateEditor,
 } from '../types/editor'
 import type {EditorSchema} from './define-schema'
-import type {EditorContext} from './editor-snapshot'
-import {getActiveDecorators} from './get-active-decorators'
+import {createEditorSnapshot} from './editor-snapshot'
 import {withApplyingBehaviorActions} from './with-applying-behavior-actions'
 
 export * from 'xstate/guards'
@@ -109,6 +105,10 @@ export type InternalEditorEvent =
       type: 'update behaviors'
       behaviors: Array<Behavior>
     }
+  | {
+      type: 'update key generator'
+      keyGenerator: () => string
+    }
   | {
       type: 'update value'
       value: Array<PortableTextBlock> | undefined
@@ -342,27 +342,11 @@ export const editorMachine = setup({
         return
       }
 
-      const value = fromSlateValue(
-        event.editor.children,
-        context.schema.block.name,
-        KEY_TO_VALUE_ELEMENT.get(event.editor),
-      )
-      const selection = toPortableTextRange(
-        value,
-        event.editor.selection,
-        context.schema,
-      )
-
-      const editorContext = {
-        activeDecorators: getActiveDecorators({
-          schema: context.schema,
-          slateEditorInstance: event.editor,
-        }),
+      const editorSnapshot = createEditorSnapshot({
+        editor: event.editor,
         keyGenerator: context.keyGenerator,
         schema: context.schema,
-        selection,
-        value,
-      } satisfies EditorContext
+      })
 
       let behaviorOverwritten = false
 
@@ -370,7 +354,7 @@ export const editorMachine = setup({
         const shouldRun =
           eventBehavior.guard === undefined ||
           eventBehavior.guard({
-            context: editorContext,
+            context: editorSnapshot.context,
             event: event.behaviorEvent,
           })
 
@@ -380,7 +364,7 @@ export const editorMachine = setup({
 
         const actionIntendSets = eventBehavior.actions.map((actionSet) =>
           actionSet(
-            {context: editorContext, event: event.behaviorEvent},
+            {context: editorSnapshot.context, event: event.behaviorEvent},
             shouldRun,
           ),
         )
@@ -513,6 +497,9 @@ export const editorMachine = setup({
     '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}),
+    },
     'update schema': {actions: 'assign schema'},
     'update value': {actions: assign({value: ({event}) => event.value})},
     'update maxBlocks': {

package/src/editor/editor-provider.tsx

@@ -23,6 +23,21 @@ export type EditorProviderProps = {
 
 /**
  * @public
+ * The EditorProvider component is used to set up the editor context and configure the Portable Text Editor.
+ * @example
+ * ```tsx
+ * import {EditorProvider} from '@portabletext/editor'
+ *
+ * function App() {
+ *  return (
+ *    <EditorProvider initialConfig={{ ... }} >
+ *      ...
+ *    </EditorProvider>
+ *  )
+ * }
+ *
+ * ```
+ * @group Components
  */
 export function EditorProvider(props: EditorProviderProps) {
   const editor = useCreateEditor(props.initialConfig)
@@ -66,6 +81,18 @@ export function EditorProvider(props: EditorProviderProps) {
 
 /**
  * @public
+ * Get the current editor context from the `EditorProvider`.
+ * Must be used inside the `EditorProvider` component.
+ * @returns The current editor object.
+ * @example
+ * ```tsx
+ * import { useEditor } from '@portabletext/editor'
+ *
+ * function MyComponent() {
+ *  const editor = useEditor()
+ * }
+ * ```
+ * @group Hooks
  */
 export function useEditor() {
   const editor = React.useContext(EditorContext)

package/src/editor/editor-selector.ts

@@ -17,6 +17,27 @@ export type EditorSelector<TSelected> = (snapshot: EditorSnapshot) => TSelected
 
 /**
  * @public
+ * Hook to select a value from the editor state.
+ * @example
+ * Pass a selector as the second argument
+ * ```tsx
+ * import { useEditorSelector } from '@portabletext/editor'
+ *
+ * function MyComponent(editor) {
+ *  const value = useEditorSelector(editor, selector)
+ * }
+ * ```
+ * @example
+ * Pass an inline selector as the second argument.
+ * In this case, use the editor context to obtain the schema.
+ * ```tsx
+ * import { useEditorSelector } from '@portabletext/editor'
+ *
+ * function MyComponent(editor) {
+ *  const schema = useEditorSelector(editor, (snapshot) => snapshot.context.schema)
+ * }
+ * ```
+ * @group Hooks
  */
 export function useEditorSelector<TSelected>(
   editor: Editor,

package/src/editor/editor-snapshot.ts

@@ -1,6 +1,10 @@
 import type {PortableTextBlock} from '@sanity/types'
-import type {EditorSelection} from '../types/editor'
+import {toPortableTextRange} from '../internal-utils/ranges'
+import {fromSlateValue} from '../internal-utils/values'
+import {KEY_TO_VALUE_ELEMENT} from '../internal-utils/weakMaps'
+import type {EditorSelection, PortableTextSlateEditor} from '../types/editor'
 import type {EditorSchema} from './define-schema'
+import {getActiveDecorators} from './get-active-decorators'
 
 /**
  * @public
@@ -19,3 +23,35 @@ export type EditorContext = {
 export type EditorSnapshot = {
   context: EditorContext
 }
+
+export function createEditorSnapshot({
+  editor,
+  keyGenerator,
+  schema,
+}: {
+  editor: PortableTextSlateEditor
+  keyGenerator: () => string
+  schema: EditorSchema
+}) {
+  const value = fromSlateValue(
+    editor.children,
+    schema.block.name,
+    KEY_TO_VALUE_ELEMENT.get(editor),
+  )
+  const selection = toPortableTextRange(value, editor.selection, schema)
+
+  const context = {
+    activeDecorators: getActiveDecorators({
+      schema,
+      slateEditorInstance: editor,
+    }),
+    keyGenerator,
+    schema,
+    selection,
+    value,
+  } satisfies EditorContext
+
+  return {
+    context,
+  } satisfies EditorSnapshot
+}

package/src/selectors/index.ts

@@ -9,6 +9,7 @@ export type {
 export type {EditorSchema} from '../editor/define-schema'
 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 {getSelectionText} from './selector.get-selection-text'
 export {getBlockTextBefore} from './selector.get-text-before'

package/src/selectors/selector.get-selected-slice.ts

@@ -0,0 +1,12 @@
+import type {PortableTextBlock} from '@sanity/types'
+import type {EditorSelector} from '../editor/editor-selector'
+import {sliceBlocks} from '../utils'
+
+/**
+ * @public
+ */
+export const getSelectedSlice: EditorSelector<Array<PortableTextBlock>> = ({
+  context,
+}) => {
+  return sliceBlocks({blocks: context.value, selection: context.selection})
+}

package/src/utils/index.ts

@@ -9,3 +9,4 @@ export {getTextBlockText} from './util.get-text-block-text'
 export {isEmptyTextBlock} from './util.is-empty-text-block'
 export {isKeyedSegment} from './util.is-keyed-segment'
 export {reverseSelection} from './util.reverse-selection'
+export {sliceBlocks} from './util.slice-blocks'

package/src/utils/util.slice-blocks.test.ts

@@ -0,0 +1,257 @@
+import type {PortableTextBlock, PortableTextTextBlock} from '@sanity/types'
+import {describe, expect, test} from 'vitest'
+import {sliceBlocks} from './util.slice-blocks'
+
+const b1: PortableTextTextBlock = {
+  _type: 'block',
+  _key: 'b1',
+  children: [
+    {
+      _type: 'span',
+      _key: 'b1c1',
+      text: 'foo',
+    },
+    {
+      _type: 'span',
+      _key: 'b1c2',
+      text: 'bar',
+    },
+  ],
+}
+const b2: PortableTextBlock = {
+  _type: 'image',
+  _key: 'b2',
+  src: 'https://example.com/image.jpg',
+  alt: 'Example',
+}
+const b3: PortableTextTextBlock = {
+  _type: 'block',
+  _key: 'b3',
+  children: [
+    {
+      _type: 'span',
+      _key: 'b3c1',
+      text: 'baz',
+    },
+  ],
+}
+const b4: PortableTextTextBlock = {
+  _type: 'block',
+  _key: 'b4',
+  children: [
+    {
+      _type: 'span',
+      _key: 'b4c1',
+      text: 'fizz',
+    },
+    {
+      _type: 'stock-ticker',
+      _key: 'b4c2',
+      symbol: 'AAPL',
+    },
+    {
+      _type: 'span',
+      _key: 'b4c3',
+      text: 'buzz',
+    },
+  ],
+}
+
+const blocks: Array<PortableTextBlock> = [b1, b2, b3, b4]
+
+describe(sliceBlocks.name, () => {
+  test('sensible defaults', () => {
+    expect(sliceBlocks({blocks: [], selection: null})).toEqual([])
+    expect(sliceBlocks({blocks, selection: null})).toEqual([])
+  })
+
+  test('slicing a single block', () => {
+    expect(
+      sliceBlocks({
+        blocks,
+        selection: {
+          anchor: {
+            path: [{_key: b1._key}, 'children', {_key: b1.children[0]._key}],
+            offset: 0,
+          },
+          focus: {
+            path: [{_key: b1._key}, 'children', {_key: b1.children[0]._key}],
+            offset: 3,
+          },
+        },
+      }),
+    ).toEqual([
+      {
+        ...b1,
+        children: [b1.children[0]],
+      },
+    ])
+  })
+
+  test('slicing a single span', () => {
+    expect(
+      sliceBlocks({
+        blocks,
+        selection: {
+          anchor: {
+            path: [{_key: b1._key}, 'children', {_key: b1.children[0]._key}],
+            offset: 1,
+          },
+          focus: {
+            path: [{_key: b1._key}, 'children', {_key: b1.children[0]._key}],
+            offset: 2,
+          },
+        },
+      }),
+    ).toEqual([
+      {
+        ...b1,
+        children: [
+          {
+            ...b1.children[0],
+            text: 'o',
+          },
+        ],
+      },
+    ])
+  })
+
+  test('starting and ending selection on a block object', () => {
+    expect(
+      sliceBlocks({
+        blocks,
+        selection: {
+          anchor: {
+            path: [{_key: b2._key}],
+            offset: 0,
+          },
+          focus: {
+            path: [{_key: b2._key}],
+            offset: 0,
+          },
+        },
+      }),
+    ).toEqual([b2])
+  })
+
+  test('ending selection on a block object', () => {
+    expect(
+      sliceBlocks({
+        blocks,
+        selection: {
+          anchor: {
+            path: [{_key: b1._key}, 'children', {_key: b1.children[0]._key}],
+            offset: 3,
+          },
+          focus: {
+            path: [{_key: b2._key}],
+            offset: 0,
+          },
+        },
+      }),
+    ).toEqual([
+      {
+        ...b1,
+        children: [
+          {
+            ...b1.children[0],
+            text: '',
+          },
+          ...b1.children.slice(1),
+        ],
+      },
+      blocks[1],
+    ])
+  })
+
+  test('slicing across block object', () => {
+    expect(
+      sliceBlocks({
+        blocks,
+        selection: {
+          anchor: {
+            path: [{_key: b1._key}, 'children', {_key: b1.children[0]._key}],
+            offset: 0,
+          },
+          focus: {
+            path: [{_key: b3._key}, 'children', {_key: b3.children[0]._key}],
+            offset: 3,
+          },
+        },
+      }),
+    ).toEqual([b1, b2, b3])
+  })
+
+  test('starting and ending mid-span', () => {
+    expect(
+      sliceBlocks({
+        blocks,
+        selection: {
+          anchor: {
+            path: [{_key: b3._key}, 'children', {_key: b3.children[0]._key}],
+            offset: 2,
+          },
+          focus: {
+            path: [{_key: b4._key}, 'children', {_key: b4.children[0]._key}],
+            offset: 1,
+          },
+        },
+      }),
+    ).toEqual([
+      {
+        ...b3,
+        children: [
+          {
+            ...b3.children[0],
+            text: 'z',
+          },
+        ],
+      },
+      {
+        ...b4,
+        children: [
+          {
+            ...b4.children[0],
+            text: 'f',
+          },
+        ],
+      },
+    ])
+  })
+
+  test('starting mid-span and ending end-span', () => {
+    expect(
+      sliceBlocks({
+        blocks,
+        selection: {
+          anchor: {
+            path: [{_key: b3._key}, 'children', {_key: b3.children[0]._key}],
+            offset: 2,
+          },
+          focus: {
+            path: [{_key: b4._key}, 'children', {_key: b4.children[0]._key}],
+            offset: 4,
+          },
+        },
+      }),
+    ).toEqual([
+      {
+        ...b3,
+        children: [
+          {
+            ...b3.children[0],
+            text: 'z',
+          },
+        ],
+      },
+      {
+        ...b4,
+        children: [
+          {
+            ...b4.children[0],
+          },
+        ],
+      },
+    ])
+  })
+})

package/src/utils/util.slice-blocks.ts

@@ -0,0 +1,153 @@
+import {
+  isKeySegment,
+  isPortableTextSpan,
+  isPortableTextTextBlock,
+  type PortableTextBlock,
+} from '@sanity/types'
+import type {EditorSelection} from '../selectors'
+
+/**
+ * @public
+ */
+export function sliceBlocks({
+  blocks,
+  selection,
+}: {
+  blocks: Array<PortableTextBlock>
+  selection: EditorSelection
+}): Array<PortableTextBlock> {
+  const slice: Array<PortableTextBlock> = []
+
+  if (!selection) {
+    return slice
+  }
+
+  let startBlock: PortableTextBlock | undefined
+  const middleBlocks: PortableTextBlock[] = []
+  let endBlock: PortableTextBlock | undefined
+
+  const startPoint = selection.backward ? selection.focus : selection.anchor
+  const endPoint = selection.backward ? selection.anchor : selection.focus
+
+  const startBlockKey = isKeySegment(startPoint.path[0])
+    ? startPoint.path[0]._key
+    : undefined
+  const endBlockKey = isKeySegment(endPoint.path[0])
+    ? endPoint.path[0]._key
+    : undefined
+  const startChildKey = isKeySegment(startPoint.path[2])
+    ? startPoint.path[2]._key
+    : undefined
+  const endChildKey = isKeySegment(endPoint.path[2])
+    ? endPoint.path[2]._key
+    : undefined
+
+  if (!startBlockKey || !endBlockKey) {
+    return slice
+  }
+
+  for (const block of blocks) {
+    if (block._key === startBlockKey) {
+      if (isPortableTextTextBlock(block) && startChildKey) {
+        for (const child of block.children) {
+          if (child._key === startChildKey) {
+            if (isPortableTextSpan(child)) {
+              const text =
+                child._key === endChildKey
+                  ? child.text.slice(startPoint.offset, endPoint.offset)
+                  : child.text.slice(startPoint.offset)
+
+              startBlock = {
+                ...block,
+                children: [
+                  {
+                    ...child,
+                    text,
+                  },
+                ],
+              }
+              continue
+            }
+
+            startBlock = {
+              ...block,
+              children: [child],
+            }
+          }
+
+          if (startChildKey === endChildKey) {
+            break
+          }
+
+          if (startBlock && isPortableTextTextBlock(startBlock)) {
+            startBlock.children.push(child)
+
+            if (
+              block._key === endBlockKey &&
+              endChildKey &&
+              child._key === endChildKey
+            ) {
+              break
+            }
+          }
+        }
+
+        if (startBlockKey === endBlockKey) {
+          break
+        }
+
+        continue
+      }
+
+      startBlock = block
+
+      if (startBlockKey === endBlockKey) {
+        break
+      }
+    }
+
+    if (block._key === endBlockKey) {
+      if (isPortableTextTextBlock(block) && endBlockKey) {
+        endBlock = {
+          ...block,
+          children: [],
+        }
+
+        for (const child of block.children) {
+          if (endBlock && isPortableTextTextBlock(endBlock)) {
+            if (child._key === endChildKey && isPortableTextSpan(child)) {
+              endBlock.children.push({
+                ...child,
+                text: child.text.slice(0, endPoint.offset),
+              })
+
+              break
+            }
+
+            endBlock.children.push(child)
+
+            if (endChildKey && child._key === endChildKey) {
+              break
+            }
+          }
+        }
+
+        break
+      }
+
+      endBlock = block
+
+      break
+    }
+
+    if (startBlock) {
+      middleBlocks.push(block)
+    }
+  }
+
+  return [
+    ...(startBlock ? [startBlock] : []),
+    ...middleBlocks,
+    ...(endBlock ? [endBlock] : []),
+  ]
+}

package/lib/_chunks-cjs/util.get-block-start-point.cjs.map

@@ -1 +0,0 @@
-{"version":3,"file":"util.get-block-start-point.cjs","sources":["../../src/utils/util.reverse-selection.ts","../../src/utils/util.get-block-start-point.ts"],"sourcesContent":["import type {EditorSelection} from '../types/editor'\n\n/**\n * @public\n */\nexport function reverseSelection(\n  selection: NonNullable<EditorSelection>,\n): NonNullable<EditorSelection> {\n  if (selection.backward) {\n    return {\n      anchor: selection.focus,\n      focus: selection.anchor,\n      backward: false,\n    }\n  }\n\n  return {\n    anchor: selection.focus,\n    focus: selection.anchor,\n    backward: true,\n  }\n}\n","import {\n  isPortableTextTextBlock,\n  type KeyedSegment,\n  type PortableTextBlock,\n} from '@sanity/types'\nimport type {EditorSelectionPoint} from '../types/editor'\n\n/**\n * @public\n */\nexport function getBlockStartPoint({\n  node,\n  path,\n}: {\n  node: PortableTextBlock\n  path: [KeyedSegment]\n}): EditorSelectionPoint {\n  if (isPortableTextTextBlock(node)) {\n    return {\n      path: [...path, 'children', {_key: node.children[0]._key}],\n      offset: 0,\n    }\n  }\n\n  return {\n    path,\n    offset: 0,\n  }\n}\n"],"names":["reverseSelection","selection","backward","anchor","focus","getBlockStartPoint","node","path","isPortableTextTextBlock","_key","children","offset"],"mappings":";;AAKO,SAASA,iBACdC,WAC8B;AAC9B,SAAIA,UAAUC,WACL;AAAA,IACLC,QAAQF,UAAUG;AAAAA,IAClBA,OAAOH,UAAUE;AAAAA,IACjBD,UAAU;AAAA,EAAA,IAIP;AAAA,IACLC,QAAQF,UAAUG;AAAAA,IAClBA,OAAOH,UAAUE;AAAAA,IACjBD,UAAU;AAAA,EACZ;AACF;ACXO,SAASG,mBAAmB;AAAA,EACjCC;AAAAA,EACAC;AAIF,GAAyB;AACnBC,SAAAA,MAAAA,wBAAwBF,IAAI,IACvB;AAAA,IACLC,MAAM,CAAC,GAAGA,MAAM,YAAY;AAAA,MAACE,MAAMH,KAAKI,SAAS,CAAC,EAAED;AAAAA,IAAAA,CAAK;AAAA,IACzDE,QAAQ;AAAA,EAAA,IAIL;AAAA,IACLJ;AAAAA,IACAI,QAAQ;AAAA,EACV;AACF;;;"}

package/lib/_chunks-es/util.get-block-start-point.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"util.get-block-start-point.js","sources":["../../src/utils/util.reverse-selection.ts","../../src/utils/util.get-block-start-point.ts"],"sourcesContent":["import type {EditorSelection} from '../types/editor'\n\n/**\n * @public\n */\nexport function reverseSelection(\n  selection: NonNullable<EditorSelection>,\n): NonNullable<EditorSelection> {\n  if (selection.backward) {\n    return {\n      anchor: selection.focus,\n      focus: selection.anchor,\n      backward: false,\n    }\n  }\n\n  return {\n    anchor: selection.focus,\n    focus: selection.anchor,\n    backward: true,\n  }\n}\n","import {\n  isPortableTextTextBlock,\n  type KeyedSegment,\n  type PortableTextBlock,\n} from '@sanity/types'\nimport type {EditorSelectionPoint} from '../types/editor'\n\n/**\n * @public\n */\nexport function getBlockStartPoint({\n  node,\n  path,\n}: {\n  node: PortableTextBlock\n  path: [KeyedSegment]\n}): EditorSelectionPoint {\n  if (isPortableTextTextBlock(node)) {\n    return {\n      path: [...path, 'children', {_key: node.children[0]._key}],\n      offset: 0,\n    }\n  }\n\n  return {\n    path,\n    offset: 0,\n  }\n}\n"],"names":["reverseSelection","selection","backward","anchor","focus","getBlockStartPoint","node","path","isPortableTextTextBlock","_key","children","offset"],"mappings":";AAKO,SAASA,iBACdC,WAC8B;AAC9B,SAAIA,UAAUC,WACL;AAAA,IACLC,QAAQF,UAAUG;AAAAA,IAClBA,OAAOH,UAAUE;AAAAA,IACjBD,UAAU;AAAA,EAAA,IAIP;AAAA,IACLC,QAAQF,UAAUG;AAAAA,IAClBA,OAAOH,UAAUE;AAAAA,IACjBD,UAAU;AAAA,EACZ;AACF;ACXO,SAASG,mBAAmB;AAAA,EACjCC;AAAAA,EACAC;AAIF,GAAyB;AACnBC,SAAAA,wBAAwBF,IAAI,IACvB;AAAA,IACLC,MAAM,CAAC,GAAGA,MAAM,YAAY;AAAA,MAACE,MAAMH,KAAKI,SAAS,CAAC,EAAED;AAAAA,IAAAA,CAAK;AAAA,IACzDE,QAAQ;AAAA,EAAA,IAIL;AAAA,IACLJ;AAAAA,IACAI,QAAQ;AAAA,EACV;AACF;"}