merge

docs/api/locations/README.md

@@ -0,0 +1,12 @@
+# Location Types
+
+The `Location` interface is a union of the ways to refer to a specific location in a Slate document: paths, points or ranges. Methods will often accept a `Location` instead of requiring only a `Path`, `Point` or `Range`.
+
+```typescript
+type Location = Path | Point | Range
+```
+
+- [Location](https://github.com/ianstormtaylor/slate/tree/5b6b29d33ddcdb9f7f3601477f1ae93c7d5fe45b/docs/api/api/location.md)
+- [Path](https://github.com/ianstormtaylor/slate/tree/5b6b29d33ddcdb9f7f3601477f1ae93c7d5fe45b/docs/api/api/path.md)
+- [Point](https://github.com/ianstormtaylor/slate/tree/5b6b29d33ddcdb9f7f3601477f1ae93c7d5fe45b/docs/api/api/point.md)
+- [Range](https://github.com/ianstormtaylor/slate/tree/5b6b29d33ddcdb9f7f3601477f1ae93c7d5fe45b/docs/api/api/range.md)

docs/api/locations/location.md

@@ -0,0 +1,18 @@
+# Location
+
+The Location interface is a union of the ways to refer to a specific location in a Slate document: paths, points or ranges. Methods will often accept a Location instead of requiring only a Path, Point or Range.
+
+```typescript
+type Location = Path | Point | Range
+```
+
+- [Static methods](location.md#static-methods)
+  - [Check methods](location.md#check-methods)
+
+## Static methods
+
+### Check methods
+
+#### `Location.isLocation(value: any): value is Location`
+
+Check if a value implements the `Location` interface.

docs/api/locations/path.md

@@ -0,0 +1,124 @@
+# Path
+
+`Path` arrays are a list of indexes that describe a node's exact position in a Slate node tree. Although they are usually relative to the root `Editor` object, they can be relative to any `Node` object.
+
+```typescript
+type Path = number[]
+```
+
+- [Static methods](path.md#static-methods)
+  - [Retrieval methods](path.md#retrieval-methods)
+  - [Check methods](path.md#check-methods)
+  - [Transform method](path.md#transform-method)
+
+## Static methods
+
+### Retrieval methods
+
+#### `Path.ancestors(path: Path, options: { reverse?: boolean } = {}): Path[]`
+
+Get a list of ancestor paths for a given path.
+
+The paths are sorted from deepest to shallowest ancestor. However, if the `reverse: true` option is passed, they are reversed.
+
+#### `Path.common(path: Path, another: Path): Path`
+
+Get the common ancestor path of two paths.
+
+#### `Path.compare(path: Path, another: Path): -1 | 0 | 1`
+
+Compare a path to another, returning an integer indicating whether the path was before, at, or after the other.
+
+Note: Two paths of unequal length can still receive a `0` result if one is directly above or below the other. If you want exact matching, use \[\[Path.equals\]\] instead.
+
+#### `Path.levels(path: Path, options?): Path[]`
+
+Get a list of paths at every level down to a path. Note: this is the same as `Path.ancestors`, but including the path itself.
+
+The paths are sorted from shallowest to deepest. However, if the `reverse: true` option is passed, they are reversed.
+
+Options: `{reverse?: boolean}`
+
+#### `Path.next(path: Path): Path`
+
+Given a path, get the path to the next sibling node.
+
+#### `Path.parent(path: Path): Path`
+
+Given a path, return a new path referring to the parent node above it.
+
+#### `Path.previous(path: Path): Path`
+
+Given a path, get the path to the previous sibling node.
+
+#### `Path.relative(path: Path, ancestor: Path): Path`
+
+Get a path relative to an ancestor.
+
+### Check methods
+
+Check some attribute of a path. Always returns a boolean.
+
+#### `Path.endsAfter(path: Path, another: Path): boolean`
+
+Check if a path ends after one of the indexes in another.
+
+#### `Path.endsAt(path: Path, another: Path): boolean`
+
+Check if a path ends at one of the indexes in another.
+
+#### `Path.endsBefore(path: Path, another: Path): boolean`
+
+Check if a path ends before one of the indexes in another.
+
+#### `Path.equals(path: Path, another: Path): boolean`
+
+Check if a path is exactly equal to another.
+
+#### `Path.hasPrevious(path: Path): boolean`
+
+Check if the path of previous sibling node exists
+
+#### `Path.isAfter(path: Path, another: Path): boolean`
+
+Check if a path is after another.
+
+#### `Path.isAncestor(path: Path, another: Path): boolean`
+
+Check if a path is an ancestor of another.
+
+#### `Path.isBefore(path: Path, another: Path): boolean`
+
+Check if a path is before another.
+
+#### `Path.isChild(path: Path, another: Path): boolean`
+
+Check if a path is a child of another.
+
+#### `Path.isCommon(path: Path, another: Path): boolean`
+
+Check if a path is equal to or an ancestor of another.
+
+#### `Path.isDescendant(path: Path, another: Path): boolean`
+
+Check if a path is a descendant of another.
+
+#### `Path.isParent(path: Path, another: Path): boolean`
+
+Check if a path is the parent of another.
+
+#### `Path.isPath(value: any): value is Path`
+
+Check is a value implements the `Path` interface.
+
+#### `Path.isSibling(path: Path, another: Path): boolean`
+
+Check if a path is a sibling of another.
+
+### Transform method
+
+#### `Path.transform(path: Path, operation: Operation, options?): Path | null`
+
+Transform a path by an operation.
+
+Options: `{ affinity?: 'forward' | 'backward' | null }`

docs/api/locations/point-ref.md

@@ -0,0 +1,22 @@
+# PointRef
+
+`PointRef` objects keep a specific point in a document synced over time as new operations are applied to the editor. You can access their property `current` at any time for the up-to-date `Point` value.
+
+```typescript
+interface PointRef {
+  current: Point | null
+  affinity: 'forward' | 'backward' | null
+  unref(): Point | null
+}
+```
+
+- [Static methods](point-ref.md#static-methods)
+  - [Transform methods](point-ref.md#trasnform-methods)
+
+## Static methods
+
+### Transform methods
+
+#### `PointRef.transform(ref: PointRef, op: Operation)`
+
+Transform the point refs current value by an `op`.

docs/api/locations/point.md

@@ -0,0 +1,49 @@
+# Point
+
+`Point` objects refer to a specific location in a text node in a Slate document. Its `path` refers to the location of the node in the tree, and its offset refers to distance into the node's string of text. Points may only refer to `Text` nodes.
+
+```typescript
+interface Point {
+  path: Path
+  offset: number
+}
+```
+
+- [Static methods](point.md#static-methods)
+  - [Retrieval methods](point.md#retrieval-methods)
+  - [Check methods](point.md#check-methods)
+  - [Transform methods](point.md#transform-methods)
+
+## Static methods
+
+### Retrieval methods
+
+#### `Point.compare(point: Point, another: Point): -1 | 0 | 1`
+
+Compare a `point` to `another`, returning an integer indicating whether the point was before, at or after the other.
+
+### Check methods
+
+#### `Point.isAfter(point: Point, another: Point): boolean`
+
+Check if a `point` is after `another`.
+
+#### `Point.isBefore(point: Point, another: Point): boolean`
+
+Check if a `point` is before `another`.
+
+#### `Point.equals(point: Point, another: Point): boolean`
+
+Check if a `point` is exactly equal to `another`.
+
+#### `Point.isPoint(value: any): value is Point`
+
+Check if a `value` implements the `Point` interface.
+
+### Transform methods
+
+#### `Point.transform(point: Point, op: Operation, options?): Point | null`
+
+Transform a `point` by an `op`.
+
+Options: `{affinity?: 'forward' | 'backward' | null}`

docs/api/locations/range-ref.md

@@ -0,0 +1,22 @@
+# RangeRef
+
+`RangeRef` objects keep a specific range in a document synced over time as new operations are applied to the editor. You can access their property `current` at any time for the up-to-date `Range` value.
+
+```typescript
+interface RangeRef {
+  current: Range | null
+  affinity: 'forward' | 'backward' | 'outward' | 'inward' | null
+  unref(): Range | null
+}
+```
+
+- [Static methods](range-ref.md#static-methods)
+  - [Transform methods](range-ref.md#transform-methods)
+
+## Static methods
+
+### Transform methods
+
+#### `RangeRef.transform(ref: RangeRef, op: Operation)`
+
+Transform the range refs current value by an `op`.

docs/api/locations/range.md

@@ -0,0 +1,81 @@
+# Range
+
+`Range` objects are a set of points that refer to a specific span of a Slate document. They can define a span inside a single node or they can span across multiple nodes. The editor's `selection` is stored as a range.
+
+```typescript
+interface Range {
+  anchor: Point
+  focus: Point
+}
+```
+
+- [Static methods](range.md#static-methods)
+  - [Retrieval methods](range.md#retrieval-methods)
+  - [Check methods](range.md#check-methods)
+  - [Transform methods](range.md#transform-methods)
+
+## Static methods
+
+### Retrieval methods
+
+#### `Range.edges(range: Range, options?): [Point, Point]`
+
+Get the start and end points of a `range`, in the order in which they appear in the document.
+
+Options: `{reverse?: boolean}`
+
+#### `Range.end(range: Range): Point`
+
+Get the end point of a `range`.
+
+#### `Range.intersection(range: Range, another: Range): Range | null`
+
+Get the intersection of one `range` with `another`.
+
+#### `Range.points(range: Range): Generator<PointEntry>`
+
+Iterate through all the point entries in a `range`.
+
+#### `Range.start(range: Range): Point`
+
+Get the start point of a `range`
+
+### Check methods
+
+Check some attribute of a Range. Always returns a boolean.
+
+#### `Range.equals(range: Range, another: Range): boolean`
+
+Check if a `range` is exactly equal to `another`.
+
+#### `Range.includes(range: Range, target: Path | Point | Range): boolean`
+
+Check if a `range` includes a path, a point, or part of another range.
+
+#### `Range.isBackward(range: Range): boolean`
+
+Check if a `range` is backward, meaning that its anchor point appears _after_ its focus point in the document.
+
+#### `Range.isCollapsed(range: Range): boolean`
+
+Check if a `range` is collapsed, meaning that both its anchor and focus points refer to the exact same position in the document.
+
+#### `Range.isExpanded(range: Range): boolean`
+
+Check if a `range` is expanded. This is the opposite of `Range.isCollapsed` and is provided for legibility.
+
+#### `Range.isForward(range: Range): boolean`
+
+Check if a `range` is forward. This is the opposite of `Range.isBackward` and is provided for legibility.
+
+#### `Range.isRange(value: any): value is Range`
+
+Check if a `value` implements the `Range` interface.
+
+### Transform methods
+
+#### `Range.transform(range: Range, op: Operation, options): Range | null`
+
+Transform a `range` by an `op`.
+
+Options: `{affinity: 'forward' | 'backward' | 'outward' | 'inward' | null}`