Model, engine and document organisation

[pjasiun]

At this point, we have a mess. The document is at the same time:

• document data structure with roots, selection, and history,
• the model entry point with methods like transformDeltas (which has nothing to do with the document), enqueueChanges or even schema (which is mostly used in converters which operates on data outside the document).

Also, after changes proposed in https://github.com/ckeditor/ckeditor5-engine/issues/858#issuecomment-344947666, the document will fire change event also for changes which do not change the document (changes in document fragments or detached elements). This is the same change event which is overused (and should be replaced with post fixers https://github.com/ckeditor/ckeditor5-engine/issues/1101).

This is why I proposed to change the structure to this:

The current model writer class will be part of the batch API, the new writer will be more similar to the view writer.

The key concept is split between document, which is a read-only data structure, and writer which is the way to modify the document, but it can also modify any element or document fragment. It will be the writer who fires event about applied operations (currently it is document#change event), it will be writer#operation. document#change will be a more semantic event, the proper event to use by plugins, most probably the result of the document diff util https://github.com/ckeditor/ckeditor5-engine/issues/1172.

Note, that this way any util which listens on applied operations (markers, differ), can work on any subtree, while these focused on the document can filter only document operation or listen on document events.

Also, model and view will have a very similar architecture: read-only document and writer to modify it. It won't be identical because you will have to create a batch, to modify the model in batches, but this is because the problems are different (view does not need the concept of batches).

Another change is to split model and document. Now, the document will be... only a document. It will not be model entry point anymore. Schema, default transformations, transformDeltas, creating writer will be moved to the Model class.

[pjasiun]

This ticket can be done together with https://github.com/ckeditor/ckeditor5-engine/issues/678.

[pjasiun]

Now, Batch merges 2 responsibilities: it's both collection of deltas, representing single undo step and the util to modify the document (and other elements). At the same time, Writer do not do much: creates batches and fire events. This is why I propose to move all modifications methods to writer. It will be more natural to write:

writer.insert( element, position );

A writer will have batch as a property to which all deltas are saved. Creating writer you will be able to say to which batch this writer is saving changes:

const writer = new Writer( batch );
writer.insert( element, position );

Writer constructor should create a new batch by default.

const writer = new Writer();
writer.insert( element, position ); // works on the new batch

It also solves the problem with methods and cases when a batch is not really needed. It was strange that you call batch.createElement, when the batch is not involved in creating the element. Also, when you modify a detached element, which is not tracked by undo, batch is not really needed.

At the same time, it means that writer, will not be able to fire operation event since multiple writers will be used. However, I find model a perfectly fine class to fire such event.

The only inconvenience in the new solution is that you will have to use two writers if you want to have 2 separate undo steps. However, I think that:

1. it's not a very popular case, usually all changes in your features suppose to be a single undo step, creating multiple undo steps, or adding something to an old one is an advance case, for advance users;
2. when you think that each writer is saving changes to its batch, so if you want to work on 2 separate batches you need 2 separate writers, it's not that strange anymore.

[pjasiun]

Lets consider it closed by ckeditor/ckeditor5-engine@5be1ad6. Details will be handled in follow-up.

[pjasiun]

In the PR which closes this issue:

• model and document were split (model handles all nodes: these in the document and these detached),
• batch and writer were split (batch is only the collection of deltas while writer gets all methods to modify the tree),
• instead of enqueueChanges, 2 new syntax were introduced: change and enqueueChange, see https://github.com/ckeditor/ckeditor5-engine/blob/a8e0f3732d2ef6dbc2e604103edb393df8e6b89f/src/model/model.js#L60-L153,
• change and enqueueChange blocks become now the only proper API to get the writer and modify the model.

We decided not to introducing engine class because of reasone described here: https://github.com/ckeditor/ckeditor5-engine/issues/678#issuecomment-352760701.