@portabletext/editor 0.0.0

package/src/editor/PortableTextEditor.tsx

@@ -0,0 +1,308 @@
+import {
+  type ArrayDefinition,
+  type ArraySchemaType,
+  type BlockSchemaType,
+  type ObjectSchemaType,
+  type Path,
+  type PortableTextBlock,
+  type PortableTextChild,
+  type PortableTextObject,
+  type SpanSchemaType,
+} from '@sanity/types'
+import {Component, type MutableRefObject, type PropsWithChildren} from 'react'
+import {Subject} from 'rxjs'
+
+import {
+  type EditableAPI,
+  type EditableAPIDeleteOptions,
+  type EditorChange,
+  type EditorChanges,
+  type EditorSelection,
+  type PatchObservable,
+  type PortableTextMemberSchemaTypes,
+} from '../types/editor'
+import {debugWithName} from '../utils/debug'
+import {getPortableTextMemberSchemaTypes} from '../utils/getPortableTextMemberSchemaTypes'
+import {compileType} from '../utils/schema'
+import {SlateContainer} from './components/SlateContainer'
+import {Synchronizer} from './components/Synchronizer'
+import {defaultKeyGenerator} from './hooks/usePortableTextEditorKeyGenerator'
+
+const debug = debugWithName('component:PortableTextEditor')
+
+/**
+ * Props for the PortableTextEditor component
+ *
+ * @public
+ */
+/**
+ * Props for the PortableTextEditor component
+ *
+ * @public
+ */
+export type PortableTextEditorProps = PropsWithChildren<{
+  /**
+   * Function that gets called when the editor changes the value
+   */
+  onChange: (change: EditorChange) => void
+
+  /**
+   * Schema type for the portable text field
+   */
+  schemaType: ArraySchemaType<PortableTextBlock> | ArrayDefinition
+
+  /**
+   * Maximum number of blocks to allow within the editor
+   */
+  maxBlocks?: number | string
+
+  /**
+   * Whether or not the editor should be in read-only mode
+   */
+  readOnly?: boolean
+
+  /**
+   * The current value of the portable text field
+   */
+  value?: PortableTextBlock[]
+
+  /**
+   * Function used to generate keys for array items (`_key`)
+   */
+  keyGenerator?: () => string
+
+  /**
+   * Observable of local and remote patches for the edited value.
+   */
+  patches$?: PatchObservable
+
+  /**
+   * Backward compatibility (renamed to patches$).
+   */
+  incomingPatches$?: PatchObservable
+
+  /**
+   * A ref to the editor instance
+   */
+  editorRef?: MutableRefObject<PortableTextEditor | null>
+}>
+
+/**
+ * The main Portable Text Editor component.
+ * @public
+ */
+export class PortableTextEditor extends Component<PortableTextEditorProps> {
+  /**
+   * An observable of all the editor changes.
+   */
+  public change$: EditorChanges = new Subject()
+  /**
+   * A lookup table for all the relevant schema types for this portable text type.
+   */
+  public schemaTypes: PortableTextMemberSchemaTypes
+  /**
+   * The editor API (currently implemented with Slate).
+   */
+  private editable?: EditableAPI
+
+  constructor(props: PortableTextEditorProps) {
+    super(props)
+
+    if (!props.schemaType) {
+      throw new Error('PortableTextEditor: missing "type" property')
+    }
+
+    if (props.incomingPatches$) {
+      console.warn(`The prop 'incomingPatches$' is deprecated and renamed to 'patches$'`)
+    }
+
+    this.change$.next({type: 'loading', isLoading: true})
+
+    this.schemaTypes = getPortableTextMemberSchemaTypes(
+      props.schemaType.hasOwnProperty('jsonType')
+        ? props.schemaType
+        : compileType(props.schemaType),
+    )
+  }
+
+  componentDidUpdate(prevProps: PortableTextEditorProps) {
+    // Set up the schema type lookup table again if the source schema type changes
+    if (this.props.schemaType !== prevProps.schemaType) {
+      this.schemaTypes = getPortableTextMemberSchemaTypes(
+        this.props.schemaType.hasOwnProperty('jsonType')
+          ? this.props.schemaType
+          : compileType(this.props.schemaType),
+      )
+    }
+    if (this.props.editorRef !== prevProps.editorRef && this.props.editorRef) {
+      this.props.editorRef.current = this
+    }
+  }
+
+  public setEditable = (editable: EditableAPI) => {
+    this.editable = {...this.editable, ...editable}
+  }
+
+  render() {
+    const {onChange, value, children, patches$, incomingPatches$} = this.props
+    const {change$} = this
+    const _patches$ = incomingPatches$ || patches$ // Backward compatibility
+
+    const maxBlocks =
+      typeof this.props.maxBlocks === 'undefined'
+        ? undefined
+        : parseInt(this.props.maxBlocks.toString(), 10) || undefined
+
+    const readOnly = Boolean(this.props.readOnly)
+    const keyGenerator = this.props.keyGenerator || defaultKeyGenerator
+    return (
+      <SlateContainer
+        keyGenerator={keyGenerator}
+        maxBlocks={maxBlocks}
+        patches$={_patches$}
+        portableTextEditor={this}
+        readOnly={readOnly}
+      >
+        <Synchronizer
+          change$={change$}
+          keyGenerator={keyGenerator}
+          onChange={onChange}
+          portableTextEditor={this}
+          readOnly={readOnly}
+          value={value}
+        >
+          {children}
+        </Synchronizer>
+      </SlateContainer>
+    )
+  }
+
+  // Static API methods
+  static activeAnnotations = (editor: PortableTextEditor): PortableTextObject[] => {
+    return editor && editor.editable ? editor.editable.activeAnnotations() : []
+  }
+  static isAnnotationActive = (
+    editor: PortableTextEditor,
+    annotationType: PortableTextObject['_type'],
+  ): boolean => {
+    return editor && editor.editable ? editor.editable.isAnnotationActive(annotationType) : false
+  }
+  static addAnnotation = (
+    editor: PortableTextEditor,
+    type: ObjectSchemaType,
+    value?: {[prop: string]: unknown},
+  ): {spanPath: Path; markDefPath: Path} | undefined => editor.editable?.addAnnotation(type, value)
+  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,
+  ) => {
+    // eslint-disable-next-line react/no-find-dom-node
+    return editor.editable?.findDOMNode(element)
+  }
+  static findByPath = (editor: PortableTextEditor, path: Path) => {
+    return editor.editable?.findByPath(path) || []
+  }
+  static focus = (editor: PortableTextEditor): void => {
+    debug('Host requesting focus')
+    editor.editable?.focus()
+  }
+  static focusBlock = (editor: PortableTextEditor) => {
+    return editor.editable?.focusBlock()
+  }
+  static focusChild = (editor: PortableTextEditor): PortableTextChild | undefined => {
+    return editor.editable?.focusChild()
+  }
+  static getSelection = (editor: PortableTextEditor) => {
+    return editor.editable ? editor.editable.getSelection() : null
+  }
+  static getValue = (editor: PortableTextEditor) => {
+    return editor.editable?.getValue()
+  }
+  static hasBlockStyle = (editor: PortableTextEditor, blockStyle: string) => {
+    return editor.editable?.hasBlockStyle(blockStyle)
+  }
+  static hasListStyle = (editor: PortableTextEditor, listStyle: string) => {
+    return editor.editable?.hasListStyle(listStyle)
+  }
+  static isCollapsedSelection = (editor: PortableTextEditor) =>
+    editor.editable?.isCollapsedSelection()
+  static isExpandedSelection = (editor: PortableTextEditor) =>
+    editor.editable?.isExpandedSelection()
+  static isMarkActive = (editor: PortableTextEditor, mark: string) =>
+    editor.editable?.isMarkActive(mark)
+  static insertChild = (
+    editor: PortableTextEditor,
+    type: SpanSchemaType | ObjectSchemaType,
+    value?: {[prop: string]: unknown},
+  ): Path | undefined => {
+    debug(`Host inserting child`)
+    return editor.editable?.insertChild(type, value)
+  }
+  static insertBlock = (
+    editor: PortableTextEditor,
+    type: BlockSchemaType | ObjectSchemaType,
+    value?: {[prop: string]: unknown},
+  ): Path | undefined => {
+    return editor.editable?.insertBlock(type, value)
+  }
+  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()
+  }
+  static select = (editor: PortableTextEditor, selection: EditorSelection | null) => {
+    debug(`Host setting selection`, selection)
+    editor.editable?.select(selection)
+  }
+  static removeAnnotation = (editor: PortableTextEditor, type: ObjectSchemaType) =>
+    editor.editable?.removeAnnotation(type)
+  static toggleBlockStyle = (editor: PortableTextEditor, blockStyle: string) => {
+    debug(`Host is toggling block style`)
+    return editor.editable?.toggleBlockStyle(blockStyle)
+  }
+  static toggleList = (editor: PortableTextEditor, listStyle: string): void => {
+    return editor.editable?.toggleList(listStyle)
+  }
+  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,
+    selectionB: EditorSelection,
+  ) => {
+    return editor.editable?.isSelectionsOverlapping(selectionA, selectionB)
+  }
+}

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

@@ -0,0 +1,386 @@
+import {describe, expect, it, jest} from '@jest/globals'
+/* eslint-disable no-irregular-whitespace */
+import {type PortableTextBlock} from '@sanity/types'
+import {render, waitFor} from '@testing-library/react'
+import {createRef, type RefObject} from 'react'
+
+import {type EditorSelection} from '../..'
+import {PortableTextEditor} from '../PortableTextEditor'
+import {PortableTextEditorTester, schemaType} from './PortableTextEditorTester'
+
+const helloBlock: PortableTextBlock = {
+  _key: '123',
+  _type: 'myTestBlockType',
+  markDefs: [],
+  children: [{_key: '567', _type: 'span', text: 'Hello', marks: []}],
+}
+
+const renderPlaceholder = () => 'Jot something down here'
+
+describe('initialization', () => {
+  it('receives initial onChange events and has custom placeholder', async () => {
+    const editorRef: RefObject<PortableTextEditor> = createRef()
+    const onChange = jest.fn()
+    const {container} = render(
+      <PortableTextEditorTester
+        onChange={onChange}
+        renderPlaceholder={renderPlaceholder}
+        ref={editorRef}
+        schemaType={schemaType}
+        value={undefined}
+      />,
+    )
+
+    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
+    aria-describedby="desc_foo"
+    aria-multiline="true"
+    autocapitalize="false"
+    autocorrect="false"
+    class="pt-editable"
+    contenteditable="true"
+    data-slate-editor="true"
+    data-slate-node="value"
+    role="textbox"
+    spellcheck="false"
+    style="position: relative; white-space: pre-wrap; word-wrap: break-word;"
+    zindex="-1"
+  >
+    <div
+      class="pt-block pt-text-block pt-text-block-style-normal"
+      data-slate-node="element"
+    >
+      <div
+        draggable="false"
+      >
+        <div>
+          <span
+            data-slate-node="text"
+          >
+            <span
+              contenteditable="false"
+              style="position: absolute; user-select: none; pointer-events: none; left: 0px; right: 0px;"
+            >
+              Jot something down here
+            </span>
+            <span
+              data-slate-leaf="true"
+            >
+              <span
+                data-slate-length="0"
+                data-slate-zero-width="n"
+              >
+                
+                <br />
+              </span>
+            </span>
+          </span>
+        </div>
+      </div>
+    </div>
+  </div>
+</div>
+`)
+    })
+  })
+  it('takes value from props and confirms it by emitting value change event', async () => {
+    const initialValue = [helloBlock]
+    const onChange = jest.fn()
+    const editorRef = createRef<PortableTextEditor>()
+    render(
+      <PortableTextEditorTester
+        ref={editorRef}
+        onChange={onChange}
+        schemaType={schemaType}
+        value={initialValue}
+      />,
+    )
+    const normalizedEditorValue = [{...initialValue[0], style: 'normal'}]
+    await waitFor(() => {
+      expect(onChange).toHaveBeenCalledWith({type: 'value', value: initialValue})
+    })
+    if (editorRef.current) {
+      expect(PortableTextEditor.getValue(editorRef.current)).toStrictEqual(normalizedEditorValue)
+    }
+  })
+
+  it('takes initial selection from props', async () => {
+    const editorRef: RefObject<PortableTextEditor> = createRef()
+    const initialValue = [helloBlock]
+    const initialSelection: EditorSelection = {
+      anchor: {path: [{_key: '123'}, 'children', {_key: '567'}], offset: 2},
+      focus: {path: [{_key: '123'}, 'children', {_key: '567'}], offset: 2},
+      backward: false,
+    }
+    const onChange = jest.fn()
+    render(
+      <PortableTextEditorTester
+        onChange={onChange}
+        ref={editorRef}
+        selection={initialSelection}
+        schemaType={schemaType}
+        value={initialValue}
+      />,
+    )
+    await waitFor(() => {
+      if (editorRef.current) {
+        PortableTextEditor.focus(editorRef.current)
+        expect(PortableTextEditor.getSelection(editorRef.current)).toStrictEqual(initialSelection)
+      }
+    })
+  })
+
+  it('updates editor selection from new prop and keeps object equality in editor.getSelection()', async () => {
+    const editorRef: RefObject<PortableTextEditor> = createRef()
+    const initialValue = [helloBlock]
+    const initialSelection: EditorSelection = {
+      anchor: {path: [{_key: '123'}, 'children', {_key: '567'}], offset: 0},
+      focus: {path: [{_key: '123'}, 'children', {_key: '567'}], offset: 0},
+      backward: false,
+    }
+    const newSelection: EditorSelection = {
+      anchor: {path: [{_key: '123'}, 'children', {_key: '567'}], offset: 0},
+      focus: {path: [{_key: '123'}, 'children', {_key: '567'}], offset: 3},
+      backward: false,
+    }
+    const onChange = jest.fn()
+    const {rerender} = render(
+      <PortableTextEditorTester
+        onChange={onChange}
+        ref={editorRef}
+        selection={initialSelection}
+        schemaType={schemaType}
+        value={initialValue}
+      />,
+    )
+    await waitFor(() => {
+      if (editorRef.current) {
+        expect(onChange).toHaveBeenCalledWith({type: 'ready'})
+        expect(onChange).toHaveBeenCalledWith({type: 'value', value: initialValue})
+        const sel = PortableTextEditor.getSelection(editorRef.current)
+        PortableTextEditor.focus(editorRef.current)
+
+        // Test for object equality here!
+        const anotherSel = PortableTextEditor.getSelection(editorRef.current)
+        expect(PortableTextEditor.getSelection(editorRef.current)).toStrictEqual(initialSelection)
+        expect(sel).toBe(anotherSel)
+      }
+    })
+    rerender(
+      <PortableTextEditorTester
+        onChange={onChange}
+        ref={editorRef}
+        selection={newSelection}
+        schemaType={schemaType}
+        value={initialValue}
+      />,
+    )
+    waitFor(() => {
+      if (editorRef.current) {
+        expect(PortableTextEditor.getSelection(editorRef.current)).toEqual(newSelection)
+      }
+    })
+  })
+
+  it('handles empty array value', async () => {
+    const editorRef: RefObject<PortableTextEditor> = createRef()
+    const initialValue: PortableTextBlock[] = []
+    const initialSelection: EditorSelection = {
+      anchor: {path: [{_key: '123'}, 'children', {_key: '567'}], offset: 2},
+      focus: {path: [{_key: '123'}, 'children', {_key: '567'}], offset: 2},
+    }
+    const onChange = jest.fn()
+    render(
+      <PortableTextEditorTester
+        onChange={onChange}
+        ref={editorRef}
+        selection={initialSelection}
+        schemaType={schemaType}
+        value={initialValue}
+      />,
+    )
+    await waitFor(() => {
+      if (editorRef.current) {
+        expect(onChange).not.toHaveBeenCalledWith({
+          type: 'invalidValue',
+          value: initialValue,
+          resolution: {
+            action: 'Unset the value',
+            description: 'Editor value must be an array of Portable Text blocks, or undefined.',
+            item: initialValue,
+            patches: [
+              {
+                path: [],
+                type: 'unset',
+              },
+            ],
+          },
+        })
+        expect(onChange).toHaveBeenCalledWith({type: 'value', value: initialValue})
+        expect(onChange).toHaveBeenCalledWith({type: 'ready'})
+      }
+    })
+  })
+  it('validates a non-initial value', async () => {
+    const editorRef: RefObject<PortableTextEditor> = createRef()
+    let value: PortableTextBlock[] = [helloBlock]
+    const initialSelection: EditorSelection = {
+      anchor: {path: [{_key: '123'}, 'children', {_key: '567'}], offset: 2},
+      focus: {path: [{_key: '123'}, 'children', {_key: '567'}], offset: 2},
+    }
+    const onChange = jest.fn()
+    let _rerender: any
+    await waitFor(() => {
+      render(
+        <PortableTextEditorTester
+          onChange={onChange}
+          ref={editorRef}
+          selection={initialSelection}
+          schemaType={schemaType}
+          value={value}
+        />,
+      )
+      _rerender = render
+    })
+    await waitFor(() => {
+      expect(onChange).not.toHaveBeenCalledWith({
+        type: 'invalidValue',
+        value,
+        resolution: {
+          action: 'Unset the value',
+          description: 'Editor value must be an array of Portable Text blocks, or undefined.',
+          item: value,
+          patches: [
+            {
+              path: [],
+              type: 'unset',
+            },
+          ],
+        },
+      })
+      expect(onChange).toHaveBeenCalledWith({type: 'value', value})
+    })
+    value = [{_type: 'banana', _key: '123'}]
+    const newOnChange = jest.fn()
+    _rerender(
+      <PortableTextEditorTester
+        onChange={newOnChange}
+        ref={editorRef}
+        selection={initialSelection}
+        schemaType={schemaType}
+        value={value}
+      />,
+    )
+    await waitFor(() => {
+      expect(newOnChange).toHaveBeenCalledWith({
+        type: 'invalidValue',
+        value,
+        resolution: {
+          action: 'Remove the block',
+          description: "Block with _key '123' has invalid _type 'banana'",
+          item: value[0],
+          patches: [
+            {
+              path: [{_key: '123'}],
+              type: 'unset',
+            },
+          ],
+          i18n: {
+            action: 'inputs.portable-text.invalid-value.disallowed-type.action',
+            description: 'inputs.portable-text.invalid-value.disallowed-type.description',
+            values: {
+              key: '123',
+              typeName: 'banana',
+            },
+          },
+        },
+      })
+    })
+  })
+  it("doesn't crash when containing a invalid block somewhere inside the content", async () => {
+    const editorRef: RefObject<PortableTextEditor> = createRef()
+    const initialValue: PortableTextBlock[] = [
+      helloBlock,
+      {
+        _key: 'abc',
+        _type: 'myTestBlockType',
+        markDefs: [],
+        children: [{_key: 'def', _type: 'span', marks: []}],
+      },
+    ]
+    const initialSelection: EditorSelection = {
+      anchor: {path: [{_key: '123'}, 'children', {_key: '567'}], offset: 2},
+      focus: {path: [{_key: '123'}, 'children', {_key: '567'}], offset: 2},
+    }
+    const onChange = jest.fn()
+    render(
+      <PortableTextEditorTester
+        onChange={onChange}
+        ref={editorRef}
+        selection={initialSelection}
+        schemaType={schemaType}
+        value={initialValue}
+      />,
+    )
+    await waitFor(() => {
+      if (editorRef.current) {
+        expect(onChange).toHaveBeenCalledWith({
+          type: 'invalidValue',
+          value: initialValue,
+          resolution: {
+            action: 'Write an empty text property to the object',
+            description:
+              "Child with _key 'def' in block with key 'abc' has missing or invalid text property!",
+            i18n: {
+              action: 'inputs.portable-text.invalid-value.invalid-span-text.action',
+              description: 'inputs.portable-text.invalid-value.invalid-span-text.description',
+              values: {
+                key: 'abc',
+                childKey: 'def',
+              },
+            },
+            item: {
+              _key: 'abc',
+              _type: 'myTestBlockType',
+              children: [
+                {
+                  _key: 'def',
+                  _type: 'span',
+                  marks: [],
+                },
+              ],
+              markDefs: [],
+            },
+            patches: [
+              {
+                path: [
+                  {
+                    _key: 'abc',
+                  },
+                  'children',
+                  {
+                    _key: 'def',
+                  },
+                ],
+                type: 'set',
+                value: {
+                  _key: 'def',
+                  _type: 'span',
+                  marks: [],
+                  text: '',
+                },
+              },
+            ],
+          },
+        })
+      }
+    })
+    expect(onChange).not.toHaveBeenCalledWith({type: 'value', value: initialValue})
+    expect(onChange).toHaveBeenCalledWith({type: 'ready'})
+  })
+})