Proposal: Rename Range.includes to Range.intersects and add Range.surrounds to remove confusion

[thesunny]

Problem
Jason Tamulonis expressed that to him includes means that one Range fully includes another in Slack.

Anyone else feel like https://github.com/ianstormtaylor/slate/blame/main/packages/slate/src/interfaces/range.ts#L91 this should be an && and not an or? includes to me implies it includes the entire target not just has some overlap.

Andrew Herron added

This has come up a few times, iirc

My intuition is similar. The issue can be addressed by renaming the method for clarity and adding another method to handle the use case of what others were looking for.

Solution
Rename Range.includes to Range.intersects. This adds clarity as the language suggests that if any part of one range is in any part of the other, it shall return true, which is the behavior.

Add a method Range.surrounds which addresses the desired functionality of detecting that one range completely surrounds (or is equal to) the entire other range.

Alternatives
Improving the documentation is one step towards reducing confusion, which I will also do. I'll just add it since that's an easy win. Note: DONE https://docs.slatejs.org/api/locations/range#range-includes-range-range-target-path-or-point-or-range-boolean

Context

As this is a breaking change, @ianstormtaylor 

Thumbs up to approve, Thumbs down to disapprove proposal

[ianstormtaylor]

Sounds good! Should be implemented as a deprecation with tiny-warning first and can be removed in a later version that way without breaking in the interim.

[electroluxcode]

agree with this proposal; the range.include parameter is confusing(any part of one range).this sounds like an intersection rather than an include. I am currently using the following code to replace this behavior.

const RangeInclude = (targetIncludeData, AllData) => {
	return Range.equals(Range.intersection(targetIncludeData, AllData), targetIncludeData)
}