Slate: Documentation is missing Change.normalize

[tashburn]

The documentation here --

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

-- needs the normalize function.

[CameronAckermanSEL]

Not sure if it does, because ideally people should not have to call this manually.

[ianstormtaylor]

Feel free to pull request it, thanks.

[tashburn]

@CameronAckermanSEL I needed to call it manually. I don't think my use-case is that esoteric. Clicking a toolbar button to change the block type requires calling change.setBlocks(type), which doesn't run the validations unless I do change.normalize.

[CameronAckermanSEL]

I disagree with you because it probably is a defect that setBlocks did not fire off validation, therefore eliminating the need to call it manually in this case.

In fact yeah the setBlocks function does trigger normalization, so I think it might be suppressed somewhere unintentionally in your code base.

[tashburn]

@CameronAckermanSEL @ianstormtaylor

Validations are certainly supposed to be called when a user makes edits in an Editor. Are they also supposed to be called after all programmatic changes to a Value?

I actually did expect the validations to be run after my setBlocks call. I thought that withoutNormalize is the way to prevent this default behavior.

[CameronAckermanSEL]

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.

[tashburn]

@CameronAckermanSEL Thanks for all that detail.

It does sounds like withoutNormalization should be renamed to deferNormalization.

But if "normalize" is synonymous with "validation", then one of them should probably be renamed to the other, to have a consistent namespace (perhaps it should be deferValidation?)

I do like the behavior of having validations run automatically, even for programmatic changes. I don't think my code runs withoutNormalization or setFlag('normalize', false), but I'll check.

[SmilinBrian]

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