Refactor editor methods and fix JSDoc

[zbeyens]

Description

This pull request introduces a new pattern without any breaking changes. All Editor and Transforms methods now call editor methods. For example, Transforms.setNodes is now calling editor.setNodes, and editor.setNodes is now calling setNodes, an exported function implementing the default editor behavior. You can override editor.setNodes on your end so that you can either use Editor.setNodes or editor.setNodes, and both will use your overridden behavior, and Slate will too.

The editor object now has many more methods, and some changes have been made to improve code style consistency. None of the implementation of the methods has changed, except for the addition of a new argument to editor.insertText.

This PR also includes:

• Moving JSDoc's to the interface type to allow IDEs access to the interface methods.
• Removing method types where type inference can be used to reduce redundancy.
• Improving code style consistency.

Example

Please refer to the example code snippet below for the usage of the new pattern:

import { createEditor } from 'slate'
import { withReact } from 'slate-react'

const customSetNodes = editor => {
  // Your custom behavior here
}

const editor = withReact(createEditor())

editor.setNodes = customSetNodes

// Now, if you (or Slate) uses Transforms.setNodes or editor.setNodes, it will use your overridden behavior.

Context

This pull request allows for more flexibility in implementing custom behavior for Editor and Transforms methods without breaking any existing functionality. It achieves this by introducing a new pattern where Editor and Transforms methods call editor methods, and editor methods call an exported function implementing the default editor behavior.

This pattern allows for overriding editor methods with custom behavior, and using either Editor or editor methods, which will both use the overridden behavior, and Slate will too.

ReactEditor is not yet following that pattern. I'd wait for this pattern approval first.

With the introduction of many new methods to editor, it may be beneficial to consider implementing a plugin-based architecture to prevent overloading the editor object. This would involve relocating all queries to editor.queries and all transforms to editor.transforms. However, this is a significant breaking change that is not included in this PR.

[changeset-bot]

🦋 Changeset detected

Latest commit: e6e8724

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 2 packages

Name	Type
slate-react	Minor
slate	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[12joan]

Does this have implications for the withX pattern like we use in Plate? I imagine something like this could be used now instead of the old pattern:

import { someFunction } from 'slate[-react]';

export const withX = (editor) => ({
  ...editor,
  someFunction: (x, y, z) => {
    console.log('someFunction', x, y, z);
    return someFunction(x, y, z);
  },
});

[zbeyens]

@12joan This composition pattern is now possible, indeed! However, in that example, the last plugin would override the other plugins overrides (on the same method), so we'd need to slightly change Plate core logic to support the piping pattern.

[TheSpyder]

This change bloated the minified core by 19% and destroyed one of the things I really liked about slate; a focus on static method implementations meant any features I didn't use were tree-shaken away.

I'm disappointed to see Slate moved in this direction while I was away. I don't think it meshes with the goals Ian set out for it. Surely you could've done this all-in-one just with the slate-react editor instance? Maybe having a spaghetti bundle with all features linked as methods on the editor object is fine if you're using slate-react, but that's not something I plan to do.

[dylans]

This change bloated the minified core by 19% and destroyed one of the things I really liked about slate; a focus on static method implementations meant any features I didn't use were tree-shaken away.

I'm disappointed to see Slate moved in this direction while I was away. I don't think it meshes with the goals Ian set out for it. Surely you could've done this all-in-one just with the slate-react editor instance? Maybe having a spaghetti bundle with all features linked as methods on the editor object is fine if you're using slate-react, but that's not something I plan to do.

Yikes, ok. Plan wasn’t to bloat/break tree shaking, but to try to make things more consistent. Will look into this asap.