mismatch between "editor" and "value" concepts

[ianstormtaylor]

Do you want to request a feature or report a bug?

Discussion.

What's the current behavior?

Just opening this up for discussion, since it's something that I think Slate hasn't really solved well so far, and leads to it being hard to decide in either direction for the API...

Right now there are two concepts vying for the "top spot" in the architecture:

1. value — which holds the document, the selection, the history and the schema. This can easily be created server-side (or wherever), since it's not coupled to the view layer at all. (I'd consider change to be equivalent to value here, since they hold all the same data.)

2. editor — which holds the plugins, the current value, and the schema to an extent. This is less easy to use server-side, since the editor is inherently tied to the view layer. (Although this need not always be the case.)

So far, it's been unclear which is the "primary" concept. For example...

• Event handlers are passed both a change and an editor to allow the user to decide which they want to use. You normally use the change, but sometimes, for example if you want to trigger an async change later, you need to use the editor.

• For the idea of "commands and queries" from #2066, it's unclear whether these commands should live inside the schema (or similar) and be exposed as change.command(...). Or whether, since they are tied to the plugins, they should be exposed as editor.command(...). Both have tradeoffs.

• You could make the argument that history shouldn't really be inside the value, and instead be controlled by the editor which is the long-lived entity—which would seem totally reasonable to me.

• Right now there's a confusion in that the editor's plugins create a final schema object that gets set on the value. But the value can also be initialized with its own schema, which will be overwritten... and it's not clear how they interact.

What's the expected behavior?

I'm not totally sure. This is something that I've wrestled with, but never found a nice mental model for being clear about the distinctions between the two. I'd love for anyone with ideas to comment! (Even if you aren't sure yourself, anything is helpful!)

I think it's helpful to have a few goals:

• It would be good for "commands", "history", etc. to all be able to be modeled in server-side environments where there is no concept of the "view" layer. This doesn't necessarily mean it has to be the value model, but it has to be something that isn't tied to the DOM or rendering.

• It would be best if the top-level concept can unify the plugins, schema, history, commands, etc. in a way that makes it clear where all of this stuff stems from.

[zhujinxuan]

but sometimes, for example if you want to trigger an async change later, you need to use the editor.

Perhaps we shall expose editor.change as get change instead of change(fn), then it appears reasonable that editor.change is same with change in onEvent(chang, editor), but different in the setTimeout. (But the problem is how to flush the change in setTimeout? calling editor.onChnage(editor.change) is not a good idea.)

Perhaps we shall expose editor.requestNextCycle to deal with the asynchronous calling? We cannot guarantee that window.requestAnimation is exactly after this lifecycle update if multi-components are updated in the same time with editor.value.

Right now there's a confusion in that the editor's plugins create a final schema object that gets set on the value.

Can I know where we need about value.schema? It seems that we run normalization by insidestack.run rather than with value.schema. Perhaps we can have stack inside change to run server side tests?

[ericedem]

Hmm I've been wrestling with this one myself. The mental model I have for the Editor is that it is simply the view layer. Given a bunch of props like value / schema etc., Render something to the page. The value is then just the pure state of the app: what is the current snapshot of the app's state.

I think the problem is that this gives us the "view" and the "model" but it doesn't really tell us where the controller lives (in a traditional MVC architecture). So the current "controller" is a combination of change, value and the editor that don't always know how to talk to each other. This is why there is some confusion about whether to make changes you need to talk to the value or the editor.

I wonder if there should be a third component like Controller that contains all the event / state management. Then the "editor" is just a simple view layer that renders and proxies interaction events into the controller. The controller would also just be pure non-react JS, easy to work with on the server side. It would probably also be easier to test than the editor.

The big downside I see to this is that in React a component is generally also the controller. This might cause us to move further away from React best practices.

[zhujinxuan]

I think one problem is that we expose editor as React.Component, but its interface appears like something/proxy from packages/slate.

[bryanph]

I like @ericedem's suggestion. Perhaps we should consider Editor as a target environment and allow plugins to target different environments. This would also make it easier to target other environments later like react-native for plugins or even completely different frameworks than React (if someone would want to do this). Just a late night thought :man_shrugging:

[ianstormtaylor]

@bryanph can you give some pseudocode to explain what you mean? or explain more?

[justinweiss]

I don't really have anything concrete to add, other than that I think of Editor purely as the view/controller layer, and that I really really like being able to work with a Value outside of the context of showing an editor. It's one of my favorite things about Slate -- with just a Value, I can create and apply operations, I can apply schemas, I can serialize / deserialize, etc. I get all the transformations I want, and just get a new Value at the end.

A few things people have mentioned here that I'd appreciate:

• A way to replace the default implementation of History. For collaborative editing, it would be nice to have an Editor / Value be completely agnostic as to how undo / redo are implemented. Right now, it isn't even possible to replace history with .setValue, and it'd be nice to open this up. Having it be a property of Editor makes some sense to me, since I think of Value changes as automated, and I can't imagine a program wanting undo / redo that it couldn't handle itself.
• I would love a way to hook the next steady state of Editor. I'm using an older version of Slate right now, so this may have improved, but I've had a few times where I've had to delay 10-20 ms to get things like forcing editor focus to take. I think this is because there might be a few Editor -> Browser -> Editor selection cycles that happen before their states converge, and I really don't care about what happens until they're done.
• If we rethink the responsibilities of Editor as View, it would be nice to imagine what an Editor that's not in-browser React might look like. For example, what would a React Native view/controller on a Slate Value look like? Not that anyone needs to build that right now, but in thinking about how we could help support that kind of View replacement, it might give some hints to where the architectural lines should be.

[ianstormtaylor]

@ericedem I agree with you, having a plain-JS "controller" concept is compelling. It would help the server-side story, it would probably clean up some of the existing client-side story, and it would make it more clear where the interoperability boundary is for plugins and other view layers in the future.

@justinweiss I agree with you too, I'd like history to be more pluggable. And it sounds like you're talking about similar things to @ericedem as well.

---

I think one thing I'm struggling with is where the plugins and schema live. Right now they sort of live in both places. And there are tradeoffs in both directions:

1. If they live in the controller, then you wouldn't be able to call plugin-defined "commands" if you only have the value model instance. You'd need an instance of the controller as well.

2. If they live in the value (model), it feels slightly weird to have the model's API be something that is fluid and defined dynamically in plugins. It's possible, but it would need to either use string-based command names (reinventing methods), or use Proxy to make it seamless.

If we approach it from the plain-JS controller mindset, then 1. might not be as much of an issue, because instantiating a lightweight Controller isn't hard. And this does feel the most natural to me.

We could decide to get rid of the:

value.change()...

In favor of only having the:

controller.change(change => ...)

But that loses some of the niceties that @justinweiss is talking about. But @justinweiss I'd be curious to hear which of those are truly most important to you. I'm not sure I'd personally mind it if the schema was tied to the editor instead of the value. But I would definitely miss the nice serialization of values. Doing this would result in maintaining:

• [x] Values can be serialized/deserialized.
• [x] Values can have low-level operations applied to them.
• [x] Values can have low-level mutations applied via their removeNode-style methods. (These aren't super useful by themselves, and are rarely used today.)

And losing:

• [ ] Values can't have schemas. (Without a controller.)
• [ ] Values can't have high-level mutations applied via changes. (Without a controller.)
• [ ] Values can't have high-level "commands" and "queries" applied to them. (Without a controller.)

This would make it clear that these things are the domain of the controller:

controller.change(change => ...)
controller.command('toggle_bold')
controller.query('is_bold')

What are your thoughts on that? (Anyone!)

[justinweiss]

Thinking about it more, Schema isn't really a property of a Value, it's a property of how you use it. If we had a Controller, it seems like the right place for those.

It shouldn't be much of a problem -- If I could, in a Node app (for example), manually instantiate a controller, hand it a Value.fromJSON and a schema, run changes on it, and pull either an updated Value or a bunch of Operations back out of it, that wouldn't be much more complicated than it is today. And if we can still hand a Value a list of Operations and get a new Value out of them, there's always an out if going through the Controller isn't feasible. You just wouldn't be able to guarantee those operations would put the Value into a valid state. But if the list of operations originally came from change methods, you could assume that normalizing operations were already in that list.

[ianstormtaylor]

@justinweiss nice, I agree! In the OT server use case where you’re receiving the low-level “valid” operations you can operate on the value directly. And for other use cases you can instantiate a thin controller.

I think it might also make it possible for us to combine the idea of the “simulator” and the “controller” potentially which would be nice for testing.

[justinweiss]

@ianstormtaylor Yeah. In the OT case, though, you could have valid simultaneous operations put the Value into an invalid state.

Imagine you have two empty paragraphs, client 1 deletes paragraph 1, and client 2 simultaneously deletes paragraph 2. Those are both valid operations on the document, but you'd end up with a Document with no nodes.

So you'd probably want the Schema / Controller on that side, too, you just wouldn't need an Editor.

[ianstormtaylor]

I'm just going to leave a summary of my current API architecture thoughts here...

• [x] Introduce the Editor controller. The piece is to introduce a new "plain JS" controller exposed in the core slate module, called Editor. It will contain the core editor logic (like ensuring normalization, running through the plugins stack, etc.) that is currently partly in slate-react. It will be used by slate-react, or on the server-side by itself, or in the future in non-React view layers to get the basic editor behaviors. If you exposed a Slate-like API to developers you could even bundle the Editor in your API library.

• [x] Fold the Stack into Editor. Once you have the concept of this editor controller, you don't actually need the stack. It lives in "models" right now but it's not really a model. It's just thin layer around some iterations methods that can easily be moved to become methods on the Editor instance instead. This makes the public API more clear, such that plugins can invoke the stack if they have a need to (as the core plugin currently does).

• [x] Add a change.editor reference. Changes are actually editor-specific instead of value-specific like they are currently architected. This also clears up the idea that changes are "models", while they are in a sense, they are not immutable like the rest of Slate's models. By making them editor-aware we can...

• [x] Remove the schema property from Value. With the reference to change.editor and thus change.editor.schema, we no longer need to have the value.schema coupling which is confusing because the schema is really an editor-specific object. This also eliminates another "non-model" model, because the schema isn't really a "model" in the sense of being serializable or immutable in the way that all other Slate models are. (This is a pattern, there are a handful of things in "models" right now that don't really belong.)

• [x] Remove the value.change() method. Similarly, with changes now tied to the Editor controller, changes can no longer be created with only access to a value, because they rely on access to the editor's schema to make decisions about how the change occurs (for example for void nodes).

• [x] Add the "commands" concept to the editor. This introduces a new concept called "commands" which are part of the Editor and can be defined in plugins. This relates to #2066 and allows for editor-level commands that can be defined in a single place, but used in many. It is very similar in approach to Redux Actions, or the Elm Architecture, in terms of having a pre-defined set of "commands" that can change the state. And now that the Change objects are editor-aware, each command can be exposed as change[command], exactly like the current change methods. Which brings us to...

• [x] Add "queries" support. I was originally thinking of these as two separate concepts, but I think instead commands could return values, in which case "queries" are just commands that return values but don't add any operations to the stack. This way we don't need to introduce an entirely new concept? Although it can be done either way, introducing a separate "queries" concept would work just as well.

• [x] Convert the current "changes" into commands. With the concept of commands introduced, all of what are currently called "changes" can now be implemented as commands in the core plugin, instead of the current custom approach. This is functionally equivalent, but it means that now even the core commands can be overridden for use cases that need it. (This is something that comes up somewhat often in Slack as a question, and isn't easily solved right now by any other means.)

• [x] Convert History into commands on value.data. Right now the history is implemented as "changes" but it also special-cased in a way that makes it very hard to customized. With the new pluggable commands concept though, history can change to become three commands: save, undo, redo which are overridable by the user. And instead of needing to live in a custom History model, they can be implemented to live in the value.data namespace as data.undos and data.redos. This way users can implement their own history, using a totally different data structure if they'd like.

---

At the end you end up with a clearer delineations:

Layer	Concepts
Model	Value, Operations, Nodes, Marks, Ranges, Data
Controller	Editor, Changes, Schema, Commands, Queries, History
View	<Editor>, <Island>, render*

The only overlap remaining that I can see still is that "plugins" end up defining logic that lives in both the Controller and the View layers. But I'm not sure if there's a way around this. (If anyone has ideas I'm open!)

How does that sound?

[ericedem]

Hey this sounds great, just a couple questions:

Add "queries" support.

Can you clarify what these queries would be used for? Is this for grabbing a subset of the value? Would this replace access like Editor.value?

Also, I'm trying to think through what the interface to react would look like. Would the user create an instance of Editor and pass it into the react editor? Or would the user still pass in through a similar interface to what they are doing today, and have the Component build out the Editor Controller?

Is the React component still going to be controlled like it is now? By emitting the value in a change event and passing it back in through props? Or would the React component emit the entire EditorController on every change?

[ianstormtaylor]

@ericedem great questions! Thanks for reading and digging in.

Can you clarify what these queries would be used for? Is this for grabbing a subset of the value? Would this replace access like Editor.value?

Sorry, this is from #2066. Basically once you add "commands" you start to realize that many things that work with commands need to ask the editors questions to know whether to perform certain logic, and you get a parallel "queries" feature for doing that. If "commands" are schema-specific functions that perform changes. Then "queries" are schema-specific functions that return information.

Also, I'm trying to think through what the interface to react would look like. Would the user create an instance of Editor and pass it into the react editor? Or would the user still pass in through a similar interface to what they are doing today, and have the Component build out the Editor Controller?

Is the React component still going to be controlled like it is now? By emitting the value in a change event and passing it back in through props? Or would the React component emit the entire EditorController on every change?

I'm sketching this out right now. I'd like to keep the component interface the same, since it feels pretty nice to me, and feels React-ish. Such that the <Editor> component is actually just going to create its own Editor controller under the covers, and rely on the controller to handle some of the logic for it.

However, that underlying controller is never publicly exposed to the user. So for example, the <Editor> will wrap the Editor controller, and when creating a Change it will have a change.editor pointing to the component instance. (The component will be in charge of mimicking the Editor interface so that they are interchangeable.)

By doing that, the <Editor> remains a "ViewController" in the React sense. I think the pattern that will end up shaking out is that each view layer can adopt their own patterns. For React, it merges the "view" and "controller", and thus it makes sense to do that here. If some other view layer had two separate concepts, they could separate them.

However, on the server-side you'd just use the Editor directly, with the same API (since <Editor> mimics it).

What this means is that some plugins, if they happen to rely on React-specific properties of the change.editor will be React specific. But this is already the case with event being synthetic events. And I think this is inevitable so we should embrace it.

How does that sound?

[bryanph]

@ianstormtaylor So what would be possible with this architecture that isn't possible currently? I'm not sure I fully understand the issue.

Some thoughts:

• If this controller is not a React component then how will we handle making properties like History pluggable?
• Will there be a method that takes plugins as an input and return a collection of events to apply to the React editor and a schema? PluginArray => { Schema, EventMap } And the result will be applied to the React Editor component?
• Since the schema defines what values the Document can contain, doesn't that make it part of the Model?

As for what I meant with targeting an environment, this was a thought I had because plugins to me seem to do two things:

• Extend the schema (the definition of what the Document can consist of)
• Bind environment-specific events like onPaste, onDrop, etc.

Since plugins tend to wrap functional behaviour, like a nested list or adding an image block, I thought perhaps the environment-specific code like adding event listeners could be specified in the plugin as belonging to a certain environment, like React or React native. So that when iterating through all the plugins you would potentially get support for multiple environments depending on which environments the plugin supports. However, thinking about it further, you'd probably want to keep these plugins separate, so have a slate-react-plugin-list and a slate-react-native-plugin-list, with some duplicate code between them for extending the schema, normalization, etc.

But if we want to support React Native in the future we'd probably want to start naming plugins to reflect that they only work in React and not in React Native

[ianstormtaylor]

@bryanph thank you for taking the time to write that up! I really appreciate it. Those are great questions, I'll try to answer each one...

So what would be possible with this architecture that isn't possible currently? I'm not sure I fully understand the issue.

Good question. This would unlock a few different things:

• Plugins would be able to fully override the history logic for saving, undoing, and redoing operations. This way one could implement a "non-operational" history as a plugin, or a different logic for when to join operations into groups, etc. (Right now this is only possible if you define your own immutable History record that copies the mirrors API exactly, and are sure to always initialize your value with it. Not something a plugin can do, and even then certain new behaviors are probably out of reach.)

• Plugins would be able to fully override any of the commands (which are now changes). This allows for defining custom behaviors for even the built-in commands like insertNodeByPath. I think this would allow for "attribution" where you want to attach marks to any text/nodes each user does. (Although this may be possible currently at the operations level, I haven't fully investigated.) It would also be possible for users to define a custom behavior for internal editor commands like splitNodeByPath, instead of having to override the behavior from the top by overriding the enter functionality.

• With the addition of commands, plugins would be able to define their own first-class commands that can be used throughout the editor. And, more importantly, plugins can take a command as a configuration option to be performed when some logic is achieved. (This is currently possible by being diligent about factoring all of your editor logic into small helper functions, and instead designing plugins to accept those functions.)

I think that is it. But it also is about cleaning up the model distinctions that currently make the codebase confusing, and that limit it from achieving things in the future.

If this controller is not a React component then how will we handle making properties like History pluggable?

Written up above, but it comes down to adding "commands" and "queries" for this.

Will there be a method that takes plugins as an input and return a collection of events to apply to the React editor and a schema? PluginArray => { Schema, EventMap } And the result will be applied to the React Editor component?

Essentially, yes. Except I'm thinking about trying to make it more transparent, such that all of the commands are exposed as first-class methods on the Change object. This keeps the API native feeling and terse, instead of having to result to a secondary data structure, or

But I think it would be good to expose editor.commands with a map of them so that people can check to ensure that their plugins are registering properly. I haven't really fleshed this out yet.

Since the schema defines what values the Document can contain, doesn't that make it part of the Model?

This one is tricky. It defines what shape the document (and later ideally the selection too) can take. But it isn't necessarily part of the model so much as a constraint that is applied to the model. It leads to confusion if a value can have a value.schema when inserted into the editor, while at the same time the editor has an editor.schema. And then there's a question of which one is the "true" schema, or if they are somehow combined, etc.

Instead, if the editor is allowed to control the schema, those questions disappear. This matches more closely with the ideas being developed like isVoid or isAtomic not being inherent to the model, but inherent to the editor. One editor could treat images as voids in the traditional sense, whilst another could decide that it edits their textual content by leaving them non-void with the image as a background-image. (Or something 😄 else crazy!)

I thought perhaps the environment-specific code like adding event listeners could be specified in the plugin as belonging to a certain environment, like React or React native. ... However, thinking about it further, you'd probably want to keep these plugins separate, so have a slate-react-plugin-list and a slate-react-native-plugin-list, with some duplicate code between them for extending the schema, normalization, etc. ... But if we want to support React Native in the future we'd probably want to start naming plugins to reflect that they only work in React and not in React Native

These are good points. I think we're not quite close enough to seeing what React Native, or what Vue support looks like to make a decision. But it could very well be that we end up separating the fields out by environment if we need to. Same for the plugin naming. Until we get closer though I think it's safe to keep them as-is.

How does all that sound?

[zhujinxuan]

Shall we have editor.onProps (for props update) and editor.onChange (for flush change) to bind the editor model to the ` react component?

[ianstormtaylor]

@zhujinxuan yup! Currently I've got the Editor controller accepting an onChange function for calling back, and exposing its own editor.setProperties method for updating the changed properties.

[ianstormtaylor]

Some more thoughts, as a result of sketching some of this out with code...

We have the concepts of isAtomic and isVoid. Right now these are solved by the schema, with an isVoid: true or isAtomic: true entry. This is fine, but I also wonder if these aren't just two of the core "queries" that could be answered. The rest of the schema deals with validation, and this is a small outlier.

It could also be solved by allowing plugins to answer queries, and you'd achieve the same functionality. Not necessarily that that's better, because it might be more of a hassle to write, but it's just an observation of an existing code path that could be eliminated.

Further, you can actually model the existing normalizeNode plugin definitions in the same way. It could also be a "query" that plugins can choose to answer. And it would work exactly as it currently does, without having to be special-cased.