slate v0.57.0 Release Notes

Release Date: 2019-12-18 // over 4 years ago
  • BREAKING

    Overridable commands now live directly on the editor object. Previously the Command concept was implemented as an interface that was passed into the editor.exec function, allowing the "core" commands to be overridden in one place. But this introduced a lot of Redux-like indirection when implementing custom commands that wasn't necessary because they are never overridden. Instead, now the core actions that can be overridden are implemented as individual functions on the editor (eg. editor.insertText) and they can be overridden just like any other function (eg. isVoid).

    Previously to override a command you'd do:

    const withPlugin = editor => {
      const { exec } = editor
    
      editor.exec = command => {
        if (command.type === 'insert_text') {
          const { text } = command
    
          if (myCustomLogic) {
            // ...
            return
          }
        }
    
        exec(command)
      }
    
      return editor
    }
    

    Now, you'd override the specific function directly:

    const withPlugin = editor => {
      const { insertText } = editor
    
      editor.insertText = text => {
        if (myCustomLogic) {
          // ...
          return
        }
    
        insertText(text)
      }
    
      return editor
    }
    

    πŸ”Œ You shouldn't ever need to call these functions directly! They are there for plugins to tap into, but there are higher level helpers for you to call whenever you actually need to invoke them. Read on…

    Transforms now live in a separate namespace of helpers. Previously the document and selection transformation helpers were available directly on the Editor interface as Editor.*. But these helpers are fairly low level, and not something that you'd use in your own codebase all over the place, usually only inside specific custom helpers of your own. To make room for custom userland commands, these helpers have been moved to a new Transforms namespace.

    Previously you'd write:

    Editor.unwrapNodes(editor, ...)
    

    Now you'd write:

    Transforms.unwrapNodes(editor, ...)
    

    🚚 The Command interfaces were removed. As part of those changes, the existing Command, CoreCommand, HistoryCommand, and ReactCommand interfaces were all removed. You no longer need to define these "command objects", because you can just call the functions directly. Plugins can still define their own overridable commands by extending the Editor interface with new functions. The slate-react plugin does this with insertData and the slate-history plugin does this with undo and redo.

    NEW

    πŸ‘‰ User action helpers now live directly on the Editor.* interface. These are taking the place of the existing Transforms.* helpers that were moved. These helpers are equivalent to user actions, and they always operate on the existing selection. There are some defined by core, but you are likely to define your own custom helpers that are specific to your domain as well.

    For example, here are some of the built-in actions:

    Editor.insertText(editor, 'a string of text')
    Editor.deleteForward(editor)
    Editor.deleteBackward(editor, { unit: 'word' })
    Editor.addMark(editor, 'bold', true)
    Editor.insertBreak(editor)
    ...
    

    Every one of the old "core commands" has an equivalent Editor.* helper exposed now. However, you can easily define your own custom helpers and place them in a namespace as well:

    const MyEditor = {
      ...Editor,
      insertParagraph(editor) { ... },
      toggleBoldMark(editor) { ... },
      formatLink(editor, url) { ... },
      ...
    }
    

    Whatever makes sense for your specific use case!