Documentation is missing Change.normalize

The documentation here –

https://docs.slatejs.org/slate-core/change

– needs the normalize function.

[SmilinBrian]

Wow, I feel like Cameron’s comment about withoutNormalization() should be documented somewhere!

[cameracker]

Yes, the vast majority of programmatic change functions will trigger a normalization automatically on the blocks that have changed, this is an important step in ensuring that your document conforms to the schema after every change that is made to it, regardless of whether the change originates from within the editor or not.

withoutNormalization is a function that I think may be poorly named, but it basically defers normalization until after the entirety of a set of changes is applied. It’s intended to hide the need for a user to continuously pass { normalize: false } to change functions, and also to prevent the risk of having an unnormalized document after the changes where normalization has been suppressed are complete. The major flaw with withoutNormalization is it calls normalization on all nodes in the document, so it should be used sparingly and strategically. The risk of calling change.normalize() is that this causes the entire document to be normalized, which is expensive, and this is doubly true for calling change.normalize() in conjunction with withoutNormalization as your document will be normalized twice.

That you have a situation where setBlocks is not triggering a normalization means that normalization is being suppressed somehow, and it’s not really clear where without looking at a code snippet. Some big ones that come to mind are you’re somehow stuck in some weird nesting of a withoutNormalization call, or you’ve accidentally used setFlag('normalize', false) somewhere and it’s been disabled at a very wide level. It may also be that the normalization is happening but not at the interval where you expect it, but again its kinda hard to tell without a snippet.